Class: Toys::DSL::FlagGroup
- Inherits:
-
Object
- Object
- Toys::DSL::FlagGroup
- Defined in:
- lib/toys/dsl/flag_group.rb
Overview
DSL for a flag group definition block. Lets you create flags in a group.
These directives are available inside a block passed to Tool#flag_group, Tool#all_required, Tool#at_most_one, Tool#at_least_one, or Tool#exactly_one.
Example
tool "login" do
all_required do
# The directives in here are defined by this class
flag :username, "--username=VAL", desc: "Set username (required)"
flag :password, "--password=VAL", desc: "Set password (required)"
end
# ...
end
Instance Method Summary collapse
-
#desc(desc) ⇒ self
Set the short description for the current flag group.
-
#flag(key, *flags, accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, desc: nil, long_desc: nil, display_name: nil, &block) ⇒ self
Add a flag to the current group.
-
#long_desc(*long_desc) ⇒ self
Add to the long description for the current flag group.
Instance Method Details
#desc(desc) ⇒ self
Set the short description for the current flag group. The short description is displayed as the group title in online help.
The description is a WrappableString, which may be word-wrapped when displayed in a help screen. You may pass a WrappableString directly to this method, or you may pass any input that can be used to construct a wrappable string:
- If you pass a String, its whitespace will be compacted (i.e. tabs, newlines, and multiple consecutive whitespace will be turned into a single space), and it will be word-wrapped on whitespace.
- If you pass an Array of Strings, each string will be considered a literal word that cannot be broken, and wrapping will be done across the strings in the array. In this case, whitespace is not compacted.
Examples
If you pass in a sentence as a simple string, it may be word wrapped when displayed:
desc "This sentence may be wrapped."
To specify a sentence that should never be word-wrapped, pass it as the sole element of a string array:
desc ["This sentence will not be wrapped."]
232 233 234 235 |
# File 'lib/toys/dsl/flag_group.rb', line 232 def desc(desc) @flag_group.desc = desc self end |
#flag(key, *flags, accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, desc: nil, long_desc: nil, display_name: nil, &block) ⇒ self
Add a flag to the current group. Each flag must specify a key which the script may use to obtain the flag value from the context. You may then provide the flags themselves in OptionParser form.
If the given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Attributes of the flag may be passed in as arguments to this method, or set in a block passed to this method. If you provide a block, you can use directives in Toys::DSL::Flag within the block.
Flag syntax
The flags themselves should be provided in OptionParser form. Following are examples of valid syntax.
-
-a
: A short boolean switch. When this appears as an argument, the value is set totrue
. -
--abc
: A long boolean switch. When this appears as an argument, the value is set totrue
. -
-aVAL
or-a VAL
: A short flag that takes a required value. These two forms are treated identically. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the following argument is taken as the value (e.g. for-a foo
, the value is set to"foo"
.) The following argument is treated as the value even if it looks like a flag (e.g.-a -a
causes the string"-a"
to be taken as the value.) -
-a[VAL]
: A short flag that takes an optional value. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the value is set totrue
. The following argument is never interpreted as the value. (Compare with-a [VAL]
.) -
-a [VAL]
: A short flag that takes an optional value. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, if the following argument does not look like a flag (i.e. it does not begin with a hyphen), it is taken as the value. (e.g.-a foo
causes the string"foo"
to be taken as the value.). If there is no following argument, or the following argument looks like a flag, the value is set totrue
. (Compare with-a[VAL]
.) -
--abc=VAL
or--abc VAL
: A long flag that takes a required value. These two forms are treated identically. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the following argument is taken as the value (e.g. for--abc foo
, the value is set to"foo"
.) The following argument is treated as the value even if it looks like a flag (e.g.--abc --def
causes the string"--def"
to be taken as the value.) -
--abc[=VAL]
: A long flag that takes an optional value. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the value is set totrue
. The following argument is never interpreted as the value. (Compare with--abc [VAL]
.) -
--abc [VAL]
: A long flag that takes an optional value. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, if the following argument does not look like a flag (i.e. it does not begin with a hyphen), it is taken as the value. (e.g.--abc foo
causes the string"foo"
to be taken as the value.). If there is no following argument, or the following argument looks like a flag, the value is set totrue
. (Compare with--abc=[VAL]
.) -
--[no-]abc
: A long boolean switch that can be turned either on or off. This effectively creates two flags,--abc
which sets the value totrue
, and--no-abc
which sets the falue tofalse
.
Default flag syntax
If no flag syntax strings are provided, a default syntax will be inferred based on the key and other options.
Specifically, if the key has one character, then that character will be chosen as a short flag. If the key has multiple characters, a long flag will be generated.
Furthermore, if a custom completion, a non-boolean acceptor, or a non-boolean default value is provided in the options, then the flag will be considered to take a value. Otherwise, it will be considered to be a boolean switch.
For example, the following pairs of flags are identical:
flag :a
flag :a, "-a"
flag :abc_def
flag :abc_def, "--abc-def"
flag :number, accept: Integer
flag :number, "--number=VAL", accept: Integer
More examples
A flag that sets its value to the number of times it appears on the command line:
flag :verbose, "-v", "--verbose",
default: 0, handler: ->(_val, count) { count + 1 }
An example using block form:
flag :shout do
flags "-s", "--shout"
default false
desc "Say it louder"
long_desc "This flag says it lowder.",
"You might use this when people can't hear you.",
"",
"Example:",
[" toys say --shout hello"]
end
188 189 190 191 192 193 194 195 196 197 198 |
# File 'lib/toys/dsl/flag_group.rb', line 188 def flag(key, *flags, accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, desc: nil, long_desc: nil, display_name: nil, &block) flag_dsl = DSL::Flag.new(flags, accept, default, handler, complete_flags, complete_values, report_collisions, @flag_group, desc, long_desc, display_name) flag_dsl.instance_exec(flag_dsl, &block) if block flag_dsl._add_to(@tool, key) DSL::Internal.maybe_add_getter(@tool_dsl, key) self end |
#long_desc(*long_desc) ⇒ self
Add to the long description for the current flag group. The long description is displayed with the flag group in online help. This directive may be given multiple times, and the results are cumulative.
A long description is a series of descriptions, which are generally displayed in a series of lines/paragraphs. Each individual description uses the form described in the #desc documentation, and may be word-wrapped when displayed. To insert a blank line, include an empty string as one of the descriptions.
Example
long_desc "This initial paragraph might get word wrapped.",
"This next paragraph is followed by a blank line.",
"",
["This line will not be wrapped."],
[" This indent is preserved."]
long_desc "This line is appended to the description."
260 261 262 263 |
# File 'lib/toys/dsl/flag_group.rb', line 260 def long_desc(*long_desc) @flag_group.append_long_desc(long_desc) self end |