JezK

Edit File: 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