0byt3m1n1-V2

Path: /home/a/home/dev2.destoffenstraat.com/vendor/hoa/console/Documentation/En/ [ Home ]

File: Index.xyl

<?xml version="1.0" encoding="utf-8"?>

<overlay xmlns="http://hoa-project.net/xyl/xylophone">
<yield id="chapter">

  <p>The terminal is a very <strong>powerful interface</strong> that is based on
  multiple concepts. <code>Hoa\Console</code> allows to write
  <strong>tools</strong> that are adapted to this kind of environment.</p>

  <h2 id="Table_of_contents">Table of contents</h2>

  <tableofcontents id="main-toc" />

  <h2 id="Introduction" for="main-toc">Introduction</h2>

  <p>Nowadays, we have two kinds of interface: <strong>textual</strong> and
  <strong>graphical</strong>. The textual interface exist since the origin of
  computers, then called terminal. This interface, despite its “raw” aspect, is
  functionally very <strong>powerful</strong> thanks to several concepts such as
  the readline or pipes. Today, it is even more used because it is often faster
  than a graphical interface when executing <strong>complex</strong> tasks. It
  can also easily be used through networks or on a machine with low
  performances. In short, this interface is still
  <strong>indispensable</strong>.</p>
  <p>From the user point of view, there is three levels to consider:</p>
  <ul>
    <li>the <strong>interface</strong>: print and edit text, manipulate the
    window, the cursor etc.,</li>
    <li>the <strong>program</strong>: interact with the user with a maximum of
    comfort, use the readline as much better as possible, build programs adapted
    to this kind of interface,</li>
    <li>the <strong>interaction</strong> with other programs: automatically
    interact and communicate with other programs.</li>
  </ul>
  <p>The <code>Hoa\Console</code> library provides tools to answer to these
  three levels. Thus, it is based on standards, such as
  <a href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.pdf">ECMA-48</a>
  that specifies the communication with the system through sequences of ASCII
  characters and control codes (also called escaping sequences), all of that, in
  order to manipulate the window, the cursor or other devices of the machine.
  Other features are also standard such as the way we read options from a
  program, very <strong>inspired</strong> of systems like
  <a href="http://linux.org/">Linux</a>, <a href="http://freebsd.org/">FreeBSD</a>
  or <a href="https://en.wikipedia.org/wiki/UNIX_System_V">System V</a>. By the
  way, if you are familiar with several C libraries, you will not be lost. And
  <em>a contrario</em>, if you learn to use <code>Hoa\Console</code>, you will
  not be lost when using low-level languages such as C.</p>
  <p>Before starting, we would like to add a little note
  <strong>only</strong> about the window and cursor support. Today, we have the
  choice among <strong>many</strong> terminals per system and some of them are
  more comprehensive than others. For example,
  <a href="https://windows.microsoft.com/">Windows</a> and its default terminal,
  <a href="http://en.wikipedia.org/wiki/MS-DOS">MS-DOS</a>, does not respect any
  standard. In this case, forget the ECMA-48 standard and take a look at
  <a href="http://msdn.microsoft.com/library/ms682087.aspx"
     title="Console Reference">the <code>Wincon</code> library</a>. It is often
  recommended to use a <strong>virtual</strong> Unix machine or a terminal
  <strong>emulator</strong>, such as
  <a href="http://ttssh2.sourceforge.jp/">TeraTerm</a>, very comprehensive. Even
  on systems that are closed to the BSD family, the embeded terminals do not
  support all the standards. This is the case of Mac OS X where we recommend to
  use <a href="http://iterm2.com">iTerm2</a> instead of Terminal. Finally, on
  other systems of the Linux or BSD family, we recommend
  <a href="http://software.schmorp.de/pkg/rxvt-unicode.html">urxvt</a>. For
  other features, such as the readline, the options reading, the processus etc.,
  <code>Hoa\Console</code> is perfectly <strong>compatible</strong> and
  suitable.</p>

  <h2 id="Window" for="main-toc">Window</h2>

  <p>The window of a terminal must be understood as a <strong>canvas</strong> of
  <strong>columns</strong> and <strong>lines</strong>. The
  <code>Hoa\Console\Window</code> allows to manipulate the
  <strong>window</strong> of a terminal and its <strong>content</strong> through
  static methods.</p>

  <h3 id="Size_and_position" for="main-toc">Size and position</h3>

  <p>The first elementary operations are about the <strong>size</strong> and the
  <strong>position</strong> of the window, thanks to the <code>setSize</code>,
  <code>getSize</code>, <code>moveTo</code> and <code>getPosition</code>
  methods. The size is defined with the <em>column</em> × <em>line</em> unit and
  the position is defined in pixels. Thus:</p>
  <pre><code class="language-php">Hoa\Console\Window::setSize(80, 50);
print_r(Hoa\Console\Window::getSize());
print_r(Hoa\Console\Window::getPosition());

/**
 * Will output:
 *     Array
 *     (
 *         [x] => 80
 *         [y] => 50
 *     )
 *     Array
 *     (
 *         [x] => 104
 *         [y] => 175
 *     )
 */</code></pre>
  <p>We will notice that the window is resized <strong>itself</strong>. Nor the
  size or the position of the window is stored in memory, they are computed at
  each call of the <code>getSize</code> and <code>getPosition</code> method.
  Attention, the <em>y</em> axe of the window position is computed from the
  <strong>bottom</strong> of the screen and not from the top of the screen as we
  might expect!</p>
  <p>It is also possible to listen the
  <code>hoa://Event/Console/Window:resize</code> <strong>event</strong> that is
  fired each time the window is resized: either manually or with the
  <code>setSize</code> method. We need two things in order to see this event
  working:</p>
  <ol>
    <li><a href="http://php.net/pcntl">the <code>pcntl</code> extension</a> must
    be activated,</li>
    <li>we have to use <a href="http://php.net/declare">the <code>declare</code>
    structure</a> to enable the <a href="http://php.net/pcntl_signal">the
    <code>pcntl_signal</code> function</a>.</li>
  </ol>
  <p>To put the program in a passive waiting state, we will use
  <a href="http://php.net/stream_select">the <code>stream_select</code>
  function</a>, this is a <strong>detail</strong>, only present to test our
  code, else the program will terminate directly. Thus:</p>
  <pre><code class="language-php">Consistency\Autoloader::load('Hoa\Console\Window'); // make sure it is loaded.

declare(ticks = 1);

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

        echo 'New size (', $size['x'], ', ', $size['y'], ')', "\n";
    });

// Passive loop.
while (true) {
    $r = [STDIN];
    @stream_select($r, $w, $e, 3600);
}</code></pre>
  <p>When we modify the size of the window, we will see for example:
  <code>New size (45, 67)</code>, and this, for each resize. This event is
  interesting if we would like to <strong>re-layout</strong> our view.</p>
  <p>Finally, we can minimize or restore the window thanks to the
  <code>Hoa\Console\Window::minimize</code> and
  <code>Hoa\Console\Window::restore</code> static methods. Moreover, we can put
  the window in the background (behind all other windows) thanks to the
  <code>Hoa\Console\Window::lower</code> static method, just like we can place
  it in the foreground with <code>Hoa\Console\Window::raise</code>. For
  example:</p>
  <pre><code class="language-php">Hoa\Console\Window::minimize();
sleep(2);
Hoa\Console\Window::restore();
sleep(2);
Hoa\Console\Window::lower();
sleep(2);
Hoa\Console\Window::raise();

echo 'Back!', "\n";</code></pre>

  <h3 id="Title_and_label" for="main-toc">Title and label</h3>

  <p>The <strong>title</strong> of a window is the text displayed in the top
  <strong>bar</strong> in which the controls of the window are often placed,
  such as the maximization, the minimization etc. The <strong>label</strong> is
  the name associated to the current <strong>processus</strong>. We have the
  <code>setTitle</code>, <code>getTitle</code> and <code>getLabel</code>
  methods, it is not possible to modify the label. To define the title of the
  processus (what we see with the <code>top</code> or <code>ps</code> command
  for example), we must take a look at
  <code>Hoa\Console\Processus::setTitle</code> and also at
  <code>Hoa\Console\Processus::getTitle</code> to get it. Thus:</p>
  <pre><code class="language-php">Hoa\Console\Window::setTitle('Foobar');
var_dump(Hoa\Console\Window::getTitle());
var_dump(Hoa\Console\Window::getLabel());

