ConsoleTools/docs/tutorial.txt

eZ Components - ConsoleTools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

Introduction
============

The ConsoleTools component provides several useful tools to build
applications that run on a computer console (sometimes also called shell or
command line). For example, eZ Publish includes several shell
scripts that perform tasks like clearing caches.

.. note::
   From version 1.5.2 on, all necessary string operations in ConsoleTools are
   performed using `ext/iconv`__. This makes the component binary safe and
   allows you to use arbitrary unicode characters in your texts. Please make
   sure to convert your text to UTF-8 before submitting it to a method in
   ConsoleTools, if you use a different, non ASCII-compatible encoding.

.. __: http://php.net/iconv

Class overview
==============

The ConsoleTools component offers several (mostly independent) classes to 
perform different tasks. The main classes are:

ezcConsoleOutput
  ezcConsoleOutput is responsible for printing text to the console. It allows 
  you to print text in different colors with different background colors.
  It can also apply other styling information to the text, making
  it bold or underlined for example. It can automatically wrap text
  after a certain number of characters are printed (keeping words
  intact) and handle output of different verbosity levels. ATTENTION: Windows
  does not support the styling of text.

ezcConsoleInput
  Using this little tool, you can handle the options and arguments provided to
  your shell application. It is capable of handling and validating three types of
  option datatypes (string, int and none) and can handle optional and mandatory
  options as well as rules to define relations between them. Rules can include
  dependencies and exclusions between options.

ezcConsoleProgressbar
  Most often you will use a console application in favor of a web application
  when it comes to processing time-consuming tasks. To indicate the
  current progress of a task, a kind of "status 
  indicator" will be used, which is most commonly a progress bar. 
  ezcConsoleProgressbar gives you an easy-to-use interface to display this. 
  It will keep track of re-drawing the bar as needed, showing current 
  and maximum values, as well as percentage completion. It is 
  fully configurable regarding its visual appearance.

ezcConsoleStatusbar
  ezcConsoleStatusbar is the "little brother" of ezcConsoleProgressbar. It
  also allows you to display the progress of a time-consuming action, but does
  not use a fixed bar-like appearance. Instead, it indicates successful
  and failed operations by displaying specific characters and keeps a
  count of successes and failures. This allows you to indicate
  the progress of a process where you don't initially know the number of
  actions to be performed.

ezcConsoleProgressMonitor
  Sometimes you need to display the progress of several actions and don't want
  to use a progress bar to do so. In this case you need the status indicator.
  It allows you to display a status entry for each action and generates the
  percentage completion of the current step.

ezcConsoleTable
  This class lets you easily create tables to be displayed on the
  console. It has a very convenient interface to create a table and manage the
  data it contains. It is highly configurable regarding the table's appearance
  (for example, different color and style information for content
  and borders on a per-cell basis, character selection for borders, variable
  width of the table and so on). ezcConsoleTable will also take care of measuring the 
  best width for table columns (to make your content fit best), automatically
  wrapping content and aligning the content in the cells as indicated.

ezcConsoleDialog
  This interface provides a common API for user interaction elements. A console
  dialog can request information from a user and react on this information
  interactively. For you as a user of ezcConsoleDialog, a dialog is displayed
  to the user and returns a result value to you, which was provided by the user
  of your application in some way. Currently 2 implementations of
  ezcConsoleDialog exist: ezcConsoleQuestionDialog is a dialog for asking a
  simply question and retrieving the answer from the user of an application.
  Instances of the  ezcConsoleMenuDialog class display a menu to the user and
  retrieves his choice of a menu item.

Usage
=====

Printing text to the console
----------------------------

As mentioned, the class ezcConsoleOutput is used to print text to the console.
Let's look at a basic example:

.. include:: tutorial_example_01_output_basic.php
   :literal:

The ezcConsoleOutput object is simply instantiated. You can optionally submit
options and predefined formatting options to its constructor, but this can also 
be done later.

In line 7, you can see how format is defined. Formats are created on the fly,
as soon as you access them (for reading or writing) through the $output->formats
attribute. There, we create a format called "info" and assign the color value
"blue" to it. This will make all text printed with this format blue. In line 9,
you can see how the format is applied to some text at printing time.

