{"id":33018416,"url":"https://github.com/hoaproject/Console","last_synced_at":"2025-11-16T14:00:35.973Z","repository":{"id":4401601,"uuid":"5538818","full_name":"hoaproject/Console","owner":"hoaproject","description":"The Hoa\\Console library.","archived":true,"fork":false,"pushed_at":"2021-10-14T14:38:59.000Z","size":832,"stargazers_count":364,"open_issues_count":18,"forks_count":33,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-11-08T02:19:18.232Z","etag":null,"topics":["console","hoa","library","php","readline","terminal"],"latest_commit_sha":null,"homepage":"https://hoa-project.net/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoaproject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-24T10:30:58.000Z","updated_at":"2025-11-01T13:16:07.000Z","dependencies_parsed_at":"2022-08-31T10:11:43.806Z","dependency_job_id":null,"html_url":"https://github.com/hoaproject/Console","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/hoaproject/Console","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoaproject%2FConsole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoaproject%2FConsole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoaproject%2FConsole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoaproject%2FConsole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoaproject","download_url":"https://codeload.github.com/hoaproject/Console/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoaproject%2FConsole/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284621240,"owners_count":27036418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-15T02:00:06.050Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["console","hoa","library","php","readline","terminal"],"created_at":"2025-11-13T18:00:39.568Z","updated_at":"2025-11-16T14:00:35.966Z","avatar_url":"https://github.com/hoaproject.png","language":"PHP","funding_links":[],"categories":["命令行","Command Line","Table of Contents","命令行( Command Line )","命令行 Command Line"],"sub_categories":["Command Line"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://static.hoa-project.net/Image/Hoa.svg\" alt=\"Hoa\" width=\"250px\" /\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/hoaproject/Console\"\u003e\u003cimg src=\"https://img.shields.io/travis/hoaproject/Console/master.svg\" alt=\"Build status\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/hoaproject/Console?branch=master\"\u003e\u003cimg src=\"https://img.shields.io/coveralls/hoaproject/Console/master.svg\" alt=\"Code coverage\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagist.org/packages/hoa/console\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/hoa/console.svg\" alt=\"Packagist\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://hoa-project.net/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/hoa/console.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Hoa is a \u003cstrong\u003emodular\u003c/strong\u003e, \u003cstrong\u003eextensible\u003c/strong\u003e and\n  \u003cstrong\u003estructured\u003c/strong\u003e set of PHP libraries.\u003cbr /\u003e\n  Moreover, Hoa aims at being a bridge between industrial and research worlds.\n\u003c/p\u003e\n\n# Hoa\\Console\n\n[![Help on IRC](https://img.shields.io/badge/help-%23hoaproject-ff0066.svg)](https://webchat.freenode.net/?channels=#hoaproject)\n[![Help on Gitter](https://img.shields.io/badge/help-gitter-ff0066.svg)](https://gitter.im/hoaproject/central)\n[![Documentation](https://img.shields.io/badge/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Console)\n[![Board](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/console)\n\nThis library allows to interact easily with a terminal: getoption, cursor,\nwindow, processus, readline etc.\n\n[Learn more](https://central.hoa-project.net/Documentation/Library/Console).\n\n## Installation\n\nWith [Composer](https://getcomposer.org/), to include this library into\nyour dependencies, you need to\nrequire [`hoa/console`](https://packagist.org/packages/hoa/console):\n\n```sh\n$ composer require hoa/console '~3.0'\n```\n\nFor more installation procedures, please read [the Source\npage](https://hoa-project.net/Source.html).\n\n## Testing\n\nBefore running the test suites, the development dependencies must be installed:\n\n```sh\n$ composer install\n```\n\nThen, to run all the test suites:\n\n```sh\n$ vendor/bin/hoa test:run\n```\n\nFor more information, please read the [contributor\nguide](https://hoa-project.net/Literature/Contributor/Guide.html).\n\n## Quick usage\n\nWe propose a quick overview of some features: cursor, window, readline,\nprocessus and finally getoption.\n\n### Cursor\n\nThe `Hoa\\Console\\Cursor` class allows to manipulate the cursor. Here is a list\nof some operations:\n\n  * `move`,\n  * `moveTo`,\n  * `save`,\n  * `restore`,\n  * `clear`,\n  * `hide`,\n  * `show`,\n  * `getPosition`,\n  * `colorize`,\n  * etc.\n\nThe API is very straightforward. For example, we can use `l`, `left` or `←` to\nmove the cursor on the left column. Thus we move the cursor to the left 3 times\nand then to the top 2 times:\n\n```php\nHoa\\Console\\Cursor::move('left left left up up');\n```\n\n… or with Unicode symbols:\n\n```php\nHoa\\Console\\Cursor::move('← ← ← ↑ ↑');\n```\n\nThis method moves the cursor relatively from its current position, but we are\nable to move the cursor to absolute coordinates:\n\n```php\nHoa\\Console\\Cursor::moveTo(13, 42);\n```\n\nWe are also able to save the current cursor position, to move, clear etc., and\nthen to restore the saved position:\n\n```php\nHoa\\Console\\Cursor::save();     // save\nHoa\\Console\\Cursor::move('↓');  // move below\nHoa\\Console\\Cursor::clear('↔'); // clear the line\necho 'Something below…';        // write something\nHoa\\Console\\Cursor::restore();  // restore\n```\n\nAnother example with colors:\n\n```php\nHoa\\Console\\Cursor::colorize(\n    'underlined foreground(yellow) background(#932e2e)'\n);\n```\n\nPlease, read the API documentation for more informations.\n\n### Mouse\n\nThe `Hoa\\Console\\Mouse` class allows to listen the mouse actions and provides\nthe following listeners: `mouseup`, `mousedown`, `wheelup` and `wheeldown`.\nExample:\n\n```php\n$mouse = Hoa\\Console\\Mouse::getInstance();\n$mouse-\u003eon('mousedown', function ($bucket) {\n    print_r($bucket-\u003egetData());\n});\n\n$mouse::track();\n```\n\nAnd then, when we left-click, we will see:\n\n```\nArray\n(\n    [x] =\u003e 69\n    [y] =\u003e 30\n    [button] =\u003e left\n    [shift] =\u003e\n    [meta] =\u003e\n    [ctrl] =\u003e\n)\n```\n\nWhen we left-click while hiting the shift key, we will see:\n\n```\nArray\n(\n    [x] =\u003e 71\n    [y] =\u003e 32\n    [button] =\u003e left\n    [shift] =\u003e 1\n    [meta] =\u003e\n    [ctrl] =\u003e\n)\n```\n\nThis is an experimental API.\n\n### Window\n\nThe `Hoa\\Console\\Window` class allows to manipulate the window. Here is a list\nof some operations:\n\n  * `setSize`,\n  * `getSize`,\n  * `moveTo`,\n  * `getPosition`,\n  * `scroll`,\n  * `minimize`,\n  * `restore`,\n  * `raise`,\n  * `setTitle`,\n  * `getTitle`,\n  * `copy`,\n  * etc.\n\nFurthermore, we have the `hoa://Event/Console/Window:resize` event channel to\nlisten when the window has been resized.\n\nFor example, we resize the window to 40 lines and 80 columns, and then we move\nthe window to 400px horizontally and 100px vertically:\n\n```php\nHoa\\Console\\Window::setSize(40, 80);\nHoa\\Console\\Window::moveTo(400, 100);\n```\n\nIf we do not like our user, we are able to minimize its window:\n\n```php\nHoa\\Console\\Window::minimize();\nsleep(2);\nHoa\\Console\\Window::restore();\n```\n\nWe are also able to set or get the title of the window:\n\n```php\nHoa\\Console\\Window::setTitle('My awesome application');\n```\n\nFinally, if we have a complex application layout, we can repaint it when the\nwindow is resized by listening the `hoa://Event/Console/Window:resize` event\nchannel:\n\n```php\nHoa\\Event\\Event::getEvent('hoa://Event/Console/Window:resize')\n    -\u003eattach(function (Hoa\\Event\\Bucket $bucket) {\n        $data = $bucket-\u003egetData();\n        $size = $data['size'];\n\n        echo\n            'New dimensions: ', $size['x'], ' lines x ',\n            $size['y'], ' columns.', \"\\n\";\n    });\n```\n\nPlease, read the API documentation for more informations\n\n### Readline\n\nThe `Hoa\\Console\\Readline\\Readline` class provides an advanced readline which\nallows the following operations:\n\n  * edition,\n  * history,\n  * autocompletion.\n\nIt supports UTF-8. It is based on bindings, and here are some:\n\n  * `arrow up` and `arrow down`: move in the history,\n  * `arrow left` and `arrow right`: move the cursor left and right,\n  * `Ctrl-A`: move to the beginning of the line,\n  * `Ctrl-E`: move to the end of the line,\n  * `Ctrl-B`: move backward of one word,\n  * `Ctrl-F`: move forward of one word,\n  * `Ctrl-W`: delete first backard word,\n  * `Backspace`: delete first backward character,\n  * `Enter`: submit the line,\n  * `Tab`: autocomplete.\n\nThus, to read one line:\n\n```php\n$readline = new Hoa\\Console\\Readline\\Readline();\n$line     = $readline-\u003ereadLine('\u003e '); // “\u003e ” is the prefix of the line.\n```\n\nThe `Hoa\\Console\\Readline\\Password` allows the same operations but without\nprinting on STDOUT.\n\n```php\n$password = new Hoa\\Console\\Readline\\Password();\n$line     = $password-\u003ereadLine('password: ');\n```\n\nWe are able to add a mapping with the help of the\n`Hoa\\Console\\Readline\\Readline::addMapping` method. We use `\\e[…` for `\\033[`,\n`\\C-…` for `Ctrl-…` and a character for the rest. We can associate a character\nor a callable:\n\n```php\n$readline-\u003eaddMapping('a', 'z'); // crazy, we replace “a” by “z”.\n$readline-\u003eaddMapping('\\C-R', function ($readline) {\n    // do something when pressing Ctrl-R.\n});\n```\n\nWe are also able to manipulate the history, thanks to the `addHistory`,\n`clearHistory`, `getHistory`, `previousHistory` and `nextHistory` methods on the\n`Hoa\\Console\\Readline\\Readline` class.\n\nFinally, we have autocompleters that are enabled on `Tab`. If one solution is\nproposed, it will be inserted directly. If many solutions are proposed, we are\nable to navigate in a menu to select the solution (with the help of keyboard\narrows, Enter, Esc etc.). Also, we are able to combine autocompleters. The\nfollowing example combine the `Word` and `Path` autocompleters:\n\n```php\n$functions = get_defined_functions();\n$readline-\u003esetAutocompleter(\n    new Hoa\\Console\\Readline\\Autocompleter\\Aggregate([\n        new Hoa\\Console\\Readline\\Autocompleter\\Path(),\n        new Hoa\\Console\\Readline\\Autocompleter\\Word($functions['internal'])\n    ])\n);\n```\n\nHere is an example of the result:\n\n![Autocompleters in action](http://central.hoa-project.net/Resource/Library/Console/Documentation/Image/Readline_autocompleters.gif?format=raw)\n\nOn Windows, a readline is equivalent to a simple `fgets(STDIN)`.\n\n### Processus\n\nThe `Hoa\\Console\\Processus` class allows to manipulate processus as a stream\nwhich implements `Hoa\\Stream\\IStream\\In`, `Hoa\\Stream\\IStream\\Out` and\n`Hoa\\Stream\\IStream\\Pathable` interfaces (please, see the\n[`Hoa\\Stream` library](http://central.hoa-project.net/Resource/Library/Stream)).\n\nBasically, we can read STDOUT like this:\n\n```php\n$processus = new Hoa\\Console\\Processus('ls');\n$processus-\u003eopen();\necho $processus-\u003ereadAll();\n```\n\nAnd we can write on STDIN like this:\n\n```php\n$processus-\u003ewriteAll('foobar');\n```\n\netc. This is very classical.\n\n`Hoa\\Console\\Processus` also proposes many events: `start`, `stop`, `input`,\n`output` and `timeout`. Thus:\n\n```php\n$processus = new Hoa\\Console\\Processus('ls');\n$processus-\u003eon('output', function (Hoa\\Event\\Bucket $bucket) {\n    $data = $bucket-\u003egetData();\n    echo '\u003e ', $data['line'], \"\\n\";\n});\n$processus-\u003erun();\n```\n\nWe are also able to read and write on more pipes than 0 (STDOUT), 1 (STDIN) and\n2 (STDERR). In the same way, we can set the current working directory of the\nprocessus and its environment.\n\nWe can quickly execute a processus without using a stream with the help of the\n`Hoa\\Console\\Processus::execute` method.\n\n### GetOption\n\nThe `Hoa\\Console\\Parser` and `Hoa\\Console\\GetOption` classes allow to parse a\ncommand-line and get options and inputs values easily.\n\nFirst, we need to parse a command-line, such as:\n\n```php\n$parser = new Hoa\\Console\\Parser();\n$parser-\u003eparse('-s --long=value input');\n```\n\nSecond, we need to define our options:\n\n```php\n$options = new Hoa\\Console\\GetOption(\n    [\n        // long name              type                  short name\n        //  ↓                      ↓                         ↓\n        ['short', Hoa\\Console\\GetOption::NO_ARGUMENT,       's'],\n        ['long',  Hoa\\Console\\GetOption::REQUIRED_ARGUMENT, 'l']\n    ],\n    $parser\n);\n```\n\nAnd finally, we iterate over options:\n\n```php\n$short = false;\n$long  = null;\n\n//          short name                  value\n//               ↓                        ↓\nwhile (false !== $c = $options-\u003egetOption($v)) {\n    switch ($c) {\n        case 's':\n            $short = true;\n\n            break;\n\n        case 'l':\n            $long = $v;\n\n            break;\n    }\n}\n\nvar_dump($short, $long); // bool(true) and string(5) \"value\".\n```\n\nPlease, see API documentation of `Hoa\\Console\\Parser` to see all supported forms\nof options (flags or switches, long or short ones, inputs etc.).\n\nIt also support typos in options. In this case, we have to add:\n\n```php\n    case '__ambiguous':\n        $options-\u003eresolveOptionAmbiguity($v);\n\n        break;\n```\n\nIf one solution is found, it will select this one automatically, else it will\nraise an exception. This exception is caught by `Hoa\\Console\\Dispatcher\\Kit`\nwhen using the `hoa` script and a prompt is proposed.\n\nThanks to the [`Hoa\\Router`\nlibrary](http://central.hoa-project.net/Resource/Library/Router) and the\n[`Hoa\\Dispatcher`\nlibrary](http://central.hoa-project.net/Resource/Library/Dispatcher) (with its\ndedicated kit `Hoa\\Console\\Dispatcher\\Kit`), we are able to build commands\neasily. Please, see all `Bin/` directories in different libraries (for example\n[`Hoa\\Cli\\Bin\\Resolve`](http://central.hoa-project.net/Resource/Library/Cli/Bin/Resolve.php))\nand\n[`Hoa/Cli/Bin/Hoa.php`](http://central.hoa-project.net/Resource/Library/Cli/Bin/Hoa.php)\nto learn more.\n\n## Awecode\n\nThe following awecodes show this library in action:\n\n  * [`Hoa\\Console\\Readline`](https://hoa-project.net/Awecode/Console-readline.html):\n    *why and how to use `Hoa\\Console\\Readline`? Simple examples will help us to\n    use default shortcuts and we will even see the auto-completion*,\n  * [`Hoa\\Websocket`](https://hoa-project.net/Awecode/Websocket.html):\n    *why and how to use `Hoa\\Websocket\\Server` and `Hoa\\Websocket\\Client`? A\n    simple example will illustrate the WebSocket protocol*.\n\n## Documentation\n\nThe\n[hack book of `Hoa\\Console`](https://central.hoa-project.net/Documentation/Library/Console)\ncontains detailed information about how to use this library and how it works.\n\nTo generate the documentation locally, execute the following commands:\n\n```sh\n$ composer require --dev hoa/devtools\n$ vendor/bin/hoa devtools:documentation --open\n```\n\nMore documentation can be found on the project's website:\n[hoa-project.net](https://hoa-project.net/).\n\n## Getting help\n\nThere are mainly two ways to get help:\n\n  * On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)\n    IRC channel,\n  * On the forum at [users.hoa-project.net](https://users.hoa-project.net).\n\n## Contribution\n\nDo you want to contribute? Thanks! A detailed [contributor\nguide](https://hoa-project.net/Literature/Contributor/Guide.html) explains\neverything you need to know.\n\n## License\n\nHoa is under the New BSD License (BSD-3-Clause). Please, see\n[`LICENSE`](https://hoa-project.net/LICENSE) for details.\n\n## Related projects\n\nThe following projects are using this library:\n\n  * [PsySH](http://psysh.org/), A runtime developer console,\n    interactive debugger and REPL for PHP.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoaproject%2FConsole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoaproject%2FConsole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoaproject%2FConsole/lists"}