Class: Toys::DSL::Flag
- Inherits:
-
Object
- Object
- Toys::DSL::Flag
- Defined in:
- core-docs/toys/dsl/flag.rb
Overview
Defined in the toys-core gem
DSL for a flag definition block. Lets you set flag attributes in a block instead of a long series of keyword arguments.
These directives are available inside a block passed to Tool#flag.
Example
tool "mytool" do
flag :value do
# The directives in here are defined by this class
flags "--value=VAL"
accept Integer
desc "An integer value"
end
# ...
end
Instance Method Summary collapse
-
#accept(spec = nil, **options, &block) ⇒ self
Set the acceptor for this flag's values.
-
#complete_flags(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for flag names.
-
#complete_values(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for flag values.
-
#default(default) ⇒ self
Set the default value.
-
#desc(desc) ⇒ self
Set the short description for the current flag.
-
#display_name(display_name) ⇒ self
Set the display name for this flag.
-
#flags(*flags) ⇒ self
Add flags in OptionParser format.
-
#group(group) ⇒ self
Set the group.
-
#handler(handler = nil, &block) ⇒ self
Set the optional handler for setting/updating the value when a flag is parsed.
-
#long_desc(*long_desc) ⇒ self
Add to the long description for the current flag.
-
#report_collisions(setting) ⇒ self
Set whether to raise an exception if a flag is requested that is already in use or marked as disabled.
Instance Method Details
#accept(spec = nil, **options, &block) ⇒ self
Set the acceptor for this flag's values. You can pass either the string name of an acceptor defined in this tool or any of its ancestors, or any other specification recognized by Acceptor.create.
99 100 101 |
# File 'core-docs/toys/dsl/flag.rb', line 99 def accept(spec = nil, **, &block) # Source available in the toys-core gem end |
#complete_flags(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for flag names. You can pass one of the following:
- The string name of a completion defined in this tool or any of its ancestors.
- A hash of options to pass to the constructor of Flag::DefaultCompletion.
-
nil
or:default
to select the standard completion strategy (which is Flag::DefaultCompletion with no extra options). - Any other specification recognized by Completion.create.
145 146 147 |
# File 'core-docs/toys/dsl/flag.rb', line 145 def complete_flags(spec = nil, **, &block) # Source available in the toys-core gem end |
#complete_values(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for flag values. You can pass either the string name of a completion defined in this tool or any of its ancestors, or any other specification recognized by Completion.create.
160 161 162 |
# File 'core-docs/toys/dsl/flag.rb', line 160 def complete_values(spec = nil, **, &block) # Source available in the toys-core gem end |
#default(default) ⇒ self
Set the default value.
109 110 111 |
# File 'core-docs/toys/dsl/flag.rb', line 109 def default(default) # Source available in the toys-core gem end |
#desc(desc) ⇒ self
Set the short description for the current flag. The short description is displayed with the flag 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."]
207 208 209 |
# File 'core-docs/toys/dsl/flag.rb', line 207 def desc(desc) # Source available in the toys-core gem end |
#display_name(display_name) ⇒ self
Set the display name for this flag. This may be used in help text and error messages.
256 257 258 |
# File 'core-docs/toys/dsl/flag.rb', line 256 def display_name(display_name) # Source available in the toys-core gem end |
#flags(*flags) ⇒ self
Add flags in OptionParser format. This may be called multiple times, and the results are cumulative.
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
.
84 85 86 |
# File 'core-docs/toys/dsl/flag.rb', line 84 def flags(*flags) # Source available in the toys-core gem end |
#group(group) ⇒ self
Set the group. A group may be set by name or group object. Setting
nil
selects the default group.
245 246 247 |
# File 'core-docs/toys/dsl/flag.rb', line 245 def group(group) # Source available in the toys-core gem end |
#handler(handler = nil, &block) ⇒ self
Set the optional handler for setting/updating the value when a flag is
parsed. A handler should be a Proc taking two arguments, the new given
value and the previous value, and it should return the new value that
should be set. You may pass the handler as a Proc (or an object
responding to the call
method) or you may pass a block.
124 125 126 |
# File 'core-docs/toys/dsl/flag.rb', line 124 def handler(handler = nil, &block) # Source available in the toys-core gem end |
#long_desc(*long_desc) ⇒ self
Add to the long description for the current flag. The long description is displayed with the flag 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."
234 235 236 |
# File 'core-docs/toys/dsl/flag.rb', line 234 def long_desc(*long_desc) # Source available in the toys-core gem end |
#report_collisions(setting) ⇒ self
Set whether to raise an exception if a flag is requested that is already in use or marked as disabled.
171 172 173 |
# File 'core-docs/toys/dsl/flag.rb', line 171 def report_collisions(setting) # Source available in the toys-core gem end |