Module: Toys::DSL::Tool
- Defined in:
- toys-core/lib/toys/dsl/tool.rb
Overview
Defined in the toys-core gem
This class defines the DSL for a Toys configuration file.
A Toys configuration defines one or more named tools. It provides syntax for setting the description, defining flags and arguments, specifying how to execute the tool, and requesting mixin modules and other services. It also lets you define subtools, nested arbitrarily deep, using blocks.
Simple example
Create a file called .toys.rb
in the current directory, with the
following contents:
tool "greet" do
desc "Prints a simple greeting"
optional_arg :recipient, default: "world"
def run
puts "Hello, #{recipient}!"
end
end
Now you can execute it using:
toys greet
or try:
toys greet rubyists
Instance Method Summary collapse
-
#acceptor(name, spec = nil, type_desc: nil, &block) ⇒ self
Create a named acceptor that can be referenced by name from any flag or positional argument in this tool or its subtools.
-
#alias_tool(word, target) ⇒ self
Create an alias, representing an "alternate name" for a tool.
-
#all_required(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
Create a flag group of type
:required
. -
#at_least_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
(also: #at_least_one_required)
Create a flag group of type
:at_least_one
. -
#at_most_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
(also: #at_most_one_required)
Create a flag group of type
:at_most_one
. -
#complete_tool_args(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for this tool's arguments.
-
#completion(name, spec = nil, **options, &block) ⇒ self
Create a named completion procedure that may be used by name by any flag or positional arg in this tool or any subtool.
-
#context_directory ⇒ String?
Return the context directory for this tool.
-
#current_tool ⇒ Toys::ToolDefinition
Return the current tool config.
-
#delegate_to(target) ⇒ self
Causes the current tool to delegate to another tool.
-
#desc(str) ⇒ self
(also: #short_desc)
Set the short description for the current 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.
-
#enforce_flags_before_args(state = true) ⇒ self
Enforce that all flags must be provided before any positional args.
-
#exactly_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
(also: #exactly_one_required)
Create a flag group of type
:exactly_one
. -
#expand(template_class, *args, **kwargs) {|template| ... } ⇒ self
Expand the given template in the current location.
-
#find_data(path, type: nil) ⇒ String?
Find the given data path (file or directory).
-
#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, &block) ⇒ self
Add a flag to the current tool.
-
#flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
Create a flag group.
-
#include(mixin, *args, **kwargs) ⇒ self
Specify that the given module should be mixed into this tool, and its methods made available when running the tool.
-
#include?(mod) ⇒ Boolean?
Determine if the given module/mixin has already been included.
-
#load(path, as: nil) ⇒ self
Load another config file or directory, as if its contents were inserted at the current location.
-
#load_git(remote: nil, path: nil, commit: nil, as: nil, update: false) ⇒ self
Load configuration from a public git repository, as if its contents were inserted at the current location.
-
#long_desc(*strs, file: nil, data: nil) ⇒ self
Add to the long description for the current tool.
-
#mixin(name, mixin_module = nil, &block) ⇒ self
Create a named mixin module that can be included by name from this tool or its subtools.
-
#on_interrupt(handler = nil, &block) ⇒ self
Specify how to handle interrupts.
-
#on_usage_error(handler = nil, &block) ⇒ self
Specify how to handle usage errors.
-
#optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self
(also: #optional)
Add an optional positional argument to the current tool.
-
#remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self
(also: #remaining)
Specify what should be done with unmatched positional arguments.
-
#require_exact_flag_match(state = true) ⇒ self
Require that flags must match exactly.
-
#required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self
(also: #required)
Add a required positional argument to the current tool.
-
#set(key, value = nil) ⇒ Object
Set a option values statically without creating helper methods.
-
#set_context_directory(dir) ⇒ self
Set a custom context directory for this tool.
-
#settings ⇒ Toys::ToolDefinition::Settings
Get the settings for this tool.
-
#source_info ⇒ Toys::SourceInfo
Return the current source info object.
-
#static(key, value = nil) ⇒ Object
Set a option values statically and create a helper method.
-
#subtool_apply(&block) ⇒ Object
Applies the given block to all subtools, recursively.
-
#template(name, template_class = nil, &block) ⇒ self
Create a named template that can be expanded by name from this tool or its subtools.
-
#to_run(&block) ⇒ self
(also: #on_run)
Specify how to run this tool.
-
#tool(words, if_defined: :combine, delegate_to: nil, &block) ⇒ self
Create a subtool.
-
#toys_version!(*requirements) ⇒ self
Asserts that the current Toys version against the given requirements, raising an exception if not.
-
#toys_version?(*requirements) ⇒ Boolean
Determines whether the current Toys version satisfies the given requirements.
-
#truncate_load_path! ⇒ Object
Remove lower-priority sources from the load path.
Instance Method Details
#acceptor(name, spec = nil, type_desc: nil, &block) ⇒ self
Create a named acceptor that can be referenced by name from any flag or positional argument in this tool or its subtools.
An acceptor validates the string parameter passed to a flag or positional argument. It also optionally converts the string to a different object before storing it in your tool's data.
Acceptors can be defined in one of four ways.
You can provide a regular expression. This acceptor validates only if the regex matches the entire string parameter.
You can also provide an optional conversion function as a block. If provided, function must take a variable number of arguments, the first being the matched string and the remainder being the captures from the regular expression. It should return the converted object that will be stored in the context data. If you do not provide a block, the original string will be used.
You can provide an array of possible values. The acceptor validates if the string parameter matches the string form of one of the array elements (i.e. the results of calling
to_s
on the array elements.)An array acceptor automatically converts the string parameter to the actual array element that it matched. For example, if the symbol
:foo
is in the array, it will match the string"foo"
, and then store the symbol:foo
in the tool data.You can provide a range of possible values, along with a conversion function that converts a string parameter to a type comparable by the range. (See the "function" spec below for a detailed description of conversion functions.) If the range has numeric endpoints, the conversion function is optional because a default will be provided.
You can provide a function by passing it as a proc or a block. This function performs both validation and conversion. It should take the string parameter as its argument, and it must either return the object that should be stored in the tool data, or raise an exception (descended from
StandardError
) to indicate that the string parameter is invalid.
Example
The following example creates an acceptor named "hex" that is defined via a regular expression. It then uses it to validate values passed to a flag.
tool "example" do
acceptor "hex", /[0-9a-fA-F]+/, type_desc: "hex numbers"
flag :number, accept: "hex"
def run
puts "number was #{number}"
end
end
110 111 112 113 114 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 110 def acceptor(name, spec = nil, type_desc: nil, &block) cur_tool = DSL::Internal.current_tool(self, false) cur_tool&.add_acceptor(name, spec, type_desc: type_desc || name.to_s, &block) self end |
#alias_tool(word, target) ⇒ self
Create an alias, representing an "alternate name" for a tool.
This is functionally equivalent to creating a subtool with the
delegate_to
option, except that alias_tool
takes a relative name
for the delegate.
Example
This example defines a tool and an alias pointing to it. Both the tool
name test
and the alias t
will then refer to the same tool.
tool "test" do
def run
puts "Running tests..."
end
end
alias_tool "t", "test"
360 361 362 363 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 360 def alias_tool(word, target) tool(word, delegate_to: @__words + @__loader.split_path(target)) self end |
#all_required(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
Create a flag group of type :required
. If a block is given, flags
defined in the block belong to the group. All flags in this group are
required.
Example
The following example creates a group of required flags.
tool "login" do
all_required do
flag :username, "--username=VAL", desc: "Set username (required)"
flag :password, "--password=VAL", desc: "Set password (required)"
end
# ...
end
676 677 678 679 680 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 676 def all_required(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) flag_group(type: :required, desc: desc, long_desc: long_desc, name: name, report_collisions: report_collisions, prepend: prepend, &block) end |
#at_least_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self Also known as: at_least_one_required
Create a flag group of type :at_least_one
. If a block is given, flags
defined in the block belong to the group. At least one flag in this
group must be provided on the command line.
Example
The following example creates a group of flags in which one or more may be set.
tool "run-tests" do
at_least_one do
flag :unit, desc: "Run unit tests"
flag :integration, desc: "Run integration tests"
flag :performance, desc: "Run performance tests"
end
# ...
end
763 764 765 766 767 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 763 def at_least_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) flag_group(type: :at_least_one, desc: desc, long_desc: long_desc, name: name, report_collisions: report_collisions, prepend: prepend, &block) end |
#at_most_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self Also known as: at_most_one_required
Create a flag group of type :at_most_one
. If a block is given, flags
defined in the block belong to the group. At most one flag in this
group must be provided on the command line.
Example
The following example creates a group of flags in which either one or none may be set, but not more than one.
tool "provision-server" do
at_most_one do
flag :restore_from_backup, "--restore-from-backup=VAL"
flag :restore_from_image, "--restore-from-image=VAL"
flag :clone_existing, "--clone-existing=VAL"
end
# ...
end
719 720 721 722 723 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 719 def at_most_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) flag_group(type: :at_most_one, desc: desc, long_desc: long_desc, name: name, report_collisions: report_collisions, prepend: prepend, &block) end |
#complete_tool_args(spec = nil, **options, &block) ⇒ self
Set the shell completion strategy for this tool's arguments. You can pass one of the following:
- The string name of a completion defined in this tool or any of its its ancestors.
- A hash of options to pass to the constructor of ToolDefinition::DefaultCompletion.
-
nil
or:default
to select the standard completion strategy (which is ToolDefinition::DefaultCompletion with no extra options). - Any other specification recognized by Completion.create.
Example
The namespace "foo" supports completion only of subtool names. It does not complete the standard flags (like --help).
tool "foo" do
complete_tool_args complete_args: false, complete_flags: false,
complete_flag_values: false
tool "bar" do
def run
puts "in foo bar"
end
end
end
1395 1396 1397 1398 1399 1400 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1395 def complete_tool_args(spec = nil, **, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.completion = Completion.scalarize_spec(spec, , block) self end |
#completion(name, spec = nil, **options, &block) ⇒ self
Create a named completion procedure that may be used by name by any flag or positional arg in this tool or any subtool.
A completion controls tab completion for the value of a flag or
positional argument. In general, it is a Ruby Proc
that takes a
context object (of type Completion::Context) and returns an
array of completion candidate strings.
Completions can be specified in one of three ways.
- A Proc object itself, either passed directly to this directive or provided as a block.
- A static array of strings, indicating the completion candidates independent of context.
- The symbol
:file_system
which indicates that paths in the file system should serve as completion candidates.
Example
The following example defines a completion that uses only the immediate
files in the current directory as candidates. (This is different from
the :file_system
completion which will descend into subdirectories
similar to how bash completes most of its file system commands.)
completion "local-files" do |_context|
`/bin/ls`.split("\n")
end
tool "example" do
flag :file, complete_values: "local-files"
def run
puts "selected file #{file}"
end
end
257 258 259 260 261 262 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 257 def completion(name, spec = nil, **, &block) cur_tool = DSL::Internal.current_tool(self, false) return self if cur_tool.nil? cur_tool.add_completion(name, spec, **, &block) self end |
#context_directory ⇒ String?
Return the context directory for this tool. Generally, this defaults to the directory containing the toys config directory structure being read, but it may be changed by setting a different context directory for the tool.
1597 1598 1599 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1597 def context_directory DSL::Internal.current_tool(self, false)&.context_directory || source_info.context_directory end |
#current_tool ⇒ Toys::ToolDefinition
Return the current tool config. This object can be queried to determine such information as the name, but it should not be altered.
1607 1608 1609 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1607 def current_tool DSL::Internal.current_tool(self, false) end |
#delegate_to(target) ⇒ self
Causes the current tool to delegate to another tool. When run, it simply invokes the target tool with the same arguments.
Example
This example defines a tool that runs one of its subtools. Running the
test
tool will have the same effect (and recognize the same args) as
the subtool test unit
.
tool "test" do
tool "unit" do
flag :faster
def run
puts "running tests..."
end
end
delegate_to "test:unit"
end
390 391 392 393 394 395 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 390 def delegate_to(target) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.delegate_to(@__loader.split_path(target)) self end |
#desc(str) ⇒ self Also known as: short_desc
Set the short description for the current tool. The short description
is displayed with the tool in a subtool list. You may also use the
equivalent method short_desc
.
The description is a WrappableString, which may be word-wrapped when displayed in a help screen. You may pass a WrappableString directly to this method, or you may pass any input that can be used to construct a wrappable string:
- If you pass a String, its whitespace will be compacted (i.e. tabs, newlines, and multiple consecutive whitespace will be turned into a single space), and it will be word-wrapped on whitespace.
- If you pass an Array of Strings, each string will be considered a literal word that cannot be broken, and wrapping will be done across the strings in the array. In this case, whitespace is not compacted.
Examples
If you pass in a sentence as a simple string, it may be word wrapped when displayed:
desc "This sentence may be wrapped."
To specify a sentence that should never be word-wrapped, pass it as the sole element of a string array:
desc ["This sentence will not be wrapped."]
537 538 539 540 541 542 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 537 def desc(str) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.desc = str self end |
#disable_argument_parsing ⇒ self
Disable argument parsing for this tool. Arguments will not be parsed and the options will not be populated. Instead, tools can retrieve the full unparsed argument list by calling Context#args.
This directive is mutually exclusive with any of the directives that declare arguments or flags.
1331 1332 1333 1334 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1331 def disable_argument_parsing DSL::Internal.current_tool(self, true)&.disable_argument_parsing self end |
#disable_flag(*flags) ⇒ self
Mark one or more flags as disabled, preventing their use by any subsequent flag definition. This can be used to prevent middleware from defining a particular flag.
Example
This tool does not support the -v
and -q
short forms for the two
verbosity flags (although it still supports the long forms --verbose
and --quiet
.)
tool "mytool" do
disable_flag "-v", "-q"
def run
# ...
end
end
1357 1358 1359 1360 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1357 def disable_flag(*flags) DSL::Internal.current_tool(self, true)&.disable_flag(*flags) self end |
#enforce_flags_before_args(state = true) ⇒ self
Enforce that all flags must be provided before any positional args.
That is, as soon as the first positional arg appears in the command
line arguments, flag parsing is disabled as if --
had appeared.
Issuing this directive by itself turns on enforcement. You may turn it
off by passsing false
as the parameter.
1300 1301 1302 1303 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1300 def enforce_flags_before_args(state = true) DSL::Internal.current_tool(self, true)&.enforce_flags_before_args(state) self end |
#exactly_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self Also known as: exactly_one_required
Create a flag group of type :exactly_one
. If a block is given, flags
defined in the block belong to the group. Exactly one flag in this
group must be provided on the command line.
Example
The following example creates a group of flags in which exactly one must be set.
tool "deploy" do
exactly_one do
flag :server, "--server=IP_ADDR", desc: "Deploy to server"
flag :vm, "--vm=ID", desc: "Deploy to a VM"
flag :container, "--container=ID", desc: "Deploy to a container"
end
# ...
end
807 808 809 810 811 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 807 def exactly_one(desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) flag_group(type: :exactly_one, desc: desc, long_desc: long_desc, name: name, report_collisions: report_collisions, prepend: prepend, &block) end |
#expand(template_class, *args, **kwargs) {|template| ... } ⇒ self
Expand the given template in the current location.
The template may be specified as a class or a well-known template name. You may also provide arguments to pass to the template.
Example
The following example creates and uses a simple template.
template "hello-generator" do
def initialize(name, )
@name = name
@message =
end
attr_reader :name, :message
expansion do |template|
tool template.name do
to_run do
puts template.
end
end
end
end
"hello-generator", "mytool", "mytool is running!"
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 485 def (template_class, *args, **kwargs) cur_tool = DSL::Internal.current_tool(self, false) return self if cur_tool.nil? name = template_class.to_s case template_class when ::String template_class = cur_tool.lookup_template(template_class) when ::Symbol template_class = @__loader.resolve_standard_template(name) end if template_class.nil? raise ToolDefinitionError, "Template not found: #{name.inspect}" end template = Compat.instantiate(template_class, args, kwargs, nil) yield template if block_given? class_exec(template, &template_class.expansion) self end |
#find_data(path, type: nil) ⇒ String?
Find the given data path (file or directory).
Data directories are a convenient place to put images, archives, keys,
or other such static data needed by your tools. Data files are located
in a directory called .data
inside a Toys directory. This directive
locates a data file during tool definition.
Example
This tool reads its description from a text file in the .data
directory.
tool "mytool" do
path = find_data("mytool-desc.txt", type: :file)
desc IO.read(path) if path
def run
# ...
end
end
1584 1585 1586 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1584 def find_data(path, type: nil) source_info.find_data(path, type: type) end |
#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, &block) ⇒ self
Add a flag to the current tool. Each flag must specify a key which the script may use to obtain the flag value from the context. You may then provide the flags themselves in OptionParser form.
If the given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Attributes of the flag may be passed in as arguments to this method, or set in a block passed to this method. If you provide a block, you can use directives in Flag within the block.
Flag syntax
The flags themselves should be provided in OptionParser form. Following are examples of valid syntax.
-
-a
: A short boolean switch. When this appears as an argument, the value is set totrue
. -
--abc
: A long boolean switch. When this appears as an argument, the value is set totrue
. -
-aVAL
or-a VAL
: A short flag that takes a required value. These two forms are treated identically. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the following argument is taken as the value (e.g. for-a foo
, the value is set to"foo"
.) The following argument is treated as the value even if it looks like a flag (e.g.-a -a
causes the string"-a"
to be taken as the value.) -
-a[VAL]
: A short flag that takes an optional value. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the value is set totrue
. The following argument is never interpreted as the value. (Compare with-a [VAL]
.) -
-a [VAL]
: A short flag that takes an optional value. If this argument appears with a value attached (e.g.-afoo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, if the following argument does not look like a flag (i.e. it does not begin with a hyphen), it is taken as the value. (e.g.-a foo
causes the string"foo"
to be taken as the value.). If there is no following argument, or the following argument looks like a flag, the value is set totrue
. (Compare with-a[VAL]
.) -
--abc=VAL
or--abc VAL
: A long flag that takes a required value. These two forms are treated identically. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the following argument is taken as the value (e.g. for--abc foo
, the value is set to"foo"
.) The following argument is treated as the value even if it looks like a flag (e.g.--abc --def
causes the string"--def"
to be taken as the value.) -
--abc[=VAL]
: A long flag that takes an optional value. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, the value is set totrue
. The following argument is never interpreted as the value. (Compare with--abc [VAL]
.) -
--abc [VAL]
: A long flag that takes an optional value. If this argument appears with a value attached (e.g.--abc=foo
), the attached string (e.g."foo"
) is taken as the value. Otherwise, if the following argument does not look like a flag (i.e. it does not begin with a hyphen), it is taken as the value. (e.g.--abc foo
causes the string"foo"
to be taken as the value.). If there is no following argument, or the following argument looks like a flag, the value is set totrue
. (Compare with--abc=[VAL]
.) -
--[no-]abc
: A long boolean switch that can be turned either on or off. This effectively creates two flags,--abc
which sets the value totrue
, and--no-abc
which sets the falue tofalse
.
Default flag syntax
If no flag syntax strings are provided, a default syntax will be inferred based on the key and other options.
Specifically, if the key has one character, then that character will be chosen as a short flag. If the key has multiple characters, a long flag will be generated.
Furthermore, if a custom completion, a non-boolean acceptor, or a non-boolean default value is provided in the options, then the flag will be considered to take a value. Otherwise, it will be considered to be a boolean switch.
For example, the following pairs of flags are identical:
flag :a
flag :a, "-a"
flag :abc_def
flag :abc_def, "--abc-def"
flag :number, accept: Integer
flag :number, "--number=VAL", accept: Integer
More examples
A flag that sets its value to the number of times it appears on the command line:
flag :verbose, "-v", "--verbose",
default: 0, handler: ->(_val, count) { count + 1 }
An example using block form:
flag :shout do
flags "-s", "--shout"
default false
desc "Say it louder"
long_desc "This flag says it lowder.",
"You might use this when people can't hear you.",
"",
"Example:",
[" toys say --shout hello"]
end
981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 981 def 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, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? flag_dsl = DSL::Flag.new( flags.flatten, accept, default, handler, complete_flags, complete_values, report_collisions, group, desc, long_desc, display_name ) flag_dsl.instance_exec(flag_dsl, &block) if block flag_dsl._add_to(cur_tool, key) DSL::Internal.maybe_add_getter(self, key) self end |
#flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) ⇒ self
Create a flag group. If a block is given, flags defined in the block belong to the group. The flags in the group are listed together in help screens.
Example
The following example creates a flag group in which all flags are optional.
tool "execute" do
flag_group desc: "Debug Flags" do
flag :debug, "-D", desc: "Enable debugger"
flag :warnings, "-W[VAL]", desc: "Enable warnings"
end
# ...
end
629 630 631 632 633 634 635 636 637 638 639 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 629 def flag_group(type: :optional, desc: nil, long_desc: nil, name: nil, report_collisions: true, prepend: false, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.add_flag_group(type: type, desc: desc, long_desc: long_desc, name: name, report_collisions: report_collisions, prepend: prepend) group = prepend ? cur_tool.flag_groups.first : cur_tool.flag_groups.last flag_group_dsl = DSL::FlagGroup.new(self, cur_tool, group) flag_group_dsl.instance_exec(flag_group_dsl, &block) if block self end |
#include(mixin, *args, **kwargs) ⇒ self
Specify that the given module should be mixed into this tool, and its methods made available when running the tool.
You may provide either a module, the string name of a mixin that you have defined in this tool or one of its ancestors, or the symbol name of a well-known mixin.
Example
Include the well-known mixin :terminal
and perform some terminal
magic.
tool "spin" do
include :terminal
def run
# The spinner method is defined by the :terminal mixin.
spinner(leading_text: "Waiting...", final_text: "\n") do
sleep 5
end
end
end
1521 1522 1523 1524 1525 1526 1527 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1521 def include(mixin, *args, **kwargs) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? mod = DSL::Internal.resolve_mixin(mixin, cur_tool, @__loader) cur_tool.include_mixin(mod, *args, **kwargs) self end |
#include?(mod) ⇒ Boolean?
Determine if the given module/mixin has already been included.
You may provide either a module, the string name of a mixin that you have defined in this tool or one of its ancestors, or the symbol name of a well-known mixin.
1541 1542 1543 1544 1545 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1541 def include?(mod) cur_tool = DSL::Internal.current_tool(self, false) return if cur_tool.nil? super(DSL::Internal.resolve_mixin(mod, cur_tool, @__loader)) end |
#load(path, as: nil) ⇒ self
Load another config file or directory, as if its contents were inserted at the current location.
407 408 409 410 411 412 413 414 415 416 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 407 def load(path, as: nil) if as tool(as) do load(path) end return self end @__loader.load_path(source_info, path, @__words, @__remaining_words, @__priority) self end |
#load_git(remote: nil, path: nil, commit: nil, as: nil, update: false) ⇒ self
Load configuration from a public git repository, as if its contents were inserted at the current location.
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 436 def load_git(remote: nil, path: nil, commit: nil, as: nil, update: false) if as tool(as) do load_git(remote: remote, path: path, commit: commit) end return self end remote ||= source_info.git_remote raise ToolDefinitionError, "Git remote not specified" unless remote path ||= "" commit ||= source_info.git_commit || "HEAD" @__loader.load_git(source_info, remote, path, commit, @__words, @__remaining_words, @__priority, update: update) self end |
#long_desc(*strs, file: nil, data: nil) ⇒ self
Add to the long description for the current tool. The long description is displayed in the usage documentation for the tool itself. This directive may be given multiple times, and the results are cumulative.
A long description is a series of descriptions, which are generally displayed in a series of lines/paragraphs. Each individual description uses the form described in the #desc documentation, and may be word-wrapped when displayed. To insert a blank line, include an empty string as one of the descriptions.
Example
long_desc "This initial paragraph might get word wrapped.",
"This next paragraph is followed by a blank line.",
"",
["This line will not be wrapped."],
[" This indent is preserved."]
long_desc "This line is appended to the description."
573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 573 def long_desc(*strs, file: nil, data: nil) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? if file unless source_info.source_path raise ::Toys::ToolDefinitionError, "Cannot set long_desc from a file because the tool is not defined in a file" end file = ::File.join(::File.dirname(source_info.source_path), file) elsif data file = source_info.find_data(data, type: :file) end strs += DSL::Internal.load_long_desc_file(file) if file cur_tool.append_long_desc(strs) self end |
#mixin(name, mixin_module = nil, &block) ⇒ self
Create a named mixin module that can be included by name from this tool or its subtools.
A mixin is a module that defines methods that can be called from a tool. It is commonly used to provide "utility" methods, implementing common functionality and allowing tools to share code.
Normally you provide a block and define the mixin's methods in that block. Alternatively, you can create a module separately and pass it directly to this directive.
Example
The following example creates a named mixin and uses it in a tool.
mixin "error-reporter" do
def error
logger.error "An error occurred: #{}"
exit 1
end
end
tool "build" do
include "error-reporter"
def run
puts "Building..."
error "Build failed!"
end
end
154 155 156 157 158 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 154 def mixin(name, mixin_module = nil, &block) cur_tool = DSL::Internal.current_tool(self, false) cur_tool&.add_mixin(name, mixin_module, &block) self end |
#on_interrupt(handler = nil, &block) ⇒ self
Specify how to handle interrupts.
You may pass a block to be called, or the name of a method to call. In either case, the block or method should take one argument, the Interrupt exception that was raised.
Example
tool "foo" do
def run
sleep 10
end
on_interrupt do |e|
puts "I was interrupted."
end
end
1454 1455 1456 1457 1458 1459 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1454 def on_interrupt(handler = nil, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.interrupt_handler = handler || block self end |
#on_usage_error(handler = nil, &block) ⇒ self
Specify how to handle usage errors.
You may pass a block to be called, or the name of a method to call. In either case, the block or method should take one argument, the array of usage errors reported.
Example
This tool runs even if a usage error is encountered. You can find info on the errors from Context::Key::USAGE_ERRORS, Context::Key::UNMATCHED_ARGS, and similar keys.
tool "foo" do
def run
puts "Errors: #{usage_errors.join("\n")}"
end
on_usage_error :run
end
1486 1487 1488 1489 1490 1491 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1486 def on_usage_error(handler = nil, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.usage_error_handler = handler || block self end |
#optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self Also known as: optional
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.
If the given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Attributes of the arg may be passed in as arguments to this method, or set in a block passed to this method. If you provide a block, you can use directives in PositionalArg within the block.
Example
This tool creates a "link" to a given target. The link location is optional; if it is not given, it is inferred from the target.
tool "ln" do
required_arg :target
optional_arg :location
def run
loc = location || File.basename(target)
puts "linking to #{target} from #{loc}..."
end
end
1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1124 def optional_arg(key, default: nil, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc) arg_dsl.instance_exec(arg_dsl, &block) if block arg_dsl._add_optional_to(cur_tool, key) DSL::Internal.maybe_add_getter(self, key) self end |
#remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self Also known as: remaining
Specify what should be done with unmatched positional arguments. You must specify a key which the script may use to obtain the remaining args from the context.
If the given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Attributes of the arg may be passed in as arguments to this method, or set in a block passed to this method. If you provide a block, you can use directives in PositionalArg within the block.
Example
This tool displays a "list" of the given directories. If no directories ar given, lists the current directory.
tool "ln" do
remaining_args :directories
def run
dirs = directories.empty? ? [Dir.pwd] : directories
dirs.each do |dir|
puts "Listing directory #{dir}..."
end
end
end
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1196 def remaining_args(key, default: [], accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc) arg_dsl.instance_exec(arg_dsl, &block) if block arg_dsl._set_remaining_on(cur_tool, key) DSL::Internal.maybe_add_getter(self, key) self end |
#require_exact_flag_match(state = true) ⇒ self
Require that flags must match exactly. That is, flags must appear in their entirety on the command line. (If false, substrings of flags are accepted as long as they are unambiguous.)
Issuing this directive by itself turns on exact match. You may turn it
off by passsing false
as the parameter.
1316 1317 1318 1319 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1316 def require_exact_flag_match(state = true) DSL::Internal.current_tool(self, true)&.require_exact_flag_match(state) self end |
#required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) ⇒ self Also known as: required
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.
If the given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Attributes of the arg may be passed in as arguments to this method, or set in a block passed to this method. If you provide a block, you can use directives in PositionalArg within the block.
Example
This tool "moves" something from a source to destination, and takes two required arguments:
tool "mv" do
required_arg :source
required_arg :dest
def run
puts "moving from #{source} to #{dest}..."
end
end
1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1052 def required_arg(key, accept: nil, complete: nil, display_name: nil, desc: nil, long_desc: nil, &block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? arg_dsl = DSL::PositionalArg.new(accept, nil, complete, display_name, desc, long_desc) arg_dsl.instance_exec(arg_dsl, &block) if block arg_dsl._add_required_to(cur_tool, key) DSL::Internal.maybe_add_getter(self, key) self end |
#set(key, value) ⇒ self #set(hash) ⇒ self
Set a option values statically without creating helper methods.
Example
tool "hello" do
set :greeting, "Hi there"
def run
puts "#{get(:greeting)}, world!"
end
end
1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1278 def set(key, value = nil) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? if key.is_a?(::Hash) cur_tool.default_data.merge!(key) else cur_tool.default_data[key] = value end self end |
#set_context_directory(dir) ⇒ self
Set a custom context directory for this tool.
1617 1618 1619 1620 1621 1622 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1617 def set_context_directory(dir) # rubocop:disable Naming/AccessorMethodName cur_tool = DSL::Internal.current_tool(self, false) return self if cur_tool.nil? cur_tool.custom_context_directory = dir self end |
#settings ⇒ Toys::ToolDefinition::Settings
Get the settings for this tool.
1686 1687 1688 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1686 def settings DSL::Internal.current_tool(self, false)&.settings end |
#source_info ⇒ Toys::SourceInfo
Return the current source info object.
1552 1553 1554 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1552 def source_info @__source.last end |
#static(key, value) ⇒ self #static(hash) ⇒ self
Set a option values statically and create a helper method.
If any given key is a symbol representing a valid method name, then a helper method is automatically added to retrieve the value. Otherwise, if the key is a string or does not represent a valid method name, the tool can retrieve the value by calling Context#get.
Example
tool "hello" do
static :greeting, "Hi there"
def run
puts "#{greeting}, world!"
end
end
1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1239 def static(key, value = nil) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? if key.is_a?(::Hash) cur_tool.default_data.merge!(key) key.each_key do |k| DSL::Internal.maybe_add_getter(self, k) end else cur_tool.default_data[key] = value DSL::Internal.maybe_add_getter(self, key) end self end |
#subtool_apply(&block) ⇒ Object
Applies the given block to all subtools, recursively. Effectively, the given block is run at the end of every tool block. This can be used, for example, to provide some shared configuration for all tools.
The block is applied only to subtools defined after the block appears. Subtools defined before the block appears are not affected.
Example
It is common for tools to use the :exec
mixin to invoke external
programs. This example automatically includes the exec mixin in all
subtools, recursively, so you do not have to repeat the include
directive in every tool.
# .toys.rb
subtool_apply do
# Include the mixin only if the tool hasn't already done so
unless include?(:exec)
include :exec, exit_on_nonzero_status: true
end
end
tool "foo" do
def run
# This tool has access to methods defined by the :exec mixin
# because the above block is applied to the tool.
sh "echo hello"
end
end
1656 1657 1658 1659 1660 1661 1662 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1656 def subtool_apply(&block) cur_tool = DSL::Internal.current_tool(self, false) return self if cur_tool.nil? cur_tool.subtool_middleware_stack.add(:apply_config, parent_source: source_info, &block) self end |
#template(name, template_class = nil, &block) ⇒ self
Create a named template that can be expanded by name from this tool or its subtools.
A template is an object that generates DSL directives. You can use it
to build "prefabricated" tools, and then instantiate them in your Toys
files. Generally, a template is a class with an associated expansion
procedure. The class defines parameters for the template expansion,
and expansion
includes DSL directives that should be run based on
those parameters.
Normally, you provide a block and define the template class in that
block. Most templates will define an initialize
method that takes any
arguments passed into the template expansion. The template must also
provide an expansion
block showing how to use the template object to
produce DSL directives.
Alternately, you can create a template class separately and pass it directly. See Template for details on creating a template class.
Example
The following example creates and uses a simple template.
template "hello-generator" do
def initialize(name, )
@name = name
@message =
end
attr_reader :name, :message
expansion do |template|
tool template.name do
to_run do
puts template.
end
end
end
end
"hello-generator", "mytool", "mytool is running!"
209 210 211 212 213 214 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 209 def template(name, template_class = nil, &block) cur_tool = DSL::Internal.current_tool(self, false) return self if cur_tool.nil? cur_tool.add_template(name, template_class, &block) self end |
#to_run(&block) ⇒ self Also known as: on_run
Specify how to run this tool. Typically you do this by defining a
method namd run
. Alternatively, however, you can pass a block to the
to_run
method.
You may want to do this if your method needs access to local variables in the lexical scope. However, it is often more convenient to use #static to set the value in the context.)
Example
tool "foo" do
cur_time = Time.new
to_run do
puts "The time at tool definition was #{cur_time}"
end
end
1423 1424 1425 1426 1427 1428 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1423 def to_run(&block) cur_tool = DSL::Internal.current_tool(self, true) return self if cur_tool.nil? cur_tool.run_handler = block self end |
#tool(words, if_defined: :combine, delegate_to: nil, &block) ⇒ self
Create a subtool. You must provide a block defining the subtool.
Example
The following example defines a tool and two subtools within it.
tool "build" do
tool "staging" do
def run
puts "Building staging"
end
end
tool "production" do
def run
puts "Building production"
end
end
end
The following example defines a tool that runs one of its subtools.
tool "test", delegate_to: ["test", "unit"] do
tool "unit" do
def run
puts "Running unit tests"
end
end
end
308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 308 def tool(words, if_defined: :combine, delegate_to: nil, &block) subtool_words = @__words.dup next_remaining = @__remaining_words @__loader.split_path(words).each do |word| word = word.to_s subtool_words << word next_remaining = Loader.next_remaining_words(next_remaining, word) end subtool = @__loader.get_tool(subtool_words, @__priority) if subtool.includes_definition? case if_defined when :ignore return self when :reset subtool.reset_definition end end if delegate_to delegator = proc { self.delegate_to(delegate_to) } @__loader.load_block(source_info, delegator, subtool_words, next_remaining, @__priority) end if block @__loader.load_block(source_info, block, subtool_words, next_remaining, @__priority) end self end |
#toys_version!(*requirements) ⇒ self
Asserts that the current Toys version against the given requirements, raising an exception if not.
1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1712 def toys_version!(*requirements) require "rubygems" version = ::Gem::Version.new(Core::VERSION) requirement = ::Gem::Requirement.new(*requirements) unless requirement.satisfied_by?(version) raise Toys::ToolDefinitionError, "Toys version requirements #{requirement} not satisfied by {version}" end self end |
#toys_version?(*requirements) ⇒ Boolean
Determines whether the current Toys version satisfies the given requirements.
1696 1697 1698 1699 1700 1701 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1696 def toys_version?(*requirements) require "rubygems" version = ::Gem::Version.new(Core::VERSION) requirement = ::Gem::Requirement.new(*requirements) requirement.satisfied_by?(version) end |
#truncate_load_path! ⇒ Object
Remove lower-priority sources from the load path. This prevents lower- priority sources (such as Toys files from parent or global directories) from executing or defining tools.
This works only if no such sources have already loaded yet.
1674 1675 1676 1677 1678 1679 |
# File 'toys-core/lib/toys/dsl/tool.rb', line 1674 def truncate_load_path! unless @__loader.stop_loading_at_priority(@__priority) raise ToolDefinitionError, "Cannot truncate load path because tools have already been loaded" end end |