The second example shows some more advanced code:

.. include:: tutorial_example_02_output_advanced.php
   :literal:

In this example, two more formats are defined: "error" and "fatal". These formats 
have an additional style attribute set, which makes them both appear bold. The
"fatal" format will also underline the text and give it a black background
color.

The difference between ezcConsoleOutput->outputText() and
ezcConsoleOutput->outputLine() is that the latter automatically adds a
newline value to your text. The newline sequence used here is adjusted based on
the operating system. The use of ezcConsoleOutput->outputLine() is recommended
over the direct output of, for example, "\n".

If you leave the second parameter of ezcConsoleOutput::outputText() and
ezcConsoleOutput::outputLine() out, the "default" format is used. The default
is set to your console's default setting, but you can also change this as
for any other format you define. A third variant to format text is
ezcConsoleOutput->formatText(), which returns the formatted string instead of
printing it.

This example shows some of the options ezcConsoleOutput supports:

.. include:: tutorial_example_03_output_options.php
   :literal:

autobreak
  Will wrap lines automatically after the set amount of characters, keeping
  word boundaries intact.

verbosityLevel
  Allows you to specify a third parameter to ezcConsoleOutput->outputLine() and
  ezcConsoleOutput->outputText() to indicate a verbosity level for when the text
  should be printed. By setting the "verbosityLevel" option for
  ezcConsoleOutput, you define which texts will and will not be printed.

In our example, the call on line 23 would not print out text with the
"verbosityLevel" option set to 3, but the call on line 25 would.

The last example shows how to change the target of a format, which allows you
to print text e.g. to STDERR.

.. include:: tutorial_example_output_targets.php
   :literal:

The error message 'Unable to connect to database' will be printed in bold, with
a red foreground color to STDOUT. The default target is
ezcConsoleOutput::TARGET_OUTPUT, which prints to STDOUT and has standar output
buffering in place. If you want to switch out the standard output bufferung,
use ezcConsoleOutput::TARGET_STDOUT.

Although this feature was originally not designed for that purpose, you can
also use any other arbitrary PHP stream definition as a target. For example
'file:///var/log/my.log' to get the messages redirected to a log file instead
of displaying them.

Mastering options and arguments
-------------------------------

Below is a simple example for ezcConsoleInput:

.. include:: tutorial_example_04_input_basic.php
   :literal:
   
After instantiating a new ezcConsoleInput object to handle the options, an
option is registered on lines 7-12. This option will be available as "-h" and
"--help". The ezcConsoleInput->process() call makes ezcConsoleInput respond to the
options submitted by the user. If any error occurs with the submitted user
data, the method will throw an exception of type ezcConsoleOptionException. By
default, all options are registered with the value type
ezcConsoleInput::TYPE_NONE, which indicates that they don't expect a value
from the user. If a value is submitted anyway, ezcConsoleInput->process() will
throw a ezcConsoleOptionTypeViolationException. 

On line 23, a check is performed to see whether an option was submitted. If an option was not 
submitted, its $value property will contain bool *false*. Depending on the $type
set, it can contain different value types if it was submitted. If you use the 
(not shown here) ezcConsoleOption->$multiple property, the value will be an array 
containing the specified value types.

The next example is more advanced:

.. include:: tutorial_example_05_input_advanced.php
   :literal:

Two options are registered here: "-i" / "--input" and "-o" / "--output". For the
first one, additional properties for the ezcConsoleOption object are submitted
through the constructor. For the second ezcConsoleOption object, you see how to
provide additional properties after construction. We change the type of both
options to expect a string value from the user (lines 13 and 20).

In lines 25 and 28 we make both parameters depend on each other. If one of them
is submitted without the other, ezcConsoleInput->process() will throw an
ezcConsoleOptionDependencyViolationException. Aside from dependency rules, you can
also define exclusion rules using ezcConsoleOption->addExclusion().

On line 43, the method ezcConsoleInput->getSynopsis() is used to retrieve a
synopsis string for the program. The synopsis for our example would look like
this: ::

  $ ./tutorial_example_05_input_advanced.php [-h] [-i <string> [-o <string>] ]  [[--] <args>] 

