Skip to content

Commit

Permalink
Revert "Incorporate feedback from maintainer (remkop#1296)"
Browse files Browse the repository at this point in the history 
This reverts commit da13d9a.
  • Loading branch information
@MarkoMackic
MarkoMackic authored Oct 17, 2021
1 parent b60ed9b commit a73d728
Showing 1 changed file with 36 additions and 41 deletions.
77 changes: 36 additions & 41 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2346,7 +2346,7 @@ When `-x VALUE` is specified on the command line, this results in an error: `Mis
Users can use the <<Double dash (`--`),end-of-options delimiter>> and disambiguate the input with
`-x &dash;&dash; VALUE`, but this may not be obvious to many users.
One idea is to <<Show End of Options,show the end-of-options>> delimiter in the usage help.
Another idea is to make use of the <<IParameterPreprocessor_Parser_Plugin,IParameterPreprocessor Parser Plugin>> introduced with picocli 4.6.
Another idea is to make use of the <<IParameterPreprocessor Parser Plugin,IParameterPreprocessor Parser Plugin>> introduced with picocli 4.6.

An alternative is to avoid the use of optional parameters and use the default arity in this scenario to eliminate the ambiguity altogether.

Expand Down Expand Up @@ -4708,8 +4708,6 @@ See the javadoc for details.

=== Custom Parameter Processing

As of version 4.6, picocli offers two different parser plugins for custom parameter processing: while the `IParameterPreprocessor` is a powerful and flexible tool, the `IParameterConsumer` serves as a simpler alternative.

==== `IParameterConsumer` Parser Plugin

Options or positional parameters can be assigned a `IParameterConsumer` that implements
Expand Down Expand Up @@ -4779,8 +4777,7 @@ class ExecParameterConsumer : IParameterConsumer {
}
----

[[IParameterPreprocessor_Parser_Plugin]]
==== `IParameterPreprocessor` Parser Plugin
==== IParameterPreprocessor Parser Plugin

Introduced in picocli 4.6, the `IParameterPreprocessor` is also a parser plugin, similar to `IParameterConsumer`, but more flexible.

Expand Down Expand Up @@ -4813,32 +4810,32 @@ class Edit {
@Parameters(index = "0", arity="0..1", description = "The file to edit.")
File file;
enum Editor { defaultEditor, eclipse, idea, netbeans }
enum Editor { eclipse, idea, netbeans }
@Option(names = "--open", arity = "0..1", preprocessor = Edit.MyPreprocessor.class,
description = {
@Option(names = "--open", arity = "0..1", preprocessor = Edit.MyPreprocessor.class,
description = {
"Optionally specify the editor to use (${COMPLETION-CANDIDATES}). " +
"If omitted the default editor is used. ",
"If omitted eclipse is used as default. ",
"Example: edit --open=idea FILE opens IntelliJ IDEA (notice the '=' separator)",
" edit --open FILE opens the specified file in the default editor"
})
Editor editor = Editor.defaultEditor;
" edit --open FILE opens the specified file in eclipse"
})
static Editor editor = Editor.eclipse;
static class MyPreprocessor implements IParameterPreprocessor {
public boolean preprocess(Stack<String> args,
CommandSpec commandSpec,
ArgSpec argSpec,
Map<String, Object> info) {
// we need to decide whether the next arg is the file to edit
// or the name of the editor to use...
if (" ".equals(info.get("separator"))) { // parameter was not attached to option
static class MyPreprocessor implements IParameterPreprocessor {
public boolean preprocess(Stack<String> args,
CommandSpec commandSpec,
ArgSpec argSpec,
Map<String, Object> info) {
// we need to decide whether the next arg is the file to edit
// or the name of the editor to use...
if (" ".equals(info.get("separator"))) { // parameter was not attached to option
// act as if the user specified --open=defaultEditor
args.push(Editor.defaultEditor.name());
}
return false; // picocli's internal parsing is resumed for this option
}
}
// act as if the user specified --open=eclipse
args.push(editor.name());
}
return false; // picocli's internal parsing is resumed for this option
}
}
}
----

Expand All @@ -4850,16 +4847,14 @@ class Edit : Runnable {
@Parameters(index = "0", arity = "0..1", description = ["The file to edit."])
var file: File? = null
enum class Editor { defaultEditor, eclipse, idea, netbeans }
enum class Editor { eclipse, idea, netbeans }
@Option(names = ["--open"], arity = "0..1", preprocessor = MyPreprocessor::class,
description = ["Optionally specify the editor to use (\${COMPLETION-CANDIDATES}). " +
"If omitted the default editor is used. ",
"Example: edit --open=idea FILE ",
" opens file in IntelliJ IDEA (notice the '=' separator)",
" edit --open FILE",
" opens the specified file in the default editor"])
var editor = Editor.defaultEditor
"If omitted eclipse is used as default. ",
"Example: edit --open=idea FILE opens in IntelliJ IDEA (notice the '=' separator)",
" edit --open FILE opens file in eclipse"])
var editor = Editor.eclipse
class MyPreprocessor : IParameterPreprocessor {
override fun preprocess(args: Stack<String>,
Expand All @@ -4870,24 +4865,24 @@ class Edit : Runnable {
// or the name of the editor to use ...
if (" " == info["separator"]) { // parameter was not attached to option
// act as if the user specified --open=defaultEditor
args.push(Editor.defaultEditor.name)
// act as if the user specified --open=eclipse
args.push(argSpec.getValue<Editor>().name)
}
return false // picocli's internal parsing is resumed for this option
}
}
}
----

With this preprocessor in place the user can now specify his editor of choice (e.g. `--open=idea`). If no editor is given, the default editor is used:
With this preprocessor in place the user can now specify his editor of choice (e.g. `--open=idea`). If no editor is given, the default editor (=`eclipse`) is used:

[grid=cols,cols=4*,options="header"]
|===
| User input | Option `Editor` | Parameter `File` | Unmatched input
| `--open file1 file2` | `defaultEditor` | `file1` | `file2`
| `--open file1` | `defaultEditor` | `file1` | none
| `--open=idea file1` | `idea` (user specified) | `file1` | none
| `--open=idea` | `idea` (user specified) | `null` | none
| User input | Option `Editor` | Parameter `File` | Unmatched input
| `--open file1 file2` | `eclipse` (default) | `file1` | `file2`
| `--open file1` | `eclipse` (default) | `file1` | none
| `--open=idea file1` | `idea` (user specificed) | `file1` | none
| `--open=idea` | `idea` (user specificed) | `null` | none
|===

==== Parser Plugin Comparison
Expand Down

0 comments on commit a73d728

Please sign in to comment.