Class: Toys::ToolDefinition
- Inherits:
-
Object
- Object
- Toys::ToolDefinition
- Defined in:
- toys-core/lib/toys/tool_definition.rb
Overview
Defined in the toys-core gem
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, Settings
Instance Attribute Summary collapse
-
#built_middleware ⇒ Array<Toys::Middleware>
readonly
The stack of built middleware specs for this tool.
-
#completion ⇒ Toys::Completion::Base, Proc
The completion strategy for this tool.
-
#custom_context_directory ⇒ String?
The custom context directory set for this tool.
-
#default_data ⇒ Hash
readonly
The default context data set by arguments.
-
#delegate_target ⇒ Array<String>?
readonly
The full name of the delegate target, if any.
-
#desc ⇒ Toys::WrappableString
The short description string.
-
#flag_groups ⇒ Array<Toys::FlagGroup>
readonly
A list of all defined flag groups, in order.
-
#flags ⇒ Array<Toys::Flag>
readonly
A list of all defined flags.
-
#full_name ⇒ Array<String>
readonly
The name of the tool as an array of strings.
-
#interrupt_handler ⇒ Proc, ...
The interrupt handler.
-
#long_desc ⇒ Array<Toys::WrappableString>
The long description strings.
-
#optional_args ⇒ Array<Toys::PositionalArg>
readonly
A list of all defined optional positional arguments.
-
#priority ⇒ Integer
readonly
The priority of this tool definition.
-
#remaining_arg ⇒ Toys::PositionalArg?
readonly
The remaining arguments specification.
-
#required_args ⇒ Array<Toys::PositionalArg>
readonly
A list of all defined required positional arguments.
-
#settings ⇒ Toys::Tool::Settings
readonly
Settings for this tool.
-
#source_info ⇒ Toys::SourceInfo?
readonly
Info on the source of this tool.
-
#source_root ⇒ Toys::SourceInfo?
readonly
The root source info defining this tool, or nil if there is no source.
-
#subtool_middleware_stack ⇒ Array<Toys::Middleware::Spec>
readonly
The stack of middleware specs used for subtools.
-
#tool_class ⇒ Class
readonly
The tool class.
-
#usage_error_handler ⇒ Proc, ...
The usage error handler.
-
#used_flags ⇒ Array<String>
readonly
A list of flags that have been used in the flag definitions.
Instance Method Summary collapse
-
#add_acceptor(name, acceptor = nil, type_desc: nil, &block) ⇒ self
Add a named acceptor to the tool.
-
#add_completion(name, completion = nil, **options, &block) ⇒ self
Add a named completion proc to this tool.
-
#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.
-
#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.
-
#add_initializer(proc, *args, **kwargs) ⇒ self
Add an initializer.
-
#add_mixin(name, mixin_module = nil, &block) ⇒ self
Add a named mixin module to this tool.
-
#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.
-
#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.
-
#add_template(name, template_class = nil, &block) ⇒ self
Add a named template class to this tool.
-
#append_long_desc(long_desc) ⇒ self
Append long description strings.
-
#argument_parsing_disabled? ⇒ Boolean
Returns true if this tool has disabled argument parsing.
-
#context_directory ⇒ String?
Return the effective context directory.
-
#definition_finished? ⇒ Boolean
Returns true if this tool's definition has been finished and is locked.
-
#delegate_to(target) ⇒ self
Causes this tool to delegate to another tool.
-
#disable_argument_parsing ⇒ self
Disable argument parsing for this tool.
-
#disable_flag(*flags) ⇒ self
Mark one or more flags as disabled, preventing their use by any subsequent flag definition.
-
#display_name ⇒ String
A displayable name of this tool, generally the full name delimited by spaces.
-
#enforce_flags_before_args(state = true) ⇒ self
Enforce that flags must come before args for this tool.
-
#exact_flag_match_required? ⇒ Boolean
Returns true if this tool requires exact flag matches.
-
#flags_before_args_enforced? ⇒ Boolean
Returns true if this tool enforces flags before args.
-
#handles_interrupts? ⇒ Boolean
Returns true if this tool handles interrupts.
-
#handles_usage_errors? ⇒ Boolean
Returns true if this tool handles usage errors.
-
#include_mixin(mod, *args, **kwargs) ⇒ self
Include the given mixin in the tool class.
-
#includes_arguments? ⇒ Boolean
Returns true if at least one flag or positional argument is defined for this tool.
-
#includes_definition? ⇒ Boolean
Returns true if this tool has any definition information.
-
#includes_description? ⇒ Boolean
Returns true if there is a specific description set for this tool.
-
#includes_modules? ⇒ Boolean
Returns true if this tool has at least one included module.
-
#lock_source(source) ⇒ self
Sets the path to the file that defines this tool.
-
#lookup_acceptor(name) ⇒ Toys::Acceptor::Base?
Get the named acceptor from this tool or its ancestors.
-
#lookup_completion(name) ⇒ Toys::Completion::Base, ...
Get the named completion from this tool or its ancestors.
-
#lookup_mixin(name) ⇒ Module?
Get the named mixin from this tool or its ancestors.
-
#lookup_template(name) ⇒ Class?
Get the named template from this tool or its ancestors.
-
#positional_args ⇒ Array<Toys::PositionalArg>
All arg definitions in order: required, optional, remaining.
-
#require_exact_flag_match(state = true) ⇒ self
Require that flags must match exactly.
-
#resolve_flag(str) ⇒ Toys::Flag::Resolution
Resolve the given flag given the flag string.
-
#root? ⇒ Boolean
Returns true if this tool is a root tool.
-
#run_handler=(proc) ⇒ Object
Set the run handler block.
-
#runnable? ⇒ Boolean
Returns true if this tool is marked as runnable.
-
#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.
-
#simple_name ⇒ String
The local name of this tool, i.e.
Instance Attribute Details
#built_middleware ⇒ Array<Toys::Middleware> (readonly)
The stack of built middleware specs for this tool.
218 219 220 |
# File 'toys-core/lib/toys/tool_definition.rb', line 218 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.
253 254 255 |
# File 'toys-core/lib/toys/tool_definition.rb', line 253 def completion @completion end |
#custom_context_directory ⇒ String?
The custom context directory set for this tool.
234 235 236 |
# File 'toys-core/lib/toys/tool_definition.rb', line 234 def custom_context_directory @custom_context_directory end |
#default_data ⇒ Hash (readonly)
The default context data set by arguments.
202 203 204 |
# File 'toys-core/lib/toys/tool_definition.rb', line 202 def default_data @default_data end |
#delegate_target ⇒ Array<String>? (readonly)
The full name of the delegate target, if any.
279 280 281 |
# File 'toys-core/lib/toys/tool_definition.rb', line 279 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.
133 134 135 |
# File 'toys-core/lib/toys/tool_definition.rb', line 133 def desc @desc end |
#flag_groups ⇒ Array<Toys::FlagGroup> (readonly)
A list of all defined flag groups, in order.
159 160 161 |
# File 'toys-core/lib/toys/tool_definition.rb', line 159 def flag_groups @flag_groups end |
#flags ⇒ Array<Toys::Flag> (readonly)
A list of all defined flags.
166 167 168 |
# File 'toys-core/lib/toys/tool_definition.rb', line 166 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.
95 96 97 |
# File 'toys-core/lib/toys/tool_definition.rb', line 95 def full_name @full_name end |
#interrupt_handler ⇒ Proc, ...
The interrupt handler.
262 263 264 |
# File 'toys-core/lib/toys/tool_definition.rb', line 262 def interrupt_handler @interrupt_handler 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.
152 153 154 |
# File 'toys-core/lib/toys/tool_definition.rb', line 152 def long_desc @long_desc end |
#optional_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined optional positional arguments.
180 181 182 |
# File 'toys-core/lib/toys/tool_definition.rb', line 180 def optional_args @optional_args end |
#priority ⇒ Integer (readonly)
The priority of this tool definition.
102 103 104 |
# File 'toys-core/lib/toys/tool_definition.rb', line 102 def priority @priority end |
#remaining_arg ⇒ Toys::PositionalArg? (readonly)
The remaining arguments specification.
188 189 190 |
# File 'toys-core/lib/toys/tool_definition.rb', line 188 def remaining_arg @remaining_arg end |
#required_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined required positional arguments.
173 174 175 |
# File 'toys-core/lib/toys/tool_definition.rb', line 173 def required_args @required_args end |
#settings ⇒ Toys::Tool::Settings (readonly)
Settings for this tool
87 88 89 |
# File 'toys-core/lib/toys/tool_definition.rb', line 87 def settings @settings end |
#source_info ⇒ Toys::SourceInfo? (readonly)
Info on the source of this tool.
226 227 228 |
# File 'toys-core/lib/toys/tool_definition.rb', line 226 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.
109 110 111 |
# File 'toys-core/lib/toys/tool_definition.rb', line 109 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.
211 212 213 |
# File 'toys-core/lib/toys/tool_definition.rb', line 211 def subtool_middleware_stack @subtool_middleware_stack end |
#tool_class ⇒ Class (readonly)
The tool class.
116 117 118 |
# File 'toys-core/lib/toys/tool_definition.rb', line 116 def tool_class @tool_class end |
#usage_error_handler ⇒ Proc, ...
The usage error handler.
271 272 273 |
# File 'toys-core/lib/toys/tool_definition.rb', line 271 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.
195 196 197 |
# File 'toys-core/lib/toys/tool_definition.rb', line 195 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.
570 571 572 573 574 575 576 577 578 579 |
# File 'toys-core/lib/toys/tool_definition.rb', line 570 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.
617 618 619 620 621 622 623 624 625 626 |
# File 'toys-core/lib/toys/tool_definition.rb', line 617 def add_completion(name, completion = nil, **, &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, **, &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.
795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 |
# File 'toys-core/lib/toys/tool_definition.rb', line 795 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
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 |
# File 'toys-core/lib/toys/tool_definition.rb', line 728 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.
994 995 996 997 998 |
# File 'toys-core/lib/toys/tool_definition.rb', line 994 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.
591 592 593 594 595 596 597 598 599 600 |
# File 'toys-core/lib/toys/tool_definition.rb', line 591 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.
898 899 900 901 902 903 904 905 906 907 908 |
# File 'toys-core/lib/toys/tool_definition.rb', line 898 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.
860 861 862 863 864 865 866 867 868 869 |
# File 'toys-core/lib/toys/tool_definition.rb', line 860 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.
638 639 640 641 642 643 644 645 646 647 |
# File 'toys-core/lib/toys/tool_definition.rb', line 638 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.
549 550 551 552 553 |
# File 'toys-core/lib/toys/tool_definition.rb', line 549 def append_long_desc(long_desc) check_definition_state @long_desc.concat(WrappableString.make_array(long_desc)) self end |
#argument_parsing_disabled? ⇒ Boolean
Returns true if this tool has disabled argument parsing.
380 381 382 |
# File 'toys-core/lib/toys/tool_definition.rb', line 380 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.
1044 1045 1046 |
# File 'toys-core/lib/toys/tool_definition.rb', line 1044 def context_directory lookup_custom_context_directory || source_info&.context_directory end |
#definition_finished? ⇒ Boolean
Returns true if this tool's definition has been finished and is locked.
372 373 374 |
# File 'toys-core/lib/toys/tool_definition.rb', line 372 def definition_finished? @definition_finished end |
#delegate_to(target) ⇒ self
Causes this tool to delegate to another tool.
1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 |
# File 'toys-core/lib/toys/tool_definition.rb', line 1054 def delegate_to(target) if @delegate_target raise ToolDefinitionError, "Cannot delegate tool #{display_name.inspect} because" \ " it already delegates to \"#{@delegate_target.join(' ')}\"." end if includes_arguments? raise ToolDefinitionError, "Cannot delegate tool #{display_name.inspect} because" \ " arguments have already been defined." end if runnable? raise ToolDefinitionError, "Cannot delegate tool #{display_name.inspect} because" \ " the run method has already been defined." 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.
654 655 656 657 658 659 660 661 662 663 |
# File 'toys-core/lib/toys/tool_definition.rb', line 654 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.
826 827 828 829 830 831 832 833 834 835 |
# File 'toys-core/lib/toys/tool_definition.rb', line 826 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.
296 297 298 |
# File 'toys-core/lib/toys/tool_definition.rb', line 296 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.
672 673 674 675 676 677 678 679 680 681 |
# File 'toys-core/lib/toys/tool_definition.rb', line 672 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? ⇒ Boolean
Returns true if this tool requires exact flag matches.
396 397 398 |
# File 'toys-core/lib/toys/tool_definition.rb', line 396 def exact_flag_match_required? @require_exact_flag_match end |
#flags_before_args_enforced? ⇒ Boolean
Returns true if this tool enforces flags before args.
388 389 390 |
# File 'toys-core/lib/toys/tool_definition.rb', line 388 def flags_before_args_enforced? @enforce_flags_before_args end |
#handles_interrupts? ⇒ Boolean
Returns true if this tool handles interrupts.
320 321 322 |
# File 'toys-core/lib/toys/tool_definition.rb', line 320 def handles_interrupts? !interrupt_handler.nil? end |
#handles_usage_errors? ⇒ Boolean
Returns true if this tool handles usage errors.
328 329 330 |
# File 'toys-core/lib/toys/tool_definition.rb', line 328 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 or Loader#resolve_standard_mixin to resolve named mixins.
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 |
# File 'toys-core/lib/toys/tool_definition.rb', line 481 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?(:super_include) tool_class.super_include(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? ⇒ Boolean
Returns true if at least one flag or positional argument is defined for this tool.
353 354 355 356 357 |
# File 'toys-core/lib/toys/tool_definition.rb', line 353 def includes_arguments? !default_data.empty? || !flags.empty? || !required_args.empty? || !optional_args.empty? || !remaining_arg.nil? || flags_before_args_enforced? end |
#includes_definition? ⇒ Boolean
Returns true if this tool has any definition information.
363 364 365 366 |
# File 'toys-core/lib/toys/tool_definition.rb', line 363 def includes_definition? includes_arguments? || runnable? || argument_parsing_disabled? || includes_modules? || includes_description? end |
#includes_description? ⇒ Boolean
Returns true if there is a specific description set for this tool.
344 345 346 |
# File 'toys-core/lib/toys/tool_definition.rb', line 344 def includes_description? !long_desc.empty? || !desc.empty? end |
#includes_modules? ⇒ Boolean
Returns true if this tool has at least one included module.
336 337 338 |
# File 'toys-core/lib/toys/tool_definition.rb', line 336 def includes_modules? @includes_modules 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.
511 512 513 514 |
# File 'toys-core/lib/toys/tool_definition.rb', line 511 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.
435 436 437 |
# File 'toys-core/lib/toys/tool_definition.rb', line 435 def lookup_acceptor(name) @acceptors.fetch(name.to_s) { |k| @parent ? @parent.lookup_acceptor(k) : nil } end |
#lookup_completion(name) ⇒ Toys::Completion::Base, ...
Get the named completion from this tool or its ancestors.
468 469 470 |
# File 'toys-core/lib/toys/tool_definition.rb', line 468 def lookup_completion(name) @completions.fetch(name.to_s) { |k| @parent ? @parent.lookup_completion(k) : nil } end |
#lookup_mixin(name) ⇒ Module?
Get the named mixin from this tool or its ancestors.
457 458 459 |
# File 'toys-core/lib/toys/tool_definition.rb', line 457 def lookup_mixin(name) @mixins.fetch(name.to_s) { |k| @parent ? @parent.lookup_mixin(k) : nil } end |
#lookup_template(name) ⇒ Class?
Get the named template from this tool or its ancestors.
446 447 448 |
# File 'toys-core/lib/toys/tool_definition.rb', line 446 def lookup_template(name) @templates.fetch(name.to_s) { |k| @parent ? @parent.lookup_template(k) : nil } end |
#positional_args ⇒ Array<Toys::PositionalArg>
All arg definitions in order: required, optional, remaining.
405 406 407 408 409 |
# File 'toys-core/lib/toys/tool_definition.rb', line 405 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.)
690 691 692 693 694 695 696 697 698 699 |
# File 'toys-core/lib/toys/tool_definition.rb', line 690 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.
420 421 422 423 424 425 426 |
# File 'toys-core/lib/toys/tool_definition.rb', line 420 def resolve_flag(str) result = Flag::Resolution.new(str) flags.each do |flag_def| result.merge!(flag_def.resolve(str)) end result end |
#root? ⇒ Boolean
Returns true if this tool is a root tool.
304 305 306 |
# File 'toys-core/lib/toys/tool_definition.rb', line 304 def root? full_name.empty? end |
#run_handler=(proc) ⇒ Object
Set the run handler block
953 954 955 956 957 958 |
# File 'toys-core/lib/toys/tool_definition.rb', line 953 def run_handler=(proc) check_definition_state(is_method: true) tool_class.class_eval do define_method(:run, &proc) end end |
#runnable? ⇒ Boolean
Returns true if this tool is marked as runnable.
312 313 314 |
# File 'toys-core/lib/toys/tool_definition.rb', line 312 def runnable? tool_class.public_instance_methods(false).include?(:run) 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.
936 937 938 939 940 941 942 943 944 945 946 |
# File 'toys-core/lib/toys/tool_definition.rb', line 936 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 |
#simple_name ⇒ String
The local name of this tool, i.e. the last element of the full name.
286 287 288 |
# File 'toys-core/lib/toys/tool_definition.rb', line 286 def simple_name full_name.last end |