[commits] [Wiki] changed: Doc/Dev/HordeCliModular

[Wiki Guest]

guest [89.204.138.74]  Thu, 06 Oct 2011 18:55:00 +0000

Modified page: http://wiki.horde.org/Doc/Dev/HordeCliModular
New Revision:  2
Change log:  Remove the leading space for headers as the rst looks bad  
otherwise

@@ -1,28 +1,28 @@
-+ Horde_Cli_Modular
++Horde_Cli_Modular

  Command line interfaces can often be composed of different modules  
responsible for distinct actions. {{Horde_Cli_Modular}} allows each  
such module to influence the overall command line interface.

-++ Introduction
+++Introduction

  The command line of the tool '''{{pear}}''' is a good example of the  
kind of interface {{Horde_Cli_Modular}} supports: There are a number  
of global options available but each command supported by  
'''{{pear}}''' may have its own subset of options. '''{{-c}}'''  
identifies the '''{{pear}}''' configuration file as a global options.  
In contrast the '''{{--register-only}}''' option is an option specific  
to the '''{{install}}''' command '''{{pear}}''' provides.

  Obviously not all command line interfaces match this scheme and  
hence {{Horde_Cli_Modular}} shouldn't be considered to be a generic  
utility for all CLI tools. But for all CLI helpers that have such a  
structure the library should provide a decent skeleton that allows to  
quickly start adding modules.

-++ Structure
+++Structure

  {{Horde_Cli_Modular}} provides four classes as main structural elements:

  : {{Horde_Cli_Modular}} : The entry point for generating the command  
line interface.
  : {{Horde_Cli_Modular_Modules}} : The handler for the list of modules.
  : {{Horde_Cli_Modular_ModuleProvide}} : A module factory.
  : {{Horde_Cli_Modular_Module}} : The interface definition for a module.

-++ Horde_Cli_Modular
+++Horde_Cli_Modular

  This class is entry point for constructing a modular command line  
interface. The class provides methods to combine and access the  
different modules.

-+++ Setup
++++Setup

  This class generates the basic setup and you will only have to  
provide a few basic parameters to setup the system. This introduction  
will only focus on the central settings and you will need to lookup  
the API documentation for further details.

  The following demonstrates how you could construct the  
{{Horde_Cli_Modular}} instance:
@@ -56,9 +56,9 @@
  </code>

  There are two modules: {{Horde_Something_Module_One}} in {{One.php}}  
and {{Horde_Something_Module_Two}} in {{Two.php}}.

-+++ Usage
++++Usage

  After creating the {{Horde_Cli_Modular}} instance you should create  
the command line parser and read the arguments the user provided.

  <code type="php">
@@ -79,9 +79,9 @@
  <code type="php">
  $module = $modular->getProvider()->getModule('one');
  </code>

-++ Writing modules
+++Writing modules

  First and foremost each module can add its own option group with a  
specific title, description and a set of module specific options (see  
Horde_Argv_OptionGroup for exact details). In addition  
{{Horde_Cli_Modular}} allows a module to modify the global usage  
string and add basic options valid for all modules.

  For that to work all modules are required to implement the  
{{Horde_Cli_Modular_Module}} interface:
@@ -103,7 +103,7 @@
  If the module defines its own option group (that will be displayed  
as a separate section in the help text for the command)  
{{hasOptionGroup()}} needs to return '''{{true}}'''.

  An option group needs a title (returned as a string by  
{{getOptionGroupTitle()}}) and a descriptions (returned as a string by  
{{getOptionGroupDescription()}}). And finally an option group needs a  
list of options valid for the specific module defining the option  
group. The corresponding list is returned as an array of  
{{Horde_Argv_Option}} instances by the method  
{{getOptionGroupOptions()}}.

-++ Examples
+++Examples

  Currently the package {{Horde_Kolab_Cli}} and the {{components}}  
application both use {{Horde_Cli_Modular}}. You are referred to these  
package in order to look at real world examples using the  
{{Horde_Cli_Modular}} library.