|
| 1 | +<?xml version="1.0"?> |
| 2 | +<document> |
| 3 | + |
| 4 | + <properties> |
| 5 | + <author email="jbjk@mac.com">John Keyes</author> |
| 6 | + <title>Usage Scenario's</title> |
| 7 | + </properties> |
| 8 | + |
| 9 | + <body> |
| 10 | + <section name="Usage Scenario's"> |
| 11 | + <p> |
| 12 | + The following sections describe some example scenarios on how to |
| 13 | + use CLI in applications. |
| 14 | + </p> |
| 15 | + |
| 16 | + <subsection name="Using a boolean option"> |
| 17 | + <p> |
| 18 | + A boolean option is represented on a command line by the presence |
| 19 | + of the option, i.e. if the option is found then the option value |
| 20 | + is true, otherwise the value is false. |
| 21 | + </p> |
| 22 | + <p> |
| 23 | + The <code>DateApp</code> utility prints the current date to standard output. If the |
| 24 | + <code>-t</code> option is present the current time is also printed. |
| 25 | + </p> |
| 26 | + </subsection> |
| 27 | + <subsection name="Create the Options"> |
| 28 | + <p> |
| 29 | + An <a href="apidocs/org/apache/commons/cli/Options.html"> |
| 30 | + <code>Options</code></a> object must be created and the <code>t</code> |
| 31 | + <code>Option</code> must be added to it. |
| 32 | + </p> |
| 33 | + <source> |
| 34 | +// create Options object |
| 35 | +Options options = new Options(); |
| 36 | + |
| 37 | +// add t option |
| 38 | +options.addOption('t', false, "display current time");</source> |
| 39 | + <p> |
| 40 | + The <code>addOption</code> method has three parameters. The first |
| 41 | + parameter is a <code>char</code> that represents the option. The |
| 42 | + second paramter is a <code>boolean</code> that specifies whether the |
| 43 | + option requires an argument or not. In the case of a boolean option |
| 44 | + (sometimes referred to as a flag) an argument value is not present so |
| 45 | + it <code>false</code> is passed. The third parameter is the description |
| 46 | + of the option. This description will be used in the usage text of the |
| 47 | + application. |
| 48 | + </p> |
| 49 | + </subsection> |
| 50 | + <subsection name="Parsing the command line arguments"> |
| 51 | + <p> |
| 52 | + The <code>parse</code> methods of <code>Options</code> are used to |
| 53 | + parse the command line arguments. |
| 54 | + </p> |
| 55 | + <source> |
| 56 | +CommandLine cmd = options.parse(args);</source> |
| 57 | + <p> |
| 58 | + Now we need to check if the <code>t</code> option is present. To do |
| 59 | + this we will interrogate the |
| 60 | + <a href="apidocs/org/apache/commons/cli/CommandLine.html"><code>CommandLine</code> |
| 61 | + </a> object. The <code>hasOption</code> method takes a |
| 62 | + <code>char</code> parameter and returns true if the option represented |
| 63 | + by the <code>char</code> is present, otherwise it returns false. |
| 64 | + </p> |
| 65 | + <source> |
| 66 | +if(cmd.hasOption('t')) { |
| 67 | + // print the date and time |
| 68 | +} |
| 69 | +else { |
| 70 | + // print the date |
| 71 | +}</source> |
| 72 | + </subsection> |
| 73 | + <subsection name="International Time"> |
| 74 | + <p> |
| 75 | + The <code>InternationalDateApp</code> utility extends the |
| 76 | + <code>DateApp</code> utility by providing the ability to print the |
| 77 | + date and time in any country in the world. To facilitate this a new |
| 78 | + command line option, <code>c</code>, has been introduced. |
| 79 | + </p> |
| 80 | + <source> |
| 81 | +// add c option |
| 82 | +options.addOption('c', true, "country code");</source> |
| 83 | + <p> |
| 84 | + The second parameter is true this time. This specifies that the |
| 85 | + <code>c</code> option requires an argument value. If the required option |
| 86 | + argument value is specified on the command line it is returned, |
| 87 | + otherwise <code>null</code> is returned. |
| 88 | + </p> |
| 89 | + </subsection> |
| 90 | + <subsection name="Retrieving the argument value"> |
| 91 | + <p> |
| 92 | + The <code>getOptionValue</code> methods of <code>Options</code> are |
| 93 | + used to retrieve the argument values of options. |
| 94 | + </p> |
| 95 | + <source> |
| 96 | +// get c option value |
| 97 | +String countryCode = options.getOptionValue('c'); |
| 98 | + |
| 99 | +if(countryCode == null) { |
| 100 | + // print default date |
| 101 | +} |
| 102 | +else { |
| 103 | + // print date for country specified by countryCode |
| 104 | +}</source> |
| 105 | + </subsection> |
| 106 | + <subsection name="More Information"> |
| 107 | + <p> |
| 108 | + <ul> |
| 109 | + <li>CLI <a href="apidocs/index.html">javadoc</a></li> |
| 110 | + <li>CLI examples</li> |
| 111 | + </ul> |
| 112 | + </p> |
| 113 | + </subsection> |
| 114 | + </section> |
| 115 | + </body> |
| 116 | +</document> |
0 commit comments