eZ component: ConsoleTools, Design, 1.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Tobias Schlitt
:Revision: $Rev$
:Date: $Date$
:Status: Draft

.. contents::

=====
Scope
=====

The scope of this document is to describe the enhancements of the ConsoleTools
component for version 1.3 of the component. The following features are part of
this design document:

- Basic dialog system to interact with a user through STDIN.
- Enhanced handling of arguments (including help output).

This document describes a new range of classes, which will be added to
ConsoleTools, to fulfill this needs.

=============
Dialog system
=============

Design overview
===============

The following section gives a brief introduction of the concept of a simple
dialog system that enables the developer of a console based application to
interact with the user through STDIN.

Clarification of terms
----------------------

User
^^^^

The "user" is the person using a program and interacting with it during
runtime. The user has no knowledge about the internals and must be guided
through the dialog system he is interacting with. The term "user" in case of
this document is _not_ the developer using the described component, but the
user who interacts with the final program.

Developer
^^^^^^^^^

In contrast to the "user", the term "developer" in this document refers to the
person who creates a program, using the described component.

Dialog
^^^^^^

The basic idea of a new mechanism to interact with the user through STDIN in
this document is called a "dialog".  A dialog is presented to the user by a
certain amount of output it generates and a certain amount of input it
requests afterwards.

Basic design
------------

The core of the new feature described in this document is a dialog. The dialog
is an object, must have the following capabilities:

- Presents itself to the user on the command line
- Requests data  from the user through STDIN.
- Validate the result for its purpose.
- Return the result to the developer.

A dialog is usually used in a loop, which displays the dialog over and over again
until it received a valid result.

Class design
============

The following classes will realize the idea of dialogs in ConsoleTools.

ezcConsoleDialog
----------------

This interface describes the external API, which is commonly used by developers
and other classes to interact with a dialog object. Each dialog class must
implement this interface.

__construct( ezcConsoleOutput $output, ezcConsoleDialogOptions $options )
  The constructor of a dialog receives an instance of ezcConsoleOutput, which
  it must use for presenting its output, when requested. In addition, it can
  receive an option object, which must be an instance or subclass instance of
  ezcConsoleDialogOptions.
hasValidResult()
  This method must return a boolean value, which indicates, if the dialog
  already received a result from the user, which is valid in its context.
getResult()
  After the hasValidResult() method returned true, this method will return the
  value received from the dialog.
display()
  Using this method, the developer can instruct the dialog object to display
  itself to the user. The dialog must use the instance of eczConsoleOutput it
  received in the constructor for displaying.
reset()
  This method resets the dialog internally to the state it had directly after
  construction, so that it can be reused by the developer.

In addition to this interface, an implementation of ezcConsoleDialog can
contain a set of static factory methods, which return a dialog in a
pre-configured state (for example a standard yes/no question, where only the
text needs to be set).

ezcConsoleDialogOptions
-----------------------

This is the base option class, which must be accepted by a dialog. It contains
options, which must be valid for each dialog class. A dialog class may request,
that the options it receives are instances of a subclass, if it expects
additional options. Each of the options defined in ezcConsoleDialogOptions must
also be available in this subclass. Every option defined must have a sensible
default value, so that there is no need for the developer to change it.

The base option class provides the following options:

format
  The name of the format this dialog uses to be displayed. The format
  identifier must be defined in the ezcConsoleOutput instance submitted to the
  constructor of the dialog.
validator
  An instance of ezcConsoleDialogValidator. This validator is responsible for
  validation and manipulation of the result a dialog received from the user. An
  implementation of ezcConsoleDialog may require a specific sub-class of
  ezcConsoleDialogValidator here (e.g. for a menu dialog, which requires a
  special validator object to work).

ezcConsoleDialogViewer
----------------------

The ezcConsoleDialogViewer class provides a set of static convenience methods
that can be used by a developer that works with dialogs and by a developer that
creates new dialogs. These methods are:

displayDialog( ezcConsoleDialog $dialog ) [static]
  This method is recommended to be used for displaying dialogs. It performs the
  typical loop: Display the dialog over and over again until it received a
  valid result. When this state is reached, it returns the dialogs value.
readLine( $trim = true ) [static]
  The readLine() method is commonly used in a dialog implementation to read a
  line from standard in. It returns the input provided by a user, optionally
  trimmed of leading and trailing white spaces.

ezcConsoleDialogValidator
-------------------------

