refactoring

h908714124 · h908714124 · commit 489669d58fe0 · 2021-08-19T15:12:07.000+02:00
diff --git a/compiler/src/main/java/net/jbock/context/BuildMethod.java b/compiler/src/main/java/net/jbock/context/BuildMethod.java
@@ -13,7 +13,7 @@
 import net.jbock.util.ExConvert;
 import net.jbock.util.ExMissingItem;
 import net.jbock.util.ExNotSuccess;
-import net.jbock.util.ItemType;
+import net.jbock.model.ItemType;
 
 import javax.inject.Inject;
 import java.util.ArrayList;
diff --git a/core/src/main/java/net/jbock/model/CommandModel.java b/core/src/main/java/net/jbock/model/CommandModel.java
@@ -1,7 +1,6 @@
 package net.jbock.model;
 
 import net.jbock.Command;
-import net.jbock.util.ItemType;
 
 import java.util.ArrayList;
 import java.util.List;
diff --git a/core/src/main/java/net/jbock/model/Item.java b/core/src/main/java/net/jbock/model/Item.java
@@ -1,7 +1,5 @@
 package net.jbock.model;
 
-import net.jbock.util.ItemType;
-
 import java.util.List;
 
 /**
diff --git a/core/src/main/java/net/jbock/model/ItemType.java b/core/src/main/java/net/jbock/model/ItemType.java
@@ -1,4 +1,4 @@
-package net.jbock.util;
+package net.jbock.model;
 
 import net.jbock.Option;
 import net.jbock.Parameter;
diff --git a/core/src/main/java/net/jbock/model/Option.java b/core/src/main/java/net/jbock/model/Option.java
@@ -1,7 +1,5 @@
 package net.jbock.model;
 
-import net.jbock.util.ItemType;
-
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
diff --git a/core/src/main/java/net/jbock/model/Parameter.java b/core/src/main/java/net/jbock/model/Parameter.java
@@ -1,7 +1,6 @@
 package net.jbock.model;
 
 import net.jbock.Parameters;
-import net.jbock.util.ItemType;
 
 import java.util.ArrayList;
 import java.util.List;
diff --git a/core/src/main/java/net/jbock/util/AtFileSyntaxError.java b/core/src/main/java/net/jbock/util/AtFileSyntaxError.java
@@ -5,7 +5,7 @@
 import java.nio.file.Path;
 
 /**
- * Represents a syntax error in the {@code @file}.
+ * Represents a syntax error in the {@code @-file}.
  * This is an intermediate step in the construction of an
  * {@link ErrAtFile} instance.
  */