/**
 * Will output:
 *     string(6) "Foobar"
 *     string(3) "php"
 */</code></pre>
  <p>Once again, the title and the label are not stored in memory, they are
  computed at each call of the methods.</p>

  <h3 id="Interact_with_the_content" for="main-toc">Interact with the
  content</h3>

  <p><code>Hoa\Console\Window</code> also allows to control the
  <strong>content</strong> of the window, or at least the viewport, it means the
  <strong>visible</strong> content of the window. Only one method is available:
  <code>scroll</code>, that allows to <strong>move</strong> the content to the
  top or the bottom. The arguments of this method are very simple:
  <code>up</code> or <code>↑</code> to move up of one line and <code>down</code>
  or <code>↓</code> to move down of one line. We are able to concatenate those
  directions by a space or to repeat one direction:</p>
  <pre><code class="language-php">Hoa\Console\Window::scroll('↑', 10);</code></pre>
  <p>In reality, this method will move the content in order to get <em>x</em>
  new lines respectively bellow or above the cursor. Attention, the cursor
  <strong>does not move</strong>!</p>
  <p>Even if it is most of the time useless, it is possible to
  <strong>refresh</strong> the window, it means to redo a full render. We can
  use the <code>refresh</code> method, still on
  <code>Hoa\Console\Window</code>.</p>
  <p>Finally, it is possible to put a text inside the <strong>clipboard</strong>
  of the user thanks to the <code>copy</code> method:</p>
  <pre><code class="language-php">Hoa\Console\Window::copy('Foobar');</code></pre>
  <p>Then, if the user pastes what is in the clipboard, she will see
  <code>Foobar</code>.</p>

  <h2 id="Cursor" for="main-toc">Cursor</h2>

  <p>Inside a window, we have a cursor that can be seen as a tip of pen. The
  <code>Hoa\Console\Cursor</code> class allows to manipulate the
  <strong>cursor</strong> of the terminal through static methods.</p>

  <h3 id="Moving" for="main-toc">Moving</h3>

  <p>We will start to <strong>move</strong> the cursor. It can move everywhere
  inside the viewport, it means the <strong>visible</strong> content of the
  terminal window, but we will write a piece of text and move around at first.
  The <code>move</code> method on <code>Hoa\Console\Cursor</code> allows to move
  the cursor in several <strong>directions</strong>. First of all,
  relatively:</p>
  <ul>
    <li><code>u[p]</code> or <code>↑</code>, to move the cursor one line
    above,</li>
    <li><code>r[ight]</code> or <code>→</code>, to move the cursor on the next
    column,</li>
    <li><code>d[own]</code> or <code>↓</code>, to move the cursor one line
    bellow,</li>
    <li><code>l[eft]</code> or <code>←</code>, to move the cursor on the
    previous column.</li>
  </ul>
  <p>We also have <strong>semi-absolute</strong> moving:</p>
  <ul>
    <li><code>U[P]</code>, to move the cursor on the first line of the
    viewport,</li>
    <li><code>R[IGHT]</code>, to move the cursor on the last column of the
    viewport,</li>
    <li><code>D[OWN]</code>, to move the cursor on the last line of the
    viewport,</li>
    <li><code>L[EFT]</code>, to move the cursor on the first column of the
    viewport.</li>
  </ul>
  <p>We are able to concatenate those directions by a space or to repeat one
  direction.</p>
  <pre><code class="language-php">echo
    'abcdef', "\n",
    'ghijkl', "\n",
    'mnopqr', "\n",
    'stuvwx';

sleep(1);
Hoa\Console\Cursor::move('↑');
sleep(1);
Hoa\Console\Cursor::move('↑ ←');
sleep(1);
Hoa\Console\Cursor::move('←', 3);
sleep(1);
Hoa\Console\Cursor::move('DOWN');
sleep(1);
Hoa\Console\Cursor::move('→', 4);</code></pre>
  <p>During the execution, we will see the cursor moving <strong>by
  itself</strong> from a letter to another one each second.</p>
  <p>To actually move the cursor in an <strong>absolute</strong> way, we will
  use the <code>moveTo</code> method that takes <em>column</em> × <em>line</em>
  coordinates (starting from 1 and not 0) as argument. Similarly, there is the
  <code>getPosition</code> method that returns the <strong>position</strong> of
  the cursor. Thus, if we would like to move the cursor from the column 12 and
  line 7, and then print its coordinates, we will write:</p>
  <pre><code class="language-php">Hoa\Console\Cursor::moveTo(12, 7);
print_r(Hoa\Console\Cursor::getPosition());

/**
 * Will output:
 *     Array(
 *         [x] => 12
 *         [y] => 7
 *     )
 */</code></pre>
  <p>Finally, we often would like to move the cursor <strong>temporary</strong>
  for some operations. In this case, it is useless to get its current position,
  to move it and then re-position it; we can benefit from the <code>save</code>
  and <code>restore</code> methods. As their names suggest, they respectively
  <strong>save</strong> the position of the cursor and then
  <strong>restore</strong> the cursor as the previously saved position. These
  functions do not manipulate a <strong>stack</strong>, it is impossible to save
  more than one position at a time (the new record will <strong>erase</strong>
  the previous one). Thus, we will write a text, save the position of the
  cursor, go back to rewrite, and then go back to our previous position:</p>
  <pre><code class="language-php">echo 'hello world';

// Save cursor position.
Hoa\Console\Cursor::save();
sleep(1);

// Go to the begining of the line.
Hoa\Console\Cursor::move('LEFT');
sleep(1);

// Replace “h” by “H”.
echo 'H';
sleep(1);

// Go to “w”.
Hoa\Console\Cursor::move('→', 5);
sleep(1);

// Replace “w” by “W”.
echo 'W';
sleep(1);

// Back to the saved position.
Hoa\Console\Cursor::restore();
sleep(1);

