2017 © Pedro Peláez
 

library console

The Hoa\Console library.

image

hoa/console

The Hoa\Console library.

  • Tuesday, January 23, 2018
  • by Hoa
  • Repository
  • 21 Watchers
  • 269 Stars
  • 71,418 Installations
  • PHP
  • 22 Dependents
  • 1 Suggesters
  • 24 Forks
  • 11 Open issues
  • 20 Versions
  • 4 % Grown

The README.md

Hoa , (*1)


Build status Code coverage Packagist License , (*2)

Hoa is a modular, extensible and structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds. , (*3)

Hoa\Console

Help on IRC Help on Gitter Documentation Board, (*4)

This library allows to interact easily with a terminal: getoption, cursor, window, processus, readline etc., (*5)

Learn more., (*6)

Installation

With Composer, to include this library into your dependencies, you need to require hoa/console:, (*7)

$ composer require hoa/console '~3.0'

For more installation procedures, please read the Source page., (*8)

Testing

Before running the test suites, the development dependencies must be installed:, (*9)

$ composer install

Then, to run all the test suites:, (*10)

$ vendor/bin/hoa test:run

For more information, please read the contributor guide., (*11)

Quick usage

We propose a quick overview of some features: cursor, window, readline, processus and finally getoption., (*12)

Cursor

The Hoa\Console\Cursor class allows to manipulate the cursor. Here is a list of some operations:, (*13)

  • move,
  • moveTo,
  • save,
  • restore,
  • clear,
  • hide,
  • show,
  • getPosition,
  • colorize,
  • etc.

The API is very straightforward. For example, we can use l, left or to move the cursor on the left column. Thus we move the cursor to the left 3 times and then to the top 2 times:, (*14)

Hoa\Console\Cursor::move('left left left up up');

… or with Unicode symbols:, (*15)

Hoa\Console\Cursor::move('← ← ← ↑ ↑');

This method moves the cursor relatively from its current position, but we are able to move the cursor to absolute coordinates:, (*16)

Hoa\Console\Cursor::moveTo(13, 42);

We are also able to save the current cursor position, to move, clear etc., and then to restore the saved position:, (*17)

Hoa\Console\Cursor::save();     // save
Hoa\Console\Cursor::move('↓');  // move below
Hoa\Console\Cursor::clear('↔'); // clear the line
echo 'Something below…';        // write something
Hoa\Console\Cursor::restore();  // restore

Another example with colors:, (*18)

Hoa\Console\Cursor::colorize(
    'underlined foreground(yellow) background(#932e2e)'
);

Please, read the API documentation for more informations., (*19)

Mouse

The Hoa\Console\Mouse class allows to listen the mouse actions and provides the following listeners: mouseup, mousedown, wheelup and wheeldown. Example:, (*20)

$mouse = Hoa\Console\Mouse::getInstance();
$mouse->on('mousedown', function ($bucket) {
    print_r($bucket->getData());
});

$mouse::track();

And then, when we left-click, we will see:, (*21)

Array
(
    [x] => 69
    [y] => 30
    [button] => left
    [shift] =>
    [meta] =>
    [ctrl] =>
)

When we left-click while hiting the shift key, we will see:, (*22)

Array
(
    [x] => 71
    [y] => 32
    [button] => left
    [shift] => 1
    [meta] =>
    [ctrl] =>
)

This is an experimental API., (*23)

Window

The Hoa\Console\Window class allows to manipulate the window. Here is a list of some operations:, (*24)

  • setSize,
  • getSize,
  • moveTo,
  • getPosition,
  • scroll,
  • minimize,
  • restore,
  • raise,
  • setTitle,
  • getTitle,
  • copy,
  • etc.

Furthermore, we have the hoa://Event/Console/Window:resize event channel to listen when the window has been resized., (*25)

For example, we resize the window to 40 lines and 80 columns, and then we move the window to 400px horizontally and 100px vertically:, (*26)

Hoa\Console\Window::setSize(40, 80);
Hoa\Console\Window::moveTo(400, 100);

If we do not like our user, we are able to minimize its window:, (*27)

Hoa\Console\Window::minimize();
sleep(2);
Hoa\Console\Window::restore();

