Class: Toys::ToolDefinition
- Inherits:
-
Object
- Object
- Toys::ToolDefinition
- 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, 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.
216 217 218 |
# File 'lib/toys/tool_definition.rb', line 216 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.
251 252 253 |
# File 'lib/toys/tool_definition.rb', line 251 def completion @completion end |
#custom_context_directory ⇒ String?
The custom context directory set for this tool.
232 233 234 |
# File 'lib/toys/tool_definition.rb', line 232 def custom_context_directory @custom_context_directory end |
#default_data ⇒ Hash (readonly)
The default context data set by arguments.
200 201 202 |
# File 'lib/toys/tool_definition.rb', line 200 def default_data @default_data end |
#delegate_target ⇒ Array<String>? (readonly)
The full name of the delegate target, if any.
277 278 279 |
# File 'lib/toys/tool_definition.rb', line 277 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.
131 132 133 |
# File 'lib/toys/tool_definition.rb', line 131 def desc @desc end |
#flag_groups ⇒ Array<Toys::FlagGroup> (readonly)
A list of all defined flag groups, in order.
157 158 159 |
# File 'lib/toys/tool_definition.rb', line 157 def flag_groups @flag_groups end |
#flags ⇒ Array<Toys::Flag> (readonly)
A list of all defined flags.
164 165 166 |
# File 'lib/toys/tool_definition.rb', line 164 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.
93 94 95 |
# File 'lib/toys/tool_definition.rb', line 93 def full_name @full_name end |
#interrupt_handler ⇒ Proc, ...
The interrupt handler.
260 261 262 |
# File 'lib/toys/tool_definition.rb', line 260 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.
150 151 152 |
# File 'lib/toys/tool_definition.rb', line 150 def long_desc @long_desc end |
#optional_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined optional positional arguments.
178 179 180 |
# File 'lib/toys/tool_definition.rb', line 178 def optional_args @optional_args end |
#priority ⇒ Integer (readonly)
The priority of this tool definition.
100 101 102 |
# File 'lib/toys/tool_definition.rb', line 100 def priority @priority end |
#remaining_arg ⇒ Toys::PositionalArg? (readonly)
The remaining arguments specification.
186 187 188 |
# File 'lib/toys/tool_definition.rb', line 186 def remaining_arg @remaining_arg end |
#required_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined required positional arguments.
171 172 173 |
# File 'lib/toys/tool_definition.rb', line 171 def required_args @required_args end |
#settings ⇒ Toys::Tool::Settings (readonly)
Settings for this tool
85 86 87 |
# File 'lib/toys/tool_definition.rb', line 85 def settings @settings end |
#source_info ⇒ Toys::SourceInfo? (readonly)
Info on the source of this tool.
224 225 226 |
# File 'lib/toys/tool_definition.rb', line 224 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.
107 108 109 |
# File 'lib/toys/tool_definition.rb', line 107 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.
209 210 211 |
# File 'lib/toys/tool_definition.rb', line 209 def subtool_middleware_stack @subtool_middleware_stack end |
#tool_class ⇒ Class (readonly)
The tool class.
114 115 116 |
# File 'lib/toys/tool_definition.rb', line 114 def tool_class @tool_class end |
#usage_error_handler ⇒ Proc, ...
The usage error handler.
269 270 271 |
# File 'lib/toys/tool_definition.rb', line 269 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.
193 194 195 |
# File 'lib/toys/tool_definition.rb', line 193 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.
568 569 570 571 572 573 574 575 576 577 |
# File 'lib/toys/tool_definition.rb', line 568 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.
615 616 617 618 619 620 621 622 623 624 |
# File 'lib/toys/tool_definition.rb', line 615 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.
793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 |
# File 'lib/toys/tool_definition.rb', line 793 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
726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 |
# File 'lib/toys/tool_definition.rb', line 726 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.
992 993 994 995 996 |
# File 'lib/toys/tool_definition.rb', line 992 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.
589 590 591 592 593 594 595 596 597 598 |
# File 'lib/toys/tool_definition.rb', line 589 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.
896 897 898 899 900 901 902 903 904 905 906 |
# File 'lib/toys/tool_definition.rb', line 896 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.
858 859 860 861 862 863 864 865 866 867 |
# File 'lib/toys/tool_definition.rb', line 858 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.
636 637 638 639 640 641 642 643 644 645 |
# File 'lib/toys/tool_definition.rb', line 636 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.
547 548 549 550 551 |
# File 'lib/toys/tool_definition.rb', line 547 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.
378 379 380 |
# File 'lib/toys/tool_definition.rb', line 378 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.
1042 1043 1044 |
# File 'lib/toys/tool_definition.rb', line 1042 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.
370 371 372 |
# File 'lib/toys/tool_definition.rb', line 370 def definition_finished? @definition_finished end |
#delegate_to(target) ⇒ self
Causes this tool to delegate to another tool.
1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 |
# File 'lib/toys/tool_definition.rb', line 1052 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.
652 653 654 655 656 657 658 659 660 661 |
# File 'lib/toys/tool_definition.rb', line 652 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.
824 825 826 827 828 829 830 831 832 833 |
# File 'lib/toys/tool_definition.rb', line 824 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.
294 295 296 |
# File 'lib/toys/tool_definition.rb', line 294 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.
670 671 672 673 674 675 676 677 678 679 |
# File 'lib/toys/tool_definition.rb', line 670 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.
394 395 396 |
# File 'lib/toys/tool_definition.rb', line 394 def exact_flag_match_required? @require_exact_flag_match end |
#flags_before_args_enforced? ⇒ Boolean
Returns true if this tool enforces flags before args.
386 387 388 |
# File 'lib/toys/tool_definition.rb', line 386 def flags_before_args_enforced? @enforce_flags_before_args end |
#handles_interrupts? ⇒ Boolean
Returns true if this tool handles interrupts.
318 319 320 |
# File 'lib/toys/tool_definition.rb', line 318 def handles_interrupts? !interrupt_handler.nil? end |
#handles_usage_errors? ⇒ Boolean
Returns true if this tool handles usage errors.
326 327 328 |
# File 'lib/toys/tool_definition.rb', line 326 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.
479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 |
# File 'lib/toys/tool_definition.rb', line 479 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.
351 352 353 354 355 |
# File 'lib/toys/tool_definition.rb', line 351 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.
361 362 363 364 |
# File 'lib/toys/tool_definition.rb', line 361 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.
342 343 344 |
# File 'lib/toys/tool_definition.rb', line 342 def includes_description? !long_desc.empty? || !desc.empty? end |
#includes_modules? ⇒ Boolean
Returns true if this tool has at least one included module.
334 335 336 |
# File 'lib/toys/tool_definition.rb', line 334 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.
509 510 511 512 |
# File 'lib/toys/tool_definition.rb', line 509 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.
433 434 435 |
# File 'lib/toys/tool_definition.rb', line 433 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.
466 467 468 |
# File 'lib/toys/tool_definition.rb', line 466 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.
455 456 457 |
# File 'lib/toys/tool_definition.rb', line 455 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.
444 445 446 |
# File 'lib/toys/tool_definition.rb', line 444 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.
403 404 405 406 407 |
# File 'lib/toys/tool_definition.rb', line 403 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.)
688 689 690 691 692 693 694 695 696 697 |
# File 'lib/toys/tool_definition.rb', line 688 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.
418 419 420 421 422 423 424 |
# File 'lib/toys/tool_definition.rb', line 418 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.
302 303 304 |
# File 'lib/toys/tool_definition.rb', line 302 def root? full_name.empty? end |
#run_handler=(proc) ⇒ Object
Set the run handler block
951 952 953 954 955 956 |
# File 'lib/toys/tool_definition.rb', line 951 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.
310 311 312 |
# File 'lib/toys/tool_definition.rb', line 310 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.
934 935 936 937 938 939 940 941 942 943 944 |
# File 'lib/toys/tool_definition.rb', line 934 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.
284 285 286 |
# File 'lib/toys/tool_definition.rb', line 284 def simple_name full_name.last end |