Package com.balsol.clp

A package to handle commandline arguments

See:
          Description

Class Summary
Argument Base class for all parameter types that can be handled by CommandLineParser instances
ArgumentUtil  
CommandLineArguments The result container for Command Line Parser runs.
CommandLineParser Handles command line parameters.
CommandLineScanner  
Operand An operand distinguishes itself from the Argument by such that is an argument which is given before a user specified parse end.
Option  
OptionSpec Option specifications contain information about how a single option is expected to be used as a command line argument.
ParsingTerminator Base class for all parameter types that can be handled by CommandLineParser instances
 

Enum Summary
Declaration Enumeration used to specify the necessity of a value that is to be declared, e.g.
 

Exception Summary
UsageException Thrown when an application has problems with the given set of arguments Wrong number of arguments.
 

Package com.balsol.clp Description

A package to handle commandline arguments

The bsjt-clp packages implements command line parsing functionality accoring to IEEE Std 1003.1 standard and the derived 'Utility Conventions' as defined by 'The Open Group'. In general command lines have to be of the form: <appname>[(options)][(argument)]

This implementation features the POSIX conventions as they have been summarized by SUN microsystems:

Additionally the following requirements have been implemented.

There are two basically different ways to specify which options a command line parser instance shall accept. Either you instantiate a parser and let it 'accept' new options [see Example 1] or you use the factory method fromGetOptString() method [see Example 2]. It is not recommended to mix the two approaches. You may find further examples in the test cases, which are contained in the source distribution.


Example 1:
import java.util.List;

import com.balsol.grammar.SyntaxException;

public class SampleApp1 {

        public static final String VERSION = "1.00";

        public static void main (String argv[]) throws Exception {
        
                CommandLineParser parser = new CommandLineParser();

                final OptionSpec sHelp =    parser.accept( new String[] {"-h","--help"} );
                final OptionSpec sVersion = parser.accept( new String[] {"-v","--versions"} );
                final OptionSpec sBoolean = parser.accept( new String[] {"-b","--boolean"}, Declaration.OPTIONAL );
                final OptionSpec sInteger = parser.accept( new String[] {"-i","--integer"}, Declaration.OPTIONAL );

                try {
                        CommandLineArguments arguments = parser.parse( argv );

                        Option oHelp = arguments.getOption(sHelp);
                        if( oHelp != null ) {
                                System.out.println(getWelcome());
                                System.out.println(getUsage());
                                System.exit (0);
                        }
        
                        Option oVersion = arguments.getOption(sVersion);
                        if (oVersion != null) {
                                System.out.println(getVersion());
                                System.exit (0);
                        }
        
                        System.out.println(getWelcome());
        
                        Option oBoolean = arguments.getOption(sBoolean);
                        if (oBoolean != null) {
                                boolean value = ArgumentUtil.booleanValueOf(oBoolean);
                                System.out.println( value );
                        }
        
                        Option oInteger = arguments.getOption(sInteger);
                        if (oInteger != null) {
                                int value = ArgumentUtil.intValueOf(oInteger);
                                System.out.println( value );
                        }
        
                        List operands = arguments.getOperands();
                        for(Operand operand : operands ){
                                System.out.println( operand.value );
                        }
                } catch( SyntaxException exception) {
                        System.err.println(exception.getMessage());
                        System.err.println(getUsage());
                        System.exit(64);        // BSD exit code for command line usage error
                }

        }

        protected static String getVersion() {
                return VERSION;
        }

        protected static String getWelcome() {
                String message;

                message =       "\n";
                message +=      "SampleApp1 v" + getVersion() +"\n";
                message +=      "(This product includes  software developed by Balanced Solutions\n"
                                          + " for project BSJT 'http://www.balsol.com/'.)";

                return message;
        }

        protected static String getUsage() {
                String usage;

                usage = "USAGE:  java SampleApp1 (-v | -h) | [-b] [-i] ()\n";
                usage += "\n";
                usage += "    -v, --version\n";
                usage += "        print version info\n";
                usage += "    -h, --help\n";
                usage += "        print help (this text)\n";
                usage += "    -b, --boolean\n";
                usage += "        dummy option (reads a boolean value as argument)\n";
                usage += "    -i, --integer\n";
                usage += "        dummy option (reads an integer as argument)\n";

                return usage;
        }
}

Example 2:
import java.util.List;

import com.balsol.grammar.SyntaxException;

public class SampleApp2 {

        public static final String VERSION = "1.00";

        public static void main (String argv[]) throws Exception {
        
                CommandLineParser parser = CommandLineParser.fromGetOptString("hvb::i::");

                try {
                        CommandLineArguments arguments = parser.parse( argv );

                        Option oHelp = arguments.getOption("-h");
                        if( oHelp != null ) {
                                System.out.println(getWelcome());
                                System.out.println(getUsage());
                                System.exit (0);
                        }
        
                        Option oVersion = arguments.getOption("-v");
                        if (oVersion != null) {
                                System.out.println(getVersion());
                                System.exit (0);
                        }
        
                        System.out.println(getWelcome());
        
                        Option oBoolean = arguments.getOption("-b");
                        if (oBoolean != null) {
                                boolean value = ArgumentUtil.booleanValueOf(oBoolean);
                                System.out.println( value );
                        }
        
                        Option oInteger = arguments.getOption("-i");
                        if (oInteger != null) {
                                int value = ArgumentUtil.intValueOf(oInteger);
                                System.out.println( value );
                        }
        
                        List operands = arguments.getOperands();
                        for(Operand operand : operands ){
                                System.out.println( operand.value );
                        }
                } catch( SyntaxException exception) {
                        System.err.println(exception.getMessage());
                        System.err.println(getUsage());
                        System.exit(64);        // BSD exit code for command line usage error
                }

        }

        protected static String getVersion() {
                return VERSION;
        }

        protected static String getWelcome() {
                String message;

                message =       "\n";
                message +=      "SampleApp1 v" + getVersion() +"\n";
                message +=      "(This product includes  software developed by Balanced Solutions\n"
                                          + " for project BSJT 'http://www.balsol.com/'.)";

                return message;
        }

        protected static String getUsage() {
                String usage;

                usage = "USAGE:  java SampleApp1 (-v | -h) | [-b] [-i] ()\n";
                usage += "\n";
                usage += "    -v\n";
                usage += "        print version info\n";
                usage += "    -h\n";
                usage += "        print help (this text)\n";
                usage += "    -b\n";
                usage += "        dummy option (reads a boolean value as argument)\n";
                usage += "    -iinteger\n";
                usage += "        dummy option (reads an integer as argument)\n";

                return usage;
        }