Class: Toys::ToolDefinition

Inherits:
Object
  • Object
show all
Defined in:
lib/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.

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:



455
456
457
 
# File 'lib/toys/tool_definition.rb', line 455

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:



490
491
492
 
# File 'lib/toys/tool_definition.rb', line 490

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.



471
472
473
 
# File 'lib/toys/tool_definition.rb', line 471

def custom_context_directory
  @custom_context_directory
end

#default_data ⇒ Hash (readonly)

The default context data set by arguments.

Returns:

  • (Hash) 


439
440
441
 
# File 'lib/toys/tool_definition.rb', line 439

def default_data
  @default_data
end

#delegate_target ⇒ Array<String>? (readonly)

The full name of the delegate target, if any.

Returns:

  • (Array<String>) —

    if this tool delegates

  • (nil) —

    if this tool does not delegate



530
531
532
 
# File 'lib/toys/tool_definition.rb', line 530

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:



370
371
372
 
# File 'lib/toys/tool_definition.rb', line 370

def desc
  @desc
end

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

A list of all defined flag groups, in order.

Returns:



396
397
398
 
# File 'lib/toys/tool_definition.rb', line 396

def flag_groups
  @flag_groups
end

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

A list of all defined flags.

Returns:



403
404
405
 
# File 'lib/toys/tool_definition.rb', line 403

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>) 


332
333
334
 
# File 'lib/toys/tool_definition.rb', line 332

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:



389
390
391
 
# File 'lib/toys/tool_definition.rb', line 389

def long_desc
  @long_desc
end

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

A list of all defined optional positional arguments.

Returns:



417
418
419
 
# File 'lib/toys/tool_definition.rb', line 417

def optional_args
  @optional_args
end

#priority ⇒ Integer (readonly)

The priority of this tool definition.

Returns:

  • (Integer) 


339
340
341
 
# File 'lib/toys/tool_definition.rb', line 339

def priority
  @priority
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.



425
426
427
 
# File 'lib/toys/tool_definition.rb', line 425

def remaining_arg
  @remaining_arg
end

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

A list of all defined required positional arguments.

Returns:



410
411
412
 
# File 'lib/toys/tool_definition.rb', line 410

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.

Returns:

  • (Proc) —

    if the run handler is defined as a Proc

  • (Symbol) —

    if the run handler is defined as a method

  • (nil) —

    if the tool is explicitly made non-runnable



507
508
509
 
# File 'lib/toys/tool_definition.rb', line 507

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.



463
464
465
 
# File 'lib/toys/tool_definition.rb', line 463

def source_info
  @source_info
end

#source_root ⇒ Toys::SourceInfo? (readonly)

The root source info defining this tool, or nil if there is no source.

Returns:



346
347
348
 
# File 'lib/toys/tool_definition.rb', line 346

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:



448
449
450
 
# File 'lib/toys/tool_definition.rb', line 448

def subtool_middleware_stack
  @subtool_middleware_stack
end

#tool_class ⇒ Class (readonly)

The tool class.

Returns:

  • (Class) 


353
354
355
 
# File 'lib/toys/tool_definition.rb', line 353

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



522
523
524
 
# File 'lib/toys/tool_definition.rb', line 522

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>) 


432
433
434
 
# File 'lib/toys/tool_definition.rb', line 432

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) 


875
876
877
878
879
880
881
882
883
884
 
# File 'lib/toys/tool_definition.rb', line 875

def add_acceptor(name, acceptor = nil, type_desc: nil, &block)
  name = name.to_s
  if @acceptors.key?(name)
    raise ToolDefinitionError,
          "An acceptor named #{name.inspect} has already been defined in tool" \
          " #{display_name.inspect}."
  end
  @acceptors[name] = Toys::Acceptor.create(acceptor, type_desc: type_desc, &block)
  self
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) 


922
923
924
925
926
927
928
929
930
931
 
# File 'lib/toys/tool_definition.rb', line 922

