[groovy] 02/02: GROOVY-9528: improve the "parser" subsection of the "Picocli" section of "Advanced CLI Usage" in domain-specific languages page

[rp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rpopma pushed a commit to branch GROOVY_3_0_X
in repository https://gitbox.apache.org/repos/asf/groovy.git

commit 487d9c4df625dee611ddfd3ec056840c6109d304
Author: Remko Popma <re...@yahoo.com>
AuthorDate: Wed Apr 29 12:54:30 2020 +0900

    GROOVY-9528: improve the "parser" subsection of the "Picocli" section of "Advanced CLI Usage"  in domain-specific languages page
    
    (cherry picked from commit cbf130f31bff51b1cd1d492a6cdae04bec280ea3)
---
 src/spec/doc/core-domain-specific-languages.adoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc
index bf2371a..f7bf4d5 100644
--- a/src/spec/doc/core-domain-specific-languages.adoc
+++ b/src/spec/doc/core-domain-specific-languages.adoc
@@ -1602,6 +1602,26 @@ image::assets/img/usageMessageSpec.png[]
 *New property: parser*
 
 The `parser` property gives access to the picocli `ParserSpec` object that can be used to customize the parser behavior.
+
+This can be useful when the `CliBuilder` options to control the parser are not fine-grained enough.
+For example, for backward compatibility with the Commons CLI implementation of `CliBuilder`, by default `CliBuilder` stops looking for options when an unknown option is encountered, and subsequent command line arguments are treated as positional parameters.
+`CliBuilder` provides a `stopAtNonOption` property, and by setting this to `false` you can make the parser more strict, so an unknown option results in `error: Unknown option: '-x'`.
+
+But what if you want to treat unknown options as positional parameters, and still process subsequent command line arguments as options?
+
+This can be accomplished with the `parser` property.
+For example:
+
+[source,groovy]
+----
+def cli = new CliBuilder()
+cli.parser.stopAtPositional(false)
+cli.parser.unmatchedOptionsArePositionalParams(true)
+// ...
+def opts = cli.parse(args)
+// ...
+----
+
 See the http://picocli.info/apidocs/picocli/CommandLine.Model.ParserSpec.html[documentation] for details.
 
 *Map options*