additional doco tweaks
Project: http://git-wip-us.apache.org/repos/asf/groovy/repo Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/17fbbb85 Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/17fbbb85 Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/17fbbb85 Branch: refs/heads/master Commit: 17fbbb85781e4300560eeafa578bbd336b304b7b Parents: dac0bd8 Author: paulk <pa...@asert.com.au> Authored: Sun Apr 10 20:19:01 2016 +1000 Committer: paulk <pa...@asert.com.au> Committed: Wed Apr 13 20:38:55 2016 +1000 ---------------------------------------------------------------------- src/main/groovy/util/CliBuilder.groovy | 55 ++++++++++++++++++++ .../doc/core-domain-specific-languages.adoc | 2 + src/test/groovy/util/CliBuilderTest.groovy | 4 -- 3 files changed, 57 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/groovy/blob/17fbbb85/src/main/groovy/util/CliBuilder.groovy ---------------------------------------------------------------------- diff --git a/src/main/groovy/util/CliBuilder.groovy b/src/main/groovy/util/CliBuilder.groovy index 91d2938..a5027b4 100644 --- a/src/main/groovy/util/CliBuilder.groovy +++ b/src/main/groovy/util/CliBuilder.groovy @@ -42,6 +42,10 @@ import java.lang.reflect.Method /** * Provides a builder to assist the processing of command line arguments. + * Two styles are supported: dynamic api style (declarative method calls provide a mini DSL for describing options) + * and annotation style (annotations on an interface or class describe options). + * <p> + * <b>Dynamic api style</b> * <p> * Typical usage (emulate partial arg processing of unix command: ls -alt *.groovy): * <pre> @@ -182,10 +186,61 @@ import java.lang.reflect.Method * type: Class * valueSeparator: char * convert: Closure + * defaultValue: String * </pre> * See {@link org.apache.commons.cli.Option} for the meaning of most of these properties * and {@link CliBuilderTest} for further examples. * <p> + * <b>Annotation style with an interface</b> + * <p> + * With this style an interface is defined containing an annotated method for each option. + * It might look like this (following roughly the earlier 'ls' example): + * <pre> + * import groovy.cli.Option + * import groovy.cli.Unparsed + * + * interface OptionInterface { + * @{@link groovy.cli.Option}(shortName='a', description='display all files') boolean all() + * @{@link groovy.cli.Option}(shortName='l', description='use a long listing format') boolean longFormat() + * @{@link groovy.cli.Option}(shortName='t', description='sort by modification time') boolean time() + * @{@link groovy.cli.Unparsed} List remaining() + * } + * </pre> + * Then this description is supplied to CliBuilder during parsing, e.g.: + * <pre> + * def args = '-alt *.groovy'.split() // normally from commandline itself + * def cli = new CliBuilder(usage:'ls') + * def options = cli.parseFromSpec(OptionInterface, args) + * assert options.remaining() == ['*.groovy'] + * assert options.all() && options.longFormat() && options.time() + * </pre> + * <p> + * <b>Annotation style with a class</b> + * <p> + * With this style a user-supplied instance is used. Annotations on that instance's class + * members (properties and setter methods) indicate how to set options and provide the option details + * using annotation attributes. + * It might look like this (again using the earlier 'ls' example): + * <pre> + * import groovy.cli.Option + * import groovy.cli.Unparsed + * + * class OptionClass { + * @{@link groovy.cli.Option}(shortName='a', description='display all files') boolean all + * @{@link groovy.cli.Option}(shortName='l', description='use a long listing format') boolean longFormat + * @{@link groovy.cli.Option}(shortName='t', description='sort by modification time') boolean time + * @{@link groovy.cli.Unparsed} List remaining + * } + * </pre> + * Then this description is supplied to CliBuilder during parsing, e.g.: + * <pre> + * def args = '-alt *.groovy'.split() // normally from commandline itself + * def cli = new CliBuilder(usage:'ls') + * def options = new OptionClass() + * cli.parseFromInstance(options, args) + * assert options.remaining == ['*.groovy'] + * assert options.all && options.longFormat && options.time + * </pre> */ class CliBuilder { http://git-wip-us.apache.org/repos/asf/groovy/blob/17fbbb85/src/spec/doc/core-domain-specific-languages.adoc ---------------------------------------------------------------------- diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc index 8210f5b..e53e436 100644 --- a/src/spec/doc/core-domain-specific-languages.adoc +++ b/src/spec/doc/core-domain-specific-languages.adoc @@ -1182,6 +1182,8 @@ properties are supported when specifying an allowed commandline option: | required | whether the option is mandatory | `boolean` | type | the type of this option | `Class` | valueSeparator | the character that is the value separator | `char`<2> +| defaultValue | a default value | `String` +| convert | converts the incoming String to the required type | `Closure`<2> |====================== <1> More details later <2> Single character Strings are coerced to chars in special cases in Groovy http://git-wip-us.apache.org/repos/asf/groovy/blob/17fbbb85/src/test/groovy/util/CliBuilderTest.groovy ---------------------------------------------------------------------- diff --git a/src/test/groovy/util/CliBuilderTest.groovy b/src/test/groovy/util/CliBuilderTest.groovy index 826e2cd..aa3d680 100644 --- a/src/test/groovy/util/CliBuilderTest.groovy +++ b/src/test/groovy/util/CliBuilderTest.groovy @@ -39,10 +39,6 @@ import static org.apache.commons.cli.Option.builder * In nearly all cases, we now recommend using DefaultParser. In case you have very unique circumstances * and really need behavior that can only be supplied by one of the legacy parsers, we also include * some test case runs against some of the legacy parsers. - * - * @author Dierk König - * @author Russel Winder - * @author Paul King */ class CliBuilderTest extends GroovyTestCase {