def add_completion(name, completion = nil, **options, &block)
  name = name.to_s
  if @completions.key?(name)
    raise ToolDefinitionError,
          "A completion named #{name.inspect} has already been defined in tool" \
          " #{display_name.inspect}."
  end
  @completions[name] = Toys::Completion.create(completion, **options, &block)
  self
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.

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) 


1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
 
# File 'lib/toys/tool_definition.rb', line 1101

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)
  unless group.is_a?(FlagGroup::Base)
    group_name = group
    group = @flag_group_names[group_name]
    raise ToolDefinitionError, "No such flag group: #{group_name.inspect}" if group.nil?
  end
  check_definition_state(is_arg: true)
  accept = resolve_acceptor_name(accept)
  complete_flags = resolve_completion_name(complete_flags)
  complete_values = resolve_completion_name(complete_values)
  flag_def = Flag.new(key, flags, @used_flags, report_collisions, accept, handler, default,
                      complete_flags, complete_values, desc, long_desc, display_name, group)
  if flag_def.active?
    @flags << flag_def
    group << flag_def
  end
  @default_data[key] = default
  self
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) 


1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
 
# File 'lib/toys/tool_definition.rb', line 1033

def add_flag_group(type: :optional, desc: nil, long_desc: nil,
                   name: nil, report_collisions: true, prepend: false)
  if !name.nil? && @flag_group_names.key?(name)
    return self unless report_collisions
    raise ToolDefinitionError, "Flag group #{name} already exists"
  end
  group = FlagGroup.create(type: type, name: name, desc: desc, long_desc: long_desc)
  @flag_group_names[name] = group unless name.nil?
  if prepend
    @flag_groups.unshift(group)
  else
    @flag_groups.push(group)
  end
  self
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) 


1340
1341
1342
1343
1344
 
# File 'lib/toys/tool_definition.rb', line 1340

def add_initializer(proc, *args, **kwargs)
  check_definition_state
  @initializers << [proc, args, kwargs]
  self
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) 


896
897
898
899
900
901
902
903
904
905
 
# File 'lib/toys/tool_definition.rb', line 896

def add_mixin(name, mixin_module = nil, &block)
  name = name.to_s
  if @mixins.key?(name)
    raise ToolDefinitionError,
          "A mixin named #{name.inspect} has already been defined in tool" \
          " #{display_name.inspect}."
  end
  @mixins[name] = mixin_module || Mixin.create(&block)
  self
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 given on the command line, the value is set to the given default.

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) 


1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
 
# File 'lib/toys/tool_definition.rb', line 1212

def add_optional_arg(key, default: nil, accept: nil, complete: nil,
                     display_name: nil, desc: nil, long_desc: nil)
  check_definition_state(is_arg: true)
  accept = resolve_acceptor_name(accept)
  complete = resolve_completion_name(complete)
  arg_def = PositionalArg.new(key, :optional, accept, default, complete,
                              desc, long_desc, display_name)
  @optional_args << arg_def
  @default_data[key] = default
  self
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) 


1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
 
# File 'lib/toys/tool_definition.rb', line 1170

def add_required_arg(key, accept: nil, complete: nil, display_name: nil,
                     desc: nil, long_desc: nil)
  check_definition_state(is_arg: true)
  accept = resolve_acceptor_name(accept)
  complete = resolve_completion_name(complete)
  arg_def = PositionalArg.new(key, :required, accept, nil, complete,
                              desc, long_desc, display_name)
  @required_args << arg_def
  self
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) 


943
944
945
946
947
948
949
950
951
952
 
# File 'lib/toys/tool_definition.rb', line 943

def add_template(name, template_class = nil, &block)
  name = name.to_s
  if @templates.key?(name)
    raise ToolDefinitionError,
          "A template named #{name.inspect} has already been defined in tool" \
          " #{display_name.inspect}."
  end
  @templates[name] = template_class || Template.create(&block)
  self
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) 


