roxspring 2004/12/27 09:41:28 Modified: cli/xdocs/examples ant.xml cli/src/test/org/apache/commons/cli2 DocumentationTest.java Log: Documented ant example Revision Changes Path 1.2 +266 -1 jakarta-commons/cli/xdocs/examples/ant.xml Index: ant.xml =================================================================== RCS file: /home/cvs/jakarta-commons/cli/xdocs/examples/ant.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- ant.xml 2 Sep 2004 13:58:16 -0000 1.1 +++ ant.xml 27 Dec 2004 17:41:27 -0000 1.2 @@ -23,12 +23,277 @@ <body> <section name="ant"> - <p>TODO what is ant</p> + <p> + This example works through modelling Apache Ant using CLI2, the + example is based on Apache Ant version 1.6.1 compiled on February 12 + 2004. + </p> + <p> + "Apache Ant is a Java-based build tool. In theory, it is kind of like + Make, but without Make's wrinkles." - For more information please + visit <a href="http://ant.apache.org/">http://ant.apache.org/</a> + </p> <subsection name="Modelling"> + <p> + To model the ant options we first need to create some Builders so that + each of the option instances can be created: + </p> +<source>final DefaultOptionBuilder obuilder = new DefaultOptionBuilder(); +final ArgumentBuilder abuilder = new ArgumentBuilder(); +final GroupBuilder gbuilder = new GroupBuilder();</source> + <p> + For each option we create an Option instance that will model it, built + using the Builder instances above: + </p> +<source>Option help = + obuilder + .withShortName("help") + .withShortName("h") + .withDescription("print this message") + .create(); +Option projecthelp = + obuilder + .withShortName("projecthelp") + .withShortName("p") + .withDescription("print project help information") + .create(); +Option version = + obuilder + .withShortName("version") + .withDescription("print the version information and exit") + .create(); +Option diagnostics = + obuilder + .withShortName("diagnostics") + .withDescription("print information that might be helpful to diagnose or report problems.") + .create(); +Option quiet = + obuilder + .withShortName("quiet") + .withShortName("q") + .withDescription("be extra quiet") + .create(); +Option verbose = + obuilder + .withShortName("verbose") + .withShortName("v") + .withDescription("be extra verbose") + .create(); +Option debug = + obuilder + .withShortName("debug") + .withShortName("d") + .withDescription("print debugging information") + .create(); +Option emacs = + obuilder + .withShortName("emacs") + .withShortName("e") + .withDescription("produce logging information without adornments") + .create(); +Option lib = + obuilder + .withShortName("lib") + .withDescription("specifies a path to search for jars and classes") + .withArgument( + abuilder + .withName("path") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option logfile = + obuilder + .withShortName("logfile") + .withShortName("l") + .withDescription("use given file for log") + .withArgument( + abuilder + .withName("file") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option logger = + obuilder + .withShortName("logger") + .withDescription("the class which is to perform logging") + .withArgument( + abuilder + .withName("classname") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option listener = + obuilder + .withShortName("listener") + .withDescription("add an instance of class as a project listener") + .withArgument( + abuilder + .withName("classname") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option noinput = + obuilder + .withShortName("noinput") + .withDescription("do not allow interactive input") + .create(); +Option buildfile = + obuilder + .withShortName("buildfile") + .withShortName("file") + .withShortName("f") + .withDescription("use given buildfile") + .withArgument( + abuilder + .withName("file") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option property = new PropertyOption(); +Option propertyfile = + obuilder + .withShortName("propertyfile") + .withDescription("load all properties from file with -D properties taking precedence") + .withArgument( + abuilder + .withName("name") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option inputhandler = + obuilder + .withShortName("inputhandler") + .withDescription("the class which will handle input requests") + .withArgument( + abuilder + .withName("class") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option find = + obuilder + .withShortName("find") + .withShortName("s") + .withDescription("search for buildfile towards the root of the filesystem and use it") + .withArgument( + abuilder + .withName("file") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); +Option targets = abuilder.withName("target").create();</source> + <p> + We now create a Group instance consisting of all the above options: + </p> +<source>Group options = + gbuilder + .withName("options") + .withOption(help) + .withOption(projecthelp) + .withOption(version) + .withOption(diagnostics) + .withOption(quiet) + .withOption(verbose) + .withOption(debug) + .withOption(emacs) + .withOption(lib) + .withOption(logfile) + .withOption(logger) + .withOption(listener) + .withOption(noinput) + .withOption(buildfile) + .withOption(property) + .withOption(propertyfile) + .withOption(inputhandler) + .withOption(find) + .withOption(targets) + .create();</source> </subsection> <subsection name="Querying"> + <p> + Once the model is built, a CommandLine needs to be parsed: + </p> +<source>Parser parser = new Parser(); +parser.setGroup(options); +CommandLine cl = parser.parse(args);</source> + <p> + The CommandLine can be tested for the presence of options using the + hasOption() methods which take either an option instance or a trigger + value to lookup against: + </p> +<source>if(cl.hasOption(help)) { + //displayHelp(); + return; +} +if(cl.hasOption("-version")) { + //displayVersion(); + return; +}</source> + <p> + For those options that have an argument, the argument needs to be + extracted and processed: + </p> +<source>if(cl.hasOption(logfile)) { + String file = (String)cl.getValue(logfile); + //setLogFile(file); +}</source> + <p> + Each target for ant to process could then be processed in order as + specified: + </p> +<source>List targetList = cl.getValues(targets); +for (Iterator i = targetList.iterator(); i.hasNext();) { + String target = (String) i.next(); + //doTarget(target); +}</source> </subsection> <subsection name="Helping"> + <p> + To generate a help page for ant we first need to create a + HelpFormatter and set some basic properties. The shell command is + the command that the used would have typed to invoke the application, + and the group is the group of options that compose the model. + </p> +<source>HelpFormatter hf = new HelpFormatter(); +hf.setShellCommand("ant"); +hf.setGroup(options);</source> + <p> + The first section of help will display the full usage string for the + application, the appearence of this line can be adjusted using the + HelpFormatter's fullUsageSettings property: + </p> +<source>hf.getFullUsageSettings().add(DisplaySetting.DISPLAY_GROUP_NAME); +hf.getFullUsageSettings().add(DisplaySetting.DISPLAY_GROUP_ARGUMENT); +hf.getFullUsageSettings().remove(DisplaySetting.DISPLAY_GROUP_EXPANDED);</source> + <p> + The main body of the help is based on a line or more of information + about each option in the model. DisplaySettings can be used again to + adjust which items are included in this display and which aren't. In + this case, we don't want to display any groups as the top one is the + only one present and can be inferred: + </p> +<source>hf.getDisplaySettings().remove(DisplaySetting.DISPLAY_GROUP_ARGUMENT);</source> + <p> + Each of the options identified by the displaySettings above has some + usage information displayed, usually this will be a minimal set of + DisplaySettings but these can be adjusted to get the desired effect: + </p> +<source>hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PROPERTY_OPTION); +hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PARENT_ARGUMENT); +hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_ARGUMENT_BRACKETED);</source> + <p> + Finally, the help can be printed to System.out with a simple call to + <code>print()</code>: + </p> +<source>hf.print();</source> </subsection> </section> </body> 1.3 +57 -4 jakarta-commons/cli/src/test/org/apache/commons/cli2/DocumentationTest.java Index: DocumentationTest.java =================================================================== RCS file: /home/cvs/jakarta-commons/cli/src/test/org/apache/commons/cli2/DocumentationTest.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- DocumentationTest.java 22 Apr 2004 23:00:06 -0000 1.2 +++ DocumentationTest.java 27 Dec 2004 17:41:27 -0000 1.3 @@ -18,6 +18,8 @@ import java.io.IOException; import java.io.PrintWriter; import java.io.StringWriter; +import java.util.Iterator; +import java.util.List; import junit.framework.TestCase; @@ -147,8 +149,8 @@ } } - public void testExampleAnt() throws IOException { - // Based on Ant 1.5.3 + public void testExampleAnt() throws IOException, OptionException { + // Apache Ant version 1.6.1 compiled on February 12 2004 final DefaultOptionBuilder obuilder = new DefaultOptionBuilder(); final ArgumentBuilder abuilder = new ArgumentBuilder(); @@ -157,11 +159,13 @@ Option help = obuilder .withShortName("help") + .withShortName("h") .withDescription("print this message") .create(); Option projecthelp = obuilder .withShortName("projecthelp") + .withShortName("p") .withDescription("print project help information") .create(); Option version = @@ -189,18 +193,31 @@ Option debug = obuilder .withShortName("debug") + .withShortName("d") .withDescription("print debugging information") .create(); Option emacs = obuilder .withShortName("emacs") + .withShortName("e") .withDescription("produce logging information without adornments") .create(); + Option lib = + obuilder + .withShortName("lib") + .withDescription("specifies a path to search for jars and classes") + .withArgument( + abuilder + .withName("path") + .withMinimum(1) + .withMaximum(1) + .create()) + .create(); Option logfile = obuilder .withShortName("logfile") .withShortName("l") - .withDescription("produce logging information without adornments") + .withDescription("use given file for log") .withArgument( abuilder .withName("file") @@ -230,11 +247,16 @@ .withMaximum(1) .create()) .create(); + Option noinput = + obuilder + .withShortName("noinput") + .withDescription("do not allow interactive input") + .create(); Option buildfile = obuilder .withShortName("buildfile") - .withShortName("b") .withShortName("file") + .withShortName("f") .withDescription("use given buildfile") .withArgument( abuilder @@ -269,6 +291,7 @@ Option find = obuilder .withShortName("find") + .withShortName("s") .withDescription("search for buildfile towards the root of the filesystem and use it") .withArgument( abuilder @@ -290,9 +313,11 @@ .withOption(verbose) .withOption(debug) .withOption(emacs) + .withOption(lib) .withOption(logfile) .withOption(logger) .withOption(listener) + .withOption(noinput) .withOption(buildfile) .withOption(property) .withOption(propertyfile) @@ -300,6 +325,33 @@ .withOption(find) .withOption(targets) .create(); + + ///////////////////////////////////// + String[] args = new String[]{}; + + Parser parser = new Parser(); + parser.setGroup(options); + CommandLine cl = parser.parse(args); + + if(cl.hasOption(help)) { + //displayHelp(); + return; + } + if(cl.hasOption("-version")) { + //displayVersion(); + return; + } + if(cl.hasOption(logfile)) { + String file = (String)cl.getValue(logfile); + //setLogFile(); + } + List targetList = cl.getValues(targets); + for (Iterator i = targetList.iterator(); i.hasNext();) { + String target = (String) i.next(); + //doTarget(target); + } + + ///////////////////////////////////// HelpFormatter hf = new HelpFormatter(); hf.setShellCommand("ant"); @@ -309,6 +361,7 @@ hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PROPERTY_OPTION); hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PARENT_ARGUMENT); + hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_ARGUMENT_BRACKETED); hf.getDisplaySettings().remove(DisplaySetting.DISPLAY_GROUP_ARGUMENT);
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]