We are also able to set or get the title of the window:, (*28)

Hoa\Console\Window::setTitle('My awesome application');

Finally, if we have a complex application layout, we can repaint it when the window is resized by listening the hoa://Event/Console/Window:resize event channel:, (*29)

Hoa\Event\Event::getEvent('hoa://Event/Console/Window:resize')
    ->attach(function (Hoa\Event\Bucket $bucket) {
        $data = $bucket->getData();
        $size = $data['size'];

        echo
            'New dimensions: ', $size['x'], ' lines x ',
            $size['y'], ' columns.', "\n";
    });

Please, read the API documentation for more informations, (*30)

Readline

The Hoa\Console\Readline\Readline class provides an advanced readline which allows the following operations:, (*31)

  • edition,
  • history,
  • autocompletion.

It supports UTF-8. It is based on bindings, and here are some:, (*32)

  • arrow up and arrow down: move in the history,
  • arrow left and arrow right: move the cursor left and right,
  • Ctrl-A: move to the beginning of the line,
  • Ctrl-E: move to the end of the line,
  • Ctrl-B: move backward of one word,
  • Ctrl-F: move forward of one word,
  • Ctrl-W: delete first backard word,
  • Backspace: delete first backward character,
  • Enter: submit the line,
  • Tab: autocomplete.

Thus, to read one line:, (*33)

$readline = new Hoa\Console\Readline\Readline();
$line     = $readline->readLine('> '); // “> ” is the prefix of the line.

The Hoa\Console\Readline\Password allows the same operations but without printing on STDOUT., (*34)

$password = new Hoa\Console\Readline\Password();
$line     = $password->readLine('password: ');

