This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-cli.git
The following commit(s) were added to refs/heads/master by this push:
new 7dfda5bb Javadoc
7dfda5bb is described below
commit 7dfda5bb37158b99d543f03ac8f56c68add46094
Author: Gary Gregory <[email protected]>
AuthorDate: Thu Oct 29 07:45:26 2026 -0400
Javadoc
- Add a header for the table
- Updates for grammar and spelling
- Normalize wording
---
.../apache/commons/cli/PatternOptionBuilder.java | 84 ++++++++++++++--------
1 file changed, 54 insertions(+), 30 deletions(-)
diff --git a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
index ec7167a6..f31bf21a 100644
--- a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
+++ b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
@@ -24,18 +24,23 @@ import java.util.Date;
import java.util.Map;
/**
- * Allows Options to be created from a single String. The pattern contains
various single character flags and via an
- * optional punctuation character, their expected type.
+ * Creates options from a single string.
+ *
+ * <p>The pattern contains single-character option names, each optionally
followed by a punctuation character that specifies the expected value type.</p>
*
* <table border="1">
* <caption>Overview of PatternOptionBuilder patterns</caption>
* <tr>
+ * <th scope="col">Pattern</th>
+ * <th scope="col">Command-line option</th>
+ * </tr>
+ * <tr>
* <td>a</td>
* <td>-a flag</td>
* </tr>
* <tr>
* <td>b@</td>
- * <td>-b [class name] (creates object via public no-argument constructor)</td>
+ * <td>-b [class name] (creates an object using its public no-argument
constructor)</td>
* </tr>
* <tr>
* <td>c></td>
@@ -47,7 +52,7 @@ import java.util.Map;
* </tr>
* <tr>
* <td>e%</td>
- * <td>-e [number] (creates Double/Long instance depending on existing of a
'.')</td>
+ * <td>-e [number] (creates a Double or Long instance depending on whether the
value contains a '.')</td>
* </tr>
* <tr>
* <td>f/</td>
@@ -59,13 +64,13 @@ import java.util.Map;
* </tr>
* <tr>
* <td>h<</td>
- * <td>-h [file name] (opens the existing file for reading, the caller must
close the stream)</td>
+ * <td>-h [file name] (opens the existing file for reading when the value is
converted; the caller must close the stream)</td>
* </tr>
* </table>
*
* <p>
- * For example, the following allows command line flags of '-v -p string-value
-f /dir/file'. The exclamation mark
- * precede a mandatory option.
+ * For example, the following accepts command-line arguments such as {@code -v
-p string-value -f https://example.com}. The exclamation mark makes the
+ * preceding option mandatory.
* </p>
*
* <pre>
@@ -79,49 +84,68 @@ import java.util.Map;
* </p>
*
* <p>
- * TODO These need to break out to OptionType and also to be pluggable.
- * </p>
+ * ODO Extract these types into OptionType and make them pluggable.</p>
*/
public class PatternOptionBuilder {
- /** String class */
+ /**
+ * String class.
+ */
public static final Class<String> STRING_VALUE = String.class;
- /** Object class */
+ /**
+ * Object class.
+ */
public static final Class<Object> OBJECT_VALUE = Object.class;
- /** Number class */
+ /**
+ * Number class.
+ */
public static final Class<Number> NUMBER_VALUE = Number.class;
- /** Date class */
+ /**
+ * Date class.
+ */
public static final Class<Date> DATE_VALUE = Date.class;
- /** Class class */
+ /**
+ * Class class.
+ */
public static final Class<?> CLASS_VALUE = Class.class;
- /** FileInputStream class */
+ /**
+ * FileInputStream class.
+ */
public static final Class<FileInputStream> EXISTING_FILE_VALUE =
FileInputStream.class;
/// can we do this one??
// is meant to check that the file exists, else it errors.
// ie) it's for reading not writing.
- /** File class */
+ /**
+ * File class.
+ */
public static final Class<File> FILE_VALUE = File.class;
- /** File array class */
+ /**
+ * File array class.
+ */
public static final Class<File[]> FILES_VALUE = File[].class;
- /** URL class */
+ /**
+ * URL class.
+ */
public static final Class<URL> URL_VALUE = URL.class;
- /** The converter to use for Unimplemented data types */
+ /**
+ * The converter to use for unimplemented data types.
+ */
private static final Converter<?, UnsupportedOperationException>
UNSUPPORTED = s -> {
throw new UnsupportedOperationException("Not yet implemented");
};
/**
- * Retrieve the class that {@code ch} represents.
+ * Gets the class that {@code ch} represents.
*
* @param ch The specified character.
* @return The class that {@code ch} represents.
@@ -133,10 +157,10 @@ public class PatternOptionBuilder {
}
/**
- * Retrieve the class that {@code ch} represents.
+ * Gets the class that {@code ch} represents.
*
- * @param ch The specified character
- * @return The class that {@code ch} represents
+ * @param ch The specified character.
+ * @return The class that {@code ch} represents.
* @since 1.7.0
*/
public static Class<?> getValueType(final char ch) {
@@ -165,9 +189,9 @@ public class PatternOptionBuilder {
}
/**
- * Returns whether {@code ch} is a value code, i.e. whether it represents
a class in a pattern.
+ * Tests whether {@code ch} specifies a value type or marks an option as
required in a pattern.
*
- * @param ch The specified character
+ * @param ch The specified character.
* @return true if {@code ch} is a value code, otherwise false.
*/
public static boolean isValueCode(final char ch) {
@@ -175,10 +199,10 @@ public class PatternOptionBuilder {
}
/**
- * Returns the {@link Options} instance represented by {@code pattern}.
+ * Parses the pattern into an {@link Options} instance.
*
- * @param pattern The pattern string
- * @return The {@link Options} instance
+ * @param pattern The pattern string.
+ * @return The {@link Options} instance.
*/
public static Options parsePattern(final String pattern) {
char opt = Char.SP;
@@ -238,9 +262,9 @@ public class PatternOptionBuilder {
}
/**
- * Deprecated, only provides static methods.
+ * Constructs an instance of this utility class.
*
- * @deprecated Will be private or class will be final.
+ * @deprecated This constructor will be made private, or this class will
be made final.
*/
@Deprecated
public PatternOptionBuilder() {
