Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Console_Getopt Component Proposal

Proposed Component Name Zend_Console_Getopt
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Console_Getopt
Proposers Bill Karwin
Revision 0.1 - Draft proposal (wiki revision: 10)

Table of Contents

1. Overview

Zend_Console_Getopt is an object-oriented component to parse command-line options for PHP scripts. This is not typically required for web applications, but it can be useful for scripts called at the command-line.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Support short, single-letter options, e.g. "-a".
  • Support clusters of short options, e.g. "-abc".
  • Support long, multi-letter options, e.g. "--apple".
  • Support parameters for options, e.g. "-a param".
  • Support simple validation of parameters as words or integers.
  • Support parameters as separate argument or combines with option, e.g. "--apple=param".
  • Support option synonyms.
  • Generate usage help message.
  • Specify valid options in a declarative syntax.
  • Support GNU Getopt syntax.
  • Support more extensive syntax to declare synonyms, parameter types, and help messages.
  • Signify end of parsable options with "--" argument.
  • Allow extension to let users define their own syntax parser.

4. Dependencies on Other Framework Components

  • Zend_Exception

5. Theory of Operation

Provide an object-oriented interface to allow application developers to specify options for a given application, and arguments from the command-line of the current invocation of the application. Presence and value of individual options are provided as magic object attributes, e.g. "$opts->optionname".

The result of this attribute is the value of the option's parameter, if any. Otherwise a true value is returned if the option takes no parameter but was given on the command-line.

Specifying options is done with a declarative syntax that defines one or more synonyms for an option, any parameters that may be given to the option, and a help string for the option. For example:

This means that --apple and -a are synonyms, and take no parameter. --banana and -b are synonyms, and take no parameter. --pear and -p are synonyms, and require (=) a string (s) parameter. Each of these rules is a key in an associative array, the values of which are the help strings for the respective option.

Any of the synonyms can be used as the magic object attributes. "$opts->apple" and "$opts->a" return the same result.

A shorter declarative syntax compatible with GNU getopt is supported. The GNU getopt short syntax supports only single-letter option names, only required string parameters, and no support for declaring help strings (though help strings can be added).

The object generates a usage text message, formatted for text output in case the user gives incorrect option arguments, or requests the usage help for reference. Help messages can be added to the GNU getopt short syntax with the addHelp() method (see use case later in this proposal).

Resolving the parsing of command-line arguments and validating them against the option rules declaration is done in a "lazy" fashion. That is, the parsing is not done until an object attribute is requested, or alternatively when the object method parse() is called directly. The lazy parsing step allows the application programmer to add more option rules, more arguments, and more help strings before the parsing is done (the parsing may generate exceptions, so it's useful to delay it until all rules, argument data, and help strings have been established).

6. Milestones / Tasks

Milestone 1: Working prototype checked into incubator
Milestone 2: Community & Zend Core team review
Milestone 3: Code & test review
Milestone 4: Write full documentation
Milestone 5: Approve and move to core library

7. Class Index

  • Zend_Console_Getopt
  • Zend_Console_Getopt_Exception

8. Use Cases

In these use-cases, an artificial ARGV array is passed to the constructor of Zend_Console_Getopt. In practice, the arguments come from the script's command-line argument array.

Parsing short options

Parsing long options

Handling user errors

Notice in the above example that querying the 'apple' option caused all options to be parsed, thus generating the exception regarding the incorrect usage of the 'pear' option.

Adding option rules

Adding arguments

Adding help messages and getting the usage message

Adding synonyms (aliases)

Dumping options as a string

Dumping options as Json

Dumping options as XML

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.