commons-cli/xdocs/introduction.xml at 5b2317c4e7761252cd0663213af449ba48e05cae · virtuoushub/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<
AB21
/div>49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->
<document>

  <properties>
    <author email="commons-dev@jakarta.apache.org">commons-dev</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/Option.html">
        Option</a> instances.  There are two ways to create
        <code>Option</code>s in CLI.  One of them is via the constructors,
        the other way is via the factory methods defined in
        <code>Options</code>.
      </p>
      <p>
        The <a href="usage.html">Usage Scenarios</a> document provides
        examples how to create an <code>Options</code> object and also
        provides some real world examples.
      </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>String[]</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 uses 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 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>