apache__commons-cli/xdocs/introduction.xml at e6ca08f00a87ad141ab46c8739374adfd396782b · OSS-Security-Assessments/apache__commons-cli · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
<?xml version="1.0"?>
<document>

  <properties>
    <author email="jbjk@mac.com">John Keyes</author>
    <title>Introduction</title>
  </properties>

  <body>
    <section name="Introduction">
      <p>
        There are three stages to command line processing.  They are the
        definition, parsing and interrogation stages.  The following
        sections will discuss each of these stages in turn, and discuss how
        to implement them with CLI.
      </p>
    </section>
    <section name="Definition Stage">
      <p>
        Each command line must define the set of options that will be used
        to define the interface to the application.
      </p>
      <p>
        CLI uses the <a href="apidocs/org/apache/commons/cli/Options.html">
        Options</a> class, as a container for
        <a href="apidocs/org/apache/commons/cli/Options.html">
        Option</a> instances.  There are two ways to create
        <code>Option</code>s in CLI.  One of them is via the constuctors,
        the other way is via the factory methods defined in
        <code>Options</code>.
      </p>
      <p>
        The <a href="usage.html">Simple Example</a> document provides examples
        how to create an <code>Options</code> object.
      </p>
      <p>
        The result of the definition stage is an <code>Options</code>
        instance.
      </p>
    </section>
    <section name="Parsing Stage">
      <p>
        The parsing stage is where the text passed into the
        application via the command line is processed.  The text is
        processed according to the rules defined by the parser
        implementation.
      </p>
      <p>
        The <code>parse</code> method defined on
        <a href="apidocs/org/apache/commons/cli/CommandLineParser.html">
        CommandLineParser</a> takes an <code>Options</code>
        instance and a <code>java.util.List</code> of arguments and
        returns a
        <a href="apidocs/org/apache/commons/cli/CommandLine.html">
        CommandLine</a>.
      </p>
      <p>
        The result of the parsing stage is a <code>CommandLine</code>
        instance.
      </p>
    </section>
    <section name="Interrogation Stage">
      <p>
        The interrogation stage is where the application querys the
        <code>CommandLine</code> to decide what execution branch to
        take depending on boolean options and to use the option values
        to provide the application data.
      </p>
      <p>
        This stage is implemented in the user code.  The accessor methods
        on <code>CommandLine</code> provide the interrogation capability
        to the user code.
      </p>
      <p>
        The <a href="usage.html">Simple Example</a> document provides examples
        how to create an <code>Options</code> object.
      </p>
      <p>
        The result of the interrogation stage is that the user code
        is fully informed of all the text that was supplied on the command
        line and processed according to the parser and <code>Options</code>
        rules.
      </p>
    </section>
  </body>
</document>