The ezcConsoleValidator interface provides signatures for methods that can be used
by a dialog to validate the result it retrieved. The validator is configured by
the user and submitted to the dialog via an option (if a dialog supports this
mechanism).

__construct( ... )
  The signature of the constructor is left to the validator implementation to
  retrieve settings (e.g. the valid results).
validate( mixed $result )
  This method is responsible for validating a given result.  The dialog will
  submit the result it received to this method which will indicate if the
  result was valid by a boolean value. To manipulate / fix a retrieved result,
  the dialog implementation can call the fixup() method.
fixup( mixed $result )
  A validator can try to fix a given result to be valid. This manipulation can
  be omitted by simply returning the result again. An example for a fixup would
  be to convert a date information into a Unix timestamp using strtotime(). The
  validate method would then expect an integer value > 0. The dialog
  implementation is responsible for calling fixup() as it thinks is appropriate
  (e.g. always before calling validate(), only if validate() fails, never).

Dialog implementations
======================

The new feature set comes with a collection of basic dialog implementations,
which will be described in this section.

ezcConsoleQuestionDialog
------------------------

The ezcConsoleQuestionDialog is the most basic imaginable dialog. It asks the
user a simply question and expects a certain answer. A typical output from an
ezcConsoleQuestionDialog object could look like this: ::

    Do you want to continue? (y/n) 

This dialog implementation provides a set of rudimentary options, which can be
used to customize its appearance and enhance its capabilities. For this
purpose, it comes with a custom options class ezcConsoleQuestionDialogOptions,
that accepts the following options in addition to those provided by
ezcConsoleDialogOptions:

text
  This option defines the main "question" text, displayed to the user.
validator
  The validator is an instance of ezcConsoleQuestionDialogValidator. For
  implementation details, see further below.
showResults
  If this boolean option is set to true, the dialog will display the possible
  result values behind the question text itself (retrieved from the validator).
  If a default value is provided, it will also indicate, which one this is. For
  example: ::
    
    Do you want to continue? (y/n) [y]

  While here "y" and "n" are valid results and "y" is the default result, which
  is selected when simply skipping this question by hitting just <RETURN>.

ezcConsoleQuestionDialogValidator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The interface if ezcConsoleQuestionValidator inherits from
ezcConsoleDialogValidator and adds the following methods:

getResultString()
  This method returns the result string to be displayed if the option
  "showResults" is true in the ezcConsoleQuestionDialogOptions object.

Concrete implementations of these interface are:

ezcConsoleQuestionDialogTypeValidator
  This validator checks the result to be of a given type (e.g. int, float). It
  optionally checks if the result is in a given range (e.g. [0-100]).
ezcConsoleQuestionDialogCollectionValidator
  This validator checks the result against a given collection of pre-defined
  values (e.g. "y" and "n"). Beside that, it can perform basic operations on
  the result before checking it (like strtolower()).
ezcConsoleQuestionDialogRegexValidator
  This validator checks the result against a given regex (e.g.
  "/([0-2]?[0-9])[:.]([0-6]?[0-9])/" for validation of a time value). In addition
  it can perform a manipulation using this regex with a given (e.g. "\1:\2" to
  unify the time value given).

ezcConsoleMenuDialog
--------------------

The second dialog implementation shipped with ConsoleTools is the menu dialog,
which is an enhanced version of the question dialog. The menu dialog will
display an ordered set of options and let the user select one of these. A
typical menu can look like this: ::

    You can choose one of the following actions.

    1)  Create something new
    2)  Edit something
    3)  Delete something
    4)  Do something else

    Please choose an action: 

The menu dialog also comes with its own set of options, the
ezcConsoleMenuDialogOptions:

text
  The text displayed before the menu.
selectionText
  The text displayed after the menu to indicate to the user that he should make
  a selection.
markerChar
  The marker character used to divide the marker of a menu entry (e.g. the
  number) from the menu value (the text of a menu entry).
validator
  The validator must be an instance of ezcConsoleMenuDialogValidator.

ezcConsoleMenuDialogValidator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In contrast to ezcConsoleQuestionDialogValidator, this is not an interface, but
a concrete implementation of ezcConsoleDialogValidator. The menu validator
offers 2 properties to determine the menu entries:

$entries
  An array of entries shown as the menu. The keys of this array represent the
  markers of the menu entries, the values represent the text shown.

In addition, the validator can be configured to perform a manipulation on the
result like the ezcConsoleQuestionDialogCollectionValidator (e.g.
strtolower()).