The synopsis will indicate the option value types, whether they are optional, the
inter-option dependencies and default values (if set). On line 46, the property 
ezcConsoleOption->$shorthelp is accessed, where you can store some short help
information. It has a reasonable default value set.

On line 49, the submission of the "-o" option is checked. Because this has a
dependency on the "-i" option, a check for that is not necessary. Line 52
shows how you can access the arguments submitted to the program.
ezcConsoleInput->getArguments() always returns an array (which is empty if no
arguments are submitted). A more advanced way of handling arguments is
explained further below.

Here is an example of how the defined program would be called: ::

  $ ./tutorial_example_05_input_advanced.php -i /var/www -o /tmp foo bar 

The program would respond by printing the following: ::

  Input: /var/www, Output: /tmp
  Arguments: foo, bar

As you can see, this example does not define, which arguments are expected and
therefore, the program simply accepts any number of arguments and provides them
through the ezcConsoleInput->getArguments() method. The following example
shows, how specific arguments can be defined:

.. include:: tutorial_example_12_input_arguments.php
   :literal:

As seen before, a help option is registered. In addition, 3 arguments are
registered: The first one with the name "source" is a standard argument. It is
mandatory for the user to submit a value here. The second argument,
"destination" is optional and a default value is assigned, which will be used,
if the user does not provide a value for it.

The third one ("iterations") is not of type string, but an integer. Because the
second argument is optional, this third one is automatically optional, too.
Since no default value is assigned, it will be null, if the user does not
submit it. If a value is provided, it must be an integer.

Argument definitions are processed as usual inside the
ezcConsoleInput->process() method, but will throw an
ezcConsoleArgumentException if something goes wrong. If desired, exceptions
about options and arguments can be caught together using ezcConsoleException or
be handled on their own.

The value of an argument can be fetched from its definition, using its value
property. As can be seen at the very end of the example, for reading purpose,
arguments can be accessed by their name. This does not work for writing
purpose, since a specific order must be given there.

If the --help option is set, mandatory arguments don't need to be submitted and
are silently ignored. The help text generated by ezcConsoleInput for this
example looks like this: ::
    
    Usage: $ tutorial_example_12_input_arguments.php [-h] [--] <string:source> [<string:destination>] [<int:iterations>]
    A simple text program

    -h / --help           No help available.
    Arguments:            
    <string:source>       The source directory.
    <string:destination>  No help available.
    <int:iterations>      Number of iterations.


For further information, please refer to the API documentation of
ezcConsoleInput.

Progress indication
-------------------

This example defines a simple progress bar:

.. include:: tutorial_example_06_progressbar_basic.php
   :literal:

The created progressbar will count to a maximum value of 15, submitted to 
ezcConsoleProgressbar->__construct() in line 7. ezcConsoleProgressbar utilizes
ezcConsoleOutput to print the generated progress bar. The call to
ezcConsoleProgressbar->advance() pushes the progress bar one step further on each
call and redraws it (line 11). Calling ezcConsoleProgressbar->finish() will set
the progress bar to 100% immediately.

The progress bar generated by the example will look like this:

.. image:: img/consoletools_tutorial_example_06.png

The next example performs more customization on the progress bar appearance:

.. include:: tutorial_example_07_progressbar_advanced.php
   :literal:

The defined options array demonstrates only a small subset of options. For
detailed information, see the API documentation on
ezcConsoleProgressbarOptions. The "emptyChar" value defines the character to
prefill the bar, the "barChar" option defines the character to fill the bar
with when calling ezcConsoleProgressbar->advance().
Using the "formatString" option, you define the appearance of the whole bar.
Here the substitution of several placeholders (like "%fraction%" and "%bar%")
is permitted. "formatString" must contain the "%bar%" placeholder, while all
other values are optional. Any other printable character is permitted.
Formatting options are allowed in the "formatString" option, but
not in any other option. "redrawFrequency" defines how often the
progressbar will be redrawn. In the example this will be every 50th call to
ezcConsoleProgressbar->advance().

The resulting progress bar looks like this:

.. image:: img/consoletools_tutorial_example_07.png