diff --git a/core/src/main/java/net/jbock/util/ConverterFailure.java b/core/src/main/java/net/jbock/util/ConverterFailure.java
@@ -2,12 +2,9 @@
 
 /**
  * Non-exceptional failure object that represents any converter failure.
- * There are a fixed number of implementations:
  *
- * <ul>
- *   <li>{@link ConverterThrewException}
- *   <li>{@link ConverterReturnedNull}
- * </ul>
+ * <p>This class is internal API and should not be used
+ * in client code.
  */
 public abstract class ConverterFailure {
 
@@ -19,5 +16,5 @@ public abstract class ConverterFailure {
      *
      * @return error message
      */
-    public abstract String converterMessage();
+    abstract String converterMessage();
 }
diff --git a/core/src/main/java/net/jbock/util/ConverterReturnedNull.java b/core/src/main/java/net/jbock/util/ConverterReturnedNull.java
@@ -3,13 +3,13 @@
 /**
  * Indicates that a converter returned {@code null}.
  */
-public final class ConverterReturnedNull extends ConverterFailure {
+final class ConverterReturnedNull extends ConverterFailure {
 
     ConverterReturnedNull() {
     }
 
     @Override
-    public String converterMessage() {
+    String converterMessage() {
         return "converter returned null";
     }
 }
diff --git a/core/src/main/java/net/jbock/util/ConverterThrewException.java b/core/src/main/java/net/jbock/util/ConverterThrewException.java
@@ -3,7 +3,7 @@
 /**
  * Indicates that an exception was thrown from a converter.
  */
-public final class ConverterThrewException extends ConverterFailure {
+final class ConverterThrewException extends ConverterFailure {
 
     private final Exception exception;
 
@@ -12,16 +12,7 @@ public final class ConverterThrewException extends ConverterFailure {
     }
 
     @Override
-    public String converterMessage() {
+    String converterMessage() {
         return exception.getMessage();
     }
-
-    /**
-     * Returns the exception that was caught in {@link StringConverter#apply(String)}
-     *
-     * @return the exception
-     */
-    public Exception exception() {
-        return exception;
-    }
 }
diff --git a/core/src/main/java/net/jbock/util/ErrAtFile.java b/core/src/main/java/net/jbock/util/ErrAtFile.java
@@ -5,8 +5,8 @@
 import java.nio.file.Path;
 
 /**
- * Non-exceptional failure object, indicates that reading options
- * from the {@code @file} was unsuccessful.
+ * Indicates that reading options
+ * from the {@code @-file} was unsuccessful.
  */
 public final class ErrAtFile extends ParsingFailed {
 
diff --git a/core/src/main/java/net/jbock/util/ErrConvert.java b/core/src/main/java/net/jbock/util/ErrConvert.java
@@ -4,8 +4,7 @@
 import net.jbock.model.Item;
 
 /**
- * Non-exceptional failure object that represents
- * any runtime error during a converter invocation.
+ * Represents a runtime error during a converter invocation.
  */
 public final class ErrConvert extends ParsingFailed {
 
@@ -28,15 +27,6 @@ public ErrConvert(
         this.item = item;
     }
 
-    /**
-     * Returns the failure object.
-     *
-     * @return the failure object
-     */
-    public ConverterFailure failure() {
-        return converterFailure;
-    }
-
     /**
      * Returns the item that the converter was bound to.
      *
diff --git a/core/src/main/java/net/jbock/util/ErrMissingItem.java b/core/src/main/java/net/jbock/util/ErrMissingItem.java
@@ -4,10 +4,8 @@
 import net.jbock.model.Item;
 
 /**
- * Non-exceptional failure object which indicates that a required item
+ * Indicates that a required option or positional parameter
  * was missing on the command line.
- *
- * @see net.jbock.model.Multiplicity#REQUIRED
  */
 public final class ErrMissingItem extends ParsingFailed {
 
diff --git a/core/src/main/java/net/jbock/util/ErrToken.java b/core/src/main/java/net/jbock/util/ErrToken.java
@@ -3,10 +3,8 @@
 import net.jbock.model.CommandModel;
 
 /**
- * Non-exceptional failure object that indicates an error in this command's
- * command line syntax.
- *
- * @see net.jbock.Command
+ * Represents some general error in the command line syntax.
+ * The specific type of error is returned from the {@link #errorType()} method.
  */
 public final class ErrToken extends ParsingFailed {
 
@@ -27,7 +25,7 @@ public ErrToken(CommandModel commandModel, ErrTokenType errorType, String token)
     }
 
     /**
-     * Returns the error type.
+     * Returns the specific type of this error.
      *
      * @return the error type
      */
diff --git a/core/src/main/java/net/jbock/util/ExConvert.java b/core/src/main/java/net/jbock/util/ExConvert.java
@@ -1,6 +1,7 @@
 package net.jbock.util;
 
 import net.jbock.model.CommandModel;
+import net.jbock.model.ItemType;
 
 /**
  * A checked exception to signal that an error has occurred
diff --git a/core/src/main/java/net/jbock/util/ExMissingItem.java b/core/src/main/java/net/jbock/util/ExMissingItem.java
@@ -1,6 +1,7 @@
 package net.jbock.util;
 
 import net.jbock.model.CommandModel;
+import net.jbock.model.ItemType;
 
 /**
  * A checked exception to signal that a required item was
diff --git a/core/src/main/java/net/jbock/util/ParsingFailed.java b/core/src/main/java/net/jbock/util/ParsingFailed.java
@@ -3,13 +3,8 @@
 import net.jbock.model.CommandModel;
 
 /**
- * Superclass of non-exceptional failure objects that may be
- * produced as a result of invoking the generated parser.
- * Each of the subclasses represents a parsing
- * result that's different from "success".
- *
- * <p>If parsing is not successful, a Left-Either containing an instance of this class
- * will be returned from the generated {@code parse(ParseRequest)} method.
+ * Superclass of failure objects that may be
+ * returned from the generated {@code parse} method.
  *
  * <p>There are a fixed number of subclasses:
  *
diff --git a/core/src/main/java/net/jbock/util/StringConverter.java b/core/src/main/java/net/jbock/util/StringConverter.java
@@ -8,8 +8,8 @@
 import static io.jbock.util.Either.right;
 
 /**
- * Converter that converts a string to any arbitrary type.
- * The implementing class must be a public class with no free type variables,
+ * Base class for a converter that converts a command line token.
+ * An implementation class must be public with no free type variables,
  * and have a parameterless public constructor.
  *
  * @param <T> the type of the conversion result
@@ -20,31 +20,27 @@ public abstract class StringConverter<T> implements Function<String, Either<Conv
      * Converts a single command line token.
      * For options, the token is the option argument.
      * This method will be invoked
-     * once per corresponding token in the input array,
-     * so it may never be invoked if no such token exists.
-     * All corresponding tokens will be handled by the same
-     * converter, so this method may be invoked more
-     * than once on the same instance, if it is bound to a
-     * repeatable item.
+     * once per corresponding token in the command line input.
      *
      * <p>The implementation is free to throw any {@link Exception}
      * to signal a converter failure.
      * It is an error to return a {@code null} result
      * from this method.
      *
      * @see net.jbock.model.Multiplicity#REPEATABLE
-     * @param token a non-null string, possibly empty
-     * @return an instance of {@code T}
+     * @param token a non-null string
+     * @return result of the conversion
      * @throws Exception converter failure
      */
     protected abstract T convert(String token) throws Exception;
 
     /**
-     * Creates a {@link StringConverter} from a function.
+     * Creates a {@link StringConverter} from a {@code Function}.
      *
-     * @param function a function that should not return null
-     * @param <T> function output type
-     * @return converter instance
+     * @param function a function that performs string conversion
+     * @param <T> output type of the conversion function
+     * @return an instance of {@code StringConverter} that converts
+     *         by invoking the {@code function}
      */
     public static <T> StringConverter<T> create(Function<String, T> function) {
         return new StringConverter<>() {
@@ -55,10 +51,17 @@ public T convert(String token) {
         };
     }
 
+    /**
+     * This method is internal API and should not be used
+     * in client code.
+     *
+     * @param token a non-null string
+     * @return conversion result
+     */
     @Override
-    public final Either<ConverterFailure, T> apply(String s) {
+    public final Either<ConverterFailure, T> apply(String token) {
         try {
-            T result = convert(s);
+            T result = convert(token);
             if (result == null) {
                 return left(new ConverterReturnedNull());
             }

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package net.jbock.util;`
	`1`	`+package net.jbock.model;`
`2`	`2`
`3`	`3`	`import net.jbock.Option;`
`4`	`4`	`import net.jbock.Parameter;`
Original file line number	Diff line number	Diff line change
`@@ -2,12 +2,9 @@`
`2`	`2`
`3`	`3`	`/**`
`4`	`4`	`* Non-exceptional failure object that represents any converter failure.`
`5`		`- * There are a fixed number of implementations:`
`6`	`5`	`*`
`7`		`- * <ul>`
`8`		`- * <li>{@link ConverterThrewException}`
`9`		`- * <li>{@link ConverterReturnedNull}`
`10`		`- * </ul>`
	`6`	`+ * <p>This class is internal API and should not be used`
	`7`	`+ * in client code.`
`11`	`8`	`*/`
`12`	`9`	`public abstract class ConverterFailure {`
`13`	`10`
`@@ -19,5 +16,5 @@ public abstract class ConverterFailure {`
`19`	`16`	`*`
`20`	`17`	`* @return error message`
`21`	`18`	`*/`
`22`		`- public abstract String converterMessage();`
	`19`	`+ abstract String converterMessage();`
`23`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,13 +3,13 @@`
`3`	`3`	`/**`
`4`	`4`	`* Indicates that a converter returned {@code null}.`
`5`	`5`	`*/`
`6`		`-public final class ConverterReturnedNull extends ConverterFailure {`
	`6`	`+final class ConverterReturnedNull extends ConverterFailure {`
`7`	`7`
`8`	`8`	`ConverterReturnedNull() {`
`9`	`9`	`}`
`10`	`10`
`11`	`11`	`@Override`
`12`		`- public String converterMessage() {`
	`12`	`+ String converterMessage() {`
`13`	`13`	`return "converter returned null";`
`14`	`14`	`}`
`15`	`15`	`}`