==============================
Enhanced handling of arguments
==============================

Design overview
===============

The current functionality for handling options and arguments for a console
based application in eZ Components (mainly the class ezcConsoleInput) has only
rudimentary support for dealing with arguments. The current possibility is to
either switch arguments on or off and does not allow to specify the following
things:

- How many arguments are possible
- Which arguments are mandatory/optional
- Names and types for the arguments.

The goal of this design section is to provide these 3 features for argument
handling.

Clarification of terms
----------------------

Parameter
^^^^^^^^^

The term parameter is a generic term, which covers options and arguments
together.

Option
^^^^^^

An option for a console based application is specified using a short or a long
name and can (optionally) carry a value of a given type. Short names are built
using "-<name>" syntax, long names use "--<name>". Options are already handled
by the ezcConsoleInput class, using objects of ezcConsoleOption.

Example: ::

    foo.php --save "bar.txt" -a

"--save" is a long name and the parameter carries a string value "bar.txt".
"-a" is a short name of an option, while this option does not carry any value.

Argument
^^^^^^^^

In contrast to an option, an argument is not specified using a specific name, but
by by the order of submission to the program. Arguments can only be given to a
program, after all options have been specified.

Example: ::

    foo.php --save "bar.txt" -a -- "baz" 23
    
"baz" is the value of the first argument, 23 the value of the second one.

Arguments separator
^^^^^^^^^^^^^^^^^^^

In some cases the semantic for specifying parameters on the console is not
deterministic. Since the algorithm used to parse parameters cannot handle
nondeterministic semantics, a separator must be used to determine the border
between options and arguments. The separator used is "-- ", which indicates
that anything following it is an argument and does not belong to the option
before it. The seperator is not mandatory and must only be used in cases where
the parsing would not be deterministic.

Example: ::

    foo.php --save "bar.txt" -a "baz" 23
    foo.php --save "bar.txt" -a -- "baz" 23

In the first line, it is not possible to determine if "baz" is the value for
the parameter "-a" or if it is an argument. The second line clarifies this.

Basic design
------------

The core of the new functionality is built upon 2 classes:

- ezcConsoleArguments
- ezcConsoleArgument

The first one is a collection class, which takes care of holding all arguments.
The second one is a struct class, which handles 1 specific argument.

Class design
============

ezcConsoleArgument
------------------

This struct class represents a single argument and defines the following
properties:

name
  A descriptive name for the argument. This name is used for 2 purposes:
  - Displaying it in the help text generated by ezcConsoleInput.
  - Identifying and retrieving the object from the argument collection.
  This property is mandatory and may not be left out.
type
  The data type of the argument. The type is used for validation purposes when
  the parameter string of the console application is parsed and is indicated to
  the user in the help text generated by ezcConsoleInput. The default for this
  property will be ezcConsoleInput::TYPE_STRING. ezcConsoleInput::TYPE_NONE
  will not be allowed.
shorthelp
  A short help text, which is used by ezcConsoleInput when generating a short
  help output. A sensible default will be set for this property.
longhelp
  A long help text, which is used by ezcConsoleInput when generating a long
  help output. A sensible default will be set for this property.
mandatory
  This boolean flag specifies if an argument is mandatory or optional. Since
  ezcConsoleArguments is an ordered collection, all arguments following an
  optional argument will be handled as optional, too. The default value for
  this property is true.
default
  This property carries the default value for optional arguments. If these are
  not submitted, the default value will be used as the value property. If no
  default value was explicitly defined, it is null and therefore the value
  property will be null, if the argument was not submitted.
multiple
  This booloan property determines, if an argument can carry multiple values.
  The default here is false. If this is set to true, no more arguments may
  follow the current argument, since multiple defines the number of values to
  be undefined. If arguments would follow, the parameter string would be
  non-deterministic. Therefore all following arguments are silently ignored.
  For arguments with this property true, the returned value is an array. The
  default value may be an array, too.
value
  This property is not meant to be set by the developer directly, but by
  ezcConsoleInput while parsing the parameter string of the application. It
  will contain the value submitted for the argument after parsing. If this
  argument was not submitted, the value of the default property will be set
  here.

ezcConsoleArguments
-------------------

This collection class carries the arguments for an application. It keeps track
of the order of the ezcConsoleArgument objects and offers 2 access methods for
them:

- By their order (using numeric identification)
- By their name

