net.dpml.cli
Interface Option

All Known Subinterfaces:
Argument, Group, Parent
All Known Implementing Classes:
ArgumentImpl, GroupImpl, OptionImpl, ParentImpl

public interface Option

The super type of all options representing a particular element of the command line interface.

Version:
1.0.0
Author:
Digital Product Meta Library

Method Summary
 void appendUsage(StringBuffer buffer, Set helpSettings, Comparator comp)
          Appends usage information to the specified StringBuffer
 boolean canProcess(WriteableCommandLine commandLine, ListIterator arguments)
          Indicates whether this Option will be able to process the particular argument.
 boolean canProcess(WriteableCommandLine commandLine, String argument)
          Indicates whether this Option will be able to process the particular argument.
 void defaults(WriteableCommandLine commandLine)
          Adds defaults to a CommandLine.
 Option findOption(String trigger)
          Recursively searches for an option with the supplied trigger.
 String getDescription()
          Returns a description of the option.
 int getId()
          Returns the id of the option.
 String getPreferredName()
          The preferred name of an option is used for generating help and usage information.
 Set getPrefixes()
          Identifies the argument prefixes that should be considered options.
 Set getTriggers()
          Identifies the argument prefixes that should trigger this option.
 List helpLines(int depth, Set helpSettings, Comparator comp)
          Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
 boolean isRequired()
          Indicates whether this option is required to be present.
 void process(WriteableCommandLine commandLine, ListIterator args)
          Processes String arguments into a CommandLine.
 void validate(WriteableCommandLine commandLine)
          Checks that the supplied CommandLine is valid with respect to this option.
 

Method Detail

process

public void process(WriteableCommandLine commandLine,
                    ListIterator args)
             throws OptionException
Processes String arguments into a CommandLine. The iterator will initially point at the first argument to be processed and at the end of the method should point to the first argument not processed. This method MUST process at least one argument from the ListIterator.

Parameters:
commandLine - the CommandLine object to store results in
args - the arguments to process
Throws:
OptionException - if any problems occur

defaults

public void defaults(WriteableCommandLine commandLine)
Adds defaults to a CommandLine. Any defaults for this option are applied as well as the defaults for any contained options

Parameters:
commandLine - the CommandLine object to store defaults in

canProcess

public boolean canProcess(WriteableCommandLine commandLine,
                          String argument)
Indicates whether this Option will be able to process the particular argument.

Parameters:
commandLine - the CommandLine object to store defaults in
argument - the argument to be tested
Returns:
true if the argument can be processed by this Option

canProcess

public boolean canProcess(WriteableCommandLine commandLine,
                          ListIterator arguments)
Indicates whether this Option will be able to process the particular argument. The ListIterator must be restored to the initial state before returning the boolean.

Parameters:
commandLine - the CommandLine object to store defaults in
arguments - the ListIterator over String arguments
Returns:
true if the argument can be processed by this Option
See Also:
canProcess(WriteableCommandLine,String)

getTriggers

public Set getTriggers()
Identifies the argument prefixes that should trigger this option. This is used to decide which of many Options should be tried when processing a given argument string. The returned Set must not be null.

Returns:
The set of triggers for this Option

getPrefixes

public Set getPrefixes()
Identifies the argument prefixes that should be considered options. This is used to identify whether a given string looks like an option or an argument value. Typically an option would return the set [--,-] while switches might offer [-,+]. The returned Set must not be null.

Returns:
The set of prefixes for this Option

validate

public void validate(WriteableCommandLine commandLine)
              throws OptionException
Checks that the supplied CommandLine is valid with respect to this option.

Parameters:
commandLine - the CommandLine to check.
Throws:
OptionException - if the CommandLine is not valid.

helpLines

public List helpLines(int depth,
                      Set helpSettings,
                      Comparator comp)
Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.

Parameters:
depth - the initial indent depth
helpSettings - the HelpSettings that should be applied
comp - a comparator used to sort options when applicable.
Returns:
a List of HelpLineImpl objects
See Also:
HelpLine, HelpFormatter

appendUsage

public void appendUsage(StringBuffer buffer,
                        Set helpSettings,
                        Comparator comp)
Appends usage information to the specified StringBuffer

Parameters:
buffer - the buffer to append to
helpSettings - a set of display settings @see DisplaySetting
comp - a comparator used to sort the Options

getPreferredName

public String getPreferredName()
The preferred name of an option is used for generating help and usage information.

Returns:
The preferred name of the option

getDescription

public String getDescription()
Returns a description of the option. This string is used to build help messages as in the HelpFormatter.

Returns:
a description of the option.
See Also:
HelpFormatter

getId

public int getId()
Returns the id of the option. This can be used in a loop and switch construct: for(Option o : cmd.getOptions()){ switch(o.getId()){ case POTENTIAL_OPTION: ... } } The returned value is not guarenteed to be unique.

Returns:
the id of the option.

findOption

public Option findOption(String trigger)
Recursively searches for an option with the supplied trigger.

Parameters:
trigger - the trigger to search for.
Returns:
the matching option or null.

isRequired

public boolean isRequired()
Indicates whether this option is required to be present.

Returns:
true if the CommandLine will be invalid without this Option