With ezcConsoleStatusbar, you can indicate the progress of a time-consuming
action in a simpler way. Here is an example:

.. include:: tutorial_example_08_statusbar.php
   :literal:

This variant of indicating progress only displays success or failure indicators
for an action and allows you to run any number of actions, without specifying
in advance how many you will perform. The "successChar" and "failureChar" options
indicate which string to print on a successful or failed action. Lines 11 and
12 format these strings.

Indicating a status is done using ezcConsoleStatusbar->add(), which expects
*true* for a succeeded action and *false* for a failed one (line 20). You can 
access the number of successes and failures through
ezcConsoleStatusbar->getSuccessCount() and
ezcConsoleStatusbar->getFailureCount(). To make ezcConsoleStatusbar
wrap a line after a certain amount of statuses, you can use 
ezcConsoleOutput->$autobreak.

Here the result of the example:

.. image:: img/consoletools_tutorial_example_08.png

Finally, ezcConsoleProgressMonitor can indicate progress, but does not use a
bar-like interface. It simply prints status information about each action you
perform and shows the current progress as a percentage value in relation to the
number of actions you plan to perform overall.

.. include:: tutorial_example_11_progressmonitor.php
   :literal:

Line 7 creates a new status indicator, which will iterate over 7 actions.
Inside the while loop, we simulate some actions. The
call to $status->addEntry() adds a status entry and causes the indicator to
print the entry. Every entry consists of a tag (first parameter) and a message.

The result of the example is as follows:

::

    14.3% ACTION Performed action #1.
    28.6% ACTION Performed action #2.
    42.9% ACTION Performed action #3.
    57.1% ACTION Performed action #4.
    71.4% ACTION Performed action #5.
    85.7% ACTION Performed action #6.
   100.0% ACTION Performed action #7.

More information on these classes can be found in the API documentation of 
ezcConsoleProgressbar, ezcConsoleStatusbar and ezcConsoleProgressMonitor.

Large data served in a table
----------------------------

This is the result of a table generated by ezcConsoleTable:

.. image:: img/consoletools_tutorial_example_09.png

Here is its corresponding source code:

.. include:: tutorial_example_09_table_basic.php
   :literal:

ezcConsoleTable (like ezcConsoleStatusbar and ezcConsoleProgressbar) uses the
ezcConsoleOutput class to print to the console. To create a table, you just
need to submit the maximum width of the table to its constructor:
ezcConsoleTable->__construct(). Options for table formatting are inherited
from the table itself to the table rows and from there to the table cells.
On each inheritance level, options can be overridden individually. The
"defaultBorderFormat" option sets the global format value for all borders (line
24). This is overridden in line 26 for the first row of the table.

Table rows are accessed like an array in PHP (this is achieved by
implementing the ArrayAccess_ interface from SPL_).
ezcConsoleTable implements the Iterator interface (SPL_, too) to allow
iteration over table rows using foreach. Each table row is represented by an
object of type ezcConsoleTableRow, which also implements the ArrayAccess_ and
Iterator interfaces to access cells contained in the rows in the same way. Each
of the named classes allows the access of its properties as usual, in addition
to access to its contained objects through the array interface.

ezcConsoleTableRow and ezcConsoleTableCell have a $format setting to define the
format of the contained text. All cells (as described above) will inherit the
setting of their parent ezcConsoleTableRow, as long as this has not been
explicitly overridden. The same applies to ezcConsoleTableRow->$align and
ezcConsoleTableCell->$align. Possible align values are:

- ezcConsoleTable::ALIGN_DEFAULT (inherit from parent)
- ezcConsoleTable::ALIGN_LEFT
- ezcConsoleTable::ALIGN_RIGHT
- ezcConsoleTable::ALIGN_CENTER

The content of a cell is stored in the ezcConsoleTableCell->$content property
(line 34). The usage of formatted text in a cell is possible, but not recommended. 
If you want to define the format of cell content, use the 
ezcConsoleTableCell->$format property.

.. _SPL:         http://php.net/spl
.. _ArrayAccess: http://www.php.net/~helly/php/ext/spl/interfaceArrayAccess.html

Below is a more advanced (but in a way useless) example to show the handling of
tables:

