|
40 | 40 | <p> |
41 | 41 | The homepage for the project is <a href="https://commons.apache.org">Apache Commons</a> |
42 | 42 | </p> |
43 | | - |
| 43 | + <section id="Introducing"> |
| 44 | + <h1>Introducing Apache Commons CLI</h1> |
| 45 | + <p> |
| 46 | + There are three stages to command line processing. They are the |
| 47 | + definition, parsing and interrogation stages. The following |
| 48 | + sections discuss each of these stages in turn, and show how |
| 49 | + to implement them with CLI. |
| 50 | + </p> |
| 51 | + <section> |
| 52 | + <h2>Defining the CLI</h2> |
| 53 | + <p> |
| 54 | + Each command line must define the set of options that will be used |
| 55 | + to define the interface to the application. |
| 56 | + </p> |
| 57 | + <p> |
| 58 | + CLI uses the <a href="javadocs/api-release/org/apache/commons/cli/Options.html"> |
| 59 | + Options</a> class, as a container for |
| 60 | + <a href="javadocs/api-release/org/apache/commons/cli/Option.html"> |
| 61 | + Option</a> instances. There are two ways to create |
| 62 | + <code>Option</code>s in CLI. One of them is via the constructors, |
| 63 | + the other way is via the factory methods defined in |
| 64 | + <code>Options</code>. |
| 65 | + </p> |
| 66 | + <p> |
| 67 | + The <a href="usage.html">Usage Scenarios</a> document provides |
| 68 | + examples how to create an <code>Options</code> object and also |
| 69 | + provides some real world examples. |
| 70 | + </p> |
| 71 | + <p> |
| 72 | + The result of the definition stage is an <code>Options</code> |
| 73 | + instance. |
| 74 | + </p> |
| 75 | + </section> |
| 76 | + <section> |
| 77 | + <h2>Parsing the CLI</h2> |
| 78 | + <p> |
| 79 | + The parsing stage is where the text passed into the |
| 80 | + application via the command line is processed. The text is |
| 81 | + processed according to the rules defined by the parser |
| 82 | + implementation. |
| 83 | + </p> |
| 84 | + <p> |
| 85 | + The <code>parse</code> method defined on |
| 86 | + <a href="javadocs/api-release/org/apache/commons/cli/CommandLineParser.html"> |
| 87 | + CommandLineParser</a> takes an <code>Options</code> |
| 88 | + instance and a <code>String[]</code> of arguments and |
| 89 | + returns a |
| 90 | + <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html"> |
| 91 | + CommandLine</a>. |
| 92 | + </p> |
| 93 | + <p> |
| 94 | + The result of the parsing stage is a <code>CommandLine</code> |
| 95 | + instance. |
| 96 | + </p> |
| 97 | + </section> |
| 98 | + <section> |
| 99 | + <h2>Interrogating the CLI</h2> |
| 100 | + <p> |
| 101 | + The interrogation stage is where the application queries the |
| 102 | + <code>CommandLine</code> to decide what execution branch to |
| 103 | + take depending on boolean options and uses the option values |
| 104 | + to provide the application data. |
| 105 | + </p> |
| 106 | + <p> |
| 107 | + This stage is implemented in the user code. The accessor methods |
| 108 | + on <code>CommandLine</code> provide the interrogation capability |
| 109 | + to the user code. |
| 110 | + </p> |
| 111 | + <p> |
| 112 | + The result of the interrogation stage is that the user code |
| 113 | + is fully informed of all the text that was supplied on the command |
| 114 | + line and processed according to the parser and <code>Options</code> |
| 115 | + rules. |
| 116 | + </p> |
| 117 | + </section> |
| 118 | + </section> |
44 | 119 | <section id="Using"> |
45 | 120 | <h1>Using Apache Commons CLI</h1> |
46 | 121 | <p> |
|
0 commit comments