Jakarta Commons - CLI

1. Jakarta Commons - CLI Kun-Tse Wu

2. Outline • Introduction • Definition Stage • Parsing Stage • Interrogation Stage • Conclusion

3. Introduction • Before Graphical User Interfaces, users interacted with their person computers by typing text commands - Command Line Interfaces. • The CLI library provides a simple and easy to use API for working with the command line arguments and options.

4. Ant Example ant [options] [target [target2 [target3] ...]] Options: -help print this message -version print the version information and exit -verbose be extra verbose -debug print debugging information -emacs produce logging information without adornments -logfile <file> use given file for log -logger <classname> the class which is to perform logging -listener <classname> add an instance of class as a project listener -buildfile <file> use given buildfile -D<property>=<value> use value for given property -find <file> search for buildfile towards the root of the filesystem and use it

5. Outline • Introduction • Definition Stage • Parsing Stage • Interrogation Stage • Conclusion

6. Definition Stage • Each command line must define the set of options that will be used to define the interface to the application. • CLI uses the Options class, as a container for Option instances.

7. Create the Options • // Create boolean Option • Option help = new Option( "h", "print this message" ); • // Create argument Option • Option logfile = OptionBuilder.withArgName( "f" ) • .hasArg() • .withDescription( "use given file for log" ) • .create( "f" ); • // Create java property Option • Option property = OptionBuilder.withArgName( "property=value" ) • .hasArgs() • .withValueSeparator() • .withDescription( "use value for given property" ) • .create( "D" ); • // Create the Options object • Options options = new Options(); • options.add( help ); • options.add( logfile ); • options.add( property );

8. Outline • Introduction • Definition Stage • Parsing Stage • Interrogation Stage • Conclusion

9. Parsing Stage • The parsing stage is where the text passed into the application via the command line is processed. • The parse method defined on CommandLineParser takes an Options instance and a String[] of arguments and returns a CommandLine .

10. Parser • A abstract class Parser which implements CommandLineParser interface creates CommandLines. • BasicParser • A simple implementation of Parser's abstract flatten method. • GnuParser • If an Option exists for the first character of the arguments entry AND an Option does not exist for the whole argument then add the first character as an option to the processed tokens list e.g. –fabc.txt  -f abc.txt • Otherwise just add the token to the processed tokens list.

11. Parser (cont) • PosixParser • An option is a hyphen followed by a single alphanumeric character, like this: -o. • An option may require an argument (which must appear immediately after the option); for example, -o argument or -oargument. • Options that do not require arguments can be grouped after a hyphen, so, for example, -lst is equivalent to -t -l -s. • Options can appear in any order; thus -lst is equivalent to -tls. • Options can appear multiple times. • Options precede other nonoption arguments: -lst nonoption. • The -- argument terminates options. • The - option is typically used to represent one of the standard input streams.

12. Create the Parser public static void main( String[] args ) { // create the parser CommandLineParser parser = new PosixParser(); try { // parse the command line arguments CommandLine line = parser.parse( options, args ); … } catch ( ParseException exp ) { // oops, something went wrong System.err.println( "Parsing failed. Reason: " + exp.getMessage() ); } }

13. Outline • Introduction • Definition Stage • Parsing Stage • Interrogation Stage • Conclusion

14. Interrogation Stage • The interrogation stage is where the application queries the CommandLine to decide what execution branch to take. • This stage is implemented in the user code. • The access methods on CommandLine provide the interrogation capability to the user code.

15. Querying the CommandLine //has the help argument been passed? if ( line.hasOption( “h” ) ) { // print the help information } // has the file argument been passed? if( line.hasOption( “f” ) ) { // initialise the member variable this.file = line.getOptionValue( “f” ); … } //has the property argument been passed? if ( line.hasOption( “D” ) ) { // set the property }

16. ls Example Usage: ls [OPTION]... [FILE]... List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuSUX nor --sort. -a, --all do not hide entries starting with . -A, --almost-all do not list implied . and .. -b, --escape print octal escapes for nongraphic characters --block-size=SIZE use SIZE-byte blocks -B, --ignore-backups do not list implied entries ending with ~ -c with -lt: sort by, and show, ctime (time of last modification of file status information) with -l: show ctime and sort by name otherwise: sort by ctime -C list entries by columns -h print this message

17. Outline • Introduction • Definition Stage • Parsing Stage • Interrogation Stage • Conclusion

18. Conclusion • We can use CLI to parse a command line to deal with the large number of options required. • Command line interfaces often allow greater flexibility and control. • All options and operations are invokable in a consistent form, one ‘level’ away from the basic command. • CLIs often can double as scripting languages and can perform operations in a batch processing mode without user interaction.

19. Reference • CLI http://jakarta.apache.org/commons/cli • GNU getOpt http://www.urbanophile.com/arenn/hacking/getopt/Package-gnu.getopt.html • POSIX Conventions for Command Line Arguments http://java.sun.com/docs/books/tutorial/essential/attributes/_posix.html