Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: Update boolean arity #1400

Merged
merged 1 commit into from
Aug 4, 2021
Merged

Documentation: Update boolean arity #1400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2347,7 +2347,7 @@ If no `arity` is specified, the number of parameters depends on the field's type
[grid=cols,cols="30,5,65",options="header"]
|===
| @Option Field Type | Default Arity | Notes
| boolean | 0 |Boolean options by default don't require an option parameter. The field is set to the opposite of its default value when the option name is recognized. (This can be <<Toggle Boolean Flags,configured>>.)
| boolean | 0..1 | Boolean options by default don't require an option parameter. The field is set to the opposite of its default value when the option name is recognized. (This can be <<Toggle Boolean Flags,configured>>.)
| Single-valued type (e.g., `int`, `String`, `File`) | 1 | The option name must be followed by a value.
| Multi-valued type (arrays, collections or maps) | 1 | The option name must be followed by a value.
|===
Expand Down
20 changes: 12 additions & 8 deletions src/main/java/picocli/CommandLine.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3734,7 +3734,7 @@ public enum ScopeType {
* command line, a {@link MissingParameterException} is thrown by the {@link #parse(String...)} method.
* <p>
* In many cases picocli can deduce the number of required parameters from the field's type.
* By default, flags (boolean options) have arity zero,
* By default, flags (boolean options) have arity "0..1",
* and single-valued type fields (String, int, Integer, double, Double, File, Date, etc) have arity one.
* Generally, fields with types that cannot hold multiple values can omit the {@code arity} attribute.
* </p><p>
Expand All @@ -3746,7 +3746,7 @@ public enum ScopeType {
* </p>
* <b>A note on boolean options</b>
* <p>
* By default picocli does not expect boolean options (also called "flags" or "switches") to have a parameter.
* By default picocli allows boolean options (also called "flags" or "switches") to have an optional parameter.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small addition:

(...) an optional parameter, which must be either true or false.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this one is very redundant, it's a boolean option.

Copy link
Owner

@remkop remkop Aug 4, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you are saying, but I think it makes sense to be very specific about what parameters are allowed. For example, the following parameters would be rejected: TRUE, FALSE, True, False, 1, 0, YES, NO, Yes, No.

Contrast this to some languages like Groovy and Python where Strings with this wider range of values are translated to true/false boolean values.

* You can make a boolean option take a required parameter by annotating your field with {@code arity="1"}.
joca-bt marked this conversation as resolved.
Show resolved Hide resolved
* For example: </p>
* <pre>&#064;Option(names = "-v", arity = "1") boolean verbose;</pre>
Expand All @@ -3756,12 +3756,11 @@ public enum ScopeType {
* on the command line, or a {@link MissingParameterException} is thrown by the {@link #parse(String...)}
* method.
* </p><p>
* To make the boolean parameter possible but optional, define the field with {@code arity = "0..1"}.
* To remove the optional parameter, define the field with {@code arity = "0"}.
* For example: </p>
* <pre>&#064;Option(names="-v", arity="0..1") boolean verbose;</pre>
* <p>This will accept any of the below without throwing an exception:</p>
joca-bt marked this conversation as resolved.
Show resolved Hide resolved
* <pre>&#064;Option(names="-v", arity="0") boolean verbose;</pre>
* <p>This will reject any of the below:</p>
* <pre>
* -v
* -v true
* -v false
* </pre>
Expand Down Expand Up @@ -5603,9 +5602,14 @@ static Range adjustForType(Range result, IAnnotatedElement member) {
return result.isUnspecified ? defaultArity(member) : result;
}
/** Returns the default arity {@code Range}: for interactive options/positional parameters,
* this is 0; for {@link Option options} this is 0 for booleans and 1 for
* other types, for {@link Parameters parameters} booleans have arity 0, arrays or Collections have
* this is 0; for {@link Option options} this is effectively "0..1" for booleans and 1 for
* other types, for {@link Parameters parameters} booleans have arity 1, arrays or Collections have
* arity "0..*", and other types have arity 1.
* <p><b><em>Implementation Notes</em></b></p>
* <p>The returned {@code Range} for boolean options has an <em>effective</em> arity of "0..1".
* This is implemented by returning a {@code Range} with arity "0",
* and its {@code unspecified} property set to {@code true}.
* This implementation may change in the future.</p>
* @param field the field whose default arity to return
* @return a new {@code Range} indicating the default arity of the specified field
* @since 2.0 */
Expand Down