Add and document parseWithResult() methods (#53)

Adds and documents parseWithResult() methods on SingleCommand and Cli
rvesse · Dec 1, 2016 · 0511ce8 · 0511ce8
1 parent e9e816c
commit 0511ce8
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 7 deletions.
diff --git a/airline-core/src/main/java/com/github/rvesse/airline/Cli.java b/airline-core/src/main/java/com/github/rvesse/airline/Cli.java
@@ -20,9 +20,18 @@
 import com.github.rvesse.airline.builder.CliBuilder;
 import com.github.rvesse.airline.model.GlobalMetadata;
 import com.github.rvesse.airline.model.MetadataLoader;
+import com.github.rvesse.airline.parser.ParseResult;
 import com.github.rvesse.airline.parser.command.CliParser;
 import com.github.rvesse.airline.utils.AirlineUtils;
 
+/**
+ * Class for encapsulating and parsing CLIs
+ * 
+ * @author rvesse
+ *
+ * @param <C>
+ *            Command type
+ */
 public class Cli<C> {
     /**
      * Creates a builder for specifying a command line in fluent style
@@ -43,7 +52,8 @@ public static <T> CliBuilder<T> builder(String name) {
      * Creates a new CLI from a class annotated with the
      * {@link com.github.rvesse.airline.annotations.Cli} annotation
      * 
-     * @param cliClass CLI class
+     * @param cliClass
+     *            CLI class
      */
     public Cli(Class<?> cliClass) {
         this(MetadataLoader.<C> loadGlobal(cliClass));
@@ -61,16 +71,70 @@ public Cli(GlobalMetadata<C> metadata) {
         this.metadata = metadata;
     }
 
+    /**
+     * Gets the global meta-data
+     * 
+     * @return Meta-data
+     */
     public GlobalMetadata<C> getMetadata() {
         return metadata;
     }
 
+    /**
+     * Parses the arguments to produce a command instance, this may be
+     * {@code null} if the arguments don't identify a command and there was no
+     * appropriate default command configured
+     * 
+     * @param args
+     *            Arguments
+     * @return Command instance
+     */
     public C parse(String... args) {
         return parse(ListUtils.unmodifiableList(AirlineUtils.arrayToList(args)));
     }
 
+    /**
+     * Parses the arguments to produce a command instance, this may be
+     * {@code null} if the arguments don't identify a command and there was no
+     * appropriate default command configured
+     * 
+     * @param args
+     *            Arguments
+     * @return Command instance
+     */
     private C parse(Iterable<String> args) {
         CliParser<C> parser = new CliParser<C>();
         return parser.parse(metadata, args);
     }
+
+    /**
+     * Parses the arguments to produce a result. The result can be inspected to
+     * see errors (assuming a suitable error handler was used e.g.
+     * {@code CollectAll}) and to get a command instance. This may be
+     * {@code null} if the arguments don't identify a command and there was no
+     * appropriate default command configured
+     * 
+     * @param args
+     *            Arguments
+     * @return Parse result
+     */
+    public ParseResult<C> parseWithResult(String... args) {
+        return parseWithResult(AirlineUtils.arrayToList(args));
+    }
+
+    /**
+     * Parses the arguments to produce a result. The result can be inspected to
+     * see errors (assuming a suitable error handler was used e.g.
+     * {@code CollectAll}) and to get a command instance. This may be
+     * {@code null} if the arguments don't identify a command and there was no
+     * appropriate default command configured
+     * 
+     * @param args
+     *            Arguments
+     * @return Parse result
+     */
+    public ParseResult<C> parseWithResult(Iterable<String> args) {
+        CliParser<C> parser = new CliParser<C>();
+        return parser.parseWithResult(metadata, args);
+    }
 }
diff --git a/airline-core/src/main/java/com/github/rvesse/airline/SingleCommand.java b/airline-core/src/main/java/com/github/rvesse/airline/SingleCommand.java
@@ -27,7 +27,7 @@
 import com.github.rvesse.airline.utils.AirlineUtils;
 
 /**
- * Class for encapsulating single commands
+ * Class for encapsulating and parsing single commands
  *
  * @param <C>
  *            Command type
@@ -65,9 +65,9 @@ public static <C> SingleCommand<C> singleCommand(Class<C> command, ParserMetadat
     private SingleCommand(Class<C> command, Iterable<GlobalRestriction> restrictions, ParserMetadata<C> parserConfig) {
         if (command == null)
             throw new NullPointerException("command is null");
-        this.parserConfig = parserConfig != null ? parserConfig : MetadataLoader.<C>loadParser(command);
-        this.restrictions = restrictions != null ? IteratorUtils.toList(restrictions.iterator()) : AirlineUtils
-                .arrayToList(GlobalRestriction.DEFAULTS);
+        this.parserConfig = parserConfig != null ? parserConfig : MetadataLoader.<C> loadParser(command);
+        this.restrictions = restrictions != null ? IteratorUtils.toList(restrictions.iterator())
+                : AirlineUtils.arrayToList(GlobalRestriction.DEFAULTS);
         if (this.restrictions.size() == 0)
             this.restrictions.addAll(AirlineUtils.arrayToList(GlobalRestriction.DEFAULTS));
 
@@ -92,19 +92,51 @@ public ParserMetadata<C> getParserConfiguration() {
         return parserConfig;
     }
 
+    /**
+     * Parses the arguments to produce a command instance
+     * 
+     * @param args
+     *            Arguments
+     * @return Command instance
+     */
     public C parse(String... args) {
         return parse(AirlineUtils.arrayToList(args));
     }
 
+    /**
+     * Parses the arguments to produce a command instance
+     * 
+     * @param args
+     *            Arguments
+     * @return Command instance
+     */
     public C parse(Iterable<String> args) {
         SingleCommandParser<C> parser = new SingleCommandParser<C>();
         return parser.parse(parserConfig, commandMetadata, restrictions, args);
     }
-
+
+    /**
+     * Parses the arguments to produce a result. The result can be inspected to
+     * see errors (assuming a suitable error handler was used e.g.
+     * {@code CollectAll}) and to get a command instance
+     * 
+     * @param args
+     *            Arguments
+     * @return Parse result
+     */
     public ParseResult<C> parseWithResult(String... args) {
         return parseWithResult(AirlineUtils.arrayToList(args));
     }
-
+
+    /**
+     * Parses the arguments to produce a result. The result can be inspected to
+     * see errors (assuming a suitable error handler was used e.g.
+     * {@code CollectAll}) and to get a command instance
+     * 
+     * @param args
+     *            Arguments
+     * @return Parse result
+     */
     public ParseResult<C> parseWithResult(Iterable<String> args) {
         SingleCommandParser<C> parser = new SingleCommandParser<C>();
         return parser.parseWithResult(parserConfig, commandMetadata, restrictions, args);