[#334] Enhancement and API Change: Renamed `ArgSpec.rawStringValues()…

…` to `ArgSpec.stringValues()`.

Closes #334.

RELEASE-NOTES.md

@@ -26,10 +26,11 @@ No features have been promoted in this picocli release.
 
 ## <a name="3.0.0-alpha-5-fixes"></a> Fixed issues
 
-- [#329] Enhancement and API Change: Add parser configuration to control whether boolean flags should be toggled.
-- [#328] Enhancement and API Change: Provide getter methods on `OptionSpec.Builder` and `PositionalParamSpec.Builder`.
-- [#326] Enhancement and API Change: Add parser configuration to treat unmatched options as positional parameters.
-- [#283] Enhancement and API Change: Provide `getMissing` method on MissingParameterException to get a reference to the problematic options and positional parameters. Thanks to [jcapsule](https://github.com/jcapsule) for the suggestion.
+- [#329] Enhancement and New API: Add parser configuration to control whether boolean flags should be toggled.
+- [#328] Enhancement and New API: Provide getter methods on `OptionSpec.Builder` and `PositionalParamSpec.Builder`.
+- [#326] Enhancement and New API: Add parser configuration to treat unmatched options as positional parameters.
+- [#283] Enhancement and New API: Provide `getMissing` method on MissingParameterException to get a reference to the problematic options and positional parameters. Thanks to [jcapsule](https://github.com/jcapsule) for the suggestion.
+- [#334] Enhancement and API Change: Renamed `ArgSpec.rawStringValues()` to `ArgSpec.stringValues()`.
 - [#333] Enhancement: Added subcommand to synopsis in generated usage help. Thanks to [jcapsule](https://github.com/jcapsule) for the pull request.
 - [#323] Enhancement: Remove dependency on java.sql package: picocli should only require the java.base module when running in Java 9.
 - [#325] Enhancement: Allow custom type converter to map empty String to custom default value for empty options. Thanks to [jesselong](https://github.com/jesselong) for the suggestion.
@@ -42,6 +43,8 @@ See [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-
 
 ## <a name="3.0.0-alpha-5-breaking-changes"></a> Potential breaking changes
 
+- Renamed `ArgSpec.rawStringValues()` to `ArgSpec.stringValues()`.
+
 
 See also breaking changes for 
 [3.0.0-alpha-4](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-4#3.0.0-alpha-4-breaking-changes),
@@ -157,8 +160,8 @@ No features have been promoted in this picocli release.
 
 ## <a name="3.0.0-alpha-3-fixes"></a> Fixed issues
 
-- [#313] Enhancement and API Change: add method `CommandLine::setMaxArityIsMaxTotalParams` to configure the parser to use `arity` to limit the total number of values accumulated in an option or positional parameter.
-- [#314] Enhancement and API Change: add method `CommandLine::setUsageHelpWidth` and `UsageMessageSpec::width` to set the max usage help message width.
+- [#313] Enhancement and New API: add method `CommandLine::setMaxArityIsMaxTotalParams` to configure the parser to use `arity` to limit the total number of values accumulated in an option or positional parameter.
+- [#314] Enhancement and New API: add method `CommandLine::setUsageHelpWidth` and `UsageMessageSpec::width` to set the max usage help message width.
 - [#316] Enhancement: Support lenient mode where annotations are optional when extracting annotations.
 - [#317] Enhancement: Change semantics of ParseResult.rawOptionValue to mean values after split (but before type conversion).
 
@@ -508,7 +511,6 @@ Method signature changes on inner classes and interfaces of the `Help` class:
 * Class `CommandLine.Help.Layout` all methods changed: `Field` parameters replaced by `CommandLine.ArgSpec`, `CommandLine.OptionSpec` and `CommandLine.PositionalParamSpec` parameters.
 
 
-TBD: should `Help.Ansi.Text::append` modify the specified `Text` instance instead of returning a new `Text` instance like it currently does?
 
 
 # <a name="2.3.0"></a> Picocli 2.3.0

src/main/java/picocli/CommandLine.java

@@ -3361,7 +3361,7 @@ public abstract static class ArgSpec {
             private final IGetter getter;
             private final ISetter setter;
             private final Range arity;
-            private List<String> rawStringValues = new ArrayList<String>();
+            private List<String> stringValues = new ArrayList<String>();
             private List<String> originalStringValues = new ArrayList<String>();
             protected String toString;
 
@@ -3497,10 +3497,10 @@ <T> T setValue(T newValue) throws PicocliException {
             /** Returns the untyped command line arguments matched by this option or positional parameter spec.
              * @return the matched arguments after {@linkplain #splitRegex() splitting}, but before type conversion.
              *      For map properties, {@code "key=value"} values are split into the key and the value part. */
-            public List<String> rawStringValues() { return Collections.unmodifiableList(rawStringValues); }
+            public List<String> stringValues() { return Collections.unmodifiableList(stringValues); }
 
-            /** Sets the {@code rawStringValues} to a new list instance. */
-            protected void resetRawStringValues() { rawStringValues = new ArrayList<String>(); }
+            /** Sets the {@code stringValues} to a new list instance. */
+            protected void resetStringValues() { stringValues = new ArrayList<String>(); }
 
             /** Returns the original command line arguments matched by this option or positional parameter spec.
              * @return the matched arguments as found on the command line: empty Strings for options without value, the
@@ -4409,7 +4409,7 @@ public Builder addPositionalParam(PositionalParamSpec positionalParam, int posit
             /** Sets the specified command line arguments that were parsed. */
             public Builder originalArgs(String[] originalArgs) { originalArgList.addAll(Arrays.asList(originalArgs)); return this;}
 
-            void addRawStringValue     (ArgSpec argSpec, String value) { if (!isInitializingDefaultValues) { argSpec.rawStringValues.add(value);} }
+            void addRawStringValue     (ArgSpec argSpec, String value) { if (!isInitializingDefaultValues) { argSpec.stringValues.add(value);} }
             void addOriginalStringValue(ArgSpec argSpec, String value) { if (!isInitializingDefaultValues) { argSpec.originalStringValues.add(value); } }
         }
         private final CommandSpec commandSpec;
@@ -4436,7 +4436,7 @@ private ParseResult(ParseResult.Builder builder) {
         /** Returns the option with the specified short name, or {@code null} if no option with that name was matched
          * on the command line.
          * <p>Use {@link OptionSpec#getValue() getValue} on the returned {@code OptionSpec} to get the matched value (or values),
-         * converted to the type of the option. Alternatively, use {@link OptionSpec#rawStringValues() stringValues}
+         * converted to the type of the option. Alternatively, use {@link OptionSpec#stringValues() stringValues}
          * to get the matched String values after they were {@linkplain OptionSpec#splitRegex() split} into parts, or
          * {@link OptionSpec#originalStringValues() originalStringValues} to get the original String values that were
          * matched on the command line, before any processing.
@@ -4448,7 +4448,7 @@ private ParseResult(ParseResult.Builder builder) {
 
         /** Returns the option with the specified name, or {@code null} if no option with that name was matched on the command line.
          * <p>Use {@link OptionSpec#getValue() getValue} on the returned {@code OptionSpec} to get the matched value (or values),
-         * converted to the type of the option. Alternatively, use {@link OptionSpec#rawStringValues() stringValues}
+         * converted to the type of the option. Alternatively, use {@link OptionSpec#stringValues() stringValues}
          * to get the matched String values after they were {@linkplain OptionSpec#splitRegex() split} into parts, or
          * {@link OptionSpec#originalStringValues() originalStringValues} to get the original String values that were
          * matched on the command line, before any processing.
@@ -4511,7 +4511,7 @@ public PositionalParamSpec positional(int position) {
          *      The specified name may include option name prefix characters or not. */
         public String rawOptionValue(String name, String defaultValue)       { return rawOptionValue(option(name), defaultValue); }
         /** Returns the command line argument String value of the specified option, or the specified default value if the specified option is {@code null}. */
-        public String rawOptionValue(OptionSpec option, String defaultValue) { return option == null || option.rawStringValues().isEmpty() ? defaultValue : option.rawStringValues().get(0); }
+        public String rawOptionValue(OptionSpec option, String defaultValue) { return option == null || option.stringValues().isEmpty() ? defaultValue : option.stringValues().get(0); }
 
         /** Returns the command line argument String value of the positional parameter at the specified position, or {@code null} if no positional parameter was matched at that position. */
         public String rawPositionalValue(int position)                       { return rawPositionalValue(positional(position), position, null); }
@@ -4521,7 +4521,7 @@ public PositionalParamSpec positional(int position) {
         private String rawPositionalValue(PositionalParamSpec positional, int position, String defaultValue) {
             if (positional == null) { return defaultValue; }
             int pos = position - positional.index().min;
-            return positional.rawStringValues().size() <= pos ? defaultValue : positional.rawStringValues().get(pos);
+            return positional.stringValues().size() <= pos ? defaultValue : positional.stringValues().get(pos);
         }
 
         /** Returns all command line argument String values matched for the option with the specified name, or an empty list if no option with the specified name was matched. */
@@ -4531,7 +4531,7 @@ private String rawPositionalValue(PositionalParamSpec positional, int position,
          *      The specified name may include option name prefix characters or not. */
         public List<String> rawOptionValues(String name)       { return rawOptionValues(option(name)); }
         /** Returns all command line argument String values matched for the specified option, or an empty list if the specified option is {@code null}. */
-        public List<String> rawOptionValues(OptionSpec option) { return option == null ? Collections.<String>emptyList() : option.rawStringValues(); }
+        public List<String> rawOptionValues(OptionSpec option) { return option == null ? Collections.<String>emptyList() : option.stringValues(); }
 
         /** Returns the command line argument value of the option with the specified name, converted to the {@linkplain OptionSpec#type() type} of the option, or the specified default value if no option with the specified name was matched. */
         public <T> T optionValue(char shortName, T defaultValue)    { return optionValue(option(shortName), defaultValue); }
@@ -4714,11 +4714,11 @@ private void clear() {
             isHelpRequested = false;
             parseResult = ParseResult.builder(getCommandSpec());
             for (OptionSpec option : getCommandSpec().options()) {
-                option.resetRawStringValues();
+                option.resetStringValues();
                 option.resetOriginalStringValues();
             }
             for (PositionalParamSpec positional : getCommandSpec().positionalParameters()) {
-                positional.resetRawStringValues();
+                positional.resetStringValues();
                 positional.resetOriginalStringValues();
             }
         }

src/test/java/picocli/CommandLineModelTest.java

@@ -720,17 +720,17 @@ class Sample {
         List<CommandLine> parsed1 = new CommandLine(new Sample()).parse();// not specified
         OptionSpec option1 = parsed1.get(0).getCommandSpec().optionsMap().get("--foo");
         assertNull("optional option is null when option not specified", option1.getValue());
-        assertTrue("optional option has no raw string value when option not specified", option1.rawStringValues().isEmpty());
+        assertTrue("optional option has no string value when option not specified", option1.stringValues().isEmpty());
 
         List<CommandLine> parsed2 = new CommandLine(new Sample()).parse("--foo");// specified without value
         OptionSpec option2 = parsed2.get(0).getCommandSpec().optionsMap().get("--foo");
         assertEquals("optional option is empty string when specified without args", "", option2.getValue());
-        assertEquals("optional option raw string value when specified without args", "", option2.rawStringValues().get(0));
+        assertEquals("optional option string value when specified without args", "", option2.stringValues().get(0));
 
         List<CommandLine> parsed3 = new CommandLine(new Sample()).parse("--foo", "value");// specified with value
         OptionSpec option3 = parsed3.get(0).getCommandSpec().optionsMap().get("--foo");
         assertEquals("optional option is empty string when specified without args", "value", option3.getValue());
-        assertEquals("optional option raw string value when specified without args", "value", option3.rawStringValues().get(0));
+        assertEquals("optional option string value when specified without args", "value", option3.stringValues().get(0));
     }
 
     @Test
@@ -1343,18 +1343,18 @@ public void testParseResetsRawAndOriginalStringValues() {
         CommandLine cmd = new CommandLine(spec);
         ParseResult parseResult = cmd.parseArgs("-x", "XVAL", "POSITIONAL");
         assertEquals("XVAL", parseResult.option('x').getValue());
-        assertEquals(Arrays.asList("XVAL"), parseResult.option('x').rawStringValues());
+        assertEquals(Arrays.asList("XVAL"), parseResult.option('x').stringValues());
         assertEquals(Arrays.asList("XVAL"), parseResult.option('x').originalStringValues());
         assertEquals("POSITIONAL", parseResult.positional(0).getValue());
-        assertEquals(Arrays.asList("POSITIONAL"), parseResult.positional(0).rawStringValues());
+        assertEquals(Arrays.asList("POSITIONAL"), parseResult.positional(0).stringValues());
         assertEquals(Arrays.asList("POSITIONAL"), parseResult.positional(0).originalStringValues());
 
         ParseResult parseResult2 = cmd.parseArgs("-x", "222", "$$$$");
         assertEquals("222", parseResult2.option('x').getValue());
-        assertEquals(Arrays.asList("222"), parseResult2.option('x').rawStringValues());
+        assertEquals(Arrays.asList("222"), parseResult2.option('x').stringValues());
         assertEquals(Arrays.asList("222"), parseResult2.option('x').originalStringValues());
         assertEquals("$$$$", parseResult2.positional(0).getValue());
-        assertEquals(Arrays.asList("$$$$"), parseResult2.positional(0).rawStringValues());
+        assertEquals(Arrays.asList("$$$$"), parseResult2.positional(0).stringValues());
         assertEquals(Arrays.asList("$$$$"), parseResult2.positional(0).originalStringValues());
 
     }