We are able to add a mapping with the help of the Hoa\Console\Readline\Readline::addMapping method. We use \e[… for \033[, \C-… for Ctrl-… and a character for the rest. We can associate a character or a callable:, (*35)

$readline->addMapping('a', 'z'); // crazy, we replace “a” by “z”.
$readline->addMapping('\C-R', function ($readline) {
    // do something when pressing Ctrl-R.
});

We are also able to manipulate the history, thanks to the addHistory, clearHistory, getHistory, previousHistory and nextHistory methods on the Hoa\Console\Readline\Readline class., (*36)

Finally, we have autocompleters that are enabled on Tab. If one solution is proposed, it will be inserted directly. If many solutions are proposed, we are able to navigate in a menu to select the solution (with the help of keyboard arrows, Enter, Esc etc.). Also, we are able to combine autocompleters. The following example combine the Word and Path autocompleters:, (*37)

$functions = get_defined_functions();
$readline->setAutocompleter(
    new Hoa\Console\Readline\Autocompleter\Aggregate([
        new Hoa\Console\Readline\Autocompleter\Path(),
        new Hoa\Console\Readline\Autocompleter\Word($functions['internal'])
    ])
);

Here is an example of the result:, (*38)

Autocompleters in action, (*39)

On Windows, a readline is equivalent to a simple fgets(STDIN)., (*40)

Processus

The Hoa\Console\Processus class allows to manipulate processus as a stream which implements Hoa\Stream\IStream\In, Hoa\Stream\IStream\Out and Hoa\Stream\IStream\Pathable interfaces (please, see the Hoa\Stream library)., (*41)

Basically, we can read STDOUT like this:, (*42)

$processus = new Hoa\Console\Processus('ls');
$processus->open();
echo $processus->readAll();

And we can write on STDIN like this:, (*43)

$processus->writeAll('foobar');

etc. This is very classical., (*44)

Hoa\Console\Processus also proposes many events: start, stop, input, output and timeout. Thus:, (*45)

$processus = new Hoa\Console\Processus('ls');
$processus->on('output', function (Hoa\Event\Bucket $bucket) {
    $data = $bucket->getData();
    echo '> ', $data['line'], "\n";
});
$processus->run();

We are also able to read and write on more pipes than 0 (STDOUT), 1 (STDIN) and 2 (STDERR). In the same way, we can set the current working directory of the processus and its environment., (*46)

We can quickly execute a processus without using a stream with the help of the Hoa\Console\Processus::execute method., (*47)

GetOption

The Hoa\Console\Parser and Hoa\Console\GetOption classes allow to parse a command-line and get options and inputs values easily., (*48)

First, we need to parse a command-line, such as:, (*49)

$parser = new Hoa\Console\Parser();
$parser->parse('-s --long=value input');

Second, we need to define our options:, (*50)

$options = new Hoa\Console\GetOption(
    [
        // long name              type                  short name
        //  ↓                      ↓                         ↓
        ['short', Hoa\Console\GetOption::NO_ARGUMENT,       's'],
        ['long',  Hoa\Console\GetOption::REQUIRED_ARGUMENT, 'l']
    ],
    $parser
);

And finally, we iterate over options:, (*51)

$short = false;
$long  = null;

//          short name                  value
//               ↓                        ↓
while (false !== $c = $options->getOption($v)) {
    switch ($c) {
        case 's':
            $short = true;

            break;

        case 'l':
            $long = $v;

            break;
    }
}

var_dump($short, $long); // bool(true) and string(5) "value".

Please, see API documentation of Hoa\Console\Parser to see all supported forms of options (flags or switches, long or short ones, inputs etc.)., (*52)

It also support typos in options. In this case, we have to add:, (*53)

    case '__ambiguous':
        $options->resolveOptionAmbiguity($v);

        break;

If one solution is found, it will select this one automatically, else it will raise an exception. This exception is caught by Hoa\Console\Dispatcher\Kit when using the hoa script and a prompt is proposed., (*54)

Thanks to the Hoa\Router library and the Hoa\Dispatcher library (with its dedicated kit Hoa\Console\Dispatcher\Kit), we are able to build commands easily. Please, see all Bin/ directories in different libraries (for example Hoa\Cli\Bin\Resolve) and Hoa/Cli/Bin/Hoa.php to learn more., (*55)

Awecode

The following awecodes show this library in action:, (*56)

  • Hoa\Console\Readline: why and how to use Hoa\Console\Readline? Simple examples will help us to use default shortcuts and we will even see the auto-completion,
  • Hoa\Websocket: why and how to use Hoa\Websocket\Server and Hoa\Websocket\Client? A simple example will illustrate the WebSocket protocol.

Documentation

The hack book of Hoa\Console contains detailed information about how to use this library and how it works., (*57)

To generate the documentation locally, execute the following commands:, (*58)

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

More documentation can be found on the project's website: hoa-project.net., (*59)

Getting help

There are mainly two ways to get help:, (*60)

Contribution

Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know., (*61)

License

Hoa is under the New BSD License (BSD-3-Clause). Please, see LICENSE for details., (*62)

The following projects are using this library:, (*63)

  • PsySH, A runtime developer console, interactive debugger and REPL for PHP.

The Versions

23/01 2018

dev-master

9999999-dev https://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

02/05 2017

3.17.05.02

3.17.05.02 https://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

11/01 2017

3.17.01.11

3.17.01.11 https://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

08/11 2016

3.16.11.08

3.16.11.08 https://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

06/09 2016

3.16.09.06

3.16.09.06 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

14/01 2016

3.16.01.14

3.16.01.14 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

11/01 2016

3.16.01.11

3.16.01.11 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

27/07 2015

2.15.07.27

2.15.07.27 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

23/07 2015

2.15.07.23

2.15.07.23 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

29/05 2015

2.15.05.29

2.15.05.29 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

19/03 2015

2.15.03.19

2.15.03.19 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

06/03 2015

2.15.03.06

2.15.03.06 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

18/02 2015

2.15.02.18

2.15.02.18 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

04/01 2015

2.15.01.04

2.15.01.04 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

09/12 2014

2.14.12.10

2.14.12.10 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

25/11 2014

2.14.11.26

2.14.11.26 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

26/09 2014

2.14.11.09

2.14.11.09 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

23/09 2014

2.14.09.23

2.14.09.23 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

17/09 2014

2.14.09.17

2.14.09.17 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput

16/09 2014

1.14.09.16

1.14.09.16 http://hoa-project.net/

The Hoa\Console library.

  Sources   Download

BSD-3-Clause

The Requires

 

parser library console cli chrome autocompletion option window readline processus getoption cursor terminfo tput