Class: Toys::ToolDefinition

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/tool_definition.rb

Overview

A ToolDefinition describes a single command that can be invoked using Toys. It has a name, a series of one or more words that you use to identify the tool on the command line. It also has a set of formal flags and command line arguments supported, and a block that gets run when the tool is executed.

This object has a two stage lifecycle:

  • During the loading process, it is editable and its mutation methods are available.
  • After loading is done, which is triggered by the internal finish_definition method, the mutation methods will raise exceptions. At that point, the object is immutable and only getter methods will function.

As a result, the method list is fairly long, comprising both mutation methods and immutable getters. Note that in Aug 2026, we studied the possibility of splitting this class into an immutable definition and a mutable builder. This plan was rejected mostly because the full interface is useful to Middleware#config.

Defined in the toys-core gem

Defined Under Namespace

Classes: DefaultCompletion

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#built_middleware ⇒ Array<Toys::Middleware> (readonly)

The stack of built middleware specs for this tool.

Returns:



239
240
241
 
# File 'core-docs/toys/tool_definition.rb', line 239

def built_middleware
  @built_middleware
end

#completion ⇒ Toys::Completion::Base, Proc

The completion strategy for this tool.

When reading, this may return an instance of one of the subclasses of Completion::Base, or a Proc that duck-types it. Generally, this defaults to a DefaultCompletion, providing a standard algorithm that finds appropriate completions from flags, positional arguments, and subtools.

When setting, you may pass any of the following:

  • nil or :default which sets the value to a default instance.
  • A Hash of options to pass to the DefaultCompletion constructor.
  • Any other form recognized by Completion.create.

Returns:



274
275
276
 
# File 'core-docs/toys/tool_definition.rb', line 274

def completion
  @completion
end

#custom_context_directory ⇒ String?

The custom context directory set for this tool.

Returns:

  • (String) —

    The directory path

  • (nil) —

    if no custom context directory is set.



255
256
257
 
# File 'core-docs/toys/tool_definition.rb', line 255

def custom_context_directory
  @custom_context_directory
end

#default_data ⇒ Hash (readonly)

The default context data set by arguments.

Returns:

  • (Hash) 


223
224
225
 
# File 'core-docs/toys/tool_definition.rb', line 223

def default_data
  @default_data
end

#delegate_target ⇒ Array<String>? (readonly)

The full name of the delegate target, if any. This array may not be modified.

Returns:

  • (Array<String>) —

    if this tool delegates

  • (nil) —

    if this tool does not delegate



324
325
326
 
# File 'core-docs/toys/tool_definition.rb', line 324

def delegate_target
  @delegate_target
end

#desc ⇒ Toys::WrappableString

The short description string.

When reading, this is always returned as a WrappableString.

When setting, the description may be provided as any of the following:

  • A WrappableString.
  • A normal String, which will be transformed into a WrappableString using spaces as word delimiters.
  • An Array of String, which will be transformed into a WrappableString where each array element represents an individual word for wrapping.

Returns:



154
155
156
 
# File 'core-docs/toys/tool_definition.rb', line 154

def desc
  @desc
end

#flag_groups ⇒ Array<Toys::FlagGroup> (readonly)

A list of all defined flag groups, in order.

Returns:



180
181
182
 
# File 'core-docs/toys/tool_definition.rb', line 180

def flag_groups
  @flag_groups
end

#flags ⇒ Array<Toys::Flag> (readonly)

A list of all defined flags.

Returns:



187
188
189
 
# File 'core-docs/toys/tool_definition.rb', line 187

def flags
  @flags
end

#full_name ⇒ Array<String> (readonly)

The name of the tool as an array of strings. This array may not be modified.

Returns:

  • (Array<String>) 


114
115
116
 
# File 'core-docs/toys/tool_definition.rb', line 114

def full_name
  @full_name
end

#long_desc ⇒ Array<Toys::WrappableString>

The long description strings.

When reading, this is returned as an Array of WrappableString representing the lines in the description.

When setting, the description must be provided as an Array where each element may be any of the following:

  • A WrappableString representing one line.
  • A normal String representing a line. This will be transformed into a WrappableString using spaces as word delimiters.
  • An Array of String representing a line. This will be transformed into a WrappableString where each array element represents an individual word for wrapping.