For these purpose, the ArrayAccess and Iterator interfaces provided by PHP will
be implemented in this class. ArrayAccess will be used for both variants of
access, while Iterator will iterate of the numeric order of the arguments.
Argument names must be unique. The registration of new arguments is only
allowed by number. The retrival is also allowed by name.

The class does not offer any additional methods to deal with arguments and
purely relies on the given interfaces.

Integration aspects
===================

The current design of ezcConsoleInput is not designed to handle arguments in
the planned way. Therefore its API must be changed slightly. Naturally this
will be done maintaining BC. The following changes are planned:

Property $argumentDefinition
----------------------------

Since ezcConsoleInput already has a property $arguments, which carries the
values of submitted arguments in an array, a new property will be introduced to
carry the instance of ezcConsoleArguments. By default, this property will be
null, which indicates, that the old manor of handling arguments is used.

If ezcConsoleArguments is used, the preferred way of retrieving argument values
is, to use the ezcConsoleArgument struct of the specific argument. The
$arguments property of ezcConsoleInput will still be set and contain the values
of the provided arguments.

Switching arguments on/off
--------------------------

The ezcConsoleOption class allows to switch arguments on or off for a console
call to the application using its property $arguments. This behaviour will not
be changed. If an option defines that arguments are not allowed, if it is
submitted, all defined arguments will not be allowed.

It is possible, that this behaviour will be enhanced in the future, so that
options can define a filter rule for arguments instead of a boolean on/off
switch. But this feature is not in scope of the design given here.

Usage example
=============

The following example shows the basic of the newly created API.

Using arguments
---------------

::

    $input = new ezcConsoleInput();
    $input->argumentDefinition = new ezcConsoleArguments();

    // First argument
    $input->argumentDefinition[] = new ezcConsoleArgument(
        "infile",
        ezcConsoleInput::TYPE_STRING,
        "The file to read from.",
        "The input file, from which the content to process is read.",
    );

    // Second argument
    $input->argumentDefinition[1] = new ezcConsoleArgument(
        "outfile"
    );
    $input->argumentDefinition[1]->shorthelp = "Output file.";
    $input->argumentDefinition[1]->longhelp  = "File to output generated
        content to. Output will be printed to STDOUT if left out.";
    $input->argumentDefinition[1]->mandatory = false;
    $input->argumentDefinition[1]->default   = "php://output;

    try
    {
        $input->process();
    }
    catch ( ezcConsoleMissingArgumentException $e )
    {
        // Only the first argument will possibly trigger this
        die( "Argument {$e->argument->name} missing!" );
    }

    // The first argument is always present if no exception occured
    $inFile  = fopen( $input->argumentDefinition["infile"]->value, "r" );
    // The second one is optional, but has a default
    $outFile = fopen( $input->argumentDefinition["infile"]->value, "w" );

Generating help
---------------
    
::
    
    $input = new ezcConsoleInput();
    $input->argumentDefinition = new ezcConsoleArguments();

    // First argument
    $input->argumentDefinition[] = new ezcConsoleArgument(
        "file",
        ezcConsoleInput::TYPE_STRING,
        "Output file.",
        "File to output generated
    );

    // Second argument
    $input->argumentDefinition[] = new ezcConsoleArgument(
        "bytes",
        ezcConsoleInput::TYPE_INT,
        "Bytes to write.",
        "The number of bytes written to the output file. If left out,
             everything will be written.",
        false,
        -1
    );

    echo $input->getHelpiText( "Some example program." );

Generates: ::

    Usage: test.php [--] <string:file> [<int:bytes>]
    Some example program

    Arguments:
    <string:file>       Output file.
    <int:bytes> = -1    Bytes to write.

Open issues
===========

- The access of arguments by number and name is comfortable, but (as described
  above) not reliable, if 2 parameters have the same name. It also makes
  implementation more complex (if a parameter is removed, namesake has to come
  in place. So, do we want this or not?
- The property name $argumentsDefinition is OK for the definition part, but
  does actually not make sense, if you access it later to retrieve the value.
  Any better naming solution?
- It is sometimes sensible to allow that for 1 argument multiple values are
  submitted (e.g. if you expect an undefined number of file names). To resolve
  this, we need to invent a property "multiple" for the ezcConsoleArgument
  struct. If multiple is defined for 1 argument, no more arguments must follow,
  since the algorithm could not determine easily where the multiple values for
  the argument end. Do we need this functionality (now)?

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