854
855
856
857
858
 
# File 'lib/toys/tool_definition.rb', line 854

def append_long_desc(long_desc)
  check_definition_state
  @long_desc.concat(WrappableString.make_array(long_desc))
  self
end

#argument_parsing_disabled? ⇒ true, false

Returns true if this tool has disabled argument parsing.

Returns:

  • (true, false) 


672
673
674
 
# File 'lib/toys/tool_definition.rb', line 672

def argument_parsing_disabled?
  @disable_argument_parsing
end

#context_directory ⇒ String?

Return the effective 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. It is possible for there to be no context directory at all, in which case, returns nil.

Returns:

  • (String) —

    The effective context directory path.

  • (nil) —

    if there is no effective context directory.



1414
1415
1416
 
# File 'lib/toys/tool_definition.rb', line 1414

def context_directory
  lookup_custom_context_directory || source_info&.context_directory
end

#definition_finished? ⇒ true, false

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

Returns:

  • (true, false) 


664
665
666
 
# File 'lib/toys/tool_definition.rb', line 664

def definition_finished?
  @definition_finished
end

#delegate_to(target) ⇒ self

Causes this tool to delegate to another tool.

Parameters:

  • target (Array<String>) —

    The full path to the delegate tool.

Returns:

  • (self) 


1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
 
# File 'lib/toys/tool_definition.rb', line 1424

def delegate_to(target)
  if @delegate_target
    return self if target == @delegate_target
    raise ToolDefinitionError,
          "Cannot delegate tool #{display_name.inspect} to #{target.join(' ')} because it" \
          " already delegates to \"#{@delegate_target.join(' ')}\"."
  end
  if includes_arguments? || runnable? || run_handler != :run || includes_modules? || !default_data.empty?
    raise ToolDefinitionError,
          "Cannot delegate tool #{display_name.inspect} because" \
          " some implementation has already been created for it."
  end
  disable_argument_parsing
  self.run_handler = make_delegation_run_handler(target)
  self.completion = DefaultCompletion.new(delegation_target: target)
  @delegate_target = target
  self
end

#disable_argument_parsing ⇒ self

Disable argument parsing for this tool.

Returns:

  • (self) 


959
960
961
962
963
964
965
966
967
968
 
# File 'lib/toys/tool_definition.rb', line 959

def disable_argument_parsing
  check_definition_state
  if includes_arguments?
    raise ToolDefinitionError,
          "Cannot disable argument parsing for tool #{display_name.inspect}" \
          " because arguments have already been defined."
  end
  @disable_argument_parsing = true
  self
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) 


1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
 
# File 'lib/toys/tool_definition.rb', line 1132

def disable_flag(*flags)
  check_definition_state(is_arg: true)
  flags = flags.uniq
  intersection = @used_flags & flags
  unless intersection.empty?
    raise ToolDefinitionError, "Cannot disable flags already used: #{intersection.inspect}"
  end
  @used_flags.concat(flags)
  self
end

#display_name ⇒ String

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

Returns:

  • (String) 


547
548
549
 
# File 'lib/toys/tool_definition.rb', line 547

def display_name
  full_name.join(" ")
end

#enforce_flags_before_args(state = true) ⇒ self

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

Parameters:

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

Returns:

  • (self) 


977
978
979
980
981
982
983
984
985
986
 
# File 'lib/toys/tool_definition.rb', line 977

def enforce_flags_before_args(state = true)
  check_definition_state
  if argument_parsing_disabled?
    raise ToolDefinitionError,
          "Cannot enforce flags before args for tool #{display_name.inspect}" \
          " because parsing is disabled."
  end
  @enforce_flags_before_args = state
  self
end

#exact_flag_match_required? ⇒ true, false

Returns true if this tool requires exact flag matches.

Returns:

  • (true, false) 


688
689
690
 
# File 'lib/toys/tool_definition.rb', line 688

