class Toys::DSL::PositionalArg
DSL
for an arg definition block. Lets you set arg attributes in a block instead of a long series of keyword arguments.
These directives are available inside a block passed to {Toys::DSL::Tool#required_arg}, {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args}.
### Example
tool "mytool" do optional_arg :value do # The directives in here are defined by this class accept Integer desc "An integer value" end # ... end
Public Class Methods
@private
# File lib/toys/dsl/positional_arg.rb, line 26 def initialize(acceptor, default, completion, display_name, desc, long_desc) @default = default @display_name = display_name @desc = desc @long_desc = long_desc || [] accept(acceptor, **{}) complete(completion, **{}) end
Public Instance Methods
@private
# File lib/toys/dsl/positional_arg.rb, line 162 def _add_optional_to(tool, key) tool.add_optional_arg(key, accept: @acceptor, default: @default, complete: @completion, display_name: @display_name, desc: @desc, long_desc: @long_desc) end
@private
# File lib/toys/dsl/positional_arg.rb, line 155 def _add_required_to(tool, key) tool.add_required_arg(key, accept: @acceptor, complete: @completion, display_name: @display_name, desc: @desc, long_desc: @long_desc) end
@private
# File lib/toys/dsl/positional_arg.rb, line 169 def _set_remaining_on(tool, key) tool.set_remaining_args(key, accept: @acceptor, default: @default, complete: @completion, display_name: @display_name, desc: @desc, long_desc: @long_desc) end
Set the acceptor for this argument'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 {Toys::Acceptor.create}.
@param spec [Object] @param options [Hash] @param block [Proc] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 46 def accept(spec = nil, **options, &block) @acceptor = Acceptor.scalarize_spec(spec, options, block) self end
Set the shell completion strategy for arg 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 {Toys::Completion.create}.
@param spec [Object] @param options [Hash] @param block [Proc] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 73 def complete(spec = nil, **options, &block) @completion = Completion.scalarize_spec(spec, options, block) self end
Set the default value.
@param default [Object] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 57 def default(default) @default = default self end
Set the short description for the current positional argument. The short description is displayed with the argument in online help.
The description is a {Toys::WrappableString}, which may be word-wrapped when displayed in a help screen. You may pass a {Toys::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."]
@param desc [String,Array<String>,Toys::WrappableString] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 121 def desc(desc) @desc = desc self end
Set the name of this arg as it appears in help screens.
@param display_name
[String] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 84 def display_name(display_name) @display_name = display_name self end
Add to the long description for the current positional argument. The long description is displayed with the argument 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."
@param long_desc
[String,Array<String>,Toys::WrappableString…] @return [self]
# File lib/toys/dsl/positional_arg.rb, line 149 def long_desc(*long_desc) @long_desc += long_desc self end