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

new(acceptor, default, completion, display_name, desc, long_desc) click to toggle source

@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

_add_optional_to(tool, key) click to toggle source

@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
_add_required_to(tool, key) click to toggle source

@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
_set_remaining_on(tool, key) click to toggle source

@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
accept(spec = nil, **options, &block) click to toggle source

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
complete(spec = nil, **options, &block) click to toggle source

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
default(default) click to toggle source

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
desc(desc) click to toggle source

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
display_name(display_name) click to toggle source

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
long_desc(*long_desc) click to toggle source

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