def exact_flag_match_required?
  @require_exact_flag_match
end

#flags_before_args_enforced? ⇒ true, false

Returns true if this tool enforces flags before args.

Returns:

  • (true, false) 


680
681
682
 
# File 'lib/toys/tool_definition.rb', line 680

def flags_before_args_enforced?
  @enforce_flags_before_args
end

#handles_interrupts? ⇒ true, false

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

Returns:

  • (true, false) 


602
603
604
 
# File 'lib/toys/tool_definition.rb', line 602

def handles_interrupts?
  handles_signal?(2)
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) 


612
613
614
615
 
# File 'lib/toys/tool_definition.rb', line 612

def handles_signal?(signal)
  signal = canonicalize_signal(signal)
  !@signal_handlers[signal].nil?
end

#handles_usage_errors? ⇒ true, false

Returns true if this tool handles usage errors.

Returns:

  • (true, false) 


621
622
623
 
# File 'lib/toys/tool_definition.rb', line 621

def handles_usage_errors?
  !usage_error_handler.nil?
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) 


786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
 
# File 'lib/toys/tool_definition.rb', line 786

def include_mixin(mod, *args, **kwargs)
  check_definition_state
  if tool_class.included_modules.include?(mod)
    raise ToolDefinitionError, "Mixin already included: #{mod.name}"
  end
  @includes_modules = true
  if tool_class.respond_to?(:include_module)
    tool_class.include_module(mod)
  else
    tool_class.include(mod)
  end
  if mod.respond_to?(:initializer)
    callback = mod.initializer
    add_initializer(callback, *args, **kwargs) if callback
  end
  if mod.respond_to?(:inclusion)
    callback = mod.inclusion
    tool_class.class_exec(*args, **kwargs, &callback) if callback
  end
  self
end

#includes_arguments? ⇒ true, false

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

Returns:

  • (true, false) 


646
647
648
649
 
# File 'lib/toys/tool_definition.rb', line 646

def includes_arguments?
  !flags.empty? || !required_args.empty? || !optional_args.empty? ||
    !remaining_arg.nil? || flags_before_args_enforced?
end

#includes_definition? ⇒ true, false

Returns true if this tool has any definition information.

Returns:

  • (true, false) 


655
656
657
658
 
# File 'lib/toys/tool_definition.rb', line 655

def includes_definition?
  includes_arguments? || runnable? || argument_parsing_disabled? ||
    includes_modules? || includes_description? || !default_data.empty?
end

#includes_description? ⇒ true, false

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

Returns:

  • (true, false) 


637
638
639
 
# File 'lib/toys/tool_definition.rb', line 637

def includes_description?
  !long_desc.empty? || !desc.empty?
end

#includes_modules? ⇒ true, false

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

Returns:

  • (true, false) 


629
630
631
 
# File 'lib/toys/tool_definition.rb', line 629

def includes_modules?
  @includes_modules
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.



1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
 
# File 'lib/toys/tool_definition.rb', line 1390

def inheritable_helper_methods=(val)
  check_definition_state
  @inheritable_helper_methods =
    case val
    when nil
      nil
    when false
      false
    else
      true
    end
end

#inheritable_helper_methods? ⇒ true, false

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

Returns:

  • (true, false) 


697
698
699
700
701
702
703
 
# File 'lib/toys/tool_definition.rb', line 697

def inheritable_helper_methods?
  if @inheritable_helper_methods.nil?
    @parent&.inheritable_helper_methods? || false
  else
    @inheritable_helper_methods
  end
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



575
576
577
 
# File 'lib/toys/tool_definition.rb', line 575

def interrupt_handler
  signal_handler(2)
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



1289
1290
1291
 
# File 'lib/toys/tool_definition.rb', line 1289

def interrupt_handler=(handler)
  set_signal_handler(2, handler)
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) 


816
817
818
819
 
# File 'lib/toys/tool_definition.rb', line 816

