[args4j] 03/05: Imported Upstream version 2.0.26
Emmanuel Bourg
ebourg-guest at moszumanska.debian.org
Mon Mar 3 13:28:50 UTC 2014
This is an automated email from the git hooks/post-receive script.
ebourg-guest pushed a commit to branch master
in repository args4j.
commit 3807d5f8e47ffb044e58e564074a2a40c04af682
Author: Emmanuel Bourg <ebourg at apache.org>
Date: Mon Mar 3 13:21:48 2014 +0100
Imported Upstream version 2.0.26
---
.classpath | 12 ---
.project | 17 ----
.settings/org.eclipse.jdt.core.prefs | 12 ---
args4j-maven-plugin-example/pom.xml | 2 +-
args4j-maven-plugin/pom.xml | 2 +-
args4j-tools/pom.xml | 2 +-
args4j-tools/src/org/kohsuke/args4j/apt/Main.java | 1 +
args4j/lib/ant.jar | Bin 716139 -> 0 bytes
args4j/lib/junit-src.zip | Bin 57635 -> 0 bytes
args4j/lib/junit.jar | Bin 121070 -> 0 bytes
args4j/pom.xml | 2 +-
args4j/src/org/kohsuke/args4j/Argument.java | 2 +-
.../src/org/kohsuke/args4j/CmdLineException.java | 2 +-
args4j/src/org/kohsuke/args4j/CmdLineParser.java | 88 ++++++++++++--------
args4j/src/org/kohsuke/args4j/ExampleMode.java | 2 +-
.../org/kohsuke/args4j/IllegalAnnotationError.java | 4 +-
args4j/src/org/kohsuke/args4j/Option.java | 47 ++++++-----
.../org/kohsuke/args4j/OptionHandlerFilter.java | 14 ++--
args4j/src/org/kohsuke/args4j/package.html | 92 ++++++++++++---------
.../kohsuke/args4j/spi/DelimitedOptionHandler.java | 6 +-
.../org/kohsuke/args4j/spi/MapOptionHandler.java | 8 +-
.../src/org/kohsuke/args4j/spi/OptionHandler.java | 13 +--
args4j/src/org/kohsuke/args4j/spi/Parameters.java | 8 +-
.../kohsuke/args4j/spi/RestOfArgumentsHandler.java | 5 +-
args4j/src/org/kohsuke/args4j/spi/Setter.java | 34 ++++----
.../org/kohsuke/args4j/spi/StopOptionHandler.java | 12 +--
.../args4j/spi/StringArrayOptionHandler.java | 25 +++---
.../org/kohsuke/args4j/spi/SubCommandHandler.java | 16 ++--
args4j/test/org/kohsuke/args4j/KeyValue.java | 12 +++
args4j/test/org/kohsuke/args4j/KeyValueTest.java | 22 +++++
pom.xml | 2 +-
src/site/apt/apt.apt | 4 +-
src/site/apt/implementOptionhandler.apt | 4 +-
src/site/apt/index.apt | 14 ++--
src/site/apt/sample.apt | 40 +++++----
35 files changed, 288 insertions(+), 238 deletions(-)
diff --git a/.classpath b/.classpath
deleted file mode 100644
index 327c709..0000000
--- a/.classpath
+++ /dev/null
@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<classpath>
- <classpathentry kind="src" path="args4j-tools/src"/>
- <classpathentry kind="src" output="args4j/target/examples" path="args4j/examples"/>
- <classpathentry kind="src" output="args4j/target/classes" path="args4j/src"/>
- <classpathentry kind="src" output="args4j/target/test-classes" path="args4j/test"/>
- <classpathentry kind="lib" path="args4j/lib/ant.jar"/>
- <classpathentry kind="lib" path="C:/jdk/150_14/lib/tools.jar"/>
- <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/150_14"/>
- <classpathentry kind="con" path="org.eclipse.jdt.junit.JUNIT_CONTAINER/4"/>
- <classpathentry kind="output" path="bin"/>
-</classpath>
diff --git a/.project b/.project
deleted file mode 100644
index 95c7aa3..0000000
--- a/.project
+++ /dev/null
@@ -1,17 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>args4j</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.jdt.core.javabuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.jdt.core.javanature</nature>
- </natures>
-</projectDescription>
diff --git a/.settings/org.eclipse.jdt.core.prefs b/.settings/org.eclipse.jdt.core.prefs
deleted file mode 100644
index 8923d4d..0000000
--- a/.settings/org.eclipse.jdt.core.prefs
+++ /dev/null
@@ -1,12 +0,0 @@
-#Wed Jun 18 20:01:43 CEST 2008
-eclipse.preferences.version=1
-org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
-org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
-org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
-org.eclipse.jdt.core.compiler.compliance=1.5
-org.eclipse.jdt.core.compiler.debug.lineNumber=generate
-org.eclipse.jdt.core.compiler.debug.localVariable=generate
-org.eclipse.jdt.core.compiler.debug.sourceFile=generate
-org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
-org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
-org.eclipse.jdt.core.compiler.source=1.5
diff --git a/args4j-maven-plugin-example/pom.xml b/args4j-maven-plugin-example/pom.xml
index d41fdf4..36f6128 100644
--- a/args4j-maven-plugin-example/pom.xml
+++ b/args4j-maven-plugin-example/pom.xml
@@ -4,7 +4,7 @@
<parent>
<groupId>args4j</groupId>
<artifactId>args4j-site</artifactId>
- <version>2.0.25</version>
+ <version>2.0.26</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>args4j-maven-plugin-example</artifactId>
diff --git a/args4j-maven-plugin/pom.xml b/args4j-maven-plugin/pom.xml
index 9d634f8..b179632 100644
--- a/args4j-maven-plugin/pom.xml
+++ b/args4j-maven-plugin/pom.xml
@@ -4,7 +4,7 @@
<parent>
<groupId>args4j</groupId>
<artifactId>args4j-site</artifactId>
- <version>2.0.25</version>
+ <version>2.0.26</version>
<relativePath>../pom.xml</relativePath>
</parent>
<groupId>org.kohsuke.args4j</groupId>
diff --git a/args4j-tools/pom.xml b/args4j-tools/pom.xml
index c1edf8f..b9e9a9b 100644
--- a/args4j-tools/pom.xml
+++ b/args4j-tools/pom.xml
@@ -4,7 +4,7 @@
<parent>
<groupId>args4j</groupId>
<artifactId>args4j-site</artifactId>
- <version>2.0.25</version>
+ <version>2.0.26</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>args4j-tools</artifactId>
diff --git a/args4j-tools/src/org/kohsuke/args4j/apt/Main.java b/args4j-tools/src/org/kohsuke/args4j/apt/Main.java
index 3839447..92d0205 100644
--- a/args4j-tools/src/org/kohsuke/args4j/apt/Main.java
+++ b/args4j-tools/src/org/kohsuke/args4j/apt/Main.java
@@ -15,6 +15,7 @@ import java.util.List;
/**
* Entry point that invokes APT.
+ *
* @author Kohsuke Kawaguchi
*/
public class Main {
diff --git a/args4j/lib/ant.jar b/args4j/lib/ant.jar
deleted file mode 100644
index 310e105..0000000
Binary files a/args4j/lib/ant.jar and /dev/null differ
diff --git a/args4j/lib/junit-src.zip b/args4j/lib/junit-src.zip
deleted file mode 100644
index 63c80be..0000000
Binary files a/args4j/lib/junit-src.zip and /dev/null differ
diff --git a/args4j/lib/junit.jar b/args4j/lib/junit.jar
deleted file mode 100644
index 674d71e..0000000
Binary files a/args4j/lib/junit.jar and /dev/null differ
diff --git a/args4j/pom.xml b/args4j/pom.xml
index bbd0d74..0d6a704 100644
--- a/args4j/pom.xml
+++ b/args4j/pom.xml
@@ -3,7 +3,7 @@
<parent>
<groupId>args4j</groupId>
<artifactId>args4j-site</artifactId>
- <version>2.0.25</version>
+ <version>2.0.26</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>args4j</artifactId>
diff --git a/args4j/src/org/kohsuke/args4j/Argument.java b/args4j/src/org/kohsuke/args4j/Argument.java
index 28f9829..145d840 100644
--- a/args4j/src/org/kohsuke/args4j/Argument.java
+++ b/args4j/src/org/kohsuke/args4j/Argument.java
@@ -53,7 +53,7 @@ public @interface Argument {
*
* <p>
* If you define multiple single value properties to bind to arguments,
- * they should have index=0, index=1, index=2, ... and so on.
+ * they should have {@code index=0, index=1, index=2}, ... and so on.
*
* <p>
* Multi value properties bound to arguments must be always the last entry.
diff --git a/args4j/src/org/kohsuke/args4j/CmdLineException.java b/args4j/src/org/kohsuke/args4j/CmdLineException.java
index 7151801..340971e 100644
--- a/args4j/src/org/kohsuke/args4j/CmdLineException.java
+++ b/args4j/src/org/kohsuke/args4j/CmdLineException.java
@@ -56,7 +56,7 @@ public class CmdLineException extends Exception {
*
* <p>
* Unless you have legacy {@link OptionHandler} that doesn't pass in this information
- * when it throws an exception, this method should always return a non-null value. a
+ * when it throws an exception, this method should always return a non-null value.
*/
public CmdLineParser getParser() {
return parser;
diff --git a/args4j/src/org/kohsuke/args4j/CmdLineParser.java b/args4j/src/org/kohsuke/args4j/CmdLineParser.java
index aa7dba3..5a3f1df 100644
--- a/args4j/src/org/kohsuke/args4j/CmdLineParser.java
+++ b/args4j/src/org/kohsuke/args4j/CmdLineParser.java
@@ -49,7 +49,7 @@ import org.kohsuke.args4j.spi.URLOptionHandler;
* Command line argument owner.
*
* <p>
- * For a typical usage, see <a href="https://args4j.dev.java.net/source/browse/args4j/args4j/examples/SampleMain.java?view=markup">this example</a>.
+ * For typical usage, see <a href="https://args4j.dev.java.net/source/browse/args4j/args4j/examples/SampleMain.java?view=markup">this example</a>.
*
* @author
* Kohsuke Kawaguchi (kk at kohsuke.org)
@@ -70,8 +70,9 @@ public class CmdLineParser {
/**
* The length of a usage line.
- * If the usage message is longer than this value, the parser
- * wraps the line. Defaults to 80.
+ * If the usage message is longer than this value, the parser wraps the line.
+ *
+ * Defaults to {@code 80}.
*/
private int usageWidth = 80;
@@ -82,7 +83,7 @@ public class CmdLineParser {
*
* @param bean
* instance of a class annotated by {@link Option} and {@link Argument}.
- * this object will receive values. If this is null, the processing will
+ * this object will receive values. If this is {@code null}, the processing will
* be skipped, which is useful if you'd like to feed metadata from other sources.
*
* @throws IllegalAnnotationError
@@ -105,7 +106,7 @@ public class CmdLineParser {
}
/**
- * Programmatically defines an argument (instead of reading it from annotations like you normally do.)
+ * Programmatically defines an argument (instead of reading it from annotations as normal).
*
* @param setter the setter for the type
* @param a the Argument
@@ -124,10 +125,10 @@ public class CmdLineParser {
}
/**
- * Programmatically defines an option (instead of reading it from annotations like you normally do.)
+ * Programmatically defines an option (instead of reading it from annotations as normal).
*
* @param setter the setter for the type
- * @param o the Option
+ * @param o the {@code Option}
*/
public void addOption(Setter setter, Option o) {
checkOptionNotInMap(o.name());
@@ -199,9 +200,9 @@ public class CmdLineParser {
* See {@link #printExample(OptionHandlerFilter, ResourceBundle)} for more details.
*
* @param filter
- * must not be null.
+ * must not be {@code null}.
* @return
- * always non-null.
+ * always non-{@code null}.
*/
public String printExample(OptionHandlerFilter filter) {
return printExample(filter,null);
@@ -219,28 +220,27 @@ public class CmdLineParser {
* Formats a command line example into a string.
*
* <p>
- * This method produces a string like " -d <dir> -v -b",
- * which is useful for printing a command line example, perhaps
- * as a part of the usage screen.
+ * This method produces a string like <samp> -d <dir> -v -b</samp>.
+ * This is useful for printing a command line example (perhaps
+ * as a part of the usage screen).
*
*
* @param mode
* Determines which options will be a part of the returned string.
- * Must not be null.
+ * Must not be {@code null}.
* @param rb
- * If non-null, meta variables (<dir> in the above example)
+ * If non-{@code null}, meta variables (<samp><dir></samp> in the above example)
* is treated as a key to this resource bundle, and the associated
* value is printed. See {@link Option#metaVar()}. This is to support
* localization.
*
- * Passing <tt>null</tt> would print {@link Option#metaVar()} directly.
+ * Passing {@code null} would print {@link Option#metaVar()} directly.
* @return
- * always non-null. If there's no option, this method returns
- * just the empty string "". Otherwise, this method returns a
- * string that contains a space at the beginning (but not at the end.)
+ * always non-{@code null}. If there's no option, this method returns
+ * just the empty string {@code ""}. Otherwise, this method returns a
+ * string that contains a space at the beginning (but not at the end).
* This allows you to do something like:
- *
- * <pre>System.err.println("java -jar my.jar"+parser.printExample(REQUIRED)+" arg1 arg2");</pre>
+ * <code><pre>System.err.println("java -jar my.jar"+parser.printExample(REQUIRED)+" arg1 arg2");</pre></code>
*/
public String printExample(OptionHandlerFilter mode,ResourceBundle rb) {
StringBuilder buf = new StringBuilder();
@@ -290,7 +290,7 @@ public class CmdLineParser {
* Prints the list of all the non-hidden options and their usages to the screen.
*
* @param rb
- * if this is non-null, {@link Option#usage()} is treated
+ * If non-{@code null}, {@link Option#usage()} is treated
* as a key to obtain the actual message from this resource bundle.
* @param filter
* Controls which options to be printed.
@@ -320,16 +320,16 @@ public class CmdLineParser {
}
/**
- * Prints the usage information for a given option.
+ * Prints usage information for a given option.
*
* <p>
- * Subtypes can override this method and determine which options get printed and what not,
- * based on {@link OptionHandler}, perhaps by using {@code handler.setter.asAnnotatedElement()}
+ * Subtypes may override this method and determine which options get printed (or other things),
+ * based on {@link OptionHandler} (perhaps by using {@code handler.setter.asAnnotatedElement()}).
*
* @param out Writer to write into
* @param handler handler where to receive the information
* @param len Maximum length of metadata column
- * @param rb ResourceBundle for I18N
+ * @param rb {@code ResourceBundle} for I18N
* @see Setter#asAnnotatedElement()
*/
protected void printOption(PrintWriter out, OptionHandler handler, int len, ResourceBundle rb, OptionHandlerFilter filter) {
@@ -367,6 +367,7 @@ public class CmdLineParser {
/**
* Wraps a line so that the resulting parts are not longer than a given maximum length.
+ *
* @param line Line to wrap
* @param maxLength maximum length for the resulting parts
* @return list of all wrapped parts
@@ -398,7 +399,7 @@ public class CmdLineParser {
/**
* Essentially a pointer over a {@link String} array.
- * Can move forward, can look ahead.
+ * Can move forward; can look ahead.
*/
private class CmdLineImpl implements Parameters {
private final String[] args;
@@ -422,7 +423,7 @@ public class CmdLineParser {
}
public String getParameter(int idx) throws CmdLineException {
- if( pos+idx>=args.length )
+ if( pos+idx>=args.length || pos+idx<0 )
throw new CmdLineException(CmdLineParser.this, Messages.MISSING_OPERAND.format(getOptionName()));
return args[pos+idx];
}
@@ -430,6 +431,19 @@ public class CmdLineParser {
public int size() {
return args.length-pos;
}
+
+ /**
+ * Used when the current token is of the form "-option=value",
+ * to replace the current token by "value", as if this was given as two tokens "-option value"
+ */
+ void splitToken() {
+ if (pos < args.length && pos >= 0) {
+ int idx = args[pos].indexOf("=");
+ if (idx > 0) {
+ args[pos] = args[pos].substring(idx + 1);
+ }
+ }
+ }
}
private String getOptionName() {
@@ -472,7 +486,11 @@ public class CmdLineParser {
}
// known option; skip its name
- cmdLine.proceed(1);
+ if (isKeyValuePair) {
+ cmdLine.splitToken();
+ } else {
+ cmdLine.proceed(1);
+ }
} else {
if (argIndex >= arguments.size()) {
Messages msg = arguments.size() == 0 ? Messages.NO_ARGUMENT_ALLOWED : Messages.TOO_MANY_ARGUMENTS;
@@ -514,7 +532,7 @@ public class CmdLineParser {
/**
* @param option
* @param present
- * @return true if all options required by <code>option</code> are present, false otherwise
+ * @return {@code true} if all options required by {@code option} are present, {@code false} otherwise
*/
private boolean isHandlerHasHisOptions(NamedOptionDef option, Set<OptionHandler> present) {
if (option.depends() != null) {
@@ -542,9 +560,9 @@ public class CmdLineParser {
}
/**
- * Finds a registered OptionHandler by its name or its alias.
+ * Finds a registered {@code OptionHandler} by its name or its alias.
* @param name name
- * @return the OptionHandler or <tt>null</tt>
+ * @return the {@code OptionHandler} or {@code null}
*/
private OptionHandler findOptionByName(String name) {
for (OptionHandler h : options) {
@@ -565,15 +583,15 @@ public class CmdLineParser {
private Map<String,OptionHandler> filter(List<OptionHandler> opt, String keyFilter) {
Map<String,OptionHandler> rv = new TreeMap<String,OptionHandler>();
for (OptionHandler h : opt) {
- if (opt.toString().startsWith(keyFilter)) rv.put(opt.toString(), h);
+ if (h.option.toString().startsWith(keyFilter)) rv.put(h.option.toString(), h);
}
return rv;
}
/**
- * Returns true if the given token is an option
- * (as opposed to an argument.)
+ * Returns {@code true} if the given token is an option
+ * (as opposed to an argument).
*/
protected boolean isOption(String arg) {
return parsingOptions && arg.startsWith("-");
@@ -676,7 +694,7 @@ public class CmdLineParser {
* Prints a single-line usage to the screen.
*
* @param rb
- * if this is non-null, {@link Option#usage()} is treated
+ * if this is non-{@code null}, {@link Option#usage()} is treated
* as a key to obtain the actual message from this resource bundle.
*/
public void printSingleLineUsage(Writer w, ResourceBundle rb) {
diff --git a/args4j/src/org/kohsuke/args4j/ExampleMode.java b/args4j/src/org/kohsuke/args4j/ExampleMode.java
index 3987063..3f2edb5 100644
--- a/args4j/src/org/kohsuke/args4j/ExampleMode.java
+++ b/args4j/src/org/kohsuke/args4j/ExampleMode.java
@@ -14,7 +14,7 @@ public enum ExampleMode implements OptionHandlerFilter {
* Print all defined options in the example.
*
* <p>
- * This would be useful only when you have small number of options.
+ * This would only be useful with small numbers of options.
*/
ALL() {
public boolean select(OptionHandler o) {
diff --git a/args4j/src/org/kohsuke/args4j/IllegalAnnotationError.java b/args4j/src/org/kohsuke/args4j/IllegalAnnotationError.java
index d7fab10..80cd937 100644
--- a/args4j/src/org/kohsuke/args4j/IllegalAnnotationError.java
+++ b/args4j/src/org/kohsuke/args4j/IllegalAnnotationError.java
@@ -5,8 +5,8 @@ package org.kohsuke.args4j;
*
* <p>
* This only happens when there's something wrong with the way you use
- * args4j in your code, not when the arguments supplied by the user is
- * wrong. Hence this class is an {@link Error}.
+ * args4j in your code--<em>not</em> when the user's arguments are wrong.
+ * Therefore, this class is an {@link Error}.
*
* @author Kohsuke Kawaguchi
*/
diff --git a/args4j/src/org/kohsuke/args4j/Option.java b/args4j/src/org/kohsuke/args4j/Option.java
index b78b6cd..4132fbb 100644
--- a/args4j/src/org/kohsuke/args4j/Option.java
+++ b/args4j/src/org/kohsuke/args4j/Option.java
@@ -19,7 +19,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
*
* <p>
* This annotation can be placed on a field of type T or the method
- * of the form <tt>void <i>methodName</i>(T value)</tt>. Its access
+ * of the form <code>void <i><samp>methodName</samp></i>(T value)</code>. Its access
* modified can be anything, but if it's not public, your application
* needs to run in a security context that allows args4j to access
* the field/method (see {@link AccessibleObject#setAccessible(boolean)}.
@@ -30,38 +30,38 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
*
* <h2>Boolean Switch</h2>
* <p>
- * When T is boolean , it represents
- * a boolean option that takes the form of "-OPT". When this option is set,
- * the property will be set to true.
+ * When <var>T</var> is {@code boolean} , it represents
+ * a {@code boolean} option that takes the form of <samp>-OPT</samp>. When this option is set,
+ * the property will be set to {@code true}.
*
* <h2>String Switch</h2>
* <p>
- * When T is {@link String}, it represents
+ * When <var>T</var> is {@link String}, it represents
* an option that takes one operand. The value of the operand is set
* to the property.
*
* <h2>Enum Switch</h2>
* <p>
- * When T is derived from {@link Enum}, it represents an option that takes
+ * When <var>T</var> is derived from {@link Enum}, it represents an option that takes
* an operand, which must be one of the enum constant. The comparion between
* the operand and the enum constant name is done in a case insensitive fashion.
* <p>
* For example, the following definition will represent command line options
- * like "-coin penny" or "-coin DIME" but things like "-coin" or "-coin abc" are
- * errors.
+ * like <samp>-coin penny</samp> or <samp>-coin DIME</samp>,
+ * but things like <samp>-coin</samp> or <samp>-coin abc</samp> are errors.
*
- * <pre>
+ * <code><pre>
* enum Coin { PENNY,NICKEL,DIME,QUARTER }
*
* class Option {
* @Option(name="-coin")
* public Coin coin;
* }
- * </pre>
+ * </pre></code>
*
* <h2>File Switch</h2>
* <p>
- * When T is a {@link File}, it represents an option that takes a file/directory
+ * When <var>T</var> is a {@link File}, it represents an option that takes a file/directory
* name as an operand.
*
* @author Kohsuke Kawaguchi
@@ -70,12 +70,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Target({FIELD,METHOD,PARAMETER})
public @interface Option {
/**
- * Name of the option, such as "-foo" or "-bar".
+ * Name of the option, such as <samp>-foo</samp> or <samp>-bar</samp>.
*/
String name();
/**
- * Aliases for the options, such as "--long-option-name".
+ * Aliases for the options, such as <samp>--long-option-name</samp>.
*/
String[] aliases() default { };
@@ -102,11 +102,13 @@ public @interface Option {
String usage() default "";
/**
- * When the option takes an operand, the usage screen will show something like this:
- * <pre>
+ * When the option takes an operand, the usage screen will show something like this
+ *
+ * <code><pre>
* -x FOO : blah blah blah
- * </pre>
- * You can replace the 'FOO' token by using this parameter.
+ * </pre></code>
+ *
+ * You can replace the <samp>FOO</samp> token by using this parameter.
*
* <p>
* If left unspecified, this value is infered from the type of the option.
@@ -164,7 +166,8 @@ public @interface Option {
* defining a non-standard option parsing semantics.
*
* <h3>Example</h3>
- * <pre>
+ *
+ * <code><pre>
* // this is a normal "-r" option
* @Option(name="-r")
* boolean value;
@@ -173,7 +176,7 @@ public @interface Option {
* // handler provided for boolean
* @Option(name="-b",handler=MyHandler.class)
* boolean value;
- * </pre>
+ * </pre></code>
*/
Class<? extends OptionHandler> handler() default OptionHandler.class;
@@ -181,13 +184,15 @@ public @interface Option {
* List of other options that this option depends on.
*
* <h3>Example</h3>
- * <pre>
+ *
+ * <code><pre>
* @Option(name="-a")
* int a;
* //-b is not required but if it's provided, then a becomes required
* @Option(name="-b", depends={"-a"}
* int b;
- * </pre>
+ * </pre></code>
+ *
* <p>
* At the end of {@link CmdLineParser#parseArgument(String...)},
* a {@link CmdLineException} will be thrown if options required by another one
diff --git a/args4j/src/org/kohsuke/args4j/OptionHandlerFilter.java b/args4j/src/org/kohsuke/args4j/OptionHandlerFilter.java
index a7447a1..894662a 100644
--- a/args4j/src/org/kohsuke/args4j/OptionHandlerFilter.java
+++ b/args4j/src/org/kohsuke/args4j/OptionHandlerFilter.java
@@ -9,8 +9,8 @@ import java.util.ResourceBundle;
* Selects {@link OptionHandler}.
*
* <p>
- * For example, we use this to let the caller specify which options get printed
- * and which ones don't.
+ * For example, we use this to let the caller specify which
+ * options are printed, and which ones aren't.
*
* @author Kohsuke Kawaguchi
* @see CmdLineParser#printExample(OptionHandlerFilter)
@@ -20,9 +20,9 @@ public interface OptionHandlerFilter {
/**
*
* @param o
- * Never null. Internally options (like "-r") and arguments (others)
- * are treated uniformly as {@link OptionHandler}. See
- * {@link OptionDef#isArgument()} to distinguish them.
+ * Never {@code null}. Internally options (like <samp>-r</samp>) and arguments (others)
+ * are treated uniformly as {@link OptionHandler}.
+ * See {@link OptionDef#isArgument()} to distinguish them.
* @return
* true to choose this option, false to ignore/discard/disregard it.
*/
@@ -41,7 +41,7 @@ public interface OptionHandlerFilter {
* Print all {@linkplain Option#hidden() non-hidden} options.
*
* <p>
- * This would be useful only when you have small number of options.
+ * This would only be useful with a small number of options.
*/
OptionHandlerFilter PUBLIC = new OptionHandlerFilter() {
public boolean select(OptionHandler o) {
@@ -50,7 +50,7 @@ public interface OptionHandlerFilter {
};
/**
- * Print all {@linkplain Option#required() required} option.
+ * Print all {@linkplain Option#required() required} options.
*/
OptionHandlerFilter REQUIRED = new OptionHandlerFilter() {
public boolean select(OptionHandler o) {
diff --git a/args4j/src/org/kohsuke/args4j/package.html b/args4j/src/org/kohsuke/args4j/package.html
index bac7614..3d2cc74 100644
--- a/args4j/src/org/kohsuke/args4j/package.html
+++ b/args4j/src/org/kohsuke/args4j/package.html
@@ -1,31 +1,45 @@
-<html><body>
+<html>
+<body>
+
<p>Core classes of the Args4J command line parser.</p>
-<h1>What is Args4J</h1>
-<p>Args4J is a command line parser. As such a parser its job is to parse the String-array passed to the main() method
-and transfer the values to a java object, which includes type conversion. The entry point into this parsing is
-the CmdLineParser class with its parse() Method.</p>
-<p>Args4J must know the mapping between the flag from the command line and the target for the value.
-There are multiple ways for Args4J: <ul>
- <li>place an @Option or @Argument annotation at a setter or on a field</li>
- <li>provide a XML configuration file</li>
- <li>make all fields public available</li>
-</ul>
-depending on what you want, you have to do a configuration step before starting the parsing.</p>
+<h1>What is Args4J?</h1>
+
+ <p>
+ Args4J is a command line parser.
+ As such, its job is to parse the String-array passed to the <code>main()</code> method and
+ transfer the values to a Java object, which includes type conversion.
+ The entry point into this parsing is the <code>CmdLineParser</code> class,
+ with its <code>parse()</code> method.
+ </p>
+
+ <p>Args4J must know the mapping between the flag from the command line and the target for the value.
+ There are many ways to use Args4J:</p>
+
+ <ul>
+ <li>place an <code>@Option</code> or <code>@Argument</code> annotation at a setter or on a field</li>
+ <li>provide a XML configuration file</li>
+ <li>make all fields publicly available</li>
+ </ul>
+
+ <p>Depending on what you want, you may have perform a configuration step before parsing.</p>
+
<h1>Examples</h1>
-<p><tt>java Main -text newText</tt></p>
+<p><code>java Main -text newText</code></p>
+
+<p>The typical use involves writing a small bean class and providing the annotations.</p>
+<p>This feature is available since the first Args4J release:</p>
-<p>The standard use case is having a bean class and providing the annotations.
-This feature is available since the first Args4J release:
<!-- TODO:
-Javadoc stops when reaching the at-sign. When I load the package.html directly into Firefox,
-all is fine. But when creating the javadoc it stops copying the content at that sign.
-(a) is a compromise here ...
-Does anyone know how to handle that?
+ Javadoc stops when reaching the at-sign. When I load the package.html directly into Firefox,
+ all is fine. But when creating the javadoc it stops copying the content at that sign.
+ (a) is a compromise here ...
+
+ Does anyone know how to handle that?
-->
-<pre>
+<code><pre>
public class Bean {
(a)Option(name="-text")
String text;
@@ -37,14 +51,16 @@ public class Main {
parser.parse(args);
}
}
-</pre>
-
-<p>An easy way for initializing fields and not touching the bean source code
-is using the FieldParser. The FieldParser scans all fields of the bean class
-(including inheritance) and makes them public available as options with
-a '-' prefix in the name.
-This feature is available since Args4J release 2.0.16:
-<pre>
+</pre></code>
+
+
+<p>An easy way to initialize fields without touching the bean source code is to use the <code>FieldParser</code>.</p>
+
+<p>The <code>FieldParser</code> scans all fields of bean class (including inheritance), and makes them publicly available as options with a <code>-</code> prefix in the name.</p>
+
+<p>This feature is available since Args4J release 2.0.16:</p>
+
+<code><pre>
public class Bean {
String text;
}
@@ -56,13 +72,14 @@ public class Main {
parser.parse(args);
}
}
-</pre>
+</pre></code>
-<p>While the FieldParser is easier to use, the XmlParser supports more features.
-That said it supports all features which are available via annotations: usage text, specifying handlers and more.
-You have to provide an XML InputSource or an URL to the XML file.
-This feature is available since Args4J release 2.0.16:
-<pre>
+<p>While the <code>FieldParser</code> is easier to use, the <code>XmlParser</code> supports more features.</p>
+<p>That said, it supports all features which are available via annotations: usage text, specifying handlers, and more. You have to provide an XML <code>InputSource</code> or a URL to the XML file.</p>
+
+<p>This feature is available since Args4J release 2.0.16:</p>
+
+<code><pre>
public class Bean {
String text;
}
@@ -77,8 +94,7 @@ public class Main {
<args>
<option field="text" name="-text" usage="Output text"/>
</args>
-</pre>
-</p>
-
+</pre></code>
-</body></html>
\ No newline at end of file
+</body>
+</html>
\ No newline at end of file
diff --git a/args4j/src/org/kohsuke/args4j/spi/DelimitedOptionHandler.java b/args4j/src/org/kohsuke/args4j/spi/DelimitedOptionHandler.java
index b00114d..def390d 100644
--- a/args4j/src/org/kohsuke/args4j/spi/DelimitedOptionHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/DelimitedOptionHandler.java
@@ -7,11 +7,11 @@ import org.kohsuke.args4j.OptionDef;
/**
* Partial {@link OptionHandler} implementation that takes a single value to the option,
- * which is then gets split into individual tokens by looking at a fixed delimiter.
+ * which is then gets split into individual tokens using fixed delimiter.
*
* <p>
- * This class is marked as abstract even though it has no abstract method,
- * to signify the fact that the class by itself cannot be used in {@link Option#handler()}
+ * This class is marked as {@code abstract} even though it has no abstract methods
+ * to indicate that the class cannot be used by itself in {@link Option#handler()},
* due to the extra argument that it takes.
*
* @author kmahoney
diff --git a/args4j/src/org/kohsuke/args4j/spi/MapOptionHandler.java b/args4j/src/org/kohsuke/args4j/spi/MapOptionHandler.java
index f513ef6..06ce323 100644
--- a/args4j/src/org/kohsuke/args4j/spi/MapOptionHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/MapOptionHandler.java
@@ -8,17 +8,17 @@ import org.kohsuke.args4j.*;
/**
* Parses options into a {@link Map}.
*
- * <pre>
+ * <code><pre>
* class Foo {
* @Option(name="-P",handler={@link MapOptionHandler}.class)
* Map<String,String> args;
* }
- * </pre>
+ * </pre></code>
*
* <p>
- * With this, <tt>-P x=1 -P y=2</tt> parses to map of size 2.
+ * With this, <samp>-P x=1 -P y=2</samp> parses to map of size {@code 2}.
* This option handler can be subtyped if you want to convert values to different types
- * or to handle key=value in other formats, like "key:=value".
+ * or to handle <samp>key=value</samp> in other formats, like <samp>key:=value</samp>.
* */
public class MapOptionHandler extends OptionHandler<Map<?,?>> {
diff --git a/args4j/src/org/kohsuke/args4j/spi/OptionHandler.java b/args4j/src/org/kohsuke/args4j/spi/OptionHandler.java
index 8e78081..beccd26 100644
--- a/args4j/src/org/kohsuke/args4j/spi/OptionHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/OptionHandler.java
@@ -19,9 +19,10 @@ import org.kohsuke.args4j.CmdLineParser;
* {@link CmdLineParser#registerHandler(Class,Class)}
*
* @param <T>
- * The "component" type of the field that this {@link OptionHandler} works with.
- * When I say "component", what I mean is that for a field that can hold multiple values
- * (such as {@link Collection} or array), this should refer to its component time.
+ * The {@code component} type of the field that this {@link OptionHandler} works with.
+ * When I say "component", I mean a field that can hold multiple values
+ * (such as {@link Collection} or array). This should refer to its component time.
+ *
* {@link Setter} implementations abstract away multi-value-ness by allowing {@link OptionHandler}
* to invoke its {@link Setter#addValue(Object)} multiple times.
*
@@ -57,15 +58,15 @@ public abstract class OptionHandler<T> {
* The object is valid only during the method call.
*
* @return
- * The number of arguments consumed. For example, return 0
- * if this option doesn't take any parameter.
+ * The number of arguments consumed. (For example, returns {@code 0}
+ * if this option doesn't take any parameters.)
*/
public abstract int parseArguments( Parameters params ) throws CmdLineException;
/**
* Gets the default meta variable name used to print the usage screen.
*
- * @return null to hide a meta variable.
+ * @return {@code null} to hide a meta variable.
*/
public abstract String getDefaultMetaVariable();
diff --git a/args4j/src/org/kohsuke/args4j/spi/Parameters.java b/args4j/src/org/kohsuke/args4j/spi/Parameters.java
index 9fc2e6b..28efc39 100644
--- a/args4j/src/org/kohsuke/args4j/spi/Parameters.java
+++ b/args4j/src/org/kohsuke/args4j/spi/Parameters.java
@@ -16,12 +16,12 @@ public interface Parameters {
*
* @param idx
* specifying 0 will retrieve the token next to the option.
- * For example, if the command line looks like "-o abc -d x",
- * then <code>getParameter(0)</code> for "-o" returns "abc"
- * and <code>getParameter(1)</code> will return "-d".
+ * For example, if the command line looks like <samp>-o abc -d x</samp>,
+ * then {@code getParameter(0)} for <samp>-o</samp> returns {@code abc}
+ * and {@code getParameter(1)} will return <samp>-d</samp>.
*
* @return
- * Always return non-null valid String. If an attempt is
+ * Always return non-{@code null} valid {@code String}. If an attempt is
* made to access a non-existent index, this method throws
* appropriate {@link org.kohsuke.args4j.CmdLineException}.
*/
diff --git a/args4j/src/org/kohsuke/args4j/spi/RestOfArgumentsHandler.java b/args4j/src/org/kohsuke/args4j/spi/RestOfArgumentsHandler.java
index 6cfdd7b..d1a4001 100644
--- a/args4j/src/org/kohsuke/args4j/spi/RestOfArgumentsHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/RestOfArgumentsHandler.java
@@ -11,8 +11,9 @@ import org.kohsuke.args4j.CmdLineException;
* <p>
* Used with {@link Argument}, this implements a semantics where
* non-option token causes the option parsing to terminate.
- * An example of this is ssh(1), where "ssh -p 222 abc" will treat "-p" as an option
- * to ssh but "ssh abc -p 222" is considered to have no option for ssh.
+ * An example of this is <tt>ssh(1)</tt>, where <samp>ssh -p 222 abc</samp> will treat
+ * <samp>-p</samp> as an option to <tt>ssh</tt>, but <samp>ssh abc -p 222</samp> is
+ * considered to have no option for <tt>ssh</tt>.
*
* @author Kohsuke Kawaguchi
*/
diff --git a/args4j/src/org/kohsuke/args4j/spi/Setter.java b/args4j/src/org/kohsuke/args4j/spi/Setter.java
index 7824bff..258eab9 100644
--- a/args4j/src/org/kohsuke/args4j/spi/Setter.java
+++ b/args4j/src/org/kohsuke/args4j/spi/Setter.java
@@ -10,7 +10,8 @@ import java.lang.reflect.AnnotatedElement;
* Abstraction of the value setter.
*
* <p>
- * This abstracts away the difference between a field and a setter method, which object we are setting the value to,
+ * This abstracts away the difference between a field and a setter method,
+ * which object we are setting the value to,
* and/or how we handle collection fields differently.
*
* @author Kohsuke Kawaguchi
@@ -33,31 +34,32 @@ public interface Setter<T> {
/**
* Whether this setter is intrinsically multi-valued.
*
- * When used for parsing arguments (and not options), intrinsically multi-valued setters consume
- * all the remaining arguments. So if the setter can store multiple values, this method should return true.
+ * <p>
+ * When parsing arguments (instead of options), intrinsically multi-valued setters consume
+ * all the remaining arguments. So, if the setter can store multiple values,
+ * this method should return {@code true}.
*
* <p>
- * This characteristics of a setter does not affect option parsing at all, as any options can be
- * specified multiple times (which in many cases are no-op, but when your shell script expands
- * multiple environment variables that each can contain options, tolerating such redundant options
- * are often useful.)
+ * This characteristics of a setter doesn't affect option parsing at all; any options can be
+ * specified multiple times. In many cases, this is a no-op--but when your shell script expands
+ * multiple environment variables (each of which may contain options), tolerating such
+ * redundant options can be useful.
*/
boolean isMultiValued();
/**
* If this setter encapsulates a field, return the direct access to that field as
- * {@link FieldSetter}. This method serves two purposes.
- *
- * <p>
- * One is that this lets {@link OptionHandler}s to bypass the collection/array handling of fields.
- * This is useful if you are defining an option handler that produces array or collection
- * from a single argument.
+ * {@link FieldSetter}. This method serves two purposes:
*
- * <p>
- * The other is to retrieve the current value of the field, via {@link FieldSetter#getValue()}.
+ * <ol>
+ * <li>This lets {@link OptionHandler}s bypass the collection/array handling of fields.
+ * This is useful if you're defining an option handler that produces array or collection
+ * from a single argument.</li>
+ * <li>The other is to retrieve the current value of the field (via {@link FieldSetter#getValue()}).</li>
+ * </ol>
*
* @return
- * null if this setter wraps a method.
+ * {@code null} if this setter wraps a method.
*/
FieldSetter asFieldSetter();
diff --git a/args4j/src/org/kohsuke/args4j/spi/StopOptionHandler.java b/args4j/src/org/kohsuke/args4j/spi/StopOptionHandler.java
index 16be42f..053a838 100644
--- a/args4j/src/org/kohsuke/args4j/spi/StopOptionHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/StopOptionHandler.java
@@ -5,16 +5,16 @@ import org.kohsuke.args4j.CmdLineParser;
import org.kohsuke.args4j.OptionDef;
/**
- * {@link OptionHandler} for the option terminator "--".
+ * {@link OptionHandler} for the option terminator <tt>--</tt>.
*
* <p>
* This {@link OptionHandler} can be used to implement the special token
- * "--" that indicates that the rest of tokens are not options, but arguments.
+ * <tt>--</tt> that indicates that the rest of tokens are not options, but arguments.
*
* <p>
* For example, if you have the following class:
*
- * <pre>
+ * <code><pre>
* class Foo {
* @Argument
* @Option(name="--",handler={@link StopOptionHandler}.class)
@@ -23,11 +23,11 @@ import org.kohsuke.args4j.OptionDef;
* @Option(name="-n")
* int n;
* }
- * </pre>
+ * </pre></code>
*
* <p>
- * The command line {@code -n 5 abc def} would parse into n=5, args={"abc",def"},
- * but {@code -- -n 5 abc def} would parse into n=0, args={"-n","5","abc","def"}.
+ * The command line <samp>-n 5 abc def</samp> would parse into {@code n=5, args={"abc",def"}},
+ * but <samp> -- -n 5 abc def</samp> would parse into {@code n=0, args={"-n","5","abc","def"}}.
*
* @author Kohsuke Kawaguchi
*/
diff --git a/args4j/src/org/kohsuke/args4j/spi/StringArrayOptionHandler.java b/args4j/src/org/kohsuke/args4j/spi/StringArrayOptionHandler.java
index cce9e81..685f8b7 100644
--- a/args4j/src/org/kohsuke/args4j/spi/StringArrayOptionHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/StringArrayOptionHandler.java
@@ -6,24 +6,29 @@ import org.kohsuke.args4j.OptionDef;
/**
* <p>
- * An {@link OptionHandler} for greedily mapping a list of tokens into a collection of {@link String}s,
- * such as {@code String[]}, {@code List<String>}, etc.
+ * An {@link OptionHandler} for greedily mapping a list of tokens into a collection of {@link String}s
+ * (such as {@code String[]}, {@code List<String>}, etc.).
* </p>
*
* <h1>How it works:</h1>
+ *
* <p>
- * Example for parameter -s, which is String[] type:
- * <pre>
+ * Example for parameter {@code -s}, which is type {@code String[]}:</p>
+ *
+ * <code><pre>
* java -jar aaa.jar -s banan hruska jablko
* java -jar aaa.jar -s banan "hruska jablko"
* java -jar aaa.jar -s "banan hruska jablko"
* java -jar aaa.jar -s banan hruska jablko -l 4 -r
* java -jar aaa.jar -t 222 -s banan hruska jablko -r
- * </pre>
+ * </pre></code>
+ *
* <p>
- * All of them result in a single string array that contains three tokens "banan", "hruska", and "jablko".
- * This OptionHandler scans for parameter which begins with "-". If it found it, it will stop.
- * </p>
+ * All of them result in a single string array that contains three tokens:
+ * <samp>banan</samp>, <samp>hruska</samp>, and <samp>jablko</samp>.</p>
+ *
+ * <p>
+ * This {@code OptionHandler} scans for parameter which begins with <tt>-</tt>. If found, it will stop.</p>
*
* @author PlainText,LuVar
*/
@@ -34,7 +39,7 @@ public class StringArrayOptionHandler extends OptionHandler<String> {
}
/**
- * Returns "STRING[]".
+ * Returns {@code "STRING[]"}.
*
* @return return "STRING[]";
*/
@@ -44,7 +49,7 @@ public class StringArrayOptionHandler extends OptionHandler<String> {
}
/**
- * Tries to parse String[] argument from {@link Parameters}.
+ * Tries to parse {@code String[]} argument from {@link Parameters}.
*/
@Override
public int parseArguments(Parameters params) throws CmdLineException {
diff --git a/args4j/src/org/kohsuke/args4j/spi/SubCommandHandler.java b/args4j/src/org/kohsuke/args4j/spi/SubCommandHandler.java
index 618f896..c0e1725 100644
--- a/args4j/src/org/kohsuke/args4j/spi/SubCommandHandler.java
+++ b/args4j/src/org/kohsuke/args4j/spi/SubCommandHandler.java
@@ -12,21 +12,21 @@ import java.util.AbstractList;
* {@link OptionHandler} used with {@link Argument} for parsing typical "sub-command" pattern.
*
* <p>
- * The "sub-command" pattern refers to the design of the command line like git and svn, where
- * the first argument to the command designates a sub-command (say "git checkout"), then everything
- * that follows afterward are parsed by this sub-command (and are usually different depending on
+ * The "sub-command" pattern refers to the design of the command line like <tt>git</tt> and <tt>svn</tt>, where
+ * the first argument to the command designates a sub-command (say <samp>git checkout</samp>), then everything
+ * that follows afterward are parsed by this sub-command (which is usually different depending on
* which sub-command was selected.)
*
* <p>
* This {@link OptionHandler} models this design pattern with the {@link SubCommands} annotation.
* See the following example:
*
- * <pre>
+ * <code><pre>
* class Git {
* @Argument(handler={@link SubCommandHandler}.class)
* @SubCommands({
- * @SubCommand(name="checkout",CheckoutCommand.class),
- * @SubCommand(name="commit",CommitCommand.class),
+ * @SubCommand(name="checkout", impl=CheckoutCommand.class),
+ * @SubCommand(name="commit", impl=CommitCommand.class),
* ...
* })
* Command cmd;
@@ -47,10 +47,10 @@ import java.util.AbstractList;
*
* ...
* }
- * </pre>
+ * </pre></code>
*
* <p>
- * An example of legal command line option for this is "-r checkout -a".
+ * An example of legal command line option for this is <samp>-r checkout -a</samp>.
*
* <ul>
* <li>
diff --git a/args4j/test/org/kohsuke/args4j/KeyValue.java b/args4j/test/org/kohsuke/args4j/KeyValue.java
new file mode 100644
index 0000000..96fe887
--- /dev/null
+++ b/args4j/test/org/kohsuke/args4j/KeyValue.java
@@ -0,0 +1,12 @@
+package org.kohsuke.args4j;
+
+ at SuppressWarnings("unused")
+public class KeyValue {
+
+ @Option(name="-string")
+ public String _string;
+
+ @Option(name="-double")
+ public double _double;
+
+}
diff --git a/args4j/test/org/kohsuke/args4j/KeyValueTest.java b/args4j/test/org/kohsuke/args4j/KeyValueTest.java
new file mode 100644
index 0000000..dd06c59
--- /dev/null
+++ b/args4j/test/org/kohsuke/args4j/KeyValueTest.java
@@ -0,0 +1,22 @@
+package org.kohsuke.args4j;
+
+public class KeyValueTest extends Args4JTestBase<KeyValue> {
+
+ @Override
+ public KeyValue getTestObject() {
+ return new KeyValue();
+ }
+
+ public void testDouble() throws CmdLineException {
+ args = new String[]{"-double=42.54"};
+ parser.parseArgument(args);
+ assertEquals(42.54, testObject._double, 0);
+ }
+
+ public void testChar() throws CmdLineException {
+ args = new String[]{"-string=stringValue"};
+ parser.parseArgument(args);
+ assertEquals("stringValue", testObject._string);
+ }
+
+}
diff --git a/pom.xml b/pom.xml
index 65ff17c..e221a0f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -9,7 +9,7 @@
<groupId>args4j</groupId>
<artifactId>args4j-site</artifactId>
<name>args4j parent</name>
- <version>2.0.25</version>
+ <version>2.0.26</version>
<packaging>pom</packaging>
<description>args4j : Java command line arguments parser</description>
<url>http://args4j.kohsuke.org/</url>
diff --git a/src/site/apt/apt.apt b/src/site/apt/apt.apt
index fbde596..16135ca 100644
--- a/src/site/apt/apt.apt
+++ b/src/site/apt/apt.apt
@@ -1,4 +1,4 @@
- args4j can examine your annotated source code and generate HTML table or XML for the list of command line options. You can use this in the build process to generate your documentation, so that it will be always in sync with your code.
+ args4j can examine your annotated source code and generate HTML table or XML for the list of command line options. You can use this in your build process to generate your documentation, so it's always in sync with your code.
To do so, download {{{http://maven.jenkins-ci.org/content/repositories/releases/args4j/args4j-tools/}args4j-tools}} and run it as follows:
@@ -6,4 +6,4 @@
$ java -jar args4j-tools.jar path/to/my/OptionBean.java
----------------------------------------
- To see all the options, run it withouy any parameter.
+ To see all the options, run it without any parameters.
diff --git a/src/site/apt/implementOptionhandler.apt b/src/site/apt/implementOptionhandler.apt
index be08376..337e8b0 100644
--- a/src/site/apt/implementOptionhandler.apt
+++ b/src/site/apt/implementOptionhandler.apt
@@ -1,3 +1,3 @@
- args4j comes with a built-in support for parsing options into several Java datatypes, such as <<<int>>>, <<<String>>>, and <<<Enum>>>. This support can be extended by writing {{{apidocs/org/kohsuke/args4j/spi/OptionHandler.html}OptionHandler}} implementation in an application and registering it to the <<<CmdLineParser>>> class.
+ args4j comes with a built-in support for parsing options into several Java datatypes (such as <<<int>>>, <<<String>>>, and <<<Enum>>>). You can extend this further by writing your own {{{apidocs/org/kohsuke/args4j/spi/OptionHandler.html}OptionHandler}} implementation, then registering it to the <<<CmdLineParser>>> class.
- In fact most of the built-in suppor is implemented as using this mechanism. See the source code for some of the OptionHandler class for details of how to do this.
+ In fact, most of the built-in support is implemented using this mechanism. The <<<OptionHandler>>> class's source code details how to do this.
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 46a187e..7575eb0 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -10,17 +10,17 @@ Why should I use it?
See {{{http://weblogs.java.net/blog/kohsuke/archive/2005/05/parsing_command.html}my quick intro}}.
- * It makes the command line parsing very easy by using annotations.
+ * It makes command line parsing very easy by using annotations
- * You can generate the usage screen very easily.
+ * Generate usage text very easily
- * You can generate HTML/XML that lists all options for your documentation.
+ * Generate HTML/XML documentation listing all options
- * Fully supports localization.
+ * Full localization support
- * It is designed to parse <<<javac>>> like options (as opposed to GNU-style where ls <<<-lR>>> is considered to have two options <<<l>>> and <<<R>>>.)
+ * Designed to parse <<<javac>>> like options, as opposed to GNU-style (where <<<ls -lR>>> is considered to have two options <<<l>>> and <<<R>>>).
- * It is licensed under {{{http://www.opensource.org/licenses/mit-license.php}the MIT license}}.
+ * Licensed under {{{http://www.opensource.org/licenses/mit-license.php}the MIT license}}.
[]
@@ -34,7 +34,7 @@ How can I use it?
[]
-More Resource
+More Resources
[[1]] {{{./sample.html}A small tutorial}} for the use of the Starter and Args4J
diff --git a/src/site/apt/sample.apt b/src/site/apt/sample.apt
index 0c2a9be..4de9da9 100644
--- a/src/site/apt/sample.apt
+++ b/src/site/apt/sample.apt
@@ -4,7 +4,7 @@
Prepare your environment
- Because we only want to have a very small example, we use only one single directory containing all the stuff - sources, class files and the args4j jarfile. You need a JDK 1.5 or higher.
+ Because we only want to have a very small example, we use only one single directory containing all the stuff— sources, class files and the args4j jarfile. You need a JDK 1.5 or higher.
[[1]] Create a directory args4j-sample this will be our project directory.
@@ -16,7 +16,7 @@ Prepare your environment
Implementing pure business logic
- Create the business bean Business.java. At this step it contains only the business logic. To run this logic, we want to have a run() method.
+ Create the business bean <<<Business.java>>>. At this point, it only contains the business logic. To run this logic, we want a <<<run()>>> method.
------------------------------
import java.io.File;
@@ -59,7 +59,7 @@ Start the class
[]
- Ok, because this is a args4j sample, the first method is not the right solution here ;-) In the first step we just use the Starter.
+ Okay...because this is a sample, the first method isn't the right solution here ;-) In the first step we just use the <<<Starter>>>.
Start the class
@@ -67,7 +67,7 @@ Start the class
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter
------------------------------
- and we will get
+ and we get
------------------------------
Business-Logic
@@ -75,9 +75,9 @@ Business-Logic
- file: null
------------------------------
- What happened? The starter class had a look into the java system property <<<mainclass>>> loads that class, instantiates it and executes their run() method. We provide the classpath so the Java VM could find the starter class and our business class.
+ What happened? The starter class had a look into the Java system property <<<mainclass>>> loads that class, instantiates it, and executes their <<<run()>>> method. We provide the <<<classpath>>> so the Java VM could find the starter class and our business class.
- Next we try to start the class with arguments:
+ Next, let's try to start the class with arguments:
------------------------------
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter -name "Hrld" -file args4j-2.0.5.jar
@@ -92,7 +92,7 @@ Business
Adding Args4J Annotations
- Ok, we don't have any annotations for handling the command line parameters yet. So we modify to the source:
+ Well, we don't have any annotations to handle the command line parameters yet. Let's fix that:
------------------------------
...
@@ -106,7 +106,7 @@ Adding Args4J Annotations
...
------------------------------
- recompile it and try the start again
+ Recompile and try the start again
------------------------------
Business-Logic
@@ -114,13 +114,15 @@ Business-Logic
- file: C:\temp\args4j-sample\args4j-2.0.5.jar
------------------------------
- Ok, so far so good. What is with wrong parameters? We will type a
+ So far so good.
+
+ What is with wrong parameters?
------------------------------
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter -wrong
------------------------------
- and the output is
+ which outputs
------------------------------
"-wrong" is not a valid option
@@ -129,13 +131,19 @@ Business [options]
-name VAL : Sets a name
------------------------------
- Again - what happened? args4j throws a CmdLineException when we type an incorrect parameter (<<<-wrong>>>). The starter class catches this and prints out a help message: the classname and an <<<[Option]>>> because we have some @Option's in the code. (We dont have an @Argument so that line is not <<<Business [options] arguments>>>). After that it shows the possible options, as given by the parsers printUsage() method.
+ Again—what happened?
+
+ args4j throws a <<<CmdLineException>>> when we wrote an incorrect parameter (<<<-wrong>>>). The starter class catches this and prints a help message: the classname and an <<<[Option]>>> (since we have some <<<@Option>>>s in the code). (Since we don't have an <<<@Argument>>>, that line is not <<<Business [options] arguments>>>.)
+
+ Then it shows the possible options, as given by the parser's <<<printUsage()>>> method.
- As you can see we added an @Option to an attribute and to a setter method. Adding to an attribute is the simplest thing. If we want to do some checks (like our file existance check) you could add the annotation to a setter.
+ As you can see, we added an <<<@Option>>> to an attribute and to a setter method. Using this with attributes is the simplest way to use args4j. But if you wanted to do some checks (e.g. our file existence check), you could add the annotation to a setter.
Enhancing the parsing
- If you want to have more control about the parsing and error handling - dont use the starter. Use the CmdLineParser directly. Base steps are shown below:
+ If you want to have more control over parsing and error handling, don't use the starter. Use <<<CmdLineParser>>> directly.
+
+ Here are the main steps:
------------------------------
import org.kohsuke.args4j.CmdLineParser;
@@ -155,13 +163,13 @@ Enhancing the parsing
}
------------------------------
- Because we dont use the Starter we also have to supply the main method and start this. So after compiling we could start that with
+ Since we're not using the <<<Starter>>>, we also have to supply the main method and start it. So, after compiling, we could start that with:
------------------------------
java -classpath .;args4j-2.0.5.jar Business -name "Hello World" -file args4j-2.0.5.jar
------------------------------
- and we will get
+ and we get
------------------------------
Business-Logic
@@ -175,7 +183,7 @@ Business-Logic
java -classpath .;args4j-2.0.5.jar Business -wrong
------------------------------
-will result in
+results in
------------------------------
"-wrong" is not a valid option
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/args4j.git
More information about the pkg-java-commits
mailing list