Class: Toys::ToolDefinition
- Inherits:
-
Object
- Object
- Toys::ToolDefinition
- Defined in:
- core-docs/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.
245 246 247 |
# File 'core-docs/toys/tool_definition.rb', line 245 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.
280 281 282 |
# File 'core-docs/toys/tool_definition.rb', line 280 def completion @completion end |
#custom_context_directory ⇒ String?
The custom context directory set for this tool.
261 262 263 |
# File 'core-docs/toys/tool_definition.rb', line 261 def custom_context_directory @custom_context_directory end |
#default_data ⇒ Hash (readonly)
The default context data set by arguments.
229 230 231 |
# File 'core-docs/toys/tool_definition.rb', line 229 def default_data @default_data end |
#delegate_target ⇒ Array<String>? (readonly)
The full name of the delegate target, if any.
306 307 308 |
# File 'core-docs/toys/tool_definition.rb', line 306 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.
160 161 162 |
# File 'core-docs/toys/tool_definition.rb', line 160 def desc @desc end |
#flag_groups ⇒ Array<Toys::FlagGroup> (readonly)
A list of all defined flag groups, in order.
186 187 188 |
# File 'core-docs/toys/tool_definition.rb', line 186 def flag_groups @flag_groups end |
#flags ⇒ Array<Toys::Flag> (readonly)
A list of all defined flags.
193 194 195 |
# File 'core-docs/toys/tool_definition.rb', line 193 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.
122 123 124 |
# File 'core-docs/toys/tool_definition.rb', line 122 def full_name @full_name end |
#interrupt_handler ⇒ Proc, ...
The interrupt handler.
289 290 291 |
# File 'core-docs/toys/tool_definition.rb', line 289 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.
179 180 181 |
# File 'core-docs/toys/tool_definition.rb', line 179 def long_desc @long_desc end |
#optional_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined optional positional arguments.
207 208 209 |
# File 'core-docs/toys/tool_definition.rb', line 207 def optional_args @optional_args end |
#priority ⇒ Integer (readonly)
The priority of this tool definition.
129 130 131 |
# File 'core-docs/toys/tool_definition.rb', line 129 def priority @priority end |
#remaining_arg ⇒ Toys::PositionalArg? (readonly)
The remaining arguments specification.
215 216 217 |
# File 'core-docs/toys/tool_definition.rb', line 215 def remaining_arg @remaining_arg end |
#required_args ⇒ Array<Toys::PositionalArg> (readonly)
A list of all defined required positional arguments.
200 201 202 |
# File 'core-docs/toys/tool_definition.rb', line 200 def required_args @required_args end |
#settings ⇒ Toys::Tool::Settings (readonly)
Settings for this tool
114 115 116 |
# File 'core-docs/toys/tool_definition.rb', line 114 def settings @settings end |
#source_info ⇒ Toys::SourceInfo? (readonly)
Info on the source of this tool.
253 254 255 |
# File 'core-docs/toys/tool_definition.rb', line 253 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.
136 137 138 |
# File 'core-docs/toys/tool_definition.rb', line 136 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.
238 239 240 |
# File 'core-docs/toys/tool_definition.rb', line 238 def subtool_middleware_stack @subtool_middleware_stack end |
#tool_class ⇒ Class (readonly)
The tool class.
143 144 145 |
# File 'core-docs/toys/tool_definition.rb', line 143 def tool_class @tool_class end |
#usage_error_handler ⇒ Proc, ...
The usage error handler.
298 299 300 |
# File 'core-docs/toys/tool_definition.rb', line 298 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.
222 223 224 |
# File 'core-docs/toys/tool_definition.rb', line 222 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.
565 566 567 |
# File 'core-docs/toys/tool_definition.rb', line 565 def add_acceptor(name, acceptor = nil, type_desc: nil, &block) # Source available in the toys-core gem end |
#add_completion(name, completion = nil, **options, &block) ⇒ self
Add a named completion proc to this tool. The completion may be referenced by name when adding a flag or an arg. See Completion.create for detailed information on how to specify a completion.
598 599 600 |
# File 'core-docs/toys/tool_definition.rb', line 598 def add_completion(name, completion = nil, **, &block) # Source available in the toys-core gem end |
#add_flag(key, flags = [], accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, group: nil, desc: nil, long_desc: nil, display_name: nil) ⇒ self
Add a flag to the current tool. Each flag must specify a key which
the script may use to obtain the flag value from the context.
You may then provide the flags themselves in OptionParser
form.
730 731 732 733 734 735 |
# File 'core-docs/toys/tool_definition.rb', line 730 def add_flag(key, flags = [], accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil, report_collisions: true, group: nil, desc: nil, long_desc: nil, display_name: nil) # Source available in the toys-core gem end |
#add_flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false) ⇒ self
Add a flag group to the group list.
The type should be one of the following symbols:
-
:optional
All flags in the group are optional -
:required
All flags in the group are required -
:exactly_one
Exactly one flag in the group must be provided -
:at_least_one
At least one flag in the group must be provided -
:at_most_one
At most one flag in the group must be provided
674 675 676 677 |
# File 'core-docs/toys/tool_definition.rb', line 674 def add_flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false) # Source available in the toys-core gem end |
#add_initializer(proc, *args, **kwargs) ⇒ self
Add an initializer.
875 876 877 |
# File 'core-docs/toys/tool_definition.rb', line 875 def add_initializer(proc, *args, **kwargs) # Source available in the toys-core gem end |
#add_mixin(name, mixin_module = nil, &block) ⇒ self
Add a named mixin module to this tool. You may provide a mixin module or a block that configures one.
579 580 581 |
# File 'core-docs/toys/tool_definition.rb', line 579 def add_mixin(name, mixin_module = nil, &block) # Source available in the toys-core gem end |
#add_optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self
Add an optional positional argument to the current tool. You must specify a key which the script may use to obtain the argument value from the context. If an optional argument is not given on the command line, the value is set to the given default.
804 805 806 807 |
# File 'core-docs/toys/tool_definition.rb', line 804 def add_optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) # Source available in the toys-core gem end |
#add_required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self
Add a required positional argument to the current tool. You must specify a key which the script may use to obtain the argument value from the context.
772 773 774 775 |
# File 'core-docs/toys/tool_definition.rb', line 772 def add_required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) # Source available in the toys-core gem end |
#add_template(name, template_class = nil, &block) ⇒ self
Add a named template class to this tool. You may provide a template class or a block that configures one.
612 613 614 |
# File 'core-docs/toys/tool_definition.rb', line 612 def add_template(name, template_class = nil, &block) # Source available in the toys-core gem end |
#append_long_desc(long_desc) ⇒ self
Append long description strings.
You must pass an array of lines in the long description. See #long_desc for details on how each line may be represented.
546 547 548 |
# File 'core-docs/toys/tool_definition.rb', line 546 def append_long_desc(long_desc) # Source available in the toys-core gem end |
#argument_parsing_disabled? ⇒ Boolean
Returns true if this tool has disabled argument parsing.
404 405 406 |
# File 'core-docs/toys/tool_definition.rb', line 404 def argument_parsing_disabled? # Source available in the toys-core gem 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.
912 913 914 |
# File 'core-docs/toys/tool_definition.rb', line 912 def context_directory # Source available in the toys-core gem end |
#definition_finished? ⇒ Boolean
Returns true if this tool's definition has been finished and is locked.
396 397 398 |
# File 'core-docs/toys/tool_definition.rb', line 396 def definition_finished? # Source available in the toys-core gem end |
#delegate_to(target) ⇒ self
Causes this tool to delegate to another tool.
922 923 924 |
# File 'core-docs/toys/tool_definition.rb', line 922 def delegate_to(target) # Source available in the toys-core gem end |
#disable_argument_parsing ⇒ self
Disable argument parsing for this tool.
621 622 623 |
# File 'core-docs/toys/tool_definition.rb', line 621 def disable_argument_parsing # Source available in the toys-core gem end |
#disable_flag(*flags) ⇒ self
Mark one or more flags as disabled, preventing their use by any subsequent flag definition. This may be used to prevent middleware from defining a particular flag.
745 746 747 |
# File 'core-docs/toys/tool_definition.rb', line 745 def disable_flag(*flags) # Source available in the toys-core gem end |
#display_name ⇒ String
A displayable name of this tool, generally the full name delimited by spaces.
323 324 325 |
# File 'core-docs/toys/tool_definition.rb', line 323 def display_name # Source available in the toys-core gem end |
#enforce_flags_before_args(state = true) ⇒ self
Enforce that flags must come before args for this tool.
You may disable enforcement by passoing false
for the state.
632 633 634 |
# File 'core-docs/toys/tool_definition.rb', line 632 def enforce_flags_before_args(state = true) # Source available in the toys-core gem end |
#exact_flag_match_required? ⇒ Boolean
Returns true if this tool requires exact flag matches.
420 421 422 |
# File 'core-docs/toys/tool_definition.rb', line 420 def exact_flag_match_required? # Source available in the toys-core gem end |
#flags_before_args_enforced? ⇒ Boolean
Returns true if this tool enforces flags before args.
412 413 414 |
# File 'core-docs/toys/tool_definition.rb', line 412 def flags_before_args_enforced? # Source available in the toys-core gem end |
#handles_interrupts? ⇒ Boolean
Returns true if this tool handles interrupts.
347 348 349 |
# File 'core-docs/toys/tool_definition.rb', line 347 def handles_interrupts? # Source available in the toys-core gem end |
#handles_usage_errors? ⇒ Boolean
Returns true if this tool handles usage errors.
355 356 357 |
# File 'core-docs/toys/tool_definition.rb', line 355 def handles_usage_errors? # Source available in the toys-core gem end |
#include_mixin(mod, *args, **kwargs) ⇒ self
Include the given mixin in the tool class.
The mixin must be given as a module. You can use #lookup_mixin to resolve named mixins.
499 500 501 |
# File 'core-docs/toys/tool_definition.rb', line 499 def include_mixin(mod, *args, **kwargs) # Source available in the toys-core gem end |
#includes_arguments? ⇒ Boolean
Returns true if at least one flag or positional argument is defined for this tool.
380 381 382 |
# File 'core-docs/toys/tool_definition.rb', line 380 def includes_arguments? # Source available in the toys-core gem end |
#includes_definition? ⇒ Boolean
Returns true if this tool has any definition information.
388 389 390 |
# File 'core-docs/toys/tool_definition.rb', line 388 def includes_definition? # Source available in the toys-core gem end |
#includes_description? ⇒ Boolean
Returns true if there is a specific description set for this tool.
371 372 373 |
# File 'core-docs/toys/tool_definition.rb', line 371 def includes_description? # Source available in the toys-core gem end |
#includes_modules? ⇒ Boolean
Returns true if this tool has at least one included module.
363 364 365 |
# File 'core-docs/toys/tool_definition.rb', line 363 def includes_modules? # Source available in the toys-core gem end |
#lock_source(source) ⇒ self
Sets the path to the file that defines this tool. A tool may be defined from at most one path. If a different path is already set, it is left unchanged.
511 512 513 |
# File 'core-docs/toys/tool_definition.rb', line 511 def lock_source(source) # Source available in the toys-core gem end |
#lookup_acceptor(name) ⇒ Toys::Acceptor::Base?
Get the named acceptor from this tool or its ancestors.
453 454 455 |
# File 'core-docs/toys/tool_definition.rb', line 453 def lookup_acceptor(name) # Source available in the toys-core gem end |
#lookup_completion(name) ⇒ Toys::Completion::Base, ...
Get the named completion from this tool or its ancestors.
486 487 488 |
# File 'core-docs/toys/tool_definition.rb', line 486 def lookup_completion(name) # Source available in the toys-core gem end |
#lookup_mixin(name) ⇒ Module?
Get the named mixin from this tool or its ancestors.
475 476 477 |
# File 'core-docs/toys/tool_definition.rb', line 475 def lookup_mixin(name) # Source available in the toys-core gem end |
#lookup_template(name) ⇒ Class?
Get the named template from this tool or its ancestors.
464 465 466 |
# File 'core-docs/toys/tool_definition.rb', line 464 def lookup_template(name) # Source available in the toys-core gem end |
#positional_args ⇒ Array<Toys::PositionalArg>
All arg definitions in order: required, optional, remaining.
429 430 431 |
# File 'core-docs/toys/tool_definition.rb', line 429 def positional_args # Source available in the toys-core gem end |
#require_exact_flag_match(state = true) ⇒ self
Require that flags must match exactly. (If false, flags can match an unambiguous substring.)
643 644 645 |
# File 'core-docs/toys/tool_definition.rb', line 643 def require_exact_flag_match(state = true) # Source available in the toys-core gem end |
#resolve_flag(str) ⇒ Toys::Flag::Resolution
Resolve the given flag given the flag string. Returns an object that describes the resolution result, including whether the resolution matched a unique flag, the specific flag syntax that was matched, and additional information.
442 443 444 |
# File 'core-docs/toys/tool_definition.rb', line 442 def resolve_flag(str) # Source available in the toys-core gem end |
#root? ⇒ Boolean
Returns true if this tool is a root tool.
331 332 333 |
# File 'core-docs/toys/tool_definition.rb', line 331 def root? # Source available in the toys-core gem end |
#run_handler=(proc) ⇒ Object
Set the run handler block
845 846 847 |
# File 'core-docs/toys/tool_definition.rb', line 845 def run_handler=(proc) # Source available in the toys-core gem end |
#runnable? ⇒ Boolean
Returns true if this tool is marked as runnable.
339 340 341 |
# File 'core-docs/toys/tool_definition.rb', line 339 def runnable? # Source available in the toys-core gem end |
#set_remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) ⇒ self
Specify what should be done with unmatched positional arguments. You must specify a key which the script may use to obtain the remaining args from the context.
835 836 837 838 |
# File 'core-docs/toys/tool_definition.rb', line 835 def set_remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil) # Source available in the toys-core gem end |
#simple_name ⇒ String
The local name of this tool, i.e. the last element of the full name.
313 314 315 |
# File 'core-docs/toys/tool_definition.rb', line 313 def simple_name # Source available in the toys-core gem end |