.. include:: tutorial_example_10_table_advanced.php
   :literal:

The "corner", "lineHorizontal" and "lineVertical" options define which
characters to use for the borders of the table. These options must be
exactly one character long and cannot contain formatting information. To style the
borders, use the ezcConsoleTable->$defaultBorderFormat and
ezcConsoleTableRow->$borderFormat properties. 

The random format and alignment options selected above create the following
table:

.. image:: img/consoletools_tutorial_example_10.png

More information on the handling of tables on the shell can be found in the API
documentation of ezcConsoleTable, ezcConsoleTableRow and ezcConsoleTableCell.

Interacting with the user
-------------------------

Implementations of the interface ezcConsoleDialog are generic building blocks,
which allow to interact with the user of a shell application using STDIN. A
dialog is initialized, displayed and will return a value provided by the user.
What exactly happens inside a specific dialog may vary. Commonly, the dialog
validates and possibly manipulates the provided value before returning it.

The most basic dialog is the ezcConsoleQuestionDialog, which prints out some
text and retrieves a single value back.

.. include:: tutorial_example_13_dialog_question.php
   :literal:

Every dialog expects an instance of ezcConsoleOutput which is used to display
it. The question dialog here will display the text "Do you want to proceed?"
and expects an answer from the user. The $showResults option indicates, that
the possible values the user may provide will be indicated, as well as the
default value, if one is set.

The mechanism for validating the answer is defined by an instance of
ezcConsoleQuestionDialogValidator. In the example, a collection validator is
used, which defines a collection of valid values. Beside that, it performs a
case conversion on the user provided result before validating it, if desired.

Displaying a dialog can either be done directly, by calling
ezcConsoleDialog->display(), or the more convenient way, shown in the example.
The ezcConsoleDialogViewer::displayDialog() method displays the dialog in a
loop, until the user provided a valid value, so that the program can rely on
this. In the example, the user is asked after every performed action, if he
still wants to proceed. If the answer is "n" or "N", the program stops.

An example run of this application could look like this: ::

    Some action performed...

    Do you want to proceed? (y/n) [y] y

    Some action performed...

    Do you want to proceed? (y/n) [y] 

    Some action performed...

    Do you want to proceed? (y/n) [y] n
    Goodbye!


A very similar yes/no question can be created through convenience method very
easily:

.. include:: tutorial_example_14_dialog_yesnoquestion.php
   :literal:

The created yes/no question dialog contains a custom question and defaults to
"y", if nothing is selected. In contrast to the last example, the dialog
created here also accepts "yes" and "no" as answers. Both phrases can be used
in any typing, e.g. like "yEs" or "NO". This is made possibly by the
ezcConsoleQuestionDialogMappingValidator, which extends
ezcConsoleQuestionDialogCollectionValidator. The mapping validator allows to
define an arbitrary mapping between the user typed answers and expected ones.
Therefore the dialog still only returns either "y" or "n".

The second dialog type, provided with ConsoleTools, is the
ezcConsoleMenuDialog. Similar to the ezcConsoleQuestionDialog, it displays a
list of menu items to the user and requires him to choose one of these. An
example for this class looks like this:

.. include:: tutorial_example_15_dialog_menu.php
   :literal:

Again the dialog is instantiated and some options are tweaked to get the
desired behaviour. The validator in this case receives an array of possible
menu items, while the key represents the identifier and the value contains the
text to be displayed for the item. The second argument is the default value,
chosen if the user simply presses <return>.

An example run of this program could look like this: ::

    Please choose a possibility:

      1) Perform some more actions
      2) Perform another action
      0) Quit

    Select: [0] 1
    Performing some more actions...
    Please choose a possibility:

      1) Perform some more actions
      2) Perform another action
      0) Quit

    Select: [0] 2
    Performing some other actions!
    Please choose a possibility:

      1) Perform some more actions
      2) Perform another action
      0) Quit

    Select: [0] 

The character used to divide the identifier and text, as well as the text
indicating that a selection must be done, can be tweaked, too.

Further information about dialogs can be found in the API documentation of
ezcConsoleDialog, ezcConsoleQuestionDialog and ezcConsoleMenuDialog.


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79