|
| 1 | +<?xml version="1.0"?> |
| 2 | +<document> |
| 3 | + |
| 4 | + <properties> |
| 5 | + <author email="jbjk@mac.com">John Keyes</author> |
| 6 | + <title>Introduction</title> |
| 7 | + </properties> |
| 8 | + |
| 9 | + <body> |
| 10 | + <section name="Introduction"> |
| 11 | + <p> |
| 12 | + There are three stages to command line processing. They are the |
| 13 | + definition, parsing and interrogation stages. The following |
| 14 | + sections will discuss each of these stages in turn, and discuss how |
| 15 | + to implement them with CLI. |
| 16 | + </p> |
| 17 | + </section> |
| 18 | + <section name="Definition Stage"> |
| 19 | + <p> |
| 20 | + Each command line must define the set of options that will be used |
| 21 | + to define the interface to the application. |
| 22 | + </p> |
| 23 | + <p> |
| 24 | + CLI uses the <a href="apidocs/org/apache/commons/cli/Options.html"> |
| 25 | + <code>Options</code></a> class, as a container for |
| 26 | + <a href="apidocs/org/apache/commons/cli/Options.html"> |
| 27 | + <code>Option</code></a> instances. There are two ways to create |
| 28 | + <code>Option</code>s in CLI. One of them is via the constuctors, |
| 29 | + the other way is via the factory methods defined in |
| 30 | + <code>Options</code>. |
| 31 | + </p> |
| 32 | + <p> |
| 33 | + The <a href="usage.html">Simple Option</a> document provides examples |
| 34 | + how to create an <code>Options</code> object. |
| 35 | + </p> |
| 36 | + <p> |
| 37 | + The result of the definition stage is an <code>Options</code> |
| 38 | + instance. |
| 39 | + </p> |
| 40 | + </section> |
| 41 | + <section name="Parsing Stage"> |
| 42 | + <p> |
| 43 | + The parsing stage is where the text passed into the |
| 44 | + application via the command line is processed. The text is |
| 45 | + processed according to the rules defined by the parser |
| 46 | + implementation. |
| 47 | + </p> |
| 48 | + <p> |
| 49 | + The <code>parse</code> method defined on |
| 50 | + <a href="apidocs/org/apache/commons/cli/CommandLineParser.html"> |
| 51 | + <code>CommandLineParser</code></a> takes an <code>Options</code> |
| 52 | + instance and a <code>java.util.List</code> of arguments and |
| 53 | + returns a |
| 54 | + <a href="apidocs/org/apache/commons/cli/CommandLine.html"> |
| 55 | + <code>CommandLine</code></a>. |
| 56 | + </p> |
| 57 | + <p> |
| 58 | + The result of the parsing stage is a <code>CommandLine</code> |
| 59 | + instance. |
| 60 | + </p> |
| 61 | + </section> |
| 62 | + <section name="Interrogation Stage"> |
| 63 | + <p> |
| 64 | + The interrogation stage is where the application querys the |
| 65 | + <code>CommandLine</code> to decide what execution branch to |
| 66 | + take depending on boolean options and to use the option values |
| 67 | + to provide the application data. |
| 68 | + </p> |
| 69 | + <p> |
| 70 | + This stage is implemented in the user code. The accessor methods |
| 71 | + on <code>CommandLine</code> provide the interrogation capability |
| 72 | + to the user code. |
| 73 | + </p> |
| 74 | + <p> |
| 75 | + The <a href="usage.html">Simple Option</a> document provides examples |
| 76 | + how to create an <code>Options</code> object. |
| 77 | + </p> |
| 78 | + <p> |
| 79 | + The result of the interrogation stage is that the user code |
| 80 | + is fully informed of all the text that was supplied on the command |
| 81 | + line and processed according to the parser and <code>Options</code> |
| 82 | + rules. |
| 83 | + </p> |
| 84 | + </section> |
| 85 | + </body> |
| 86 | +</document> |
0 commit comments