def lock_source(source)
  @source_info ||= source
  self
end

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

Get the named acceptor from this tool or its ancestors.

Parameters:

  • name (String) —

    The acceptor name.

Returns:



740
741
742
 
# File 'lib/toys/tool_definition.rb', line 740

def lookup_acceptor(name)
  @acceptors.fetch(name.to_s) { |k| @parent&.lookup_acceptor(k) }
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.



773
774
775
 
# File 'lib/toys/tool_definition.rb', line 773

def lookup_completion(name)
  @completions.fetch(name.to_s) { |k| @parent&.lookup_completion(k) }
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.



762
763
764
 
# File 'lib/toys/tool_definition.rb', line 762

def lookup_mixin(name)
  @mixins.fetch(name.to_s) { |k| @parent&.lookup_mixin(k) }
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.



751
752
753
 
# File 'lib/toys/tool_definition.rb', line 751

def lookup_template(name)
  @templates.fetch(name.to_s) { |k| @parent&.lookup_template(k) }
end

#positional_args ⇒ Array<Toys::PositionalArg>

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

Returns:



710
711
712
713
714
 
# File 'lib/toys/tool_definition.rb', line 710

def positional_args
  result = required_args + optional_args
  result << remaining_arg if remaining_arg
  result
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) 


995
996
997
998
999
1000
1001
1002
1003
1004
 
# File 'lib/toys/tool_definition.rb', line 995

def require_exact_flag_match(state = true)
  check_definition_state
  if argument_parsing_disabled?
    raise ToolDefinitionError,
          "Cannot require exact flag match for tool" \
          " #{display_name.inspect} because parsing is disabled."
  end
  @require_exact_flag_match = state
  self
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:



725
726
727
728
729
730
731
 
# File 'lib/toys/tool_definition.rb', line 725

def resolve_flag(str)
  result = Flag::Resolution.new(str)
  flags.each do |flag_def|
    result.merge!(flag_def.resolve(str))
  end
  result
end

#root? ⇒ true, false

Returns true if this tool is a root tool.

Returns:

  • (true, false) 


583
584
585
 
# File 'lib/toys/tool_definition.rb', line 583

def root?
  full_name.empty?
end

#runnable? ⇒ true, false

Returns true if this tool is marked as runnable.

Returns:

  • (true, false) 


591
592
593
594
 
# File 'lib/toys/tool_definition.rb', line 591

def runnable?
  @run_handler.is_a?(::Proc) ||
    (@run_handler.is_a?(::Symbol) && tool_class.public_instance_methods(false).include?(@run_handler))
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.

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) 


1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
 
# File 'lib/toys/tool_definition.rb', line 1250

def set_remaining_args(key, default: [], accept: nil, complete: nil,
                       display_name: nil, desc: nil, long_desc: nil)
  check_definition_state(is_arg: true)
  accept = resolve_acceptor_name(accept)
  complete = resolve_completion_name(complete)
  arg_def = PositionalArg.new(key, :remaining, accept, default, complete,
                              desc, long_desc, display_name)
  @remaining_arg = arg_def
  @default_data[key] = default
  self
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



1304
1305
1306
1307
1308
1309
1310
1311
 
# File 'lib/toys/tool_definition.rb', line 1304

def set_signal_handler(signal, handler)
  check_definition_state(is_method: true)
  if !handler.is_a?(::Proc) && !handler.is_a?(::Symbol) && !handler.nil?
    raise ToolDefinitionError, "Signal handler must be a proc or symbol"
  end
  signal = canonicalize_signal(signal)
  @signal_handlers[signal] = handler
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



564
565
566
 
# File 'lib/toys/tool_definition.rb', line 564

def signal_handler(signal)
  @signal_handlers[canonicalize_signal(signal)]
end

#simple_name ⇒ String

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

Returns:

  • (String) 


537
538
539
 
# File 'lib/toys/tool_definition.rb', line 537

def simple_name
  full_name.last
end