Returns:



173
174
175
 
# File 'core-docs/toys/tool_definition.rb', line 173

def long_desc
  @long_desc
end

#optional_args ⇒ Array<Toys::PositionalArg> (readonly)

A list of all defined optional positional arguments.

Returns:



201
202
203
 
# File 'core-docs/toys/tool_definition.rb', line 201

def optional_args
  @optional_args
end

#remaining_arg ⇒ Toys::PositionalArg? (readonly)

The remaining arguments specification.

Returns:

  • (Toys::PositionalArg) —

    The argument definition

  • (nil) —

    if remaining arguments are not supported by this tool.



209
210
211
 
# File 'core-docs/toys/tool_definition.rb', line 209

def remaining_arg
  @remaining_arg
end

#required_args ⇒ Array<Toys::PositionalArg> (readonly)

A list of all defined required positional arguments.

Returns:



194
195
196
 
# File 'core-docs/toys/tool_definition.rb', line 194

def required_args
  @required_args
end

#run_handler ⇒ Proc, ...

The run handler.

This handler is called to run the tool. Normally it is a method name, represented by a symbol. (The default is :run.) It can be set to a different method name, or to a proc that will be called with self set to the tool context. Either way, it takes no arguments. The run handler can also be explicitly set to nil indicating a non-runnable tool; however, typically a tool is made non-runnable simply by leaving the run handler set to :run and not defining the method.

Additionally, if this tool delegates to another tool, the run handler is the full name of the delegate target, as an array of strings. This array may not be modified. Note also that this value cannot be assigned through #run_handler=, which accepts only a proc, symbol, or nil. Delegation is configured by calling #delegate_to, which sets this attribute along with the rest of the delegation state. The getter and setter are thus not symmetrical: the getter can return an array that the setter would reject.

Returns:

  • (Proc) —

    if the run handler is defined as a Proc

  • (Symbol) —

    if the run handler is defined as a method

  • (Array<String>) —

    if this tool delegates to another tool

  • (nil) —

    if the tool is explicitly made non-runnable



300
301
302
 
# File 'core-docs/toys/tool_definition.rb', line 300

def run_handler
  @run_handler
end

#source_info ⇒ Toys::SourceInfo? (readonly)

Info on the source of this tool.

Returns:

  • (Toys::SourceInfo) —

    The source info

  • (nil) —

    if the source is not defined.



247
248
249
 
# File 'core-docs/toys/tool_definition.rb', line 247

def source_info
  @source_info
end

#source_root ⇒ Toys::SourceInfo (readonly)

The root source info defining this tool.

Returns:



130
131
132
 
# File 'core-docs/toys/tool_definition.rb', line 130

def source_root
  @source_root
end

#subtool_middleware_stack ⇒ Array<Toys::Middleware::Spec> (readonly)

The stack of middleware specs used for subtools.

This array may be modified in place.

Returns:



232
233
234
 
# File 'core-docs/toys/tool_definition.rb', line 232

def subtool_middleware_stack
  @subtool_middleware_stack
end

#tool_class ⇒ Class (readonly)

The tool class.

Returns:

  • (Class) 


137
138
139
 
# File 'core-docs/toys/tool_definition.rb', line 137

def tool_class
  @tool_class
end

#usage_error_handler ⇒ Proc, ...

The usage error handler.

This handler is called when at least one usage error is detected during argument parsing, and is called instead of the run method. It can be specified as a Proc, or a Symbol indicating a method to call. It optionally takes an array of ArgParser::UsageError as the sole argument.

Returns:

  • (Proc) —

    if the usage error handler is defined as a Proc

  • (Symbol) —

    if the user error handler is defined as a method

  • (nil) —

    if there is no usage error handler



315
316
317
 
# File 'core-docs/toys/tool_definition.rb', line 315

def usage_error_handler
  @usage_error_handler
end

#used_flags ⇒ Array<String> (readonly)

A list of flags that have been used in the flag definitions.

Returns:

  • (Array<String>) 


216
217
218
 
# File 'core-docs/toys/tool_definition.rb', line 216

def used_flags
  @used_flags
end

Instance Method Details

#add_acceptor(name, acceptor = nil, type_desc: nil, &block) ⇒ self

