Class: Toys::DSL::Flag

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

Overview

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

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.

Parameters:

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

Returns:

  • (self)
[View source]

100
101
102
103
 
# File 'lib/toys/dsl/flag.rb', line 100

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

#add_method(value) ⇒ Object

Specify whether to add a method for this flag.

Recognized values are true to force creation of a method, false to disable method creation, and nil for the default behavior. The default checks the name and adds a method if the name is a symbol representing a legal method name that starts with a letter and does not override any public method in the Ruby Object class or collide with any method directly defined in the tool class.

Parameters:

  • value (true, false, nil)
[View source]

290
291
292
293
294
295
296
297
298
299
 
# File 'lib/toys/dsl/flag.rb', line 290

def add_method(value)
  @add_method =
    if value.nil?
      nil
    elsif value
      true
    else
      false
    end
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.

Parameters:

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

Returns:

  • (self)
[View source]

156
157
158
159
 
# File 'lib/toys/dsl/flag.rb', line 156

def complete_flags(spec = nil, **options, &block)
  @flag_completion = Completion.scalarize_spec(spec, options, block)
  self
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.

Parameters:

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

Returns:

  • (self)
[View source]

172
173
174
175
 
# File 'lib/toys/dsl/flag.rb', line 172

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

#default(default) ⇒ self

Set the default value.

Parameters:

  • default (Object)

Returns:

  • (self)
[View source]

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

def default(default)
  @default = default
  self
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."]

Parameters:

Returns:

  • (self)
[View source]

221
222
223
224
 
# File 'lib/toys/dsl/flag.rb', line 221

def desc(desc)
  @desc = desc
  self
end

#display_name(display_name) ⇒ self

Set the display name for this flag. This may be used in help text and error messages.

Parameters:

  • display_name (String)

Returns:

  • (self)
[View source]

273
274
275
276
 
# File 'lib/toys/dsl/flag.rb', line 273

def display_name(display_name)
  @display_name = display_name
  self
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 to true.
  • --abc : A long boolean switch. When this appears as an argument, the value is set to true.
  • -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 to true. 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 to true. (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 to true. 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 to true. (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 to true, and --no-abc which sets the falue to false.

Parameters:

  • flags (String...)

Returns:

  • (self)
[View source]

84
85
86
87
 
# File 'lib/toys/dsl/flag.rb', line 84

def flags(*flags)
  @flags += flags.flatten
  self
end

#group(group) ⇒ self

Set the group. A group may be set by name or group object. Setting nil selects the default group.

Parameters:

Returns:

  • (self)
[View source]

261
262
263
264
 
# File 'lib/toys/dsl/flag.rb', line 261

def group(group)
  @group = group
  self
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.

You can also pass one of the special values :set or :push as the handler. The :set handler replaces the previous value (equivalent to -> (val, _prev) { val }.) The :push handler expects the previous value to be an array and pushes the given value onto it; it should be combined with setting the default value to [] and is intended for "multi-valued" flags.

Parameters:

  • handler (Proc, :set, :push) (defaults to: nil)
  • block (Proc)

Returns:

  • (self)
[View source]

134
135
136
137
 
# File 'lib/toys/dsl/flag.rb', line 134

def handler(handler = nil, &block)
  @handler = handler || block
  self
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."

Parameters:

Returns:

  • (self)
[View source]

249
250
251
252
 
# File 'lib/toys/dsl/flag.rb', line 249

def long_desc(*long_desc)
  @long_desc += long_desc
  self
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.

Parameters:

  • setting (Boolean)

Returns:

  • (self)
[View source]

184
185
186
187
 
# File 'lib/toys/dsl/flag.rb', line 184

def report_collisions(setting)
  @report_collisions = setting
  self
end