Release picocli version 3.0.0-alpha-3

README.md

@@ -37,7 +37,8 @@ interactively showing users what options and subcommands are available.
 ![Picocli Demo help message with ANSI colors](docs/images/picocli.Demo.png?raw=true)
 
 #### Releases
-* [Releases](https://github.com/remkop/picocli/releases) - latest: 3.0.0-alpha-2
+* [Releases](https://github.com/remkop/picocli/releases) - latest: 3.0.0-alpha-3
+* [Picocli 3.0.0-alpha-2 Release Notes](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-2) - note there are some [potential breaking changes](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-2#3.0.0-alpha-2-breaking-changes) from prior versions
 * [Picocli 3.0.0-alpha-1 Release Notes](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1) - note there are some [potential breaking changes](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1-breaking-changes) from prior versions
 * [Picocli 2.0 Release Notes](https://github.com/remkop/picocli/releases/tag/v2.0.0) - note there are some [potential breaking changes](https://github.com/remkop/picocli/releases/tag/v2.0.0#2.0-breaking-changes) from prior versions
 
@@ -139,35 +140,35 @@ See the [source code](https://github.com/remkop/picocli/blob/master/src/main/jav
 
 ### Gradle
 ```
-compile 'info.picocli:picocli:3.0.0-alpha-2'
+compile 'info.picocli:picocli:3.0.0-alpha-3'
 ```
 ### Maven
 ```
 <dependency>
   <groupId>info.picocli</groupId>
   <artifactId>picocli</artifactId>
-  <version>3.0.0-alpha-2</version>
+  <version>3.0.0-alpha-3</version>
 </dependency>
 ```
 ### Scala SBT
 ```
-libraryDependencies += "info.picocli" % "picocli" % "3.0.0-alpha-2"
+libraryDependencies += "info.picocli" % "picocli" % "3.0.0-alpha-3"
 ```
 ### Ivy
 ```
-<dependency org="info.picocli" name="picocli" rev="3.0.0-alpha-2" />
+<dependency org="info.picocli" name="picocli" rev="3.0.0-alpha-3" />
 ```
 ### Grape
 ```groovy
 @Grapes(
-    @Grab(group='info.picocli', module='picocli', version='3.0.0-alpha-2')
+    @Grab(group='info.picocli', module='picocli', version='3.0.0-alpha-3')
 )
 ```
 ### Leiningen
 ```
-[info.picocli/picocli "3.0.0-alpha-2"]
+[info.picocli/picocli "3.0.0-alpha-3"]
 ```
 ### Buildr
 ```
-'info.picocli:picocli:jar:3.0.0-alpha-2'
+'info.picocli:picocli:jar:3.0.0-alpha-3'
 ```

RELEASE-NOTES.md

@@ -1,12 +1,66 @@
 # picocli Release Notes
 
-# <a name="3.0.0-alpha-3"></a> Picocli 3.0.0-alpha-3 (UNRELEASED)
+# <a name="3.0.0-alpha-3"></a> Picocli 3.0.0-alpha-3
+The picocli community is pleased to announce picocli 3.0.0-alpha-3.
+
+This release includes changes to allow picocli to be configured to function like Apache Commons CLI, to support [GROOVY-8520](https://issues.apache.org/jira/browse/GROOVY-8520):
+* `maxArityIsMaxTotalParams` parser configuration option to use `arity` to limit the total number of values accumulated in an option or positional parameter.
+* Usage message width can now be configured programmatically.
+* "Lenient" mode when extracting annotations from a class where picocli annotations are optional (to allow mixing Groovy CLI annotations in Groovy CliBuilder).
+* Change semantics of ParseResult.rawOptionValue to mean values after split (but before type conversion).
+
+See [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1) and [3.0.0-alpha-2](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-2#3.0.0-alpha-2) for recent functional changes.
+
+This is the twenty-third public release.
+Picocli follows [semantic versioning](http://semver.org/).
+
+## <a name="3.0.0-alpha-3-toc"></a> Table of Contents
+
+* [New and noteworthy](#3.0.0-alpha-3-new)
+* [Promoted features](#3.0.0-alpha-3-promoted)
+* [Fixed issues](#3.0.0-alpha-3-fixes)
+* [Deprecations](#3.0.0-alpha-3-deprecated)
+* [Potential breaking changes](#3.0.0-alpha-3-breaking-changes)
+
+## <a name="3.0.0-alpha-3-new"></a> New and Noteworthy
+### Max Arity Is Max Total Params
+
+This release introduces a `maxArityIsMaxTotalParams` parser configuration option.
+
+By default, the arity of an option is the number of arguments _for each occurrence_ of the option.
+For example, if option `-a` has `arity = "2"`, then the following is a perfectly valid command:
+for each occurrence of the option, two option parameters are specified.
+```bash
+<command> -a 1 2 -a 3 4 -a 5 6
+```
+However, if `CommandLine.setMaxArityIsMaxTotalParams(true)` is called first, the above example would result in a `MaxValuesExceededException` because the total number of values (6) exceeds the arity of 2.
+
+Additionally, by default, when `maxArityIsMaxTotalParams` is `false`, arity is only applied _before_ the argument is split into parts,
+while when `maxArityIsMaxTotalParams` is set to `true`, validation is applied _after_ a command line argument has been split into parts.
+
+For example, if we have an option like this:
+```java
+@Option(name = "-a", arity = "1..2", split = ",") String[] values;
+```
+By default, the following input would be a valid command:
+```bash
+<command> -a 1,2,3
+```
+By default, the option arity tells the parser to consume 1 to 2 arguments, and the option was followed by a single parameter, `"1,2,3"`, which is fine.
+
+However, if `maxArityIsMaxTotalParams` is set to true, the above example would result in a `MaxValuesExceededException` because the argument is split into 3 parts, which exceeds the max arity of 2.
+
+## <a name="3.0.0-alpha-3-promoted"></a> Promoted Features
+Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. 
+
+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.
 - [#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).
 
 ## <a name="3.0.0-alpha-3-deprecated"></a> Deprecations
 See [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1-deprecated)
@@ -25,6 +79,7 @@ See [3.0.0-alpha-2](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-
 See [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1-breaking-changes).
 
 
+
 # <a name="3.0.0-alpha-2"></a> Picocli 3.0.0-alpha-2
 The picocli community is pleased to announce picocli 3.0.0-alpha-2.
 

build.gradle

@@ -1,11 +1,11 @@
 group 'info.picocli'
 description 'Annotation-based Java command line parser. Usage help with ANSI styles and colors. Autocomplete. Nested subcommands. Easily included as source to avoid adding a dependency.'
-version '3.0.0-alpha-3-SNAPSHOT'
+version '3.0.0-alpha-3'
 
 // for bumpVersion task
-def oldVersion = '3\\.0\\.0-alpha-2'
+def oldVersion = '3\\.0\\.0-alpha-3-SNAPSHOT'
 def oldRevdate = '2018\\-03\\-27'
-def revDate    = '2018-03-27'
+def revDate    = '2018-03-31'
 
 // for bumpReadmeVersion task
 def previousReleaseVersion = '3.0.0-alpha-2'

docs/apidocs/allclasses-frame.html

@@ -2,9 +2,9 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (version 1.7.0_80) on Tue Mar 27 21:44:03 JST 2018 -->
-<title>All Classes (picocli 3.0.0-alpha-2 API)</title>
-<meta name="date" content="2018-03-27">
+<!-- Generated by javadoc (version 1.7.0_80) on Sat Mar 31 09:42:08 JST 2018 -->
+<title>All Classes (picocli 3.0.0-alpha-3 API)</title>
+<meta name="date" content="2018-03-31">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 </head>
 <body>
@@ -43,7 +43,7 @@ <h1 class="bar">All Classes</h1>
 <li><a href="picocli/CommandLine.IParseResultHandler2.html" title="interface in picocli" target="classFrame"><i>CommandLine.IParseResultHandler2</i></a></li>
 <li><a href="picocli/CommandLine.ITypeConverter.html" title="interface in picocli" target="classFrame"><i>CommandLine.ITypeConverter</i></a></li>
 <li><a href="picocli/CommandLine.IVersionProvider.html" title="interface in picocli" target="classFrame"><i>CommandLine.IVersionProvider</i></a></li>
-<li><a href="picocli/CommandLine.MaxValuesforFieldExceededException.html" title="class in picocli" target="classFrame">CommandLine.MaxValuesforFieldExceededException</a></li>
+<li><a href="picocli/CommandLine.MaxValuesExceededException.html" title="class in picocli" target="classFrame">CommandLine.MaxValuesExceededException</a></li>
 <li><a href="picocli/CommandLine.MissingParameterException.html" title="class in picocli" target="classFrame">CommandLine.MissingParameterException</a></li>
 <li><a href="picocli/CommandLine.MissingTypeConverterException.html" title="class in picocli" target="classFrame">CommandLine.MissingTypeConverterException</a></li>
 <li><a href="picocli/CommandLine.Mixin.html" title="annotation in picocli" target="classFrame">CommandLine.Mixin</a></li>

docs/apidocs/allclasses-noframe.html

@@ -2,9 +2,9 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (version 1.7.0_80) on Tue Mar 27 21:44:03 JST 2018 -->
-<title>All Classes (picocli 3.0.0-alpha-2 API)</title>
-<meta name="date" content="2018-03-27">
+<!-- Generated by javadoc (version 1.7.0_80) on Sat Mar 31 09:42:08 JST 2018 -->
+<title>All Classes (picocli 3.0.0-alpha-3 API)</title>
+<meta name="date" content="2018-03-31">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 </head>
 <body>
@@ -43,7 +43,7 @@ <h1 class="bar">All Classes</h1>
 <li><a href="picocli/CommandLine.IParseResultHandler2.html" title="interface in picocli"><i>CommandLine.IParseResultHandler2</i></a></li>
 <li><a href="picocli/CommandLine.ITypeConverter.html" title="interface in picocli"><i>CommandLine.ITypeConverter</i></a></li>
 <li><a href="picocli/CommandLine.IVersionProvider.html" title="interface in picocli"><i>CommandLine.IVersionProvider</i></a></li>
-<li><a href="picocli/CommandLine.MaxValuesforFieldExceededException.html" title="class in picocli">CommandLine.MaxValuesforFieldExceededException</a></li>
+<li><a href="picocli/CommandLine.MaxValuesExceededException.html" title="class in picocli">CommandLine.MaxValuesExceededException</a></li>
 <li><a href="picocli/CommandLine.MissingParameterException.html" title="class in picocli">CommandLine.MissingParameterException</a></li>
 <li><a href="picocli/CommandLine.MissingTypeConverterException.html" title="class in picocli">CommandLine.MissingTypeConverterException</a></li>
 <li><a href="picocli/CommandLine.Mixin.html" title="annotation in picocli">CommandLine.Mixin</a></li>

docs/apidocs/constant-values.html

@@ -2,15 +2,15 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (version 1.7.0_80) on Tue Mar 27 21:44:03 JST 2018 -->
-<title>Constant Field Values (picocli 3.0.0-alpha-2 API)</title>
-<meta name="date" content="2018-03-27">
+<!-- Generated by javadoc (version 1.7.0_80) on Sat Mar 31 09:42:08 JST 2018 -->
+<title>Constant Field Values (picocli 3.0.0-alpha-3 API)</title>
+<meta name="date" content="2018-03-31">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 </head>
 <body>
 <script type="text/javascript"><!--
     if (location.href.indexOf('is-external=true') == -1) {
-        parent.document.title="Constant Field Values (picocli 3.0.0-alpha-2 API)";
+        parent.document.title="Constant Field Values (picocli 3.0.0-alpha-3 API)";
     }
 //-->
 </script>
@@ -87,7 +87,7 @@ <h2 title="picocli">picocli.*</h2>
 <!--   -->
 </a><code>public&nbsp;static&nbsp;final&nbsp;java.lang.String</code></td>
 <td><code><a href="picocli/CommandLine.html#VERSION">VERSION</a></code></td>
-<td class="colLast"><code>"3.0.0-alpha-2"</code></td>
+<td class="colLast"><code>"3.0.0-alpha-3"</code></td>
 </tr>
 </tbody>
 </table>
@@ -137,6 +137,25 @@ <h2 title="picocli">picocli.*</h2>
 </tbody>
 </table>
 </li>
+<li class="blockList">
+<table border="0" cellpadding="3" cellspacing="0" summary="Constant Field Values table, listing constant fields, and values">
+<caption><span>picocli.<a href="picocli/CommandLine.Model.UsageMessageSpec.html" title="class in picocli">CommandLine.Model.UsageMessageSpec</a></span><span class="tabEnd">&nbsp;</span></caption>
+<tr>
+<th class="colFirst" scope="col">Modifier and Type</th>
+<th scope="col">Constant Field</th>
+<th class="colLast" scope="col">Value</th>
+</tr>
+<tbody>
+<tr class="altColor">
+<td class="colFirst"><a name="picocli.CommandLine.Model.UsageMessageSpec.DEFAULT_USAGE_WIDTH">
+<!--   -->
+</a><code>public&nbsp;static&nbsp;final&nbsp;int</code></td>
+<td><code><a href="picocli/CommandLine.Model.UsageMessageSpec.html#DEFAULT_USAGE_WIDTH">DEFAULT_USAGE_WIDTH</a></code></td>
+<td class="colLast"><code>80</code></td>
+</tr>
+</tbody>
+</table>
+</li>
 </ul>
 <a name="picocli.groovy">
 <!--   -->

docs/apidocs/deprecated-list.html

@@ -2,15 +2,15 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (version 1.7.0_80) on Tue Mar 27 21:44:03 JST 2018 -->
-<title>Deprecated List (picocli 3.0.0-alpha-2 API)</title>
-<meta name="date" content="2018-03-27">
+<!-- Generated by javadoc (version 1.7.0_80) on Sat Mar 31 09:42:08 JST 2018 -->
+<title>Deprecated List (picocli 3.0.0-alpha-3 API)</title>
+<meta name="date" content="2018-03-31">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 </head>
 <body>
 <script type="text/javascript"><!--
     if (location.href.indexOf('is-external=true') == -1) {
-        parent.document.title="Deprecated List (picocli 3.0.0-alpha-2 API)";
+        parent.document.title="Deprecated List (picocli 3.0.0-alpha-3 API)";
     }
 //-->
 </script>

docs/apidocs/help-doc.html

@@ -2,15 +2,15 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (version 1.7.0_80) on Tue Mar 27 21:44:03 JST 2018 -->
-<title>API Help (picocli 3.0.0-alpha-2 API)</title>
-<meta name="date" content="2018-03-27">
+<!-- Generated by javadoc (version 1.7.0_80) on Sat Mar 31 09:42:08 JST 2018 -->
+<title>API Help (picocli 3.0.0-alpha-3 API)</title>
+<meta name="date" content="2018-03-31">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 </head>
 <body>
 <script type="text/javascript"><!--
     if (location.href.indexOf('is-external=true') == -1) {
-        parent.document.title="API Help (picocli 3.0.0-alpha-2 API)";
+        parent.document.title="API Help (picocli 3.0.0-alpha-3 API)";
     }
 //-->
 </script>