Add a named acceptor to the tool. This acceptor may be refereneced by name when adding a flag or an arg. See Acceptor.create for detailed information on how to specify an acceptor.

Parameters:

  • name (String) —

    The name of the acceptor.

  • acceptor (Toys::Acceptor::Base, Object) (defaults to: nil) —

    The acceptor to add. You can provide either an acceptor object, or a spec understood by Acceptor.create.

  • type_desc (String) (defaults to: nil) —

    Type description string, shown in help. Defaults to the acceptor name.

  • block (Proc) —

    Optional block used to create an acceptor. See Acceptor.create.

Returns:

  • (self) 


640
641
642
 
# File 'core-docs/toys/tool_definition.rb', line 640

def add_acceptor(name, acceptor = nil, type_desc: nil, &block)
  # Source available in the toys-core gem
end

#add_completion(name, completion = nil, **options, &block) ⇒ self

Add a named completion proc to this tool. The completion may be referenced by name when adding a flag or an arg. See Completion.create for detailed information on how to specify a completion.

Parameters:

  • name (String) —

    The name of the completion.

  • completion (Proc, Toys::Completion::Base, Object) (defaults to: nil) —

    The completion to add. You can provide either a completion object, or a spec understood by Completion.create.

  • options (Hash) —

    Additional options to pass to the completion.

  • block (Proc) —

    Optional block used to create a completion. See Completion.create.

Returns:

  • (self) 


673
674
675
 
# File 'core-docs/toys/tool_definition.rb', line 673

def add_completion(name, completion = nil, **options, &block)
  # Source available in the toys-core gem
end

#add_flag(key, flags = [], accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, group: nil, desc: nil, long_desc: nil, display_name: nil) ⇒ self

Add a flag to the current tool. Each flag must specify a key which the script may use to obtain the flag value from the context. You may then provide the flags themselves in OptionParser form. If a flag is not present in the command line, the value is set to the given default, unless it was already set separately.

