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

[Wiki Guest]

guest [92.224.22.83]  Fri, 04 Nov 2011 19:56:03 +0000

Modified page: http://wiki.horde.org/Doc/Dev/HordeCliModular
New Revision:  4
Change log:  Typos.

@@ -3,11 +3,11 @@
  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

-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.
+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 option.  
In contrast the '''{{--register-only}}''' option is specific to the  
'''{{install}}''' command provided by '''{{pear}}'''.

-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.
+Obviously not all command line interfaces match this scheme. 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

  {{Horde_Cli_Modular}} provides four classes as main structural elements:
@@ -18,13 +18,13 @@
  : {{Horde_Cli_Modular_Module}} : The interface definition for a module.

  ++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.
+The {{Horde_Cli_Modular}} class is the entry point for constructing a  
modular command line interface. The class provides methods to combine  
and access the different modules.

  +++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.
+This class generates the basic setup and you will only have to  
provide a few basic parameters to setup the system. This introduction  
will 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:

  <code type="php">
@@ -36,11 +36,11 @@
    )
  );
  </code>

-The '''{{parser}}''' parameter preparse the command line argument  
parser (usually {{Horde_Argv}}. The snippet above only provides the  
'''{{usage}}''' setting that will be displayed as the condensed usage  
instruction when the user requests the help for the command.
+The '''{{parser}}''' parameter preparse the command line argument  
parser (usually {{Horde_Argv}}). The snippet above only provides the  
'''{{usage}}''' setting that will be displayed as the condensed usage  
instruction when the user requests the help for the CLI script.

-The '''{{modules}}''' part defines the '''{{directory}}''' that  
contains the various modules that form the command line interface.
+The '''{{modules}}''' part defines the '''{{directory}}''' that  
contains the various modules which are part of the command line  
interface.

  And finally the '''{{provider}}''' setting indicates the common  
'''{{prefix}}''' that the module classes will have.

  The file structure for the hypothetical {{Horde_Something}} package  
would look like this in order to match the setup presented above:
@@ -97,9 +97,9 @@
      public function getOptionGroupOptions();
  }
  </code>

-There are two function that allow to influence the global setup of  
the command line parser: {{getUsage()}} and {{getBaseOptions()}}. The  
first one returns a string that will be added to the generic usage  
description displayed when the user requests the help screen. The  
second one returns an array of {{Horde_Argv_Option}} instances that  
each define an option valid for all modules.
+There are two functions that allow to influence the global setup of  
the command line parser: {{getUsage()}} and {{getBaseOptions()}}. The  
first one returns a string that will be added to the generic usage  
description displayed when the user requests the help screen. The  
second one returns an array of {{Horde_Argv_Option}} instances that  
each define an option valid for all modules.

  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()}}.