<?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="dev@commons.apache.org">commons-dev</author>
        <title>CLI2 - Overview</title>
    </properties>
    
    <body>
        <section name="Overview">
            <p> 
                CLI Breaks down command line processing into three distinct phases, the
                first of which is to create a model of the command line you wish to process. The
                second phase is arguably the most important as it involves processing the
                command line arguments of the application according to the model created.
                Finally the parsed command line is available to be queried by the
                application proper.  The phases are discussed in more detail below.
            </p>
            <subsection name="Modelling the interface">
                <p> 
                    In CLI2 a command line is modelled as a Group composed of many Options.
                    There are a number different Option implementations available to be
                    used including DefaultOption, Switch and Command which may all have an
                    Argument and/or a Group of child options associated with them. An
                    example of where this parental relationship could be used is where you
                    need to allow for the following scenario where one option
                    only makes sense within the context of another:
                </p>
                <p><code>myapp --output path/to/file --xml</code></p>
                <p>
                    Typically this command line would be modelled as a DefaultOption
                    (<code>--output</code>) with an Argument (to capture
                    <code>path/to/file</code>) and a Group of children consisting of a
                    DefaultOption (<code>--xml</code>) since the format only applies if the 
                    output is specified
                </p>
                <p>
                    The various Option implementations provided need careful configuration 
                    and constructors take a complex set of arguments.  To ease the construction 
                    of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder 
                    and ArgumentBuilder) have been supplied following the 
                    <a href="http://c2.com/cgi/wiki?BuilderPattern">Builder Pattern</a> 
                    which essentially involves using the DefaultOptionBuilder class to create 
                    instances of DefaultOption using descriptive method calls instead of 
                    anonymous arguments to a constructor.  The following example demonstrates how 
                    the command line shown above could be modelled in code:
                </p>
                <source>
DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
ArgumentBuilder aBuilder = new ArgumentBuilder();
GroupBuilder gBuilder = new GroupBuilder();

DefaultOption xmlOption = 
    oBuilder
        .withLongName("xml")
        .withDescription("Output using xml format")
        .create();

Argument pathArgument = 
    aBuilder
        .withName("path")
        .withMinimum(1)
        .withMaximum(1)
        .create();

Group outputChildren = 
    gBuilder
        .withOption(xmlOption)
        .create();

Option outputOption = 
    oBuilder
        .withLongName("output")
        .withDescription("Outputs to a file")
        .withArgument(pathArgument)
        .withChildren(outputChildren)
        .create();
                </source>
                <p>
                    The <a href="options.html">Options</a> and 
                    <a href="builders.html">Builders</a> sections of the manual discuss these 
                    features in greater detail.
                </p>
                <p>
                    Once all the options have been composed into a Group modelling the complete 
                    option model then we are ready to parse a command line.
                </p>
            </subsection>
            <subsection name="Parsing the command line">
                <p>
                    The Parser class can be used to parse an array of arguments against the 
                    option model into a CommandLine.  The parsing is driven by the 
                    <code>parse(String[])</code> method which delegates to the option model to do 
                    the actual parsing, with each Option implementation providing its own parsing 
                    logic.  The <code>parseAndHelp(String[])</code> method attempts to simplify 
                    the use of the former method by automatically handling any <code>--help</code> 
                    options and displaying error messages where appropriate.
                </p>
                <p>
                    The HelpFormatter class is designed to allow the option model to be described 
                    to the user in a manner typical of command line applications.  The 
                    HelpFormatter is designed with flexibility in mind so it should be possible to 
                    control exactly which structures are described to the user and what level of 
                    detail to use.  
                </p>
                <p>
                    Any errors that occur while parsing result in an OptionException being thrown 
                    which attempt to provide a meaningful message describing the problem to the 
                    user.  Parser's <code>parseAndHelp(String[])</code> method catches any 
                    OptionException and uses the HelpFormatter to display to the user:
                </p>
                <source>
// configure the options
Group options = ...;
                    
// configure a HelpFormatter
HelpFormatter hf = new HelpFormatter();

// configure a parser
Parser p = new Parser();
p.setGroup(options);
p.setHelpFormatter(hf);
p.setHelpTrigger("--help");
CommandLine cl = p.parseAndHelp(new String[]{});
                    
// abort application if no CommandLine was parsed
if(cl==null) {
    System.exit(-1);
}
                </source>
                
                <p>
                    Assuming that OptionExceptions have been averted then the next step is to have 
                    the application query the resulting CommandLine instance.
                </p>
            </subsection>
            <subsection name="Querying the result">
                <p>
                    The CommandLine interface provides lots of ways to look up information either 
                    by Option instance or by a String representing any of the forms valid on the 
                    command line.  For example if an option is configured with multiple names 
                    (e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the 
                    those strings can be used to look up the value irrespective of which form 
                    appeared on the command line.
                </p>
                <p>
                    The <code>hasOption()</code> family of methods can be used to simply test for 
                    the presence of options, while the <code>getValues()</code> family of methods 
                    can be used to retrieve the values associated with Arguments.  The status of 
                    any Switch options can be detected through the use of <code>getSwitch()</code> 
                    methods which will return a Boolean if set or null otherwise:
                </p>
                <source>
// if we have --output option
if(cl.hasOption("--output")) {
    // grab the path
    String path = (String)cl.getValue("--output");
    // grab the format
    boolean xml = cl.hasOption("--xml");
    // configure the application's output
    configureOutput(path,xml);
}
                </source>
                <p>
                    To enable complex CommandLine configurations alternative implementations are 
                    provided that can wrap a Properties or Preferences instance as a CommandLine.
                    These can then be combined with the DefaultingCommandLine and the parsed 
                    CommandLine to provide a variety of different defaulting and overriding 
                    scenarios.  
                </p>
            </subsection>
        </section>
    </body>
</document>