Class: Toys::DSL::PositionalArg

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/dsl/positional_arg.rb

Overview

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 Tool#required_arg, Tool#optional_arg, or 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

Instance Method Summary collapse

Instance Method Details

#accept(spec = nil, **options, &block) ⇒ self

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 Acceptor.create.

Parameters:

  • spec (Object) (defaults to: nil)
  • options (Hash)
  • block (Proc)

Returns:

  • (self) 


36
37
38
39
 
# File 'lib/toys/dsl/positional_arg.rb', line 36

def accept(spec = nil, **options, &block)
  @acceptor = Acceptor.scalarize_spec(spec, options, block)
  self
end

#complete(spec = nil, **options, &block) ⇒ self

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 Completion.create.

Parameters:

  • spec (Object) (defaults to: nil)
  • options (Hash)
  • block (Proc)

Returns:

  • (self) 


63
64
65
66
 
# File 'lib/toys/dsl/positional_arg.rb', line 63

def complete(spec = nil, **options, &block)
  @completion = Completion.scalarize_spec(spec, options, block)
  self
end

#default(default) ⇒ self

Set the default value.

Parameters:

  • default (Object)

Returns:

  • (self) 


47
48
49
50
 
# File 'lib/toys/dsl/positional_arg.rb', line 47

def default(default)
  @default = default
  self
end

#desc(desc) ⇒ self

Set the short description for the current positional argument. The short description is displayed with the argument 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."]

Parameters:

Returns:

  • (self) 


111
112
113
114
 
# File 'lib/toys/dsl/positional_arg.rb', line 111

def desc(desc)
  @desc = desc
  self
end

#display_name(display_name) ⇒ self

Set the name of this arg as it appears in help screens.

Parameters:

  • display_name (String)

Returns:

  • (self) 


74
75
76
77
 
# File 'lib/toys/dsl/positional_arg.rb', line 74

def display_name(display_name)
  @display_name = display_name
  self
end

#long_desc(*long_desc) ⇒ self

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."

Parameters:

Returns:

  • (self) 


139
140
141
142
 
# File 'lib/toys/dsl/positional_arg.rb', line 139

def long_desc(*long_desc)
  @long_desc += long_desc
  self
end