echo '!';</code></pre>
  <p>The final result will be <code>Hello World!</code>. We can notice that each
  time a character is written, the cursor <strong>moves</strong>.</p>

  <h3 id="Content" for="main-toc">Content</h3>

  <p>Now we know how to move, we will see how to <strong>clean</strong> some
  lines and/or columns. We will use the <code>clean</code> method that takes the
  following symbols (concatenated by a space) as argument:</p>
  <ul>
    <li><code>a[ll]</code> or <code>↕</code>, to clean all the screen and move
    the cursor in the top-left corner of the viewport,</li>
    <li><code>u[p]</code> or <code>↑</code>, to clean all the lines above the
    cursor,</li>
    <li><code>r[ight]</code> or <code>→</code>, to clean the rest of the line
    from the cursor,</li>
    <li><code>d[own]</code> or <code>↓</code>, to clean all the lines bellow the
    cursor,</li>
    <li><code>l[eft]</code> or <code>←</code>, to clean the line from its
    beginning to the cursor,</li>
    <li><code>line</code> or <code>↔</code>, to clean all the line and move the
    cursor to its beginning.</li>
  </ul>
  <p>Thus, to clean <strong>a line</strong>:</p>
  <pre><code class="language-php">Hoa\Console\Cursor::clear('↔');</code></pre>
  <p>The cursor can act as a brush and thus write in different
  <strong>colors</strong> or different <strong>styles</strong> thanks to the
  <code>colorize</code> method (we can mix everything by separating each
  “command” by spaces). We start by enumerating all the styles:</p>
  <ul>
    <li><code>n[ormal]</code>, to cancel all applied styles,</li>
    <li><code>b[old]</code>, to write in bold,</li>
    <li><code>u[nderlined]</code>, to get an underlined text,</li>
    <li><code>bl[ink]</code>, to get a blinking text,</li>
    <li><code>i[nverse]</code>, to reverse colors of the foreground and the
    background,</li>
    <li><code>!b[old]</code>, to cancel the bold,</li>
    <li><code>!u[nderlined]</code>, to cancel the underline,</li>
    <li><code>!bl[ink]</code>, to cancel the blink,</li>
    <li><code>!i[nverse]</code>, to no longer reverse colors of the foreground
    and the background.</li>
  </ul>
  <p>Those styles are very classical. Now, let's see the colors. Before all, we
  have to say if we apply a color on the <strong>foreground</strong> of the
  text (the text itself) or on the <strong>background</strong>. Then, we will
  respectively use the <code>f[ore]g[round](<em>color</em>)</code> or
  <code>b[ack]g[round](<em>color</em>)</code> syntax. The value of
  <code><em>color</em></code> can be:</p>
  <ul>
    <li><code>default</code>, to get the default color of the ground,</li>
    <li><code>black</code>, <code>red</code>, <code>green</code>,
    <code>yellow</code>, <code>blue</code>, <code>magenta</code>,
    <code>cyan</code> or <code>white</code>,</li>
    <li>a number between <code>0</code> and <code>256</code>, representing the
    number of the color in the 256 colors palette,</li>
    <li><code>#<em>rrggbb</em></code> where <code><em>rrggbb</em></code> is the
    hexadecimal number representing the number of the color in the
    2<sup>64</sup> colors palette.</li>
  </ul>
  <p>Terminals manipulate <strong>one</strong> of two palettes: 8 colors or 256
  colors. Each color is <strong>indexed</strong> starting from 0. The names of
  colors are <strong>transformed</strong> into their respective index. When a
  color is given in hexadecimal, the <strong>closest</strong> color in the 256
  colors palette is used.</p>
  <p>Thus, if we would like to write <code>Hello</code> in yellow on a red-like
  background (<code>#932e2e</code>) and underlined, then <code> world</code> but
  not underlined:</p>
  <pre><code class="language-php">Hoa\Console\Cursor::colorize('fg(yellow) bg(#932e2e) underlined');
echo 'Hello';
Hoa\Console\Cursor::colorize('!underlined');
echo ' world';</code></pre>
  <p>Finally, it is possible to modify the palette of colors thanks to the
  <code>changeColor</code> method, but use it with <strong>caution</strong>,
  this can disturb the user. This method takes as first argument the index of
  the color and as second argument its hexadecimal value. For example,
  <code>fg(yellow)</code> matches the <code>33</code> index, and we would like
  to see it blue:</p>
  <pre><code class="language-php">Hoa\Console\Cursor::changeColor(33, 0xf00);</code></pre>
  <p>However, the 256 colors palette is <strong>wide</strong> enough to not need
  to redefine colors.</p>

  <h3 id="Style" for="main-toc">Style</h3>

  <p>The cursor is not necessary visible. During some operations, we can
  <strong>hide</strong> it, make some moves and then make it
  <strong>visible</strong> again. The <code>hide</code> and <code>show</code>
  methods, still on <code>Hoa\Console\Cursor</code>, are here for that:</p>
  <pre><code class="language-php">echo 'Visible', "\n";
sleep(5);

echo 'Invisible', "\n";
Hoa\Console\Cursor::hide();
sleep(5);

echo 'Visible', "\n";
Hoa\Console\Cursor::show();
sleep(5);</code></pre>
  <p>There is three <strong>types</strong> of cursors, that we will choose with
  the <code>setStyle</code> method:</p>
  <ul>
    <li><code>b[lock]</code> or <code>▋</code>, to get a cursor represented by a
    block,</li>
    <li><code>u[nderline]</code> or <code>_</code>, to get a cursor represented
    by an underscore,</li>
    <li><code>v[ertical]</code> or <code>|</code>, to get a cursor represented
    by a pipe.</li>
  </ul>
  <p>This method takes as a second argument a boolean which indicates if the
  cursor must <strong>blink</strong> (default value) or not. Thus, we will try
  all the styles:</p>
  <pre><code class="language-php">echo 'Block/steady: ';
Hoa\Console\Cursor::setStyle('▋', false);
sleep(3);

echo "\n", 'Vertical/blink: ';
Hoa\Console\Cursor::setStyle('|', true);
sleep(3);

// etc.</code></pre>
  <p>The cursor often indicates <strong>area</strong> or
  <strong>interactive</strong> elements, just like the pointer of a mouse.</p>

  <h3 id="Sound" for="main-toc">Sound</h3>

  <p>The cursor is also able to emit a little “bip”, most of the time to
  <strong>bring</strong> the attention of the user. We will use the eponym
  <code>bip</code> method:</p>
  <pre><code class="language-php">Hoa\Console\Cursor::bip();</code></pre>
  <p>There is only one available <strong>tonality</strong>.</p>

  <h2 id="Readline" for="main-toc">Readline</h2>

  <p>A way to <strong>interact</strong> with users is to read the
  <code>STDIN</code> stream, namely the input stream. This
  <strong>reading</strong> is by default very basic: unable to erase, unable to
  use arrows, unable to use shortcuts etc. That's why there is the readline,
  that is still a reading on the <code>STDIN</code> stream, but more
  <strong>sophisticated</strong>. The <code>Hoa\Console\Readline\Readline</code>
  library provides several features that we will describe.</p>

  <h3 id="Basic_usage" for="main-toc">Basic usage</h3>

  <p>To <strong>read a line</strong> (it means an input from the user), we will
  instanciate the <code>Hoa\Console\Readline\Readline</code> class and call the
  <code>readLine</code> method. Each call of this method will wait that the user
  <strong>inputs</strong> a data and then hits <kbd title="Enter">↵</kbd>. At
  this moment, the method will returns the input from the user (or
  <code>false</code> if there is nothing to read). This method also takes a
  <strong>prefix</strong> as argument, it means a data to print before the line.
  Sometimes, the term <em>prompt</em> could be used in the literature, both
  notions are identical.</p>
  <p>Thus, we will write a program that will read the inputs from the user and
  make an echo. The program will finish if the user inputs
  <code>quit</code>:</p>
  <pre><code class="language-php">$rl = new Hoa\Console\Readline\Readline();

do {
    $line = $rl->readLine('> ');
    echo '&amp;lt; ', $line, "\n\n";
} while (false !== $line &amp;amp;&amp;amp; 'quit' !== $line);</code></pre>
  <p>Now, let's detail the features offered by
  <code>Hoa\Console\Readline\Readline</code>.</p>
  <p>We are able to <strong>move</strong> (understand, move the cursor) in the
  line with the help of the <kbd>←</kbd> and <kbd>→</kbd> keys. We can
  <strong>erase</strong> a character back at any moment with the
  <kbd title="Backspace">⌫</kbd> key or all the characters until the beginning
  of the word with <kbd>Ctrl</kbd> + <kbd>W</kbd> (where <kbd>W</kbd> stands for
  word). We are also able to move the cursor by using <strong>shortcuts</strong>
  that a shared by many softwares:</p>
  <ul>
    <li><kbd>Ctrl</kbd> + <kbd>A</kbd>, to move at the beginning of the
    line,</li>
    <li><kbd>Ctrl</kbd> + <kbd>E</kbd>, to move at the end of the line,</li>
    <li><kbd>Ctrl</kbd> + <kbd>B</kbd>, to move at the beginning of the current
    word (<kbd>B</kbd> stands for backward),</li>
    <li><kbd>Ctrl</kbd> + <kbd>F</kbd>, to move at the end of the current word
    (<kbd>F</kbd> stands for forward).</li>
  </ul>
  <p>We also have access to the <strong>history</strong> when we hit the
  <kbd>↑</kbd> and <kbd>↓</kbd> keys, respectively to search back and forth in
  the history. The <kbd title="Tabulation">⇥</kbd> key fires the
  <strong>auto-completion</strong> if set. And finally, the
  <kbd title="Enter">↵</kbd> key returns the input.</p>
  <p>There is also the <code>Hoa\Console\Readline\Password</code> class that
  allows to have a readline with the same features but the characters
  <strong>are not printed</strong> to the screen, very useful to read a
  <strong>password</strong>:</p>
  <pre><code class="language-php">$rl  = new Hoa\Console\Readline\Password();
$pwd = $rl->readLine('Password: ');

echo 'Your password is: ', $pwd, "\n";</code></pre>

  <h3 id="Shortcuts" for="main-toc">Shortcuts</h3>

  <p>To understand how to create a shortcut, we have to understand a little bit
  how the <code>Hoa\Console\Readline\Readline</code> class works
  <strong>internally</strong>, and this is very simple. Each time we hit one or
  many keys, a <strong>string</strong> representing this
  <strong>combination</strong> is received by our readline. It looks for an
  associated action to this string: if one exists, then this one will be
  executed, else the readline will use a default action consisting to print the
  string verbatim. Each action returns the <strong>state</strong> of the
  readline (which are constants on
  <code>Hoa\Console\Readline\Readline</code>):</p>
  <ul>
    <li><code>STATE_CONTINUE</code>, to continue the reading,</li>
    <li><code>STATE_BREAK</code>, to stop the reading,</li>
    <li><code>STATE_NO_ECHO</code>, to not print the reading.</li>
  </ul>
  <p>Thus, if an action returns <code class="language-php">STATE_CONTINUE |
  STATE_NO_ECHO</code>, the reading will continue but the string that has been
  received will not be printed. Another example, the action associated to the
  <kbd title="Enter">↵</kbd> key returns the <code>STATE_BREAK</code> state.</p>
  <p>To <strong>add</strong> actions, we use the <code>addMapping</code> method.
  This latter eases the add thanks to a dedicated syntax:</p>
  <ul>
    <li><code>\e[<em>…</em></code>, for sequences starting by the <kbd>Esc</kbd>
    character,</li>
    <li><code>\C-<em>…</em></code>, for sequences starting by the
    <kbd>Ctrl</kbd> character,</li>
    <li><code><em>x</em></code>, any character.</li>
  </ul>
  <p>For example, if we would like to print <code>z</code> instead of
  <code>a</code>, we will write:</p>
  <pre><code class="language-php">$rl->addMapping('a', 'z');</code></pre>
  <p>More sophisticated this time, we can use a callable as the second argument
  of the <code>addMapping</code> method. This callable will receive the instance
  of <code>Hoa\Console\Readline\Readline</code> as the only argument. Several
  methods will help to <strong>manipulate</strong> the reading (to manage the
  history, the line etc.). For example, each time we will hit
  <kbd>Ctrl</kbd> + <kbd>R</kbd>, we will reverse the case of the line:</p>
  <pre><code class="language-php">$rl = new Hoa\Console\Readline\Readline();

// Add mapping.
$rl->addMapping('\C-R', function (Hoa\Console\Readline\Readline $self) {
    // Clear the line.
    Hoa\Console\Cursor::clear('↔');
    echo $self->getPrefix();

    // Get the line text.
    $line = $self->getLine();

    // New line.
    $new  = null;

    // Loop over all characters.
    for ($i = 0, $max = $self->getLineLength(); $i &amp;lt; $max; ++$i) {
        $char = mb_substr($line, $i, 1);

        if ($char === $lower = mb_strtolower($char)) {
            $new .= mb_strtoupper($char);
        } else {
            $new .= $lower;
        }
    }

    // Set the new line.
    $self->setLine($new);

    // Set the buffer (and let the readline echoes or not).
    $self->setBuffer($new);

    // The readline will continue to read.
    return $self::STATE_CONTINUE;
});

// Try!
var_dump($rl->readLine('> '));</code></pre>
  <p>Do not hesitate to take a look at how previous listed shortcuts have been
  implemented to get ideas.</p>

  <h3 id="Auto-completion" for="main-toc">Auto-completion</h3>

  <p>Another very useful tool when we are writing a readline is the
  <strong>auto-completion</strong>. It is fired when hiting the
  <kbd title="Tabulation">⇥</kbd> key if the auto-completer has been defined
  with the <code>setAutocompleter</code> method.</p>
  <p>All the auto-completers must implement the
  <code>Hoa\Console\Readline\Autocompleter\Autocompleter</code> interface. Some
  of them are already distributed to <strong>help</strong> us in our
  development, such as <code>Hoa\Console\Readline\Autocompleter\Word</code> that
  will auto-complete the input based on a <strong>list of words</strong>. For
  example:</p>
  <pre><code class="language-php">$rl = new Hoa\Console\Readline\Readline();
$rl->setAutocompleter(new Hoa\Console\Readline\Autocompleter\Word([
    'hoa',
    'console',
    'readline',
    'autocompleter',
    'autocompletion',
    'password',
    'awesome'
]));
var_dump($rl->readLine('> '));</code></pre>
  <p>Let's try to write something, then where we would like, we hit
  <kbd title="Tabulation">⇥</kbd>. If the text at the left of the cursor starts
  by <code>h</code>, then we will see <code>hoa</code> <strong>printed</strong>
  in the line because the auto-completer has no choice (it returns a string). If
  the auto-completer does not find any appropriated word,
  <strong>nothing</strong> will happen (it will return <code>null</code>). And
  finally, if it finds <strong>several words</strong> (it will return an array),
  then a <strong>menu</strong> will appear. Let's try to simply auto-complete
  <code>a</code>: the menu will propose <code>autocompleter</code>,
  <code>autocompletion</code> and <code>awesome</code>. Either we continue to
  hit and the menu will <strong>disappear</strong>, or we can
  <strong>move</strong> the cursor inside the menu with the
  <kbd title="Tabulation">⇥</kbd>, <kbd>↑</kbd>, <kbd>→</kbd>, <kbd>↓</kbd> and
  <kbd>←</kbd> keys, then <kbd title="Enter">↵</kbd> to <strong>select</strong>
  a word. This behavior is quite <strong>natural</strong>.</p>
  <p>In addition to the auto-completer on words, we find the auto-completer on
  <strong>paths</strong> with the
  <code>Hoa\Console\Readline\Autocompleter\Path</code> class. Based on a root
  and a file iterator, this auto-completer is able to auto-complete paths.
  If the root is undefined, it will be set to the current working directory. At
  each auto-completion, a new instance of the file iterator is created by a
  factory. This latter receives the path to iterate as a unique argument. By
  default, the factory is defined by the <code>getDefaultIteratorFactory</code>
  static method on <code>Hoa\Console\Readline\Autocompleter\Path</code>. The
  factory builds a file iterator of type
  <a href="http://php.net/directoryiterator"><code>DirectoryIterator</code></a>.
  Each value computed by the iterator must be an object of type
  <a href="http://php.net/splfileinfo"><code>SplFileInfo</code></a>. Thus, to
  auto-complete all the files and directories from the
  <a href="@central_resource:path=Library/Console"><code>hoa://Library/Console</code></a>
  root, we will write:</p>
  <pre><code class="language-php">$rl->setAutocompleter(
    new Hoa\Console\Readline\Autocompleter\Path(
        resolve('hoa://Library/Console')
    )
);</code></pre>
  <p>Using a factory offers a lot of <strong>flexibility</strong> and allows us
  to use any file iterator, such as <code>Hoa\File\Finder</code> (please, see
  <a href="@hack:chapter=File">the <code>Hoa\File</code> library</a>). Thus, to
  only auto-complete not hidden files and directories that have been modified
  the last 6 months and sorted by their size, we will write:</p>
  <pre><code class="language-php">$rl->setAutocompleter(
    new Hoa\Console\Readline\Autocompleter\Path(
        resolve('hoa://Library/Console'),
        function ($path) {
            $finder = new Hoa\File\Finder();
            $finder->in($path)
                   ->files()
                   ->directories()
                   ->maxDepth(1)
                   ->name('#^(?!\.).#')
                   ->modified('since 6 months')
                   ->sortBySize();

            return $finder;
        }
    )
);</code></pre>
  <p>We can replace the local file iterator by another totally
  <strong>different</strong> iterator: on files that are stored in another
  machine, a third party service or even resources that are not files but have
  path-like URI.</p>
  <p>Finally, we can aggregate several auto-completers together thanks to the
  <code>Hoa\Console\Readline\Autocompleter\Aggregate</code> class. The
  declaration order of auto-completers is important: the first one that matches
  a word to auto-complete will break the loop over all the auto-completers.
  Thus, to auto-complete paths and words, we will write:</p>
  <pre><code class="language-php">$rl->setAutocompleter(
    new Hoa\Console\Readline\Autocompleter\Aggregate([
        new Hoa\Console\Readline\Autocompleter\Path(),
        new Hoa\Console\Readline\Autocompleter\Word($words)
    ])
);
</code></pre>
  <p>The <code>getAutocompleters</code> method from
  <code>Hoa\Console\Readline\Autocompleter\Aggregate</code> returns an
  <a href="http://php.net/arrayobject"><code>ArrayObject</code></a> object for
  more flexibility. We can consequently add or delete auto-completers after
  having declared them in the constructor.</p>
  <figure>
    <img src="https://central.hoa-project.net/Resource/Library/Console/Documentation/Image/Readline_autocompleters.gif?format=raw" />
    <figcaption>Example of an aggregation of the
    <code>Hoa\Console\Readline\Autocompleter\Path</code> auto-completer with
    <code>Hoa\Console\Readline\Autocompleter\Word</code>.</figcaption>
  </figure>

  <h2 id="Reading_options" for="main-toc">Reading options</h2>

  <p>A big benefit of programs with a command line interface is their
  <strong>flexibility</strong>. They are <strong>dedicated</strong> to one
  (little) <strong>task</strong> and we are able to parameterize them thanks to
  <strong>options</strong> that they exposed. The <strong>reading</strong> of
  those options must be very simple and straightforward because this is a
  repetitive and subtle task. The <code>Hoa\Console\Parser</code> and
  <code>Hoa\Console\GetOption</code> classes act as a <strong>duo</strong> to
  solve this problem.</p>

  <h3 id="Analyzing_options" for="main-toc">Analyzing options</h3>

  <p>We start with <code>Hoa\Console\Parser</code> that
  <strong>analyzes</strong> options given to a program. Whatever the options we
  would like to have, we just analyze them for now. Let's start by using the
  <code>parse</code> method:</p>
  <pre><code class="language-php">$parser = new Hoa\Console\Parser();
$parser->parse('-s --long=value input');

print_r($parser->getSwitches());
print_r($parser->getInputs());

/**
 * Will output:
 *     Array
 *     (
 *         [s] => 1
 *         [long] => value
 *     )
 *     Array
 *     (
 *         [0] => input
 *     )
 */</code></pre>
  <p>Let's see of what a command line is composed. We have two categories: the
  <strong>options</strong> (switches) and the <strong>inputs</strong>. The
  inputs are everything that is not an option. An option can have two forms:
  <strong>short</strong> if it has only one character or <strong>long</strong>
  if it has many.</p>
  <p>Thus, <code>-s</code> is a short option and <code>--long</code> is a
  long option. However, we have to consider the number of hyphen in front of the
  option: with two hyphens, it will always be a long option, with one hyphen, it
  depends. There is two schools that differenciate themselves with one
  <strong>parameter</strong>: <em>long only</em>. Let's take an example:
  <code>-abc</code> is considered as <code>-a -b -c</code> if the <em>long
  only</em> parameter is set to <code>false</code>, else it will be equivalent
  to a long option, such as <code>--abc</code>. Most of the time, this parameter
  is set to <code>false</code> by default and <code>Hoa\Console\Parser</code>
  has adopted the position of the majority. To modify this parameter, we have to
  use the <code>setLongOnly</code> method, let's see though:</p>
  <pre><code class="language-php">// long only is set to false.
$parser->parse('-abc');
print_r($parser->getSwitches());

$parser->setLongOnly(true);

// long only is set to true.
$parser->parse('-abc');
print_r($parser->getSwitches());

/**
 * Will output:
 *     Array
 *     (
 *         [a] => 1
 *         [b] => 1
 *         [c] => 1
 *     )
 *     Array
 *     (
 *         [abc] => 1
 *     )
 */</code></pre>
  <p>An option can be of two kinds: <strong>boolean</strong> or
  <strong>valued</strong>. If no value is associated, it is considered as a
  boolean. Thus, <code>-s</code> represents <code>true</code>, but <code>-s
  -s</code> represents <code>false</code>, <code>-s -s -s</code> represents
  <code>true</code> and so on. A boolean option behaves like a
  <strong>switch</strong>. A valued option has an associated value by using
  either a space or an equal sign (symbol <code>=</code>). Here is a
  non-exhaustive list of potential syntaxes (we use a short option but it could
  be a long one):</p>
  <ul>
    <li><code>-x=value</code>: <code>value</code>,</li>
    <li><code>-x=va\ lue</code>: <code>va lue</code>,</li>
    <li><code>-x="va lue"</code>: <code>va lue</code>,</li>
    <li><code>-x="va l\"ue"</code>: <code>va l"ue</code>,</li>
    <li><code>-x value</code>: <code>value</code>,</li>
    <li><code>-x va\ lue</code>: <code>va lue</code>,</li>
    <li><code>-x "value"</code>: <code>value</code>,</li>
    <li><code>-x "va lue"</code>: <code>va lue</code>,</li>
    <li><code>-x va\ l"ue</code>: <code>va l"ue</code>,</li>
    <li><code>-x 'va "l"ue'</code>: <code>va "l"ue</code>,</li>
    <li>etc.</li>
  </ul>
  <p>The simple (symbol <code>'</code>) and double (symbol <code>"</code>)
  quotes are supported. But be aware that there is particular syntaxes which are
  still not <strong>standards</strong>:</p>
  <ul>
    <li><code>-x=-value</code>: <code>-value</code>,</li>
    <li><code>-x "-value"</code>: <code>-value</code>,</li>
    <li><code>-x \-value</code>: <code>-value</code>,</li>
    <li><code>-x -value</code>: is the equivalent of two booleans,
    <code>-x</code> and <code>-value,</code></li>
    <li><code>-x=-7</code>: <code>-7</code>,</li>
    <li>etc.</li>
  </ul>
  <p><em>A l'instar</em> of boolean options that behave like switches, the
  valued options <strong>rewrite</strong> their values if they are declared more
  than once. Thus, <code>-a=b -a=c</code> represents <code>c</code>.</p>
  <p>Finally, there is values that are considered as <strong>special</strong>.
  We distinguish two of them:</p>
  <ul>
    <li><strong>lists</strong>, with the help of a comma as a separator:
    <code>-x=a,b,c</code>,</li>
    <li><strong>intervalles</strong>, with the help of the <code>:</code> symbol
    (without spaces around it): <code>-x=1:7</code>.</li>
  </ul>
  <p>Without any specific manipulation, those values will not be considered as
  special. We will have to use the
  <code>Hoa\Console\Parser::parseSpecialValue</code> method as we will see
  bellow.</p>

  <h3 id="Read_options_and_inputs" for="main-toc">Read options and inputs</h3>

  <p>We know how to analyze options but this is not enough to read them
  correctly. We have to define a little <strong>semantics</strong>: what do
  their expect, what is their nature etc. We will use the
  <code>Hoa\Console\GetOption</code> class. An option is defined by:</p>
  <ul>
    <li>a <strong>long</strong> name,</li>
    <li>a <strong>short</strong> name,</li>
    <li>a <strong>type</strong>, given by one of the
    <code>Hoa\Console\GetOption</code> constants among:
      <ul>
        <li><code>NO_ARGUMENT</code> if the option is a boolean one,</li>
        <li><code>REQUIRED_ARGUMENT</code> if the option is a valued one,</li>
        <li><code>OPTIONAL_ARGUMENT</code> if the option can receive a
        value.</li>
      </ul>
    </li>
  </ul>
  <p>These three informations <strong>must</strong> be specified. They must be
  given to the constructor of <code>Hoa\Console\GetOption</code> as first
  argument. The second one is the option analyzer (the analysis must be
  <strong>already</strong> done). Thus, we describe two options:
  <code>extract</code> that is a boolean option and <code>directory</code> that
  is a valued option:</p>
  <pre><code class="language-php">$parser = new Hoa\Console\Parser();
$parser->parse('-x --directory=value inputA inputB inputC');

$options = new Hoa\Console\GetOption(
    [
        // long name                  type                  short name
        //   ↓                         ↓                         ↓
        ['extract',   Hoa\Console\GetOption::NO_ARGUMENT,       'x'],
        ['directory', Hoa\Console\GetOption::REQUIRED_ARGUMENT, 'd']
    ],
    $parser
);</code></pre>
  <p>We are now ready to read our options! The options reader behaves like an
  iterator, or like a <strong>pipette</strong> though, thanks to the
  <code>getOption</code> method. This method returns the short name of the
  option currently read and will assign the value of the option (a boolean or a
  string) to its first argument passed by reference. When the pipette is empty,
  the <code>getOption</code> method will return <code>false</code>. This
  structure might seem original but it is widely <strong>spread</strong>, you
  will not be lost when seeing it in other progams (examples
  <a href="http://kernel.org/doc/man-pages/online/pages/man3/getopt.3.html#EXAMPLE"
     title="getopt(3), Linux Programmer's Manual">in Linux</a>,
  <a href="http://freebsd.org/cgi/man.cgi?query=getopt&amp;sektion=3#EXAMPLES"
     title="getopt(3), FreeBSD Library Functions Manual">in FreeBSD</a> or
  <a href="http://developer.apple.com/library/Mac/#documentation/Darwin/Reference/ManPages/man3/getopt.3.html"
     title="getopt(3), BSD Library Functions Manual">in Mac OS X</a> —same code
     base—). The simplest way to read options are to define them default values
     and then to use <code>getOption</code>, thus:</p>
  <pre><code class="language-php">$extract   = false;
$directory = '.';

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

            break;

        case 'd':
            $directory = $v;

            break;
    }
}

var_dump($extract, $directory);

/**
 * Will output:
 *     bool(true)
 *     string(5) "value"
 */</code></pre>
  <p>We read it like this: “while we have an option to read, we get the short
  name in <code>$c</code> and its value in <code>$v</code>, then we see what to
  do”.</p>
  <p>To read inputs, we will use the <code>Hoa\Console\Parser::listInputs</code>
  whose all arguments (a total of 26) are passed by <strong>reference</strong>.
  Thus:</p>
  <pre><code class="language-php">$parser->listInputs($inputA, $inputB, $inputC);

var_dump($inputA, $inputB, $inputC);

/**
 * Will output:
 *     string(6) "inputA"
 *     string(6) "inputB"
 *     string(6) "inputC"
 */</code></pre>
  <p>Attention, this approach implies that the inputs are
  <strong>ordered</strong> (as usualy most of the time). But also, reading the
  inputs without having formely given the analyzer to
  <code>Hoa\Console\GetOption</code> can lead to unexpected results (because by
  default, all options are considered as booleans). If we would like all the
  inputs and analyze them manually if they are not ordered, we can use the
  <code>Hoa\Console\Parser::getInputs</code> method which will return all the
  inputs.</p>

  <h3 id="Special_or_ambiguous_options" for="main-toc">Special or ambiguous
  options</h3>

  <p>Back to our <code>Hoa\Console\Parser::parseSpecialValue</code> method. It
  takes two arguments: a value and an array of keywords. We re-use our example
  and modify the case of the <code>d</code> option:</p>
  <pre data-line="8-11"><code class="language-php">while (false !== $c = $options->getOption($v)) {
    switch($c) {
        case 'x':
            $extract = $v;

            break;

        case 'd':
            $directory = $parser->parseSpecialValue($v, ['HOME' => '/tmp']);

            break;
    }
}

print_r($directory);</code></pre>
  <p>If we try with <code>-d=a,b,HOME,c,d</code> then <code>-d</code> will have
  the following value:</p>
  <pre><code class="language-php">/**
 * Array
 * (
 *     [0] => a
 *     [1] => b
 *     [2] => /tmp
 *     [3] => c
 *     [4] => d
 * )
 */</code></pre>
  <p>Finally, when a read option does not exist but it is
  <strong>close</strong> to an existing option modulo some
  <strong>typos</strong> (for example <code>--dirzctory</code> instead of
  <code>--directory</code>), we can use the <code>__ambiguous</code> case to
  capture and compute it:</p>
  <pre data-line="13-16"><code class="language-php">while (false !== $c = $options->getOption($v)) {
    switch($c) {
        case 'x':
            $extract = $v;

            break;

        case 'd':
            $directory = $parser->parseSpecialValue($v, ['HOME' => '/tmp']);

            break;

        case '__ambiguous':
            print_r($v);

            break;
    }
}</code></pre>
  <p>The value (in <code>$v</code>) is an array with three entries. For example
  with <code>--dirzctory</code>, we have:</p>
  <pre><code class="language-php">/**
 * Array
 * (
 *     [solutions] => Array
 *         (
 *             [0] => directory
 *         )
 *
 *     [value] => y
 *     [option] => dirzctory
 * )
 */</code></pre>
  <p>The <code>solutions</code> key provides all the <strong>similar</strong>
  options, the <code>value</code> key gives the value of the option and
  <code>option</code> is the <strong>original</strong> read name. It is part to
  the user to decide what to do based on these informations. We can use the
  <code>Hoa\Console\GetOption::resolveOptionAmbiguity</code> method by giving it
  the array, and it will choose the best option if it exists:</p>
  <pre><code class="language-php">    case '__ambiguous':
        $options->resolveOptionAmbiguity($v);

        break;
</code></pre>
  <p>It is preferable to <strong>advise</strong> the user that an ambiguity
  happened and ask her a decision. Sometimes, it can be
  <strong>dangerous</strong> to make decision in her place.</p>

  <h3 id="Integrate_a_router_and_a_dispatcher" for="main-toc">Integrate a router
  and a dispatcher</h3>

  <p>So far, we coerced the options and the inputs to the analyzer.
  <code>Hoa\Router\Cli</code> allows to <strong>extract</strong> data from a
  command line program. One method interests us:
  <code>Hoa\Router\Cli::getURI</code> will give us all the options and inputs of
  the running program, that we will <strong>provide</strong> to our analyzer.
  Thus:</p>
  <pre data-line="2"><code class="language-php">$parser = new Hoa\Console\Parser();
$parser->parse(Hoa\Router\Cli::getURI());

// …</code></pre>
  <p>Now, it is possible to interprete the options that we will give to our
  program. If you have written the tests in a file named <code>Test.php</code>,
  then you will be able to write:</p>
  <pre><code class="language-shell">$ php Test.php -x -d=a,b,HOME,c,d inputA inputB
bool(true)
Array
(
    [0] => a
    [1] => b
    [2] => /tmp
    [3] => c
    [4] => d
)
string(6) "inputA"
string(6) "inputB"
NULL</code></pre>
  <p>The <code>-x</code> option is set to <code>true</code>, the <code>-d</code>
  option is an array (because we have analyzed it with the
  <code>Hoa\Console\Parser::parseSpecialValue</code> method), and we have
  <code>inputA</code>, <code>inputB</code> and <code>null</code> as inputs.</p>
  <p>This is a good start and we can stop here most of the time. But it is
  possible to go further by using a <strong>dispatcher</strong>: writing
  commands in several functions or classes and call them regarding the given
  options and inputs to our program. We recommend to read the source code of
  <a href="@central_resource:path=Library/Cli/Bin/Hoa.php"><code>hoa://Library/Cli/Bin/Hoa.php</code></a>
  to help yourself, along with the
  <a href="@hack:chapter=Router"><code>Hoa\Router</code></a> and
  <a href="@hack:chapter=Dispatcher"><code>Hoa\Dispatcher</code></a> chapters.
  We propose a quick example without giving too much details about those
  libraries.</p>
  <p>The idea is as follows. Thanks to <code>Hoa\Router\Cli</code> we are going
  to extract data of the following form: <code>$ php script.php
  <em>controller</em> <em>tail</em></code>, where
  <code><em>controller</em></code> will be the name of the controller (of a
  class) on which we will call the <code>main</code> action (it means the
  <code>main</code> method with its default parameters) and where
  <code><em>tail</em></code> represents the options and the inputs. The name of
  the controller is identified by the special <code>_call</code> variable (from
  <code>Hoa\Router\Cli</code>) and the options along with the inputs are
  identified by <code>_tail</code> (from <code>Hoa\Dispatcher\Kit</code>). The
  options and the inputs are not mandatory. Then, we will use
  <code>Hoa\Dispatcher\Basic</code> with the dedicated kit of terminals, namely
  <code>Hoa\Console\Dispatcher\Kit</code>.  The dispatcher will try to load the
  <code>Application\Controller\<em>controller</em></code> class by default, and
  the autoloader will load them from the
  <code>hoa://Application/Controller/<em>controller</em></code> directory. We
  will then set quickly where the application is located. Finally, the exit code
  of our program will be given by the value returned by our controller and
  action. If an error occurred, we will print it and force an exit code greater
  than zero. Thus:</p>
  <pre><code class="language-php">try {
    // Prepare the router.
    $router = new Hoa\Router\Cli();
    $router->get(
        'g',
        '(?&amp;lt;_call>\w+)(?:\s+(?&amp;lt;_tail>.+))?'
    );

    // Prepare the dispatcher.
    $dispatcher = new Hoa\Dispatcher\ClassMethod([
        'synchronous.call' => 'Application\Controller\(:call:U:)',
        'synchronous.able' => 'main'
    ]);
    $dispatcher->setKitName('Hoa\Console\Dispatcher\Kit');

    // Dispatch!
    exit($dispatcher->dispatch($router));
} catch (Hoa\Exception $e) {
    echo $e->raise(true);
    exit($e->getCode() + 1);
}</code></pre>
  <p>At the same level of our program, let's create the
  <code>Application/Controller/</code> directory with the <code>Foo.php</code>
  file inside, which will contain the following code:</p>
  <pre><code class="language-php">&amp;lt;?php

namespace Application\Controller;

class Foo extends \Hoa\Console\Dispatcher\Kit
{
    protected $options = [
        ['extract',   \Hoa\Console\GetOption::NO_ARGUMENT,       'x'],
        ['directory', \Hoa\Console\GetOption::REQUIRED_ARGUMENT, 'd'],
        ['help',      \Hoa\Console\GetOption::NO_ARGUMENT,       'h']
    ];

    public function MainAction()
    {
        $extract   = false;
        $directory = '.';

        while (false !== $c = $this->getOption($v)) {
            switch($c) {
              case 'x':
                  $extract = $v;

                  break;

              case 'd':
                  $directory = $this->parser->parseSpecialValue($v, ['HOME' => '/tmp']);

                  break;

              case 'h':
                  return $this->usage();
            }
        }

        echo 'extract:   ';
        var_dump($extract);
        echo 'directory: ';
        print_r($directory);

        return;
    }

    public function usage()
    {
        echo
            'Usage   : foo &amp;lt;options>', "\n",
            'Options :', "\n",
            $this->makeUsageOptionsList([
                'x' => 'Whether we need to extract.',
                'd' => 'Directory to extract.',
                'h' => 'This help.'
            ]);
    }
}</code></pre>
  <p>Our class extends our kit to benefit from the provided methods. Among other
  things, its own <code>getOption</code> method that will exploit the
  <code>$options</code> attribute where the options are declared,
  <code>makeUsageOptionsList</code> to print a usage, its own
  <code>resolveOptionAmbiguity</code> method that asks a confirmation from the
  user, the router access through the <code>$router</code> attribute etc. Kits
  offer <strong>services</strong> to the application, they
  <strong>aggregate</strong> services offered by the libraries. Now, let's
  test:</p>
  <pre><code class="language-shell">$ php Test.php foo -x -d=1:3
extract:   bool(true)
directory: Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)</code></pre>
  <p>Awesome!</p>
  <p>Let's note that the <code>hoa</code> script is exactly build like this. Do
  not hesitate to find inspiration from it.</p>

  <h2 id="Processus" for="main-toc">Processus</h2>

  <p>In our context, a <strong>processus</strong> is a classical program that
  is executed in a <strong>terminal</strong>. The interesting part is that such
  a program <strong>communicates</strong> with the rest of its
  <strong>environment</strong> thanks to <strong>pipes</strong>, numbered from
  zero. Some of them have even names:</p>
  <ul>
    <li><code>STDIN</code> (<code>0</code>) to read <strong>inputs</strong>
    (<em>standard input</em>),</li>
    <li><code>STDOUT</code> (<code>1</code>) to write <strong>outputs</strong>
    (<em>standard output</em>),</li>
    <li><code>STDERR</code> (<code>2</code>) to write <strong>errors</strong>
    (<em>standard error</em>).</li>
  </ul>
  <p>When a processus is executed in a terminal, <code>STDIN</code> will use the
  <strong>keyboard</strong> as the source of data, and <code>STDOUT</code> with
  <code>STDERR</code> are linked to the <strong>window</strong> of the terminal.
  But when a processus is executed in a <strong>sub-terminal</strong>, it means
  executed from another processus, <code>STDIN</code> is no longer linked to the
  keyboard, like <code>STDOUT</code> and <code>STDERR</code> are not linked to
  the screen. This is the parent processus that will read and write on these
  streams to <strong>interact</strong> with the “sub”-processus. This mechanism
  is called a <strong>redirection</strong> of stream, we use it very often when
  we write a command line (please, see the
  <a href="http://gnu.org/software/bash/manual/bashref.html#Redirections">section
  Redirections from the Bash Reference Manual</a>). What we are going to do use
  another syntax but the mechanism is exactly the same.</p>
  <p>It is very important to know that these streams are all
  <strong>asynchronous</strong> from each other. Not one of these streams will
  have an impact on another one, there is no link between them and that is very
  important for the rest of this section.</p>
  <p>From the PHP level, it is possible to access to these streams by using
  respectively the following URI: <code>php://stdin</code>,
  <code>php://stdout</code> and <code>php://stderr</code>. However, we also have
  the eponymous <code>STDIN</code>, <code>STDOUT</code> and <code>STDERR</code>
  constants. They are defined as follows (example with <code>STDIN</code>):</p>
  <pre><code class="language-php">define('STDIN', fopen('php://stdin', 'r'));</code></pre>
  <p>These streams are available if and only if the program is executed from a
  command line. Remind that pipes are identified by numbers. We are then able to
  use <code>php://fd/0</code> to represent <code>STDIN</code>,
  <code>php://fd/1</code> to represent <code>STDOUT</code> etc. The
  <code>php://fd/<em>i</em></code> URI allows to access the file with the
  <code><em>i</em></code> <strong>descriptor</strong>.</p>

  <h3 id="Very_basic_execution" for="main-toc">Very basic execution</h3>

  <p>The <code>Hoa\Console\Processus</code> class provides a very
  <strong>quick</strong> way to execute a processus and get the result of
  <code>STDOUT</code>. This is the most common case. Thus, we will use the
  <code>execute</code> static method:</p>
  <pre><code class="language-php">var_dump(Hoa\Console\Processus::execute('id -u -n'));

/**
 * Could output:
 *     string(3) "hoa"
 */</code></pre>
  <p>By default, the command will be escaped for security reasons. If you are
  confident in the command, you can desactivate the escaping by setting the
  second argument to <code>false</code>.</p>
  <p>We have no control on the pipes and even if it is suitable for the majority
  of cases, this is not enough when we would like a minimum of interaction with
  the processus.</p>

  <h3 id="Reading_and_writing" for="main-toc">Reading and writing</h3>

  <p>Let's see how to <strong>interact</strong> with a processus. We will
  consider the following <code>LittleProcessus.php</code> program:</p>
  <pre><code class="language-php">&amp;lt;?php

$range = range('a', 'z');

while (false !== $line = fgets(STDIN)) {
    echo '> ', $range[intval($line)], "\n";
}</code></pre>
  <p>To test and understand its behavior, let's write the following command line
  and hit <code>3</code> and <code>4</code> on the keyboard:</p>
  <pre><code class="language-shell">$ php LittleProcessus.php
3
> d
4
> e
</code></pre>
  <p>We can also write:</p>
  <pre><code class="language-shell">$ seq 0 4 | php LittleProcessus.php
> a
> b
> c
> d
> e</code></pre>
  <p>Our program will read each line on the standard input, considering it is a
  number and transforming it into a character that will be printed on the
  standard output. We would like to execute this program by giving it our own
  custom list of numbers (like the <code>seq</code> program does) and observe
  the produced result.</p>
  <p>An instance of the <code>Hoa\Console\Processus</code> class represents a
  <strong>processus</strong>. During the instanciation, we can set:</p>
  <ul>
    <li>the <strong>name</strong> of the processus,</li>
    <li>its <strong>options</strong>,</li>
    <li>the <strong>description</strong> of pipes.</li>
  </ul>
  <p>There is other arguments but we will see them further.</p>
  <p>The description of pipes has the form of an array where each key represents
  the number of the pipe (more generally, this is the <code><em>i</em></code>
  from <code>php://fd/<em>i</em></code>) and its value is also an array
  describing the nature of the pipe: either a “real” pipe, or a file with their
  reading or writing mode (among <code>r</code>, <code>w</code> or
  <code>a</code>). Let's illustrate with an example:</p>
  <pre><code class="language-php">$processus = new Hoa\Console\Processus(
    'php',
    ['LittleProcessus.php'],
    [
        // STDIN.
        0 => ['pipe', 'r'],
        // STDOUT.
        1 => ['file', '/tmp/output', 'a']
    ]
);</code></pre>
  <p>In this case, <code>STDIN</code> is a pipe and <code>STDOUT</code> is the
  <code>/tmp/output</code> file. If we do not set a descriptor, it will be
  equivalent to write:</p>
  <pre><code class="language-php">$processus = new Hoa\Console\Processus(
    'php',
    ['LittleProcessus.php'],
    [
        // STDIN.
        0 => ['pipe', 'r'],
        // STDOUT.
        1 => ['pipe', 'w'],
        // STDERR.
        2 => ['pipe', 'w']
    ]
);</code></pre>
  <p>Each pipe is identified as a stream and can be manipulated as such. When a
  pipe is in <strong>reading</strong> (with the <code>r</code> mode), it means
  that the processus will <strong>read</strong> from it. So we, the parent
  processus, will <strong>write</strong> on this pipe. Let's take the example of
  <code>STDIN</code>: the processus reads from <code>STDIN</code> what the
  keyboard has written on it. And conversely, when a pipe is in
  <strong>writing</strong> (with the <code>w</code> mode), it means that we will
  <strong>read</strong> from it. Let's take the example of <code>STDOUT</code>:
  the screen will read what the processus has written to it.</p>
  <p>The <code>Hoa\Console\Processus</code> class extends the
  <a href="@hack:chapter=Stream"><code>Hoa\Stream</code></a> class, and
  consequently, we have all the necessary tools to read and write on the pipe of
  our choice. This class also provides several <strong>listeners</strong>:</p>
  <ul>
    <li><code>start</code>, when the processus is started,</li>
    <li><code>stop</code>, when the processus is stopped,</li>
    <li><code>input</code>, when the reading streams are ready,</li>
    <li><code>output</code>, when the writing streams are ready,</li>
    <li><code>timeout</code>, when the processus is executing too much
    time.</li>
  </ul>
  <p>Let's take directly an example. We will execute the <code>php
  LittleProcessus.php</code> processus and attach functions to the following
  listeners: <code>input</code> to write a sequence of numbers and
  <code>output</code> to read the result.</p>
  <pre><code class="language-php">$processus = new Hoa\Console\Processus('php LittleProcessus.php');
$processus->on('input', function ($bucket) {
    $source = $bucket->getSource();
    $data   = $bucket->getData();

    echo 'INPUT (', $data['pipe'], ')', "\n";

    $source->writeAll(
        implode("\n", range($i = mt_rand(0, 21), $i + 4)) . "\n"
    );

    return false;
});
$processus->on('output', function ($bucket) {
    $data = $bucket->getData();

    echo 'OUTPUT (', $data['pipe'], ') ', $data['line'], "\n";

    return;
});
$processus->run();

/**
 * Could output:
 *     INPUT (0)
 *     OUTPUT (1) > s
 *     OUTPUT (1) > t
 *     OUTPUT (1) > u
 *     OUTPUT (1) > v
 *     OUTPUT (1) > w
 */</code></pre>
  <p>Now, let's see the details to understand well.</p>
  <p>When a <strong>reading</strong> stream is <strong>ready</strong>, the
  <code>input</code> listener will be fired. Only one data is sent:
  <code>pipe</code>, that contains the number of the pipe (the
  <code><em>i</em></code> of <code>php://fd/<em>i</em></code>). When a
  <strong>writing</strong> stream is ready, the <code>output</code> listener is
  fired. Two data are sent: <code>pipe</code> (like <code>input</code>) and
  <code>line</code> that contains the <strong>received line</strong>.</p>
  <p>We see in the function attached to the <code>input</code> listener that we
  write a sequence of numbers concatenated by <code>\n</code> (one number per
  line). In order to achieve this, we use the <code>writeAll</code> method. By
  default, the writing methods write on the <code>0</code> pipe. To change this
  behavior, we will have to set the number of the pipe as the second argument of
  the writing methods. Same for the reading methods but the default pipe is
  <code>1</code>.</p>
  <p>When the callable attached to a listener returns <code>false</code>, the
  pipe that has fired this call will be <strong>closed</strong> just after. In
  our case, the function attached to <code>input</code> returns
  <code>false</code> just after having written the data, we no longer need this
  pipe. It is important for <strong>performance</strong> reasons to close pipes
  as soon as possible.</p>
  <p>Finally, to <strong>execute</strong> the processus, we use the
  <code>Hoa\Console\Processus::run</code> method with a null arity.</p>
  <p>In our example, we write all data at once but we can send them as soon as
  they are ready, which is more efficient because the processus does no wait a
  big bucket of data and can compute them gradually. Let's modify our example to
  write a data each time <code>STDIN</code> is ready:</p>
  <pre><code class="language-php">$processus->on('input', function ($bucket) {
    static $i = null;
    static $j = 5;

    if (null === $i) {
        $i = mt_rand(0, 20);
    }

    $data = $bucket->getData();

    echo 'INPUT (', $data['pipe'],')', "\n";

    $source = $bucket->getSource();
    $source->writeLine($i++);
    usleep(50000);

    if (0 >= $j--) {
        return false;
    }

    return;
});</code></pre>
  <p>We initialize two variables: <code class="language-php">$i</code> and
  <code class="language-php">$j</code>, that hold the number to send and the
  maximum number of data to send. We introduce a voluntary latency with
  <code class="language-php">usleep(50000)</code> in order that
  <code>STDOUT</code> to be ready, only to illustrate our example. In this case,
  the output would be:</p>
  <pre><code class="language-php">/** Could output:
 *     INPUT (0)
 *     OUTPUT (1) > h
 *     INPUT (0)
 *     OUTPUT (1) > i
 *     INPUT (0)
 *     OUTPUT (1) > j
 *     INPUT (0)
 *     OUTPUT (1) > k
 *     INPUT (0)
 *     OUTPUT (1) > l
 *     INPUT (0)
 *     OUTPUT (1) > m
 */</code></pre>
  <p>The processus is waiting an input and read data when they are received.
  Once we have sent all the data, we close the pipe.</p>
  <p>The processus will close itself. We have the
  <code>Hoa\Console\Processus::getExitCode</code> method to know the exit
  <strong>code</strong> of the processus. Attention, a <code>0</code> code
  represents a success. Because it is a common error, there is the
  <code>Hoa\Console\Processus::isSuccessful</code> method to know if the
  processus has been executed with success or not.</p>

  <h3 id="Detect_the_type_of_pipes" for="main-toc">Detect the type of pipes</h3>

  <p>Sometimes, it is useful to know the <strong>type</strong> of pipes, it
  means if it is a <strong>direct</strong> (regular) use, a
  <strong>pipe</strong> or a <strong>redirection</strong>. We will make use of
  the <code>Hoa\Console\Console</code> class and its <code>isDirect</code>,
  <code>isPipe</code> and <code>isRedirection</code> static methods to get these
  informations.</p>
  <p>Let's take an example to understand. Let's write the <code>Type.php</code>
  file that will study the type of <code>STDOUT</code>:</p>
  <pre><code class="language-php">echo 'is direct:      ';
var_dump(Hoa\Console\Console::isDirect(STDOUT));

echo 'is pipe:        ';
var_dump(Hoa\Console\Console::isPipe(STDOUT));

echo 'is redirection: ';
var_dump(Hoa\Console\Console::isRedirection(STDOUT));</code></pre>
  <p>And now, let's execute this file to see the result:</p>
  <pre><code class="language-shell">$ php Type.php
is direct:      bool(true)
is pipe:        bool(false)
is redirection: bool(false)

$ php Type.php | xargs -I@ echo @
is direct:      bool(false)
is pipe:        bool(true)
is redirection: bool(false)

$ php Type.php > /tmp/foo; cat /tmp/foo
is direct:      bool(false)
is pipe:        bool(false)
is redirection: bool(true)</code></pre>
  <p>In the first case, <code>STDOUT</code> is <strong>direct</strong> (for
  <code>STDOUT</code>, it means that it is <strong>linked</strong> to the
  screen, for <code>STDIN</code>, it will be linked to the keyboard etc.). In
  the second case, <code>STDOUT</code> is a <strong>pipe</strong>, it means that
  it is <strong>attached</strong> to the <code>STDIN</code> of the command
  written after the <code>|</code> symbol. In the last case, <code>STDOUT</code>
  is a <strong>redirection</strong>, it means that it is
  <strong>redirected</strong> in the <code>/tmp/foo</code> file (that we print
  just after). The operation can be done on <code>STDIN</code>,
  <code>STDERR</code> or any other resource.</p>
  <p>Knowing the type of pipes can allow different behaviors according to the
  <strong>context</strong>. For example,
  <code>Hoa\Console\Readline\Readline</code> reads on <code>STDIN</code>. If its
  type is a pipe or a redirection, the advanced edition mode of the line will be
  disabled and it will return <code>false</code> when there will be no more
  things to read. Another example, the commands verbosity of the
  <code>hoa</code> script uses the type of <code>STDOUT</code> as the default
  value: direct to be verbose, else not verbose. Try the following examples to
  see the difference:</p>
  <pre><code class="language-shell">$ hoa --no-verbose
$ hoa | xargs -I@ echo @</code></pre>
  <p>Examples are numerous but be careful to use this feature with precautions.
  We have to adapt the behaviors but keep them <strong>consistent</strong>.</p>

  <h3 id="Execution_conditions" for="main-toc">Execution conditions</h3>

  <p>The processus is executed in a particular <strong>directory</strong> and a
  particular <strong>environment</strong>. This directory is called the current
  working directory, often abbreviated <abbr lang="en">cwd</abbr>. It defines
  the directory where the processus will be executed. We can find it in PHP with
  <a href="http://php.net/getcwd">the <code>getcwd</code> function</a>. The
  environment is defined by an array, which can be retrieved for example by
  executing <code>/usr/bin/env</code>. For example, the <code>PATH</code> is
  defined in this environment. These data are given as fourth and fifth
  arguments of the <code>Hoa\Console\Processus</code> constructor. Thus:</p>
  <pre><code class="language-php">$processus = new Hoa\Console\Processus(
    'php',
    null, /* no option         */
    null, /* use default pipes */
    '/tmp',
    [
        'FOO'  => 'bar',
        'BAZ'  => 'qux',
        'PATH' => '/usr/bin:/bin'
    ]
);
$processus->on('input', function (Hoa\Event\Bucket $bucket) {
    $bucket->getSource()->writeAll(
        '&amp;lt;?php' . "\n" .
        'var_dump(getcwd());' . "\n" .
        'print_r($_ENV);'
    );

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

    return;
});
$processus->run();

/**
 * Will output:
 *     > string(12) "/tmp"
 *     > Array
 *     > (
 *     >     [FOO] => bar
 *     >     [PATH] => /usr/bin:/bin
 *     >     [PWD] => /tmp
 *     >     [BAZ] => qux
 *     >     [_] => /usr/bin/php
 *     >
 *     > )
 */</code></pre>
  <p>If the current working directory is not defined, we will use the one of the
  program. If the environment is not defined, the processus will use the one of
  its parent.</p>
  <p>We are also able to set a <strong>maximum time</strong> in seconds in order
  to get a <strong>response</strong> from the processus (defined to 30 seconds
  by default). This is the last argument of the constructor. We can use the
  <code>Hoa\Console\Processus::setTimeout</code> method. To know when this time
  is reached, we must use the <code>timeout</code> listener. No action will be
  done automatically. We can for example terminate the processus thanks to the
  <code>Hoa\Console\Processus::terminate</code> method. Thus:</p>
  <pre><code class="language-php">$processus = new Hoa\Console\Processus('php');

// 3 seconds is enough…
$processus->setTimeout(3);

// Sleep 10 seconds.
$processus->on('input', function (Hoa\Event\Bucket $bucket) {
    $bucket->getSource()->writeAll('&amp;lt;?php sleep(10);');

    return false;
});

// Terminate the processus on timeout.
$processus->on('timeout', function (Hoa\Event\Bucket $bucket) {
    echo 'TIMEOUT, terminate', "\n";
    $bucket->getSource()->terminate();

    return;
});

$processus->run();

/**
 * Will output (after 3 secondes):
 *     TIMEOUT, terminate
 */</code></pre>
  <p>No action is done automatically because they can be numerous. Maybe we can
  unblock the processus, or close it to open other ones, emit some logs etc.</p>
  <p>About the <code>terminate</code> method, it can take several different
  values, defined by the constants of <code>Hoa\Console\Processus</code>:
  <code>SIGHUP</code>, <code>SIGINT</code>, <code>SIGQUIT</code>,
  <code>SIGABRT</code>, <code>SIGKILL</code>, <code>SIGALRM</code> and
  <code>SIGTERM</code> (by default). Several <strong>signals</strong> can be
  send to the processus in order to stop them. To get the detail, please, see
  <a href="http://freebsd.org/cgi/man.cgi?query=signal"
     title="signal(3), FreeBSD Library Functions Manual">the
     <code>signal</code></a> page.</p>

  <h3 id="Miscellaneous" for="main-toc">Miscellaneous</h3>

  <p>The <code>getTitle</code> and <code>setTitle</code> static methods on the
  <code>Hoa\Console\Processus</code> class respectively allow to get and set the
  title of the processus. Thus:</p>
  <pre><code class="language-php">Hoa\Console\Processus::setTitle('hoa #1');</code></pre>
  <p>And in another terminal:</p>
  <pre data-line="2"><code class="language-shell">$ ps | grep hoa
69578 ttys006    0:00.01 hoa #1
70874 ttys008    0:00.00 grep hoa</code></pre>
  <p>These methods are really useful when we manipulate a lot of processus and
  we would like to identify them efficiently (for example with tools like
  <code>top</code> or <code>ps</code>). Note that they are working only if you
  have at least PHP5.5.</p>
  <p>Another interesting static method is
  <code>Hoa\Console\Processus::locate</code> that allows to determine the path
  to a given program. For example:</p>
  <pre><code class="language-php">var_dump(Hoa\Console\Processus::locate('php'));

/**
 * Could output:
 *     string(12) "/usr/bin/php"
 */</code></pre>
  <p>In the case where the program is not found, <code>null</code> will be
  returned. This method is based on the <code>PATH</code> of your system.</p>

  <h3 id="Interactive_processus_and_pseudo-terminals" for="main-toc">Interactive
  processus and pseudo-terminals</h3>

  <p>This section is a little bit technical but it explains a
  <strong>problem</strong> that can be met with some processus called
  <strong>interactive</strong>.</p>
  <p>The <code>Hoa\Console\Processus</code> class allows to automate the
  interaction with processus very easily. However, it is not always possible to
  create such an automation because of the behavior of the processus. We will
  illustrate the problem by writing the <code>Interactive.php</code> file:</p>
  <pre><code class="language-php">&amp;lt;?php

echo 'Login: ';

if (false === $login = fgets(STDIN)) {
    fwrite(STDERR, 'Hmm, no login.' . "\n");
    exit(1);
}

echo 'Password: ';

if (false === $password = fgets(STDIN)) {
    fwrite(STDERR, 'Hmm, no password.' . "\n");
    exit(2);
}

echo 'Result:', "\n\t", $login, "\t", $password;</code></pre>
  <p>Let's execute this processus to see what it does:</p>
  <pre><code class="language-shell">$ php Interactive.php
Login: myLogin
Password: myPassword
Result:
    myLogin
    myPassword</code></pre>
  <p>And now, let's automate the execution of this processus:</p>
  <pre><code class="language-shell">$ echo 'myLogin\nmyPassword' > data
$ php Interactive.php &amp;lt; data
Login: Password: Result:
    myLogin
    myPassword</code></pre>
  <p>Excellent. We could easily get the same result with
  <code>Hoa\Console\Processus</code>. Now, if our processus want to ensure that
  <code>STDIN</code> is empty between two inputs, it can add:</p>
  <pre data-line-offset="7" data-line="10"><code class="language-php">}

fseek(STDIN, 0, SEEK_END);

echo 'Password: ';</code></pre>
  <p>And then in this case, if we try to automate the execution:</p>
  <pre><code class="language-shell">$ php Interactive.php &amp;lt; data
Login: Password: Hmm, no password.</code></pre>
  <p>This is absolutely a normal behavior, but
  <code>Hoa\Console\Processus</code> can do nothing to solve this issue.</p>
  <p>The solution would be to use a
  <a href="https://en.wikipedia.org/wiki/Pseudo_terminal">pseudo-terminal</a> by
  using the PTY functions (please, see
  <a href="http://kernel.org/doc/man-pages/online/pages/man7/pty.7.html"
     title="pty(7), Linux Programmer's Manual">in Linux</a> or
  <a href="http://freebsd.org/cgi/man.cgi?query=pty"
     title="pty(3), FreeBSD Library Functions Manual" >in FreeBSD</a>).
  Unfortunately these functions are not available in PHP for technical reasons.
  There is no possible solutions in pure PHP, but it is still conceivable to use
  an <strong>external</strong> program, written in C for example.</p>

  <h2 id="Conclusion" for="main-toc">Conclusion</h2>

  <p>The <code>Hoa\Console</code> library provides
  <strong>comprehensive</strong> tools to write programs tailored to a
  <strong>textual</strong> interface, whether it be for interaction with the
  window or the cursor, the interaction with the user thanks to a very
  customizable readline (with autocompletion and shortcuts), the options reading
  for programs themselves, the construction of elaborated programs, or even the
  execution, interaction and communication with processus.</p>

</yield>
</overlay>

© 2018.