CLI-217: More DefaultParser constructor docs.
Project: http://git-wip-us.apache.org/repos/asf/commons-cli/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-cli/commit/23d13f5c Tree: http://git-wip-us.apache.org/repos/asf/commons-cli/tree/23d13f5c Diff: http://git-wip-us.apache.org/repos/asf/commons-cli/diff/23d13f5c Branch: refs/heads/master Commit: 23d13f5c3d7fcf810662c31d147c470e4263fe55 Parents: 86e6c65 Author: Rob Tompkins <chtom...@gmail.com> Authored: Mon Jul 31 11:51:34 2017 -0400 Committer: Rob Tompkins <chtom...@gmail.com> Committed: Mon Jul 31 11:51:34 2017 -0400 ---------------------------------------------------------------------- .../org/apache/commons/cli/DefaultParser.java | 32 +++++++++++++++++++- src/site/xdoc/usage.xml | 15 +++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-cli/blob/23d13f5c/src/main/java/org/apache/commons/cli/DefaultParser.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/cli/DefaultParser.java b/src/main/java/org/apache/commons/cli/DefaultParser.java index fa1720d..cab80eb 100644 --- a/src/main/java/org/apache/commons/cli/DefaultParser.java +++ b/src/main/java/org/apache/commons/cli/DefaultParser.java @@ -57,7 +57,23 @@ public class DefaultParser implements CommandLineParser /** Flag indicating if partial matching of long options is supported. */ private boolean allowPartialMatching; - /** Creates a new DefaultParser instance with partial matching enabled. */ + /** + * Creates a new DefaultParser instance with partial matching enabled. + * + * By "partial matching" we mean that given the following code: + * <pre> + * {@code + * final Options options = new Options(); + * options.addOption(new Option("d", "debug", false, "Turn on debug.")); + * options.addOption(new Option("e", "extract", false, "Turn on extract.")); + * options.addOption(new Option("o", "option", true, "Turn on option with argument.")); + * } + * </pre> + * with "partial matching" turned on, <code>-de</code> only matches the + * <code>"debug"</code> option. However, with "partial matching" disabled, + * <code>-de</code> would enable both <code>debug</code> as well as + * <code>extract</code> options. + */ public DefaultParser() { this.allowPartialMatching = true; } @@ -65,6 +81,20 @@ public class DefaultParser implements CommandLineParser /** * Create a new DefaultParser instance with the specified partial matching policy. * + * By "partial matching" we mean that given the following code: + * <pre> + * {@code + * final Options options = new Options(); + * options.addOption(new Option("d", "debug", false, "Turn on debug.")); + * options.addOption(new Option("e", "extract", false, "Turn on extract.")); + * options.addOption(new Option("o", "option", true, "Turn on option with argument.")); + * } + * </pre> + * with "partial matching" turned on, <code>-de</code> only matches the + * <code>"debug"</code> option. However, with "partial matching" disabled, + * <code>-de</code> would enable both <code>debug</code> as well as + * <code>extract</code> options. + * * @param allowPartialMatching if partial matching of long options shall be enabled */ public DefaultParser(final boolean allowPartialMatching) { http://git-wip-us.apache.org/repos/asf/commons-cli/blob/23d13f5c/src/site/xdoc/usage.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/usage.xml b/src/site/xdoc/usage.xml index 85f9b89..cbf81d8 100644 --- a/src/site/xdoc/usage.xml +++ b/src/site/xdoc/usage.xml @@ -90,6 +90,21 @@ CommandLine cmd = parser.parse( options, args);</source> else { // print the date }</source> + <p> + <h4>Note.</h4> + As of version 1.5-SNAPSHOT (as of 7/31/2017), the + <code>DefaultParser</code>'s constructor now has an override with + the signature <code>DefaultParser(final boolean allowPartialMatching)</code>. + Given the following code: + <source>final Options options = new Options(); +options.addOption(new Option("d", "debug", false, "Turn on debug.")); +options.addOption(new Option("e", "extract", false, "Turn on extract.")); +options.addOption(new Option("o", "option", true, "Turn on option with argument."));</source> + we define "partial matching" as <code>-de</code> only matching the + <code>"debug"</code> option. We can consequently, now, turn this off and have + <code>-de</code> match both the <code>debug</code> option as well as the + <code>extract</code> option. + </p> </subsection> <subsection name="International Time"> <p>