Parameters:

  • key (String, Symbol) —

    The key to use to retrieve the value from the execution context.

  • flags (Array<String>) (defaults to: []) —

    The flags in OptionParser format. If empty, a flag will be inferred from the key.

  • accept (Object) (defaults to: nil) —

    An acceptor that validates and/or converts the value. You may provide either the name of an acceptor you have defined, or one of the default acceptors provided by OptionParser. Optional. If not specified, accepts any value as a string.

  • default (Object) (defaults to: nil) —

    The default value. This is the value that will be set in the context if this flag is not provided on the command line. Defaults to nil.

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

    An optional handler that customizes how a value is set or updated. A handler is a proc that takes up to three arguments: the given value, the previous value, and a hash containing all the data collected so far during argument parsing. It must return the new value that should be set. You may also specify a predefined named handler. The :set handler (the default) replaces the previous value (effectively -> (val) { 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 default: [] and is intended for "multi-valued" flags.

  • complete_flags (Object) (defaults to: nil) —

    A specifier for shell tab completion for flag names associated with this flag. By default, a Flag::DefaultCompletion is used, which provides the flag's names as completion candidates. To customize completion, set this to a hash of options to pass to the constructor for Flag::DefaultCompletion, or pass any other spec recognized by Completion.create.

  • complete_values (Object) (defaults to: nil) —

    A specifier for shell tab completion for flag values associated with this flag. Pass any spec recognized by Completion.create.

  • report_collisions (true, false) (defaults to: true) —

    Raise an exception if a flag is requested that is already in use or marked as disabled. Default is true.

  • group (Toys::FlagGroup, String, Symbol, nil) (defaults to: nil) —

    Group for this flag. You may provide a group name, a FlagGroup object, or nil which denotes the default group.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the flag. See #desc for a description of allowed formats. Defaults to the empty string.

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the flag. See #long_desc for a description of allowed formats. Defaults to the empty array.

  • display_name (String) (defaults to: nil) —

    A display name for this flag, used in help text and error messages.

Returns:

  • (self) 


819
820
821
822
823
824
 
# File 'core-docs/toys/tool_definition.rb', line 819

def add_flag(key, flags = [],
             accept: nil, default: nil, handler: nil, complete_flags: nil,
             complete_values: nil, report_collisions: true, group: nil, desc: nil,
             long_desc: nil, display_name: nil)
  # Source available in the toys-core gem
end

#add_flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false) ⇒ self

Add a flag group to the group list.

The type should be one of the following symbols:

  • :optional All flags in the group are optional
  • :required All flags in the group are required
  • :exactly_one Exactly one flag in the group must be provided
  • :at_least_one At least one flag in the group must be provided
  • :at_most_one At most one flag in the group must be provided

Parameters:

  • type (Symbol) (defaults to: :optional) —

    The type of group. Default is :optional.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the group. See #desc for a description of allowed formats. Defaults to "Flags".

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the flag group. See #long_desc for a description of allowed formats. Defaults to the empty array.

  • name (String, Symbol, nil) (defaults to: nil) —

    The name of the group, or nil for no name.

  • report_collisions (true, false) (defaults to: true) —

    If true, raise an exception if a the given name is already taken. If false, ignore. Default is true.

  • prepend (true, false) (defaults to: false) —

    If true, prepend rather than append the group to the list. Default is false.

Returns:

  • (self) 


760
761
762
763
 
# File 'core-docs/toys/tool_definition.rb', line 760

def add_flag_group(type: :optional, desc: nil, long_desc: nil,
                   name: nil, report_collisions: true, prepend: false)
  # Source available in the toys-core gem
end

#add_initializer(proc, *args, **kwargs) ⇒ self

Add an initializer.

Parameters:

  • proc (Proc) —

    The initializer block

  • args (Object...) —

    Arguments to pass to the initializer

  • kwargs (keywords) —

    Keyword arguments to pass to the initializer

Returns:

  • (self) 


1009
1010
1011
 
# File 'core-docs/toys/tool_definition.rb', line 1009

def add_initializer(proc, *args, **kwargs)
  # Source available in the toys-core gem
end

#add_mixin(name, mixin_module = nil, &block) ⇒ self

Add a named mixin module to this tool. You may provide a mixin module or a block that configures one.

Parameters:

  • name (String) —

    The name of the mixin.

  • mixin_module (Module) (defaults to: nil) —

    The mixin module.

  • block (Proc) —

    Define the mixin module here if a mixin_module is not provided directly.

Returns:

  • (self) 


654
655
656
 
# File 'core-docs/toys/tool_definition.rb', line 654

def add_mixin(name, mixin_module = nil, &block)
  # Source available in the toys-core gem
end

#add_optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self

Add an optional positional argument to the current tool. You must specify a key which the script may use to obtain the argument value from the context. If an optional argument is not present in the command line, the value is set to the given default, unless it was already set separately.

In general, arguments are parsed in the order they are added to the tool definition. However, all required arguments are always parsed before all optional arguments, even if they are added afterward.

Parameters:

  • key (String, Symbol) —

    The key to use to retrieve the value from the execution context.

  • default (Object) (defaults to: nil) —

    The default value. This is the value that will be set in the context if this argument is not provided on the command line. Defaults to nil.

  • accept (Object) (defaults to: nil) —

    An acceptor that validates and/or converts the value. You may provide either the name of an acceptor you have defined, or one of the default acceptors provided by OptionParser. Optional. If not specified, accepts any value as a string.

  • complete (Object) (defaults to: nil) —

    A specifier for shell tab completion. See Completion.create for recognized formats.

  • display_name (String) (defaults to: nil) —

    A name to use for display (in help text and error reports). Defaults to the key in upper case.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the arg. See #desc for a description of allowed formats. Defaults to the empty string.

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the arg. See #long_desc for a description of allowed formats. Defaults to the empty array.

Returns:

  • (self) 


901
902
903
904
 
# File 'core-docs/toys/tool_definition.rb', line 901

def add_optional_arg(key, default: nil, accept: nil, complete: nil,
                     display_name: nil, desc: nil, long_desc: nil)
  # Source available in the toys-core gem
end

#add_required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self

Add a required positional argument to the current tool. You must specify a key which the script may use to obtain the argument value from the context.

In general, arguments are parsed in the order they are added to the tool definition. However, all required arguments are always parsed before all optional arguments, even if they are added afterward.

Parameters:

  • key (String, Symbol) —

    The key to use to retrieve the value from the execution context.

  • accept (Object) (defaults to: nil) —

    An acceptor that validates and/or converts the value. You may provide either the name of an acceptor you have defined, or one of the default acceptors provided by OptionParser. Optional. If not specified, accepts any value as a string.

  • complete (Object) (defaults to: nil) —

    A specifier for shell tab completion. See Completion.create for recognized formats.

  • display_name (String) (defaults to: nil) —

    A name to use for display (in help text and error reports). Defaults to the key in upper case.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the arg. See #desc for a description of allowed formats. Defaults to the empty string.

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the arg. See #long_desc for a description of allowed formats. Defaults to the empty array.

Returns:

  • (self) 


865
866
867
868
 
# File 'core-docs/toys/tool_definition.rb', line 865

def add_required_arg(key, accept: nil, complete: nil, display_name: nil,
                     desc: nil, long_desc: nil)
  # Source available in the toys-core gem
end

#add_template(name, template_class = nil, &block) ⇒ self

Add a named template class to this tool. You may provide a template class or a block that configures one.

Parameters:

  • name (String) —

    The name of the template.

  • template_class (Class) (defaults to: nil) —

    The template class.

  • block (Proc) —

    Define the template class here if a template_class is not provided directly.

Returns:

  • (self) 


687
688
689
 
# File 'core-docs/toys/tool_definition.rb', line 687

def add_template(name, template_class = nil, &block)
  # Source available in the toys-core gem
end

#append_long_desc(long_desc) ⇒ self

Append long description strings.

You must pass an array of lines in the long description. See #long_desc for details on how each line may be represented.

Parameters:

Returns:

  • (self) 


621
622
623
 
# File 'core-docs/toys/tool_definition.rb', line 621

def append_long_desc(long_desc)
  # Source available in the toys-core gem
end

#argument_parsing_disabled? ⇒ true, false

Returns true if this tool has disabled argument parsing.

Returns:

  • (true, false) 


462
463
464
 
# File 'core-docs/toys/tool_definition.rb', line 462

def argument_parsing_disabled?
  # Source available in the toys-core gem
end

#context_directory ⇒ String?

Return the tool's context directory.

If there is a custom context directory, uses that. Otherwise, looks for a custom context directory up the tool ancestor chain. If none is found, uses the default context directory from the source info. If the source info has no context directory either, returns nil.

Returns:

  • (String) —

    The context directory path.

  • (nil) —

    if the tool has no context directory.



1060
1061
1062
 
# File 'core-docs/toys/tool_definition.rb', line 1060

def context_directory
  # Source available in the toys-core gem
end

#definition_finished? ⇒ true, false

Returns true if this tool's definition has been finished and is locked.

Returns:

  • (true, false) 


454
455
456
 
# File 'core-docs/toys/tool_definition.rb', line 454

def definition_finished?
  # Source available in the toys-core gem
end

#delegate_to(target) ⇒ self

Causes this tool to delegate to another tool.

This sets #run_handler to the name of the target, disables argument parsing, and replaces #completion with one that defers to the target. It is the only supported way to configure delegation; #run_handler= does not accept a target name.

Parameters:

  • target (Array<String>) —

    The full path to the delegate tool. The elements are converted to strings, and a frozen copy of the array is retained.

Returns:

  • (self) 


1077
1078
1079
 
# File 'core-docs/toys/tool_definition.rb', line 1077

def delegate_to(target)
  # Source available in the toys-core gem
end

#disable_argument_parsing ⇒ self

Disable argument parsing for this tool.

Returns:

  • (self) 


696
697
698
 
# File 'core-docs/toys/tool_definition.rb', line 696

def disable_argument_parsing
  # Source available in the toys-core gem
end

#disable_flag(*flags) ⇒ self

Mark one or more flags as disabled, preventing their use by any subsequent flag definition. This may be used to prevent middleware from defining a particular flag.

Parameters:

  • flags (String...) —

    The flags to disable

Returns:

  • (self) 


834
835
836
 
# File 'core-docs/toys/tool_definition.rb', line 834

def disable_flag(*flags)
  # Source available in the toys-core gem
end

#display_name ⇒ String

A displayable name of this tool, generally the full name delimited by spaces.

Returns:

  • (String) 


341
342
343
 
# File 'core-docs/toys/tool_definition.rb', line 341

def display_name
  # Source available in the toys-core gem
end

#enforce_flags_before_args(state = true) ⇒ self

Enforce that flags must come before args for this tool. You may disable enforcement by passing false for the state.

Parameters:

  • state (true, false) (defaults to: true)

Returns:

  • (self) 


707
708
709
 
# File 'core-docs/toys/tool_definition.rb', line 707

def enforce_flags_before_args(state = true)
  # Source available in the toys-core gem
end

#exact_flag_match_required? ⇒ true, false

Returns true if this tool requires exact flag matches.

Returns:

  • (true, false) 


478
479
480
 
# File 'core-docs/toys/tool_definition.rb', line 478

def exact_flag_match_required?
  # Source available in the toys-core gem
end

#flags_before_args_enforced? ⇒ true, false

Returns true if this tool enforces flags before args.

Returns:

  • (true, false) 


470
471
472
 
# File 'core-docs/toys/tool_definition.rb', line 470

def flags_before_args_enforced?
  # Source available in the toys-core gem
end

#handles_interrupts? ⇒ true, false

Returns true if this tool handles interrupts. This is equivalent to handles_signal?(2).

Returns:

  • (true, false) 


395
396
397
 
# File 'core-docs/toys/tool_definition.rb', line 395

def handles_interrupts?
  # Source available in the toys-core gem
end

#handles_signal?(signal) ⇒ true, false

Returns true if this tool handles the given signal.

Parameters:

  • signal (Integer, String, Symbol) —

    The signal number or name

Returns:

  • (true, false) 


405
406
407
 
# File 'core-docs/toys/tool_definition.rb', line 405

def handles_signal?(signal)
  # Source available in the toys-core gem
end

#handles_usage_errors? ⇒ true, false

Returns true if this tool handles usage errors.

Returns:

  • (true, false) 


413
414
415
 
# File 'core-docs/toys/tool_definition.rb', line 413

def handles_usage_errors?
  # Source available in the toys-core gem
end

#include_mixin(mod, *args, **kwargs) ⇒ self

Include the given mixin in the tool class.

The mixin must be given as a module. You can use #lookup_mixin to resolve named mixins.

Parameters:

  • mod (Module) —

    The mixin module

Returns:

  • (self) 


574
575
576
 
# File 'core-docs/toys/tool_definition.rb', line 574

def include_mixin(mod, *args, **kwargs)
  # Source available in the toys-core gem
end

#includes_arguments? ⇒ true, false

Returns true if at least one flag or positional argument is defined for this tool.

Returns:

  • (true, false) 


438
439
440
 
# File 'core-docs/toys/tool_definition.rb', line 438

def includes_arguments?
  # Source available in the toys-core gem
end

#includes_definition? ⇒ true, false

Returns true if this tool has any definition information.

Returns:

  • (true, false) 


446
447
448
 
# File 'core-docs/toys/tool_definition.rb', line 446

def includes_definition?
  # Source available in the toys-core gem
end

#includes_description? ⇒ true, false

Returns true if there is a specific description set for this tool.

Returns:

  • (true, false) 


429
430
431
 
# File 'core-docs/toys/tool_definition.rb', line 429

def includes_description?
  # Source available in the toys-core gem
end

#includes_modules? ⇒ true, false

Returns true if this tool has at least one included module.

Returns:

  • (true, false) 


421
422
423
 
# File 'core-docs/toys/tool_definition.rb', line 421

def includes_modules?
  # Source available in the toys-core gem
end

#inheritable_helper_methods=(val) ⇒ Object

Set whether helper methods defined in this tool are inherited by subtools.

Parameters:

  • val (true, false, nil) —

    The boolean value. If nil (the default), unsets the value, causing it to revert to the setting of the parent tool if any, or false for the root tool.



1045
1046
1047
 
# File 'core-docs/toys/tool_definition.rb', line 1045

def inheritable_helper_methods=(val)
  # Source available in the toys-core gem
end

#inheritable_helper_methods? ⇒ true, false

Returns true if helper methods defined in this class are inherited by subtools.

Returns:

  • (true, false) 


495
496
497
 
# File 'core-docs/toys/tool_definition.rb', line 495

def inheritable_helper_methods?
  # Source available in the toys-core gem
end

#interrupt_handler ⇒ Proc, ...

Return the interrupt handler. This is equivalent to signal_handler(2).

Returns:

  • (Proc) —

    if the interrupt signal handler is defined as a Proc

  • (Symbol) —

    if the interrupt signal handler is defined as a method

  • (nil) —

    if there is no handler for the interrupt signals



369
370
371
 
# File 'core-docs/toys/tool_definition.rb', line 369

def interrupt_handler
  # Source available in the toys-core gem
end

#interrupt_handler=(handler) ⇒ Object

Set the interrupt handler. This is equivalent to calling #set_signal_handler for the SIGINT signal.

Parameters:

  • handler (Proc, Symbol) —

    The interrupt signal handler



967
968
969
 
# File 'core-docs/toys/tool_definition.rb', line 967

def interrupt_handler=(handler)
  # Source available in the toys-core gem
end

#lock_source(source) ⇒ self

Sets the path to the file that defines this tool. A tool may be defined from at most one path. If a different path is already set, it is left unchanged.

Parameters:

Returns:

  • (self) 


586
587
588
 
# File 'core-docs/toys/tool_definition.rb', line 586

def lock_source(source)
  # Source available in the toys-core gem
end

#lookup_acceptor(name) ⇒ Toys::Acceptor::Base?

Get the named acceptor from this tool or its ancestors.

Parameters:

  • name (String) —

    The acceptor name.

Returns:



528
529
530
 
# File 'core-docs/toys/tool_definition.rb', line 528

def lookup_acceptor(name)
  # Source available in the toys-core gem
end

#lookup_completion(name) ⇒ Toys::Completion::Base, ...

Get the named completion from this tool or its ancestors.

Parameters:

  • name (String) —

    The completion name

Returns:

  • (Toys::Completion::Base, Proc) —

    The completion proc.

  • (nil) —

    if no completion of the given name is found.



561
562
563
 
# File 'core-docs/toys/tool_definition.rb', line 561

def lookup_completion(name)
  # Source available in the toys-core gem
end

#lookup_mixin(name) ⇒ Module?

Get the named mixin from this tool or its ancestors.

Parameters:

  • name (String) —

    The mixin name.

Returns:

  • (Module) —

    The mixin module.

  • (nil) —

    if no mixin of the given name is found.



550
551
552
 
# File 'core-docs/toys/tool_definition.rb', line 550

def lookup_mixin(name)
  # Source available in the toys-core gem
end

#lookup_template(name) ⇒ Class?

Get the named template from this tool or its ancestors.

Parameters:

  • name (String) —

    The template name.

Returns:

  • (Class, nil) —

    The template class.

  • (nil) —

    if no template of the given name is found.



539
540
541
 
# File 'core-docs/toys/tool_definition.rb', line 539

def lookup_template(name)
  # Source available in the toys-core gem
end

#positional_args ⇒ Array<Toys::PositionalArg>

All arg definitions in order: required, optional, remaining.

Returns:



504
505
506
 
# File 'core-docs/toys/tool_definition.rb', line 504

def positional_args
  # Source available in the toys-core gem
end

#priority ⇒ Integer

The priority of this tool definition.

Returns:

  • (Integer) 


121
122
123
 
# File 'core-docs/toys/tool_definition.rb', line 121

def priority
  # Source available in the toys-core gem
end

#require_exact_flag_match(state = true) ⇒ self

Require that flags must match exactly. (If false, flags can match an unambiguous substring.)

Parameters:

  • state (true, false) (defaults to: true)

Returns:

  • (self) 


718
719
720
 
# File 'core-docs/toys/tool_definition.rb', line 718

def require_exact_flag_match(state = true)
  # Source available in the toys-core gem
end

#resolve_flag(str) ⇒ Toys::Flag::Resolution

Resolve the given flag given the flag string. Returns an object that describes the resolution result, including whether the resolution matched a unique flag, the specific flag syntax that was matched, and additional information.

Parameters:

  • str (String) —

    Flag string

Returns:



517
518
519
 
# File 'core-docs/toys/tool_definition.rb', line 517

def resolve_flag(str)
  # Source available in the toys-core gem
end

#root? ⇒ true, false

Returns true if this tool is a root tool.

Returns:

  • (true, false) 


377
378
379
 
# File 'core-docs/toys/tool_definition.rb', line 377

def root?
  # Source available in the toys-core gem
end

#runnable? ⇒ true, false

Returns true if this tool is marked as runnable.

Returns:

  • (true, false) 


385
386
387
 
# File 'core-docs/toys/tool_definition.rb', line 385

def runnable?
  # Source available in the toys-core gem
end

#set_remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self

Specify what should be done with unmatched positional arguments. You must specify a key which the script may use to obtain the remaining args from the context. If no remaining arguments were present in the command line, the value is set to the given default (normally the empty array), unless it was already set separately.

Parameters:

  • key (String, Symbol) —

    The key to use to retrieve the value from the execution context.

  • default (Object) (defaults to: []) —

    The default value. This is the value that will be set in the context if no unmatched arguments are provided on the command line. Defaults to the empty array [].

  • accept (Object) (defaults to: nil) —

    An acceptor that validates and/or converts the value. You may provide either the name of an acceptor you have defined, or one of the default acceptors provided by OptionParser. Optional. If not specified, accepts any value as a string.

  • complete (Object) (defaults to: nil) —

    A specifier for shell tab completion. See Completion.create for recognized formats.

  • display_name (String) (defaults to: nil) —

    A name to use for display (in help text and error reports). Defaults to the key in upper case.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the arg. See #desc for a description of allowed formats. Defaults to the empty string.

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the arg. See #long_desc for a description of allowed formats. Defaults to the empty array.

Returns:

  • (self) 


934
935
936
937
 
# File 'core-docs/toys/tool_definition.rb', line 934

def set_remaining_args(key, default: [], accept: nil, complete: nil,
                       display_name: nil, desc: nil, long_desc: nil)
  # Source available in the toys-core gem
end

#set_signal_handler(signal, handler) ⇒ Object

Set the handler for the given signal.

This handler is called when the given signal is received, immediately taking over the execution as if it were the new run method. The signal handler can be specified as a Proc, or a Symbol indicating a method to call. It optionally takes the SignalException as the sole argument.

Parameters:

  • signal (Integer, String, Symbol) —

    The signal number or name

  • handler (Proc, Symbol) —

    The signal handler



982
983
984
 
# File 'core-docs/toys/tool_definition.rb', line 982

def set_signal_handler(signal, handler)
  # Source available in the toys-core gem
end

#signal_handler(signal) ⇒ Proc, ...

Return the signal handler for the given signal.

This handler is called when the given signal is received, immediately taking over the execution as if it were the new run handler. The signal handler can be specified as a Proc, or a Symbol indicating a method to call. It optionally takes the SignalException as the sole argument.

Parameters:

  • signal (Integer, String, Symbol) —

    The signal number or name

Returns:

  • (Proc) —

    if the signal handler is defined as a Proc

  • (Symbol) —

    if the signal handler is defined as a method

  • (nil) —

    if there is no handler for the given signal



358
359
360
 
# File 'core-docs/toys/tool_definition.rb', line 358

def signal_handler(signal)
  # Source available in the toys-core gem
end

#simple_name ⇒ String

The local name of this tool, i.e. the last element of the full name.

Returns:

  • (String) 


331
332
333
 
# File 'core-docs/toys/tool_definition.rb', line 331

def simple_name
  # Source available in the toys-core gem
end

#treat_unknown_flags_as_args(state = true) ⇒ self

Treat unknown flags as positional arguments rather than reporting them as usage errors.

Parameters:

  • state (true, false) (defaults to: true)

Returns:

  • (self) 


729
730
731
 
# File 'core-docs/toys/tool_definition.rb', line 729

def treat_unknown_flags_as_args(state = true)
  # Source available in the toys-core gem
end

#unknown_flags_are_args? ⇒ true, false

Returns true if this tool treats unknown flags as positional arguments.

Returns:

  • (true, false) 


486
487
488
 
# File 'core-docs/toys/tool_definition.rb', line 486

def unknown_flags_are_args?
  # Source available in the toys-core gem
end