sorbet/rbi/gems/toys-core@0.15.6.rbi
# typed: true
# DO NOT EDIT MANUALLY
# This is an autogenerated file for types exported from the `toys-core` gem.
# Please instead update this file by running `bin/tapioca gem toys-core`.
# Toys is a configurable command line tool. Write commands in config files
# using a simple DSL, and Toys will provide the command line executable and
# take care of all the details such as argument parsing, online help, and error
# reporting. Toys is designed for software developers, IT professionals, and
# other power users who want to write and organize scripts to automate their
# workflows. It can also be used as a Rake replacement, providing a more
# natural command line interface for your project's build tasks.
#
# This module contains the command line framework underlying Toys. It can be
# used to create command line executables using the Toys DSL and classes.
#
# ## Common starting points
#
# Some of the most commonly needed class documentation is listed below:
#
# * For information on the DSL used to write tools, start with
# {Toys::DSL::Tool}.
# * The base class for tool runtime (i.e. that defines the basic methods
# available to a tool's implementation) is {Toys::Context}.
# * For information on writing mixins, see {Toys::Mixin}.
# * For information on writing templates, see {Toys::Template}.
# * For information on writing acceptors, see {Toys::Acceptor}.
# * For information on writing custom shell completions, see {Toys::Completion}.
# * Standard mixins are defined under the {Toys::StandardMixins} module.
# * Various utilities are defined under {Toys::Utils}. Some of these serve as
# the implementations of corresponding mixins.
# * The main entrypoint for the command line framework is {Toys::CLI}.
#
# Other important internal classes are listed below.
#
# * The definition of a tool is represented by {Toys::ToolDefinition} along
# the helpers {Toys::Flag}, {Toys::PositionalArg}, and {Toys::FlagGroup}.
# * Argument parsing is implemented by {Toys::ArgParser}.
# * The process of finding and loading a tool definition given a tool name, is
# implemented by {Toys::Loader}.
# * Text wrapping is handled by {Toys::WrappableString}.
# * The settings system is implemented by {Toys::Settings}.
#
# source://toys-core//lib/toys-core.rb#42
module Toys
class << self
# Create a base class for defining a tool with a given name.
#
# This method returns a base class for defining a tool with a given name.
# This is useful if the naming behavior of {Toys::Tool} is not adequate for
# your tool.
#
# ### Example
#
# class FooBar < Toys.Tool("Foo_Bar")
# desc "This is a tool called Foo_Bar"
#
# def run
# puts "Foo_Bar called"
# end
# end
#
# @param name [String] Name of the tool. Defaults to a name inferred from the
# class name. (See {Toys::Tool}.)
# @param base [Class] Use this tool class as the base class, and inherit helper
# methods from it.
# @param args [String, Class] Any string-valued positional argument is
# interpreted as the name. Any class-valued positional argument is
# interpreted as the base class.
#
# source://toys-core//lib/toys/dsl/base.rb#28
def Tool(*args, name: T.unsafe(nil), base: T.unsafe(nil)); end
# Path to the executable. This can, for example, be invoked to run a subtool
# in a clean environment.
#
# @return [String] if there is an executable
# @return [nil] if there is no such executable
#
# source://toys-core//lib/toys-core.rb#114
def executable_path; end
# Path to the executable. This can, for example, be invoked to run a subtool
# in a clean environment.
#
# @return [String] if there is an executable
# @return [nil] if there is no such executable
#
# source://toys-core//lib/toys-core.rb#114
def executable_path=(_arg0); end
end
end
# An Acceptor validates and converts arguments. It is designed to be
# compatible with the OptionParser accept mechanism.
#
# First, an acceptor validates the argument via its
# {Toys::Acceptor::Base#match} method. This method should determine whether
# the argument is valid, and return information that will help with
# conversion of the argument.
#
# Second, an acceptor converts the argument to its final form via the
# {Toys::Acceptor::Base#convert} method.
#
# Finally, an acceptor has a name that may appear in help text for flags and
# arguments that use it.
#
# source://toys-core//lib/toys/acceptor.rb#19
module Toys::Acceptor
class << self
# Create an acceptor from a variety of specification formats. The
# acceptor is constructed from the given specification object and/or the
# given block. Additionally, some acceptors can take an optional type
# description string used to describe the type of data in online help.
#
# Recognized specs include:
#
# * Any well-known acceptor recognized by OptionParser, such as
# `Integer`, `Array`, or `OptionParser::DecimalInteger`. Any block
# and type description you provide are ignored.
#
# * Any **regular expression**. The returned acceptor validates only if
# the regex matches the *entire string parameter*.
#
# You can also provide an optional conversion function as a block. If
# provided, the block 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, no conversion takes place, and the original string is used.
#
# * 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 element.)
#
# 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 may not
# further customize the conversion function; any block is ignored.
#
# * A **range** of possible values. The acceptor validates if the
# string parameter, after conversion to the range type, lies within
# the range. The final value stored in context data is the converted
# value. For numeric ranges, conversion is provided, but if the range
# has a different type, you must provide the conversion function as
# a block.
#
# * A **function** as a Proc (where the block is ignored) or a block
# (if the spec is nil). 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. You may also
# return the sentinel value {Toys::Acceptor::REJECT} to indicate that
# the string is invalid.
#
# * The value `nil` or `:default` with no block, to indicate the
# default pass-through acceptor {Toys::Acceptor::DEFAULT}. Any type
# description you provide is ignored.
#
# Additional options:
#
# * `:type_desc` (String) The type description for interpolating into
# help text. Ignored if the spec indicates the default acceptor or a
# well-known acceptor.
#
# @param spec [Object] See the description for recognized values.
# @param options [Hash] Additional options to pass to the acceptor.
# @param block [Proc] See the description for recognized forms.
# @return [Toys::Acceptor::Base, Proc]
#
# source://toys-core//lib/toys/acceptor.rb#543
def create(spec = T.unsafe(nil), **options, &block); end
# Lookup a standard acceptor name recognized by OptionParser.
#
# @param spec [Object] A well-known acceptor specification, such as
# `String`, `Integer`, `Array`, `OptionParser::DecimalInteger`, etc.
# @return [Toys::Acceptor::Base] The corresponding Acceptor object
# @return [nil] if the given standard acceptor was not recognized.
#
# source://toys-core//lib/toys/acceptor.rb#472
def lookup_well_known(spec); end
# Take the various ways to express an acceptor spec, and convert them to
# a canonical form expressed as a single object. This is called from the
# DSL to generate a spec object that can be stored.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/acceptor.rb#561
def scalarize_spec(spec, options, block); end
private
# source://toys-core//lib/toys/acceptor.rb#645
def build_array; end
# source://toys-core//lib/toys/acceptor.rb#641
def build_boolean(spec); end
# source://toys-core//lib/toys/acceptor.rb#665
def build_decimal_integer; end
# source://toys-core//lib/toys/acceptor.rb#679
def build_decimal_numeric; end
# source://toys-core//lib/toys/acceptor.rb#629
def build_float; end
# source://toys-core//lib/toys/acceptor.rb#625
def build_integer; end
# source://toys-core//lib/toys/acceptor.rb#617
def build_nil; end
# source://toys-core//lib/toys/acceptor.rb#637
def build_numeric; end
# source://toys-core//lib/toys/acceptor.rb#672
def build_octal_integer; end
# source://toys-core//lib/toys/acceptor.rb#633
def build_rational; end
# source://toys-core//lib/toys/acceptor.rb#651
def build_regexp; end
# source://toys-core//lib/toys/acceptor.rb#621
def build_string; end
# source://toys-core//lib/toys/acceptor.rb#574
def internal_create(spec, options, block); end
# source://toys-core//lib/toys/acceptor.rb#609
def optparse_well_knowns; end
# source://toys-core//lib/toys/acceptor.rb#593
def standard_well_knowns; end
end
end
# A converter proc that handles boolean strings. Recognizes {TRUE_STRINGS}
# and {FALSE_STRINGS}. Useful for Simple acceptors.
#
# @return [Proc]
#
# source://toys-core//lib/toys/acceptor.rb#447
Toys::Acceptor::BOOLEAN_CONVERTER = T.let(T.unsafe(nil), Proc)
# A base class for acceptors.
#
# The base acceptor does not do any validation (i.e. it accepts all
# arguments) or conversion (i.e. it returns the original string). You can
# subclass this base class and override the {#match} and {#convert} methods
# to implement an acceptor.
#
# source://toys-core//lib/toys/acceptor.rb#41
class Toys::Acceptor::Base
# Create a base acceptor.
#
# @param type_desc [String] Type description string, shown in help.
# Defaults to {Toys::Acceptor::DEFAULT_TYPE_DESC}.
# @param well_known_spec [Object] The well-known acceptor spec associated
# with this acceptor, or `nil` for none.
# @return [Base] a new instance of Base
#
# source://toys-core//lib/toys/acceptor.rb#50
def initialize(type_desc: T.unsafe(nil), well_known_spec: T.unsafe(nil)); end
# Convert the given input.
#
# This method is passed the results of a successful match, including the
# original input string and any other values returned from {#match}. It
# must return the final converted value to use.
#
# @param str [String] Original argument string.
# @param extra [Object...] Zero or more additional arguments comprising
# additional elements returned from the match function.
# @return [Object] The converted argument as it should be stored in the
# context data.
#
# source://toys-core//lib/toys/acceptor.rb#118
def convert(str, *extra); end
# Validate the given input.
#
# When given a valid input, return an array in which the first element is
# the original input string, and the remaining elements (which may be
# empty) comprise any additional information that may be useful during
# conversion. If there is no additional information, you can return the
# original input string by itself without wrapping in an array.
#
# When given an invalid input, return a falsy value such as `nil`.
#
# Note that a `MatchData` object is a legitimate return value because it
# duck-types the appropriate array.
#
# This default implementation simply returns the original input string,
# as the only array element, indicating all inputs are valid. You can
# override this method to provide a different validation function.
#
# @param str [String] The input argument string.
# @return [String, Array, nil]
#
# source://toys-core//lib/toys/acceptor.rb#101
def match(str); end
# Return suggestions for a given non-matching string.
#
# This method may be called when a match fails. It should return a
# (possibly empty) array of suggestions that could be displayed to the
# user as "did you mean..."
#
# The default implementation returns the empty list.
#
# @param str [String] A string that failed matching.
# @return [Array<String>] A possibly empty array of alternative
# suggestions that could be displayed with "did you mean..."
#
# source://toys-core//lib/toys/acceptor.rb#135
def suggestions(str); end
# Type description string, shown in help.
#
# @return [String]
#
# source://toys-core//lib/toys/acceptor.rb#76
def to_s; end
# Type description string, shown in help.
#
# @return [String]
#
# source://toys-core//lib/toys/acceptor.rb#59
def type_desc; end
# The well-known acceptor spec associated with this acceptor, if any.
# This generally identifies an OptionParser-compatible acceptor spec. For
# example, the acceptor object that corresponds to `Integer` will return
# `Integer` from this attribute.
#
# @return [Object] the well-known acceptor
# @return [nil] if there is no corresponding well-known acceptor
#
# source://toys-core//lib/toys/acceptor.rb#70
def well_known_spec; end
end
# The default acceptor. Corresponds to the well-known acceptor for
# `Object`.
#
# @return [Toys::Acceptor::Base]
#
# source://toys-core//lib/toys/acceptor.rb#145
Toys::Acceptor::DEFAULT = T.let(T.unsafe(nil), Toys::Acceptor::Base)
# The default type description.
#
# @return [String]
#
# source://toys-core//lib/toys/acceptor.rb#31
Toys::Acceptor::DEFAULT_TYPE_DESC = T.let(T.unsafe(nil), String)
# An acceptor that recognizes a fixed set of values.
#
# You provide a list of valid values. The input argument string will be
# matched against the string forms of these valid values. If it matches,
# the converter will return the actual value from the valid list.
#
# For example, you could pass `[:one, :two, 3]` as the set of values. If
# an argument of `"two"` is passed in, the converter will yield a final
# value of the symbol `:two`. If an argument of "3" is passed in, the
# converter will yield the integer `3`. If an argument of "three" is
# passed in, the match will fail.
#
# source://toys-core//lib/toys/acceptor.rb#267
class Toys::Acceptor::Enum < ::Toys::Acceptor::Base
# Create an acceptor.
#
# @param values [Array<Object>] Valid values.
# @param type_desc [String] Type description string, shown in help.
# Defaults to {Toys::Acceptor::DEFAULT_TYPE_DESC}.
# @param well_known_spec [Object] The well-known acceptor spec associated
# with this acceptor, or `nil` for none.
# @return [Enum] a new instance of Enum
#
# source://toys-core//lib/toys/acceptor.rb#277
def initialize(values, type_desc: T.unsafe(nil), well_known_spec: T.unsafe(nil)); end
# Overrides {Toys::Acceptor::Base#convert} to return the actual enum
# element.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#303
def convert(_str, elem); end
# Overrides {Toys::Acceptor::Base#match} to find the value.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#293
def match(str); end
# Overrides {Toys::Acceptor::Base#suggestions} to return close matches
# from the enum.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#313
def suggestions(str); end
# The array of enum values.
#
# @return [Array<Object>]
#
# source://toys-core//lib/toys/acceptor.rb#286
def values; end
end
# A set of strings that are considered false for boolean acceptors.
# Currently set to `["-", "false", "no", "nil"]`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/acceptor.rb#440
Toys::Acceptor::FALSE_STRINGS = T.let(T.unsafe(nil), Array)
# A converter proc that handles floats. Useful in Simple and Range
# acceptors.
#
# @return [Proc]
#
# source://toys-core//lib/toys/acceptor.rb#403
Toys::Acceptor::FLOAT_CONVERTER = T.let(T.unsafe(nil), Proc)
# A converter proc that handles integers. Useful in Simple and Range
# acceptors.
#
# @return [Proc]
#
# source://toys-core//lib/toys/acceptor.rb#396
Toys::Acceptor::INTEGER_CONVERTER = T.let(T.unsafe(nil), Proc)
# A converter proc that handles any numeric value. Useful in Simple and
# Range acceptors.
#
# @return [Proc]
#
# source://toys-core//lib/toys/acceptor.rb#417
Toys::Acceptor::NUMERIC_CONVERTER = T.let(T.unsafe(nil), Proc)
# An acceptor that uses a regex to validate input. It also supports a
# custom conversion function that generates the final value from the match
# results.
#
# source://toys-core//lib/toys/acceptor.rb#203
class Toys::Acceptor::Pattern < ::Toys::Acceptor::Base
# Create a pattern acceptor.
#
# You must provide a regular expression (or any object that duck-types
# `Regexp#match`) as a validator.
#
# You may also optionally provide a converter, either as a proc or a
# block. A converter must take as its arguments the values in the
# `MatchData` returned from a successful regex match. That is, the first
# argument is the original input string, and the remaining arguments are
# the captures. The converter must return the final converted value.
# If no converter is provided, no conversion is done and the input string
# is returned.
#
# @param regex [Regexp] Regular expression defining value values.
# @param converter [Proc] An optional converter function. May also be
# given as a block. Note that the converter will be passed all
# elements of the `MatchData`.
# @param type_desc [String] Type description string, shown in help.
# Defaults to {Toys::Acceptor::DEFAULT_TYPE_DESC}.
# @param well_known_spec [Object] The well-known acceptor spec associated
# with this acceptor, or `nil` for none.
# @param block [Proc] A converter function, if not provided as a normal
# parameter.
# @return [Pattern] a new instance of Pattern
#
# source://toys-core//lib/toys/acceptor.rb#229
def initialize(regex, converter = T.unsafe(nil), type_desc: T.unsafe(nil), well_known_spec: T.unsafe(nil), &block); end
# Overrides {Toys::Acceptor::Base#convert} to use the given converter.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#249
def convert(str, *extra); end
# Overrides {Toys::Acceptor::Base#match} to use the given regex.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#240
def match(str); end
end
# A converter proc that handles rationals. Useful in Simple and Range
# acceptors.
#
# @return [Proc]
#
# source://toys-core//lib/toys/acceptor.rb#410
Toys::Acceptor::RATIONAL_CONVERTER = T.let(T.unsafe(nil), Proc)
# A sentinel that may be returned from a function-based acceptor to
# indicate invalid input.
#
# @return [Object]
#
# source://toys-core//lib/toys/acceptor.rb#25
Toys::Acceptor::REJECT = T.let(T.unsafe(nil), Object)
# An acceptor that recognizes a range of values.
#
# The input argument is matched against the given range. For example, you
# can match against the integers from 1 to 10 by passing the range
# `(1..10)`.
#
# You can also provide a conversion function that takes the input string
# and converts it an object that can be compared by the range. If you do
# not provide a converter, a default converter will be provided depending
# on the types of objects serving as the range limits. Specifically:
#
# * If the range beginning and end are both `Integer`, then input strings
# are likewise converted to `Integer` when matched against the range.
# Accepted values are returned as integers.
# * If the range beginning and end are both `Float`, then input strings
# are likewise converted to `Float`.
# * If the range beginning and end are both `Rational`, then input
# strings are likewise converted to `Rational`.
# * If the range beginning and end are both `Numeric` types but different
# subtypes (e.g. an `Integer` and a `Float`), then any type of numeric
# input (integer, float, rational) is accepted and matched against the
# range.
# * If the range beginning and/or end are not numeric types, then no
# conversion is done by default.
#
# source://toys-core//lib/toys/acceptor.rb#344
class Toys::Acceptor::Range < ::Toys::Acceptor::Simple
# Create an acceptor.
#
# @param range [Range] The range of acceptable values
# @param converter [Proc] A converter proc that takes an input string and
# attempts to convert it to a type comparable by the range. For
# numeric ranges, this can be omitted because one is provided by
# default. You should provide a converter for other types of ranges.
# You can also pass the converter as a block.
# @param type_desc [String] Type description string, shown in help.
# Defaults to {Toys::Acceptor::DEFAULT_TYPE_DESC}.
# @param well_known_spec [Object] The well-known acceptor spec associated
# with this acceptor, or `nil` for none.
# @param block [Proc] Converter function, if not provided as a normal
# parameter.
# @return [Range] a new instance of Range
#
# source://toys-core//lib/toys/acceptor.rb#361
def initialize(range, converter = T.unsafe(nil), type_desc: T.unsafe(nil), well_known_spec: T.unsafe(nil), &block); end
# The range being checked.
#
# @return [Range]
#
# source://toys-core//lib/toys/acceptor.rb#374
def range; end
private
# source://toys-core//lib/toys/acceptor.rb#378
def make_converter(val1, val2); end
end
# An acceptor that uses a simple function to validate and convert input.
# The function must take the input string as its argument, and either
# return the converted object to indicate success, or raise an exception or
# return the sentinel {Toys::Acceptor::REJECT} to indicate invalid input.
#
# source://toys-core//lib/toys/acceptor.rb#153
class Toys::Acceptor::Simple < ::Toys::Acceptor::Base
# Create a simple acceptor.
#
# You should provide an acceptor function, either as a proc in the
# `function` argument, or as a block. The function must take as its one
# argument the input string. If the string is valid, the function must
# return the value to store in the tool's data. If the string is invalid,
# the function may either raise an exception (which must descend from
# `StandardError`) or return {Toys::Acceptor::REJECT}.
#
# @param function [Proc] The acceptor function
# @param type_desc [String] Type description string, shown in help.
# Defaults to {Toys::Acceptor::DEFAULT_TYPE_DESC}.
# @param well_known_spec [Object] The well-known acceptor spec associated
# with this acceptor, or `nil` for none.
# @param block [Proc] The acceptor function, if not provided as a normal
# parameter.
# @return [Simple] a new instance of Simple
#
# source://toys-core//lib/toys/acceptor.rb#172
def initialize(function = T.unsafe(nil), type_desc: T.unsafe(nil), well_known_spec: T.unsafe(nil), &block); end
# Overrides {Toys::Acceptor::Base#convert} to use the given function's
# result.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#193
def convert(_str, result); end
# Overrides {Toys::Acceptor::Base#match} to use the given function.
#
# @private
#
# source://toys-core//lib/toys/acceptor.rb#182
def match(str); end
end
# A set of strings that are considered true for boolean acceptors.
# Currently set to `["+", "true", "yes"]`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/acceptor.rb#433
Toys::Acceptor::TRUE_STRINGS = T.let(T.unsafe(nil), Array)
# An internal class that parses command line arguments for a tool.
#
# Generally, you should not need to use this class directly. It is called
# from {Toys::CLI}.
#
# source://toys-core//lib/toys/arg_parser.rb#10
class Toys::ArgParser
# Create an argument parser for a particular tool.
#
# @param cli [Toys::CLI] The CLI in effect.
# @param tool [Toys::ToolDefinition] The tool defining the argument format.
# @param default_data [Hash] Additional initial data (such as verbosity).
# @param require_exact_flag_match [Boolean] Whether to require flag matches
# be exact (not partial). Default is false.
# @return [ArgParser] a new instance of ArgParser
#
# source://toys-core//lib/toys/arg_parser.rb#277
def initialize(cli, tool, default_data: T.unsafe(nil), require_exact_flag_match: T.unsafe(nil)); end
# The current flag definition whose value is still pending
#
# @return [Toys::Flag] The pending flag definition
# @return [nil] if there is no pending flag
#
# source://toys-core//lib/toys/arg_parser.rb#344
def active_flag_def; end
# The collected tool data from parsed arguments.
#
# @return [Hash]
#
# source://toys-core//lib/toys/arg_parser.rb#330
def data; end
# An array of parse error messages.
#
# @return [Array<Toys::ArgParser::UsageError>]
#
# source://toys-core//lib/toys/arg_parser.rb#336
def errors; end
# Complete parsing. This should be called after all arguments have been
# processed. It does a final check for any errors, including:
#
# * The arguments ended with a flag that was expecting a value but wasn't
# provided.
# * One or more required arguments were never given a value.
# * One or more extra arguments were provided.
# * Restrictions defined in one or more flag groups were not fulfilled.
#
# Any errors are added to the errors array. It also fills in final values
# for `Context::Key::USAGE_ERRORS` and `Context::Key::ARGS`.
#
# After this method is called, this object is locked down, and no
# additional arguments may be parsed.
#
# @return [self]
#
# source://toys-core//lib/toys/arg_parser.rb#407
def finish; end
# Determine if this parser is finished
#
# @return [Boolean]
#
# source://toys-core//lib/toys/arg_parser.rb#358
def finished?; end
# Whether flags are currently allowed. Returns false after `--` is received.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/arg_parser.rb#350
def flags_allowed?; end
# The argument definition that will be applied to the next argument.
#
# @return [Toys::PositionalArg] The next argument definition.
# @return [nil] if all arguments have been filled.
#
# source://toys-core//lib/toys/arg_parser.rb#368
def next_arg_def; end
# Incrementally parse a single string or an array of strings
#
# @param args [String, Array<String>]
# @return [self]
#
# source://toys-core//lib/toys/arg_parser.rb#378
def parse(args); end
# All command line arguments that have been parsed.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/arg_parser.rb#306
def parsed_args; end
# The tool definition governing this parser.
#
# @return [Toys::ToolDefinition]
#
# source://toys-core//lib/toys/arg_parser.rb#300
def tool; end
# All args that were not matched.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/arg_parser.rb#324
def unmatched_args; end
# Flags that were not matched.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/arg_parser.rb#318
def unmatched_flags; end
# Extra positional args that were not matched.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/arg_parser.rb#312
def unmatched_positional; end
private
# source://toys-core//lib/toys/arg_parser.rb#542
def add_data(key, handler, accept, value, type_name, display_name); end
# source://toys-core//lib/toys/arg_parser.rb#449
def check_flag(arg); end
# source://toys-core//lib/toys/arg_parser.rb#438
def check_flag_value(arg); end
# source://toys-core//lib/toys/arg_parser.rb#522
def find_flag(name); end
# source://toys-core//lib/toys/arg_parser.rb#559
def finish_active_flag; end
# source://toys-core//lib/toys/arg_parser.rb#570
def finish_arg_defs; end
# source://toys-core//lib/toys/arg_parser.rb#589
def finish_flag_groups; end
# source://toys-core//lib/toys/arg_parser.rb#595
def finish_special_data; end
# source://toys-core//lib/toys/arg_parser.rb#472
def handle_plain_flag(name, following = T.unsafe(nil)); end
# source://toys-core//lib/toys/arg_parser.rb#507
def handle_positional(arg); end
# source://toys-core//lib/toys/arg_parser.rb#466
def handle_single_flags(str); end
# source://toys-core//lib/toys/arg_parser.rb#493
def handle_valued_flag(name, value); end
# source://toys-core//lib/toys/arg_parser.rb#422
def initial_data(cli, tool, default_data); end
end
# source://toys-core//lib/toys/arg_parser.rb#419
Toys::ArgParser::ARG_HANDLER = T.let(T.unsafe(nil), Proc)
# A UsageError indicating a required positional argument was not fulfilled.
#
# source://toys-core//lib/toys/arg_parser.rb#202
class Toys::ArgParser::ArgMissingError < ::Toys::ArgParser::UsageError
# Create an ArgMissingError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param name [String] The name of the argument. Normally required.
# @return [ArgMissingError] a new instance of ArgMissingError
#
# source://toys-core//lib/toys/arg_parser.rb#210
def initialize(message = T.unsafe(nil), name: T.unsafe(nil)); end
end
# A UsageError indicating a positional argument did not accept the value
# given it.
#
# source://toys-core//lib/toys/arg_parser.rb#182
class Toys::ArgParser::ArgValueUnacceptableError < ::Toys::ArgParser::UsageError
# Create an ArgValueUnacceptableError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param name [String] The name of the argument. Normally required.
# @param value [String] The value given. Normally required.
# @param suggestions [Array<String>] An array of suggestions to present
# to the user. Optional.
# @return [ArgValueUnacceptableError] a new instance of ArgValueUnacceptableError
#
# source://toys-core//lib/toys/arg_parser.rb#193
def initialize(message = T.unsafe(nil), name: T.unsafe(nil), value: T.unsafe(nil), suggestions: T.unsafe(nil)); end
end
# A UsageError indicating extra arguments were supplied.
#
# source://toys-core//lib/toys/arg_parser.rb#218
class Toys::ArgParser::ExtraArgumentsError < ::Toys::ArgParser::UsageError
# Create an ExtraArgumentsError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param value [String] The first extra argument. Normally required.
# @param values [Array<String>] All extra arguments. Normally required.
# @return [ExtraArgumentsError] a new instance of ExtraArgumentsError
#
# source://toys-core//lib/toys/arg_parser.rb#227
def initialize(message = T.unsafe(nil), value: T.unsafe(nil), values: T.unsafe(nil)); end
end
# A UsageError indicating a flag name prefix was given that matched
# multiple flags.
#
# source://toys-core//lib/toys/arg_parser.rb#142
class Toys::ArgParser::FlagAmbiguousError < ::Toys::ArgParser::UsageError
# Create a FlagAmbiguousError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param value [String] The requested flag name. Normally required.
# @param suggestions [Array<String>] An array of suggestions to present
# to the user. Optional.
# @return [FlagAmbiguousError] a new instance of FlagAmbiguousError
#
# source://toys-core//lib/toys/arg_parser.rb#152
def initialize(message = T.unsafe(nil), value: T.unsafe(nil), suggestions: T.unsafe(nil)); end
end
# A UsageError indicating a flag group constraint was not fulfilled.
#
# source://toys-core//lib/toys/arg_parser.rb#257
class Toys::ArgParser::FlagGroupConstraintError < ::Toys::ArgParser::UsageError
# Create a FlagGroupConstraintError.
#
# @param message [String] The message. Required.
# @return [FlagGroupConstraintError] a new instance of FlagGroupConstraintError
#
# source://toys-core//lib/toys/arg_parser.rb#263
def initialize(message); end
end
# A UsageError indicating a flag name was not recognized.
#
# source://toys-core//lib/toys/arg_parser.rb#122
class Toys::ArgParser::FlagUnrecognizedError < ::Toys::ArgParser::UsageError
# Create a FlagUnrecognizedError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param value [String] The requested flag name. Normally required.
# @param suggestions [Array<String>] An array of suggestions to present
# to the user. Optional.
# @return [FlagUnrecognizedError] a new instance of FlagUnrecognizedError
#
# source://toys-core//lib/toys/arg_parser.rb#132
def initialize(message = T.unsafe(nil), value: T.unsafe(nil), suggestions: T.unsafe(nil)); end
end
# A UsageError indicating a value was not provided for a flag that requires
# a value.
#
# source://toys-core//lib/toys/arg_parser.rb#106
class Toys::ArgParser::FlagValueMissingError < ::Toys::ArgParser::UsageError
# Create a FlagValueMissingError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param name [String] The name of the flag. Normally required.
# @return [FlagValueMissingError] a new instance of FlagValueMissingError
#
# source://toys-core//lib/toys/arg_parser.rb#114
def initialize(message = T.unsafe(nil), name: T.unsafe(nil)); end
end
# A UsageError indicating a value was provided for a flag that does not
# take a value.
#
# source://toys-core//lib/toys/arg_parser.rb#89
class Toys::ArgParser::FlagValueNotAllowedError < ::Toys::ArgParser::UsageError
# Create a FlagValueNotAllowedError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param name [String] The name of the flag. Normally required.
# @return [FlagValueNotAllowedError] a new instance of FlagValueNotAllowedError
#
# source://toys-core//lib/toys/arg_parser.rb#97
def initialize(message = T.unsafe(nil), name: T.unsafe(nil)); end
end
# A UsageError indicating a flag did not accept the value given it.
#
# source://toys-core//lib/toys/arg_parser.rb#161
class Toys::ArgParser::FlagValueUnacceptableError < ::Toys::ArgParser::UsageError
# Create a FlagValueUnacceptableError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param name [String] The name of the flag. Normally required.
# @param value [String] The value given. Normally required.
# @param suggestions [Array<String>] An array of suggestions to present
# to the user. Optional.
# @return [FlagValueUnacceptableError] a new instance of FlagValueUnacceptableError
#
# source://toys-core//lib/toys/arg_parser.rb#172
def initialize(message = T.unsafe(nil), name: T.unsafe(nil), value: T.unsafe(nil), suggestions: T.unsafe(nil)); end
end
# source://toys-core//lib/toys/arg_parser.rb#418
Toys::ArgParser::REMAINING_HANDLER = T.let(T.unsafe(nil), Proc)
# A UsageError indicating the given subtool name does not exist.
#
# source://toys-core//lib/toys/arg_parser.rb#235
class Toys::ArgParser::ToolUnrecognizedError < ::Toys::ArgParser::UsageError
# Create a ToolUnrecognizedError.
#
# @param message [String, nil] A custom message. Normally omitted, in
# which case an appropriate default is supplied.
# @param value [String] The requested subtool. Normally required.
# @param values [Array<String>] The full path of the requested tool.
# Normally required.
# @param suggestions [Array<String>] An array of suggestions to present
# to the user. Optional.
# @return [ToolUnrecognizedError] a new instance of ToolUnrecognizedError
#
# source://toys-core//lib/toys/arg_parser.rb#247
def initialize(message = T.unsafe(nil), value: T.unsafe(nil), values: T.unsafe(nil), suggestions: T.unsafe(nil)); end
end
# Base representation of a usage error reported by the ArgParser.
#
# This functions similarly to an exception, but is not raised. Rather, it
# is returned in the {Toys::ArgParser#errors} array.
#
# source://toys-core//lib/toys/arg_parser.rb#17
class Toys::ArgParser::UsageError
# Create a UsageError given a message and common data
#
# @param message [String] The basic error message.
# @param name [String, nil] The name of the element (normally flag or
# positional argument) that reported the error, or nil if there is
# no definite element.
# @param value [String, nil] The value that was rejected, or nil if not
# applicable.
# @param suggestions [Array<String>, nil] An array of suggestions from
# DidYouMean, or nil if not applicable.
# @return [UsageError] a new instance of UsageError
#
# source://toys-core//lib/toys/arg_parser.rb#30
def initialize(message, name: T.unsafe(nil), value: T.unsafe(nil), suggestions: T.unsafe(nil)); end
# A fully formatted error message including suggestions.
#
# @return [String]
#
# source://toys-core//lib/toys/arg_parser.rb#74
def full_message; end
# The basic error message. Does not include suggestions, if any.
#
# @return [String]
#
# source://toys-core//lib/toys/arg_parser.rb#42
def message; end
# The name of the element (normally a flag or positional argument) that
# reported the error.
#
# @return [String] The element name.
# @return [nil] if there is no definite element source.
#
# source://toys-core//lib/toys/arg_parser.rb#51
def name; end
# An array of suggestions from DidYouMean.
#
# @return [Array<String>] array of suggestions.
# @return [nil] if suggestions are not applicable to this error.
#
# source://toys-core//lib/toys/arg_parser.rb#67
def suggestions; end
# A fully formatted error message including suggestions.
#
# @return [String]
#
# source://toys-core//lib/toys/arg_parser.rb#74
def to_s; end
# The value that was rejected.
#
# @return [String] the value string
# @return [nil] if a value is not applicable to this error.
#
# source://toys-core//lib/toys/arg_parser.rb#59
def value; end
end
# An exception indicating problems parsing arguments.
#
# source://toys-core//lib/toys/errors.rb#19
class Toys::ArgParsingError < ::StandardError
# Create an ArgParsingError given a set of error messages
#
# @param errors [Array<Toys::ArgParser::UsageError>]
# @return [ArgParsingError] a new instance of ArgParsingError
#
# source://toys-core//lib/toys/errors.rb#24
def initialize(errors); end
# The individual usage error messages.
#
# @return [Array<Toys::ArgParser::UsageError>]
#
# source://toys-core//lib/toys/errors.rb#33
def usage_errors; end
end
# A Toys-based CLI.
#
# This is the entry point for command line execution. It includes the set of
# tool definitions (and/or information on how to load them from the file
# system), configuration parameters such as logging and error handling, and a
# method to call to invoke a command.
#
# This is the class to instantiate to create a Toys-based command line
# executable. For example:
#
# #!/usr/bin/env ruby
# require "toys-core"
# cli = Toys::CLI.new
# cli.add_config_block do
# def run
# puts "Hello, world!"
# end
# end
# exit(cli.run(*ARGV))
#
# The currently running CLI is also available at runtime, and can be used by
# tools that want to invoke other tools. For example:
#
# # My .toys.rb
# tool "foo" do
# def run
# puts "in foo"
# end
# end
# tool "bar" do
# def run
# puts "in bar"
# cli.run "foo"
# end
# end
#
# source://toys-core//lib/toys/cli.rb#41
class Toys::CLI
# Create a CLI.
#
# Most configuration parameters (besides tool definitions and tool lookup
# paths) are set as options passed to the constructor. These options fall
# roughly into four categories:
#
# * Options affecting output behavior:
# * `logger`: A global logger for all tools to use
# * `logger_factory`: A proc that returns a logger to use
# * `base_level`: The default log level
# * `error_handler`: Callback for handling exceptions
# * `executable_name`: The name of the executable
# * Options affecting tool specification
# * `extra_delimibers`: Tool name delimiters besides space
# * `completion`: Tab completion handler
# * Options affecting tool definition
# * `middleware_stack`: The middleware applied to all tools
# * `mixin_lookup`: Where to find well-known mixins
# * `middleware_lookup`: Where to find well-known middleware
# * `template_lookup`: Where to find well-known templates
# * Options affecting tool files and directories
# * `config_dir_name`: Directory name containing tool files
# * `config_file_name`: File name for tools
# * `index_file_name`: Name of index files in tool directories
# * `preload_file_name`: Name of preload files in tool directories
# * `preload_dir_name`: Name of preload directories in tool directories
# * `data_dir_name`: Name of data directories in tool directories
#
# @param logger [Logger] A global logger to use for all tools. This can be
# set if the CLI will call at most one tool at a time. However, it will
# behave incorrectly if CLI might run multiple tools at the same time
# with different verbosity settings (since the logger cannot have
# multiple level settings simultaneously). In that case, do not set a
# global logger, but use the `logger_factory` parameter instead.
# @param logger_factory [Proc] A proc that takes a {Toys::ToolDefinition}
# as an argument, and returns a `Logger` to use when running that tool.
# Optional. If not provided (and no global logger is set),
# {Toys::CLI.default_logger_factory} is called to get a basic default.
# @param base_level [Integer] The logger level that should correspond
# to zero verbosity.
# Optional. If not provided, defaults to the current level of the
# logger (which is often `Logger::WARN`).
# @param error_handler [Proc, nil] A proc that is called when an unhandled
# exception (a normal exception subclassing `StandardError`, an error
# loading a toys config file subclassing `SyntaxError`, or an unhandled
# signal subclassing `SignalException`) is detected. The proc should
# take a {Toys::ContextualError}, whose cause is the unhandled
# exception, as the sole argument, and report the error. It should
# return an exit code (normally nonzero) appropriate to the error.
# Optional. If not provided, {Toys::CLI.default_error_handler} is
# called to get a basic default handler.
# @param executable_name [String] The executable name displayed in help
# text. Optional. Defaults to the ruby program name.
# @param extra_delimiters [String] A string containing characters that can
# function as delimiters in a tool name. Defaults to empty. Allowed
# characters are period, colon, and slash.
# @param completion [Toys::Completion::Base] A specifier for shell tab
# completion for the CLI as a whole.
# Optional. If not provided, {Toys::CLI.default_completion} is called
# to get a default completion that delegates to the tool.
# @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
# middleware that will be used by default for all tools.
# Optional. If not provided, uses a default set of middleware defined
# in {Toys::CLI.default_middleware_stack}. To include no middleware,
# pass the empty array explicitly.
# @param mixin_lookup [Toys::ModuleLookup] A lookup for well-known mixin
# modules (i.e. with symbol names).
# Optional. If not provided, defaults to the set of standard mixins
# provided by toys-core, as defined by
# {Toys::CLI.default_mixin_lookup}. If you explicitly want no standard
# mixins, pass an empty instance of {Toys::ModuleLookup}.
# @param middleware_lookup [Toys::ModuleLookup] A lookup for well-known
# middleware classes.
# Optional. If not provided, defaults to the set of standard middleware
# classes provided by toys-core, as defined by
# {Toys::CLI.default_middleware_lookup}. If you explicitly want no
# standard middleware, pass an empty instance of
# {Toys::ModuleLookup}.
# @param template_lookup [Toys::ModuleLookup] A lookup for well-known
# template classes.
# Optional. If not provided, defaults to the set of standard template
# classes provided by toys core, as defined by
# {Toys::CLI.default_template_lookup}. If you explicitly want no
# standard tenokates, pass an empty instance of {Toys::ModuleLookup}.
# @param config_dir_name [String] A directory with this name that appears
# in the loader path, is treated as a configuration directory whose
# contents are loaded into the toys configuration.
# Optional. If not provided, toplevel configuration directories are
# disabled.
# Note: the standard toys executable sets this to `".toys"`.
# @param config_file_name [String] A file with this name that appears in
# the loader path, is treated as a toplevel configuration file whose
# contents are loaded into the toys configuration. This does not
# include "index" configuration files located within a configuration
# directory.
# Optional. If not provided, toplevel configuration files are disabled.
# Note: the standard toys executable sets this to `".toys.rb"`.
# @param index_file_name [String] A file with this name that appears in any
# configuration directory is loaded first as a standalone configuration
# file. This does not include "toplevel" configuration files outside
# configuration directories.
# Optional. If not provided, index configuration files are disabled.
# Note: the standard toys executable sets this to `".toys.rb"`.
# @param preload_file_name [String] A file with this name that appears
# in any configuration directory is preloaded using `require` before
# any tools in that configuration directory are defined. A preload file
# includes normal Ruby code, rather than Toys DSL definitions. The
# preload file is loaded before any files in a preload directory.
# Optional. If not provided, preload files are disabled.
# Note: the standard toys executable sets this to `".preload.rb"`.
# @param preload_dir_name [String] A directory with this name that appears
# in any configuration directory is searched for Ruby files, which are
# preloaded using `require` before any tools in that configuration
# directory are defined. Files in a preload directory include normal
# Ruby code, rather than Toys DSL definitions. Files in a preload
# directory are loaded after any standalone preload file.
# Optional. If not provided, preload directories are disabled.
# Note: the standard toys executable sets this to `".preload"`.
# @param data_dir_name [String] A directory with this name that appears in
# any configuration directory is added to the data directory search
# path for any tool file in that directory.
# Optional. If not provided, data directories are disabled.
# Note: the standard toys executable sets this to `".data"`.
# @param lib_dir_name [String] A directory with this name that appears in
# any configuration directory is added to the Ruby load path when
# executing any tool file in that directory.
# Optional. If not provided, lib directories are disabled.
# Note: the standard toys executable sets this to `".lib"`.
# @return [CLI] a new instance of CLI
#
# source://toys-core//lib/toys/cli.rb#175
def initialize(executable_name: T.unsafe(nil), middleware_stack: T.unsafe(nil), extra_delimiters: T.unsafe(nil), config_dir_name: T.unsafe(nil), config_file_name: T.unsafe(nil), index_file_name: T.unsafe(nil), preload_file_name: T.unsafe(nil), preload_dir_name: T.unsafe(nil), data_dir_name: T.unsafe(nil), lib_dir_name: T.unsafe(nil), mixin_lookup: T.unsafe(nil), middleware_lookup: T.unsafe(nil), template_lookup: T.unsafe(nil), logger_factory: T.unsafe(nil), logger: T.unsafe(nil), base_level: T.unsafe(nil), error_handler: T.unsafe(nil), completion: T.unsafe(nil)); end
# Add a configuration block to the loader.
#
# This is used to create tools "inline", and is useful for simple command
# line executables based on Toys.
#
# @param high_priority [Boolean] Add the config at the head of the priority
# list rather than the tail.
# @param source_name [String] The source name that will be shown in
# documentation for tools defined in this block. If omitted, a default
# unique string will be generated.
# @param block [Proc] The block of configuration, executed in the context
# of the tool DSL {Toys::DSL::Tool}.
# @param context_directory [String, nil] The context directory for tools
# loaded from this block. You can pass a directory path as a string, or
# `nil` to denote no context. Defaults to `nil`.
# @return [self]
#
# source://toys-core//lib/toys/cli.rb#356
def add_config_block(high_priority: T.unsafe(nil), source_name: T.unsafe(nil), context_directory: T.unsafe(nil), &block); end
# Add a specific configuration file or directory to the loader.
#
# This is generally used to load a static or "built-in" set of tools,
# either for a standalone command line executable based on Toys, or to
# provide a "default" set of tools for a dynamic executable. For example,
# the main Toys executable uses this to load the builtin tools from its
# "builtins" directory.
#
# @param path [String] A path to add. May reference a single Toys file or
# a Toys directory.
# @param high_priority [Boolean] Add the config at the head of the priority
# list rather than the tail.
# @param source_name [String] A custom name for the root source. Optional.
# @param context_directory [String, nil, :path, :parent] The context directory
# for tools loaded from this path. You can pass a directory path as a
# string, `:path` to denote the given path, `:parent` to denote the
# given path's parent directory, or `nil` to denote no context.
# Defaults to `:parent`.
# @return [self]
#
# source://toys-core//lib/toys/cli.rb#327
def add_config_path(path, high_priority: T.unsafe(nil), source_name: T.unsafe(nil), context_directory: T.unsafe(nil)); end
# Checks the given directory path. If it contains a config file and/or
# config directory, those are added to the loader.
#
# The main Toys executable uses this method to load tools from directories
# in the `TOYS_PATH`.
#
# @param search_path [String] A path to search for configs.
# @param high_priority [Boolean] Add the configs at the head of the
# priority list rather than the tail.
# @param context_directory [String, nil, :path, :parent] The context directory
# for tools loaded from this path. You can pass a directory path as a
# string, `:path` to denote the given path, `:parent` to denote the
# given path's parent directory, or `nil` to denote no context.
# Defaults to `:path`.
# @return [self]
#
# source://toys-core//lib/toys/cli.rb#384
def add_search_path(search_path, high_priority: T.unsafe(nil), context_directory: T.unsafe(nil)); end
# Walk up the directory hierarchy from the given start location, and add to
# the loader any config files and directories found.
#
# The main Toys executable uses this method to load tools from the current
# directory and its ancestors.
#
# @param start [String] The first directory to add. Defaults to the current
# working directory.
# @param terminate [Array<String>] Optional list of directories that should
# terminate the search. If the walk up the directory tree encounters
# one of these directories, the search is halted without checking the
# terminating directory.
# @param high_priority [Boolean] Add the configs at the head of the
# priority list rather than the tail.
# @return [self]
#
# source://toys-core//lib/toys/cli.rb#419
def add_search_path_hierarchy(start: T.unsafe(nil), terminate: T.unsafe(nil), high_priority: T.unsafe(nil)); end
# The initial logger level in this CLI, used as the level for verbosity 0.
# May be `nil`, indicating it will use the initial logger setting.
#
# @return [Integer, nil]
#
# source://toys-core//lib/toys/cli.rb#298
def base_level; end
# Make a clone with the same settings but no config blocks and no paths in
# the loader. This is sometimes useful for calling another tool that has to
# be loaded from a different configuration.
#
# @param opts [keywords] Any configuration arguments that should be
# modified from the original. See {#initialize} for a list of
# recognized keywords.
# @return [Toys::CLI]
# @yieldparam cli [Toys::CLI] If you pass a block, the new CLI is yielded
# to it so you can add paths and make other modifications.
#
# source://toys-core//lib/toys/cli.rb#237
def child(**opts); end
# The overall completion strategy for this CLI.
#
# @return [Toys::Completion::Base, Proc]
#
# source://toys-core//lib/toys/cli.rb#304
def completion; end
# The effective executable name used for usage text in this CLI.
#
# @return [String]
#
# source://toys-core//lib/toys/cli.rb#273
def executable_name; end
# The string of tool name delimiter characters (besides space).
#
# @return [String]
#
# source://toys-core//lib/toys/cli.rb#279
def extra_delimiters; end
# Prepare a tool to be run, but just execute the given block rather than
# performing a full run of the tool. This is intended for testing tools.
# Unlike {#run}, this does not catch errors and perform error handling.
#
# @param args [String...] Command line arguments specifying which tool to
# run and what arguments to pass to it. You may pass either a single
# array of strings, or a series of string arguments.
# @return [Object] The value returned from the block.
# @yieldparam context [Toys::Context] Yields the tool context.
#
# source://toys-core//lib/toys/cli.rb#480
def load_tool(*args); end
# The current loader for this CLI.
#
# @return [Toys::Loader]
#
# source://toys-core//lib/toys/cli.rb#267
def loader; end
# The global logger, if any.
#
# @return [Logger, nil]
#
# source://toys-core//lib/toys/cli.rb#285
def logger; end
# The logger factory.
#
# @return [Proc]
#
# source://toys-core//lib/toys/cli.rb#291
def logger_factory; end
# Run the CLI with the given command line arguments.
# Handles exceptions using the error handler.
#
# @param args [String...] Command line arguments specifying which tool to
# run and what arguments to pass to it. You may pass either a single
# array of strings, or a series of string arguments.
# @param verbosity [Integer] Initial verbosity. Default is 0.
# @param delegated_from [Toys::Context] The context from which this
# execution is delegated. Optional. Should be set only if this is a
# delegated execution.
# @return [Integer] The resulting process status code (i.e. 0 for success).
#
# source://toys-core//lib/toys/cli.rb#450
def run(*args, verbosity: T.unsafe(nil), delegated_from: T.unsafe(nil)); end
private
# source://toys-core//lib/toys/cli.rb#585
def build_context(tool, args, verbosity: T.unsafe(nil), delegated_from: T.unsafe(nil)); end
# source://toys-core//lib/toys/cli.rb#629
def build_executor(tool, context); end
# source://toys-core//lib/toys/cli.rb#665
def call_handler(context, handler, argument); end
# source://toys-core//lib/toys/cli.rb#610
def execute_tool(tool, context, &block); end
# source://toys-core//lib/toys/cli.rb#656
def handle_signal_by_tool(context, tool, exception); end
# @raise [ArgParsingError]
#
# source://toys-core//lib/toys/cli.rb#649
def handle_usage_errors(context, tool); end
# source://toys-core//lib/toys/cli.rb#674
def make_executor(middleware, context, next_executor); end
# source://toys-core//lib/toys/cli.rb#597
def make_run_handler(tool); end
class << self
# Returns a default Completion that simply uses the tool's completion.
#
# source://toys-core//lib/toys/cli.rb#576
def default_completion; end
# Returns a bare-bones error handler that takes simply reraises the
# error. If the original error (the cause of the {Toys::ContextualError})
# was a `SignalException` (or a subclass such as `Interrupted`), that
# `SignalException` itself is reraised so that the Ruby VM has a chance
# to handle it. Otherwise, for any other error, the
# {Toys::ContextualError} is reraised.
#
# @return [Proc]
#
# source://toys-core//lib/toys/cli.rb#551
def default_error_handler; end
# Returns a default logger factory that generates simple loggers that
# write to STDERR.
#
# @return [Proc]
#
# source://toys-core//lib/toys/cli.rb#564
def default_logger_factory; end
# Returns a default ModuleLookup for middleware that points at the
# StandardMiddleware module.
#
# @return [Toys::ModuleLookup]
#
# source://toys-core//lib/toys/cli.rb#528
def default_middleware_lookup; end
# Returns a default set of middleware that may be used as a starting
# point for a typical CLI. This set includes the following in order:
#
# * {Toys::StandardMiddleware::SetDefaultDescriptions} providing
# defaults for description fields.
# * {Toys::StandardMiddleware::ShowHelp} adding the `--help` flag and
# providing default behavior for namespaces.
# * {Toys::StandardMiddleware::HandleUsageErrors}
# * {Toys::StandardMiddleware::AddVerbosityFlags} adding the `--verbose`
# and `--quiet` flags for managing the logger level.
#
# @return [Array<Toys::Middleware::Spec>]
#
# source://toys-core//lib/toys/cli.rb#503
def default_middleware_stack; end
# Returns a default ModuleLookup for mixins that points at the
# StandardMixins module.
#
# @return [Toys::ModuleLookup]
#
# source://toys-core//lib/toys/cli.rb#518
def default_mixin_lookup; end
# Returns a default empty ModuleLookup for templates.
#
# @return [Toys::ModuleLookup]
#
# source://toys-core//lib/toys/cli.rb#537
def default_template_lookup; end
end
end
# @private
#
# source://toys-core//lib/toys-core.rb#120
Toys::CORE_LIB_PATH = T.let(T.unsafe(nil), String)
# Deprecated
#
# @private
#
# source://toys-core//lib/toys/core.rb#20
Toys::CORE_VERSION = T.let(T.unsafe(nil), String)
# Compatibility wrappers for older Ruby versions.
#
# @private
#
# source://toys-core//lib/toys/compat.rb#11
module Toys::Compat
class << self
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#113
def absolute_path?(path); end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#31
def allow_fork?; end
# @private
#
# source://toys-core//lib/toys/compat.rb#78
def dir_children(dir); end
# @private
#
# source://toys-core//lib/toys/compat.rb#65
def glob_in_dir(glob, dir); end
# @private
#
# source://toys-core//lib/toys/compat.rb#94
def instantiate(klass, args, kwargs, block); end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#16
def jruby?; end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#132
def method_defined_without_ancestors?(klass, name); end
# @private
#
# source://toys-core//lib/toys/compat.rb#54
def suggestions(word, list); end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#36
def supports_suggestions?; end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#21
def truffleruby?; end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/compat.rb#26
def windows?; end
end
end
# A Completion is a callable Proc that determines candidates for shell tab
# completion. You pass a {Toys::Completion::Context} object (which includes
# the current string fragment and other information) and it returns an array
# of candidates, represented by {Toys::Completion::Candidate} objects, for
# completing the fragment.
#
# A useful method here is the class method {Toys::Completion.create} which
# takes a variety of inputs and returns a suitable completion Proc.
#
# source://toys-core//lib/toys/completion.rb#14
module Toys::Completion
class << self
# Create a completion Proc from a variety of specification formats. The
# completion is constructed from the given specification object and/or the
# given block. Additionally, some completions can take a hash of options.
#
# Recognized specs include:
#
# * `:empty`: Returns the empty completion. Any block or options are
# ignored.
#
# * `:file_system`: Returns a completion that searches the current
# directory for file and directory names. You may also pass any of the
# options recognized by {Toys::Completion::FileSystem#initialize}. The
# block is ignored.
#
# * An **Array** of strings. Returns a completion that uses those values
# as candidates. You may also pass any of the options recognized by
# {Toys::Completion::Enum#initialize}. The block is ignored.
#
# * A **function**, either passed as a Proc (where the block is ignored)
# or as a block (if the spec is nil). The function must behave as a
# completion object, taking {Toys::Completion::Context} as the sole
# argument, and returning an array of {Toys::Completion::Candidate}.
#
# * `:default` and `nil` indicate the **default completion**. For this
# method, the default is the empty completion (i.e. these are synonyms
# for `:empty`). However, other completion resolution methods might
# have a different default.
#
# @param spec [Object] See the description for recognized values.
# @param options [Hash] Additional options to pass to the completion.
# @param block [Proc] See the description for recognized forms.
# @return [Toys::Completion::Base, Proc]
#
# source://toys-core//lib/toys/completion.rb#411
def create(spec = T.unsafe(nil), **options, &block); end
# Take the various ways to express a completion spec, and convert them to a
# canonical form expressed as a single object. This is called from the DSL
# DSL to generate a spec object that can be stored.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/completion.rb#444
def scalarize_spec(spec, options, block); end
end
end
# A base class that returns no completions.
#
# Completions *may* but do not need to subclass this base class. They
# merely need to duck-type `Proc` by implementing the `call` method.
#
# source://toys-core//lib/toys/completion.rb#218
class Toys::Completion::Base
# Returns candidates for the current completion.
# This default implementation returns an empty list.
#
# @param context [Toys::Completion::Context] The current completion
# context including the string fragment.
# @return [Array<Toys::Completion::Candidate>] An array of candidates
#
# source://toys-core//lib/toys/completion.rb#227
def call(context); end
end
# A candidate for completing a string fragment.
#
# A candidate includes a string representing the potential completed
# word, as well as a flag indicating whether it is a *partial* completion
# (i.e. a prefix that could still be added to) versus a *final* word.
# Generally, tab completion systems should add a trailing space after a
# final completion but not after a partial completion.
#
# source://toys-core//lib/toys/completion.rb#143
class Toys::Completion::Candidate
include ::Comparable
# Create a new candidate
#
# @param string [String] The candidate string
# @param partial [Boolean] Whether the candidate is partial. Defaults
# to `false`.
# @return [Candidate] a new instance of Candidate
#
# source://toys-core//lib/toys/completion.rb#152
def initialize(string, partial: T.unsafe(nil)); end
# @private
#
# source://toys-core//lib/toys/completion.rb#190
def <=>(other); end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/completion.rb#183
def eql?(other); end
# Determine whether the candidate is a final completion.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/completion.rb#176
def final?; end
# @private
#
# source://toys-core//lib/toys/completion.rb#197
def hash; end
# Determine whether the candidate is partial completion.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/completion.rb#168
def partial?; end
# Get the candidate string.
#
# @return [String]
#
# source://toys-core//lib/toys/completion.rb#161
def string; end
# Get the candidate string.
#
# @return [String]
#
# source://toys-core//lib/toys/completion.rb#161
def to_s; end
class << self
# Create an array of candidates given an array of strings.
#
# @param array [Array<String>]
# @return [Array<Toys::Completion::Candidate]] Array<Toys::Completion::Candidate]
#
# source://toys-core//lib/toys/completion.rb#207
def new_multi(array, partial: T.unsafe(nil)); end
end
end
# The context in which to determine completion candidates.
#
# source://toys-core//lib/toys/completion.rb#18
class Toys::Completion::Context
# Create a completion context
#
# @param cli [Toys::CLI] The CLI being run. Required.
# @param previous_words [Array<String>] Array of complete strings that
# appeared prior to the fragment to complete.
# @param fragment_prefix [String] A prefix in the fragment that does not
# participate in completion. (e.g. "key=")
# @param fragment [String] The string fragment to complete.
# @param params [Hash] Miscellaneous context data
# @return [Context] a new instance of Context
#
# source://toys-core//lib/toys/completion.rb#30
def initialize(cli:, previous_words: T.unsafe(nil), fragment_prefix: T.unsafe(nil), fragment: T.unsafe(nil), **params); end
# Get data for arbitrary key.
#
# @param key [Symbol]
# @return [Object]
#
# source://toys-core//lib/toys/completion.rb#84
def [](key); end
# Current ArgParser indicating the status of argument parsing up to
# this point.
#
# @return [Toys::ArgParser]
#
# source://toys-core//lib/toys/completion.rb#114
def arg_parser; end
# An array of complete arguments passed to the tool, prior to the
# fragment to complete.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/completion.rb#103
def args; end
# The CLI being run.
#
# @return [Toys::CLI]
#
# source://toys-core//lib/toys/completion.rb#59
def cli; end
# The current string fragment to complete
#
# @return [String]
#
# source://toys-core//lib/toys/completion.rb#77
def fragment; end
# A non-completed prefix for the current fragment.
#
# @return [String]
#
# source://toys-core//lib/toys/completion.rb#71
def fragment_prefix; end
# Get data for arbitrary key.
#
# @param key [Symbol]
# @return [Object]
#
# source://toys-core//lib/toys/completion.rb#84
def get(key); end
# @private
#
# source://toys-core//lib/toys/completion.rb#122
def inspect; end
# All previous words.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/completion.rb#65
def previous_words; end
# The tool being invoked, which should control the completion.
#
# @return [Toys::ToolDefinition]
#
# source://toys-core//lib/toys/completion.rb#93
def tool; end
# Create a new completion context with the given modifications.
#
# @param delta_params [Hash] Replace context data.
# @return [Toys::Completion::Context]
#
# source://toys-core//lib/toys/completion.rb#51
def with(**delta_params); end
private
# source://toys-core//lib/toys/completion.rb#129
def lookup_tool; end
end
# An instance of the empty completion that returns no candidates.
#
# @return [Toys:::Completion::Base]
#
# source://toys-core//lib/toys/completion.rb#375
Toys::Completion::EMPTY = T.let(T.unsafe(nil), Toys::Completion::Base)
# A Completion whose candidates come from a static list of strings.
#
# source://toys-core//lib/toys/completion.rb#331
class Toys::Completion::Enum < ::Toys::Completion::Base
# Create a completion from a list of values.
#
# @param values [Array<String>]
# @param prefix_constraint [String, Regexp] Constraint on the fragment
# prefix. Defaults to requiring the prefix be empty.
# @return [Enum] a new instance of Enum
#
# source://toys-core//lib/toys/completion.rb#339
def initialize(values, prefix_constraint: T.unsafe(nil)); end
# Returns candidates for the current completion.
#
# @param context [Toys::Completion::Context] the current completion
# context including the string fragment.
# @return [Array<Toys::Completion::Candidate>] an array of candidates
#
# source://toys-core//lib/toys/completion.rb#364
def call(context); end
# Constraint on the fragment prefix.
#
# @return [String, Regexp]
#
# source://toys-core//lib/toys/completion.rb#355
def prefix_constraint; end
# The array of completion candidates.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/completion.rb#349
def values; end
end
# A Completion that returns candidates from the local file system.
#
# source://toys-core//lib/toys/completion.rb#235
class Toys::Completion::FileSystem < ::Toys::Completion::Base
# Create a completion that gets candidates from names in the local file
# system.
#
# @param cwd [String] Working directory (defaults to the current dir).
# @param omit_files [Boolean] Omit files from candidates
# @param omit_directories [Boolean] Omit directories from candidates
# @param prefix_constraint [String, Regexp] Constraint on the fragment
# prefix. Defaults to requiring the prefix be empty.
# @return [FileSystem] a new instance of FileSystem
#
# source://toys-core//lib/toys/completion.rb#246
def initialize(cwd: T.unsafe(nil), omit_files: T.unsafe(nil), omit_directories: T.unsafe(nil), prefix_constraint: T.unsafe(nil)); end
# Returns candidates for the current completion.
#
# @param context [Toys::Completion::Context] the current completion
# context including the string fragment.
# @return [Array<Toys::Completion::Candidate>] an array of candidates
#
# source://toys-core//lib/toys/completion.rb#285
def call(context); end
# Path to the starting directory.
#
# @return [String]
#
# source://toys-core//lib/toys/completion.rb#276
def cwd; end
# Whether directories are included in the completion candidates.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/completion.rb#264
def include_directories; end
# Whether files are included in the completion candidates.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/completion.rb#258
def include_files; end
# Constraint on the fragment prefix.
#
# @return [String, Regexp]
#
# source://toys-core//lib/toys/completion.rb#270
def prefix_constraint; end
private
# source://toys-core//lib/toys/completion.rb#309
def generate_candidates(children, prefix, dir); end
end
# This is the base class for tool execution. It represents `self` when your
# tool's methods (such as `run`) are called, and it defines the methods that
# can be called by your tool (such as {#logger} and {#exit}.)
#
# This class also manages the "data" available to your tool when it runs.
# This data is a hash of key-value pairs. It consists of values set by flags
# and arguments defined by the tool, plus some "well-known" values such as
# the logger and verbosity level.
#
# You can obtain a value from the data using the {Toys::Context#get} method.
# Additionally, convenience methods are provided for many of the well-known
# keys. For instance, you can call {Toys::Context#verbosity} to obtain the
# value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
# positional arguments that store their data here will also typically
# generate convenience methods. For example, an argument with key `:abc` will
# add a method called `abc` that you can call to get the value.
#
# By convention, flags and arguments defined by your tool should use strings
# or symbols as keys. Keys that are not strings or symbols should either be
# well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
# for internal private information needed by middleware and mixins. The
# module {Toys::Context::Key} defines a number of well-known keys as
# constants.
#
# source://toys-core//lib/toys/context.rb#29
class Toys::Context
# Create a Context object. Applications generally will not need to create
# these objects directly; they are created by the tool when it is preparing
# for execution.
#
# @param data [Hash]
# @private This interface is internal and subject to change without warning.
# @return [Context] a new instance of Context
#
# source://toys-core//lib/toys/context.rb#388
def initialize(data); end
# Fetch an option or other piece of data by key.
#
# If the `get` method is overridden by the tool, you can still access it
# using the name `__get` or the `[]` operator.
#
# @param key [Symbol]
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#270
def [](key); end
# Set an option or other piece of context data by key.
#
# @param key [Symbol]
# @param value [Object]
#
# source://toys-core//lib/toys/context.rb#282
def []=(key, value); end
# The raw arguments passed to the tool, as an array of strings.
# This does not include the tool name itself.
#
# This is a convenience getter for {Toys::Context::Key::ARGS}.
#
# If the `args` method is overridden by the tool, you can still access it
# using the name `__args`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/context.rb#147
def __args; end
# The currently running CLI.
#
# This is a convenience getter for {Toys::Context::Key::CLI}.
#
# If the `cli` method is overridden by the tool, you can still access it
# using the name `__cli`.
#
# @return [Toys::CLI]
#
# source://toys-core//lib/toys/context.rb#162
def __cli; end
# 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.
#
# This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
#
# If the `context_directory` method is overridden by the tool, you can
# still access it using the name `__context_directory`.
#
# @return [String] Context directory path
# @return [nil] if there is no context.
#
# source://toys-core//lib/toys/context.rb#181
def __context_directory; end
# Exit immediately with the given status code.
#
# If the `exit` method is overridden by the tool, you can still access it
# using the name `__exit` or by calling {Context.exit}.
#
# @param code [Integer] The status code, which should be 0 for no error,
# or nonzero for an error condition. Default is 0.
# @return [void]
#
# source://toys-core//lib/toys/context.rb#361
def __exit(code = T.unsafe(nil)); end
# Find the given data file or directory in this tool's search path.
#
# If the `find_data` method is overridden by the tool, you can still access
# it using the name `__find_data`.
#
# @param path [String] The path to find
# @param type [nil, :file, :directory] Type of file system object to find,
# or nil to return any type.
# @return [String] Absolute path of the result
# @return [nil] if the data was not found.
#
# source://toys-core//lib/toys/context.rb#346
def __find_data(path, type: T.unsafe(nil)); end
# Fetch an option or other piece of data by key.
#
# If the `get` method is overridden by the tool, you can still access it
# using the name `__get` or the `[]` operator.
#
# @param key [Symbol]
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#270
def __get(key); end
# The logger for this execution.
#
# This is a convenience getter for {Toys::Context::Key::LOGGER}.
#
# If the `logger` method is overridden by the tool, you can still access it
# using the name `__logger`.
#
# @return [Logger]
#
# source://toys-core//lib/toys/context.rb#196
def __logger; end
# The subset of the context that uses string or symbol keys. By convention,
# this includes keys that are set by tool flags and arguments, but does not
# include well-known context values such as verbosity or private context
# values used by middleware or mixins.
#
# If the `options` method is overridden by the tool, you can still access
# it using the name `__options`.
#
# @return [Hash]
#
# source://toys-core//lib/toys/context.rb#326
def __options; end
# Set one or more options or other context data by key.
#
# If the `set` method is overridden by the tool, you can still access it
# using the name `__set`.
#
# @overload set
# @overload set
# @return [self]
#
# source://toys-core//lib/toys/context.rb#305
def __set(key, value = T.unsafe(nil)); end
# The full name of the tool being executed, as an array of strings.
#
# This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
#
# If the `tool_name` method is overridden by the tool, you can still access
# it using the name `__tool_name`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/context.rb#211
def __tool_name; end
# The source of the tool being executed.
#
# This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
#
# If the `tool_source` method is overridden by the tool, you can still
# access it using the name `__tool_source`.
#
# @return [Toys::SourceInfo]
#
# source://toys-core//lib/toys/context.rb#226
def __tool_source; end
# The (possibly empty) array of errors detected during argument parsing.
#
# This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
#
# If the `usage_errors` method is overridden by the tool, you can still
# access it using the name `__usage_errors`.
#
# @return [Array<Toys::ArgParser::UsageError>]
#
# source://toys-core//lib/toys/context.rb#241
def __usage_errors; end
# The current verbosity setting as an integer.
#
# This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
#
# If the `verbosity` method is overridden by the tool, you can still access
# it using the name `__verbosity`.
#
# @return [Integer]
#
# source://toys-core//lib/toys/context.rb#256
def __verbosity; end
# The raw arguments passed to the tool, as an array of strings.
# This does not include the tool name itself.
#
# This is a convenience getter for {Toys::Context::Key::ARGS}.
#
# If the `args` method is overridden by the tool, you can still access it
# using the name `__args`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/context.rb#147
def args; end
# The currently running CLI.
#
# This is a convenience getter for {Toys::Context::Key::CLI}.
#
# If the `cli` method is overridden by the tool, you can still access it
# using the name `__cli`.
#
# @return [Toys::CLI]
#
# source://toys-core//lib/toys/context.rb#162
def cli; end
# 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.
#
# This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
#
# If the `context_directory` method is overridden by the tool, you can
# still access it using the name `__context_directory`.
#
# @return [String] Context directory path
# @return [nil] if there is no context.
#
# source://toys-core//lib/toys/context.rb#181
def context_directory; end
# Exit immediately with the given status code.
#
# If the `exit` method is overridden by the tool, you can still access it
# using the name `__exit` or by calling {Context.exit}.
#
# @param code [Integer] The status code, which should be 0 for no error,
# or nonzero for an error condition. Default is 0.
# @return [void]
#
# source://toys-core//lib/toys/context.rb#361
def exit(code = T.unsafe(nil)); end
# Find the given data file or directory in this tool's search path.
#
# If the `find_data` method is overridden by the tool, you can still access
# it using the name `__find_data`.
#
# @param path [String] The path to find
# @param type [nil, :file, :directory] Type of file system object to find,
# or nil to return any type.
# @return [String] Absolute path of the result
# @return [nil] if the data was not found.
#
# source://toys-core//lib/toys/context.rb#346
def find_data(path, type: T.unsafe(nil)); end
# Fetch an option or other piece of data by key.
#
# If the `get` method is overridden by the tool, you can still access it
# using the name `__get` or the `[]` operator.
#
# @param key [Symbol]
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#270
def get(key); end
# Include the tool name in the object inspection dump.
#
# @private
#
# source://toys-core//lib/toys/context.rb#397
def inspect; end
# The logger for this execution.
#
# This is a convenience getter for {Toys::Context::Key::LOGGER}.
#
# If the `logger` method is overridden by the tool, you can still access it
# using the name `__logger`.
#
# @return [Logger]
#
# source://toys-core//lib/toys/context.rb#196
def logger; end
# The subset of the context that uses string or symbol keys. By convention,
# this includes keys that are set by tool flags and arguments, but does not
# include well-known context values such as verbosity or private context
# values used by middleware or mixins.
#
# If the `options` method is overridden by the tool, you can still access
# it using the name `__options`.
#
# @return [Hash]
#
# source://toys-core//lib/toys/context.rb#326
def options; end
# Set one or more options or other context data by key.
#
# If the `set` method is overridden by the tool, you can still access it
# using the name `__set`.
#
# @overload set
# @overload set
# @return [self]
#
# source://toys-core//lib/toys/context.rb#305
def set(key, value = T.unsafe(nil)); end
# The full name of the tool being executed, as an array of strings.
#
# This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
#
# If the `tool_name` method is overridden by the tool, you can still access
# it using the name `__tool_name`.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/context.rb#211
def tool_name; end
# The source of the tool being executed.
#
# This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
#
# If the `tool_source` method is overridden by the tool, you can still
# access it using the name `__tool_source`.
#
# @return [Toys::SourceInfo]
#
# source://toys-core//lib/toys/context.rb#226
def tool_source; end
# The (possibly empty) array of errors detected during argument parsing.
#
# This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
#
# If the `usage_errors` method is overridden by the tool, you can still
# access it using the name `__usage_errors`.
#
# @return [Array<Toys::ArgParser::UsageError>]
#
# source://toys-core//lib/toys/context.rb#241
def usage_errors; end
# The current verbosity setting as an integer.
#
# This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
#
# If the `verbosity` method is overridden by the tool, you can still access
# it using the name `__verbosity`.
#
# @return [Integer]
#
# source://toys-core//lib/toys/context.rb#256
def verbosity; end
class << self
# Exit immediately with the given status code. This class method can be
# called if the instance method is or could be replaced by the tool.
#
# @param code [Integer] The status code, which should be 0 for no error,
# or nonzero for an error condition. Default is 0.
# @return [void]
#
# source://toys-core//lib/toys/context.rb#374
def exit(code = T.unsafe(nil)); end
end
end
# Well-known context keys.
#
# This module is mixed into the runtime context. This means you can
# reference any of these constants directly from your run method.
#
# ### Example
#
# tool "my-name" do
# def run
# # TOOL_NAME is available here.
# puts "My name is #{get(TOOL_NAME)}"
# end
# end
#
# source://toys-core//lib/toys/context.rb#45
module Toys::Context::Key; end
# Context key for the argument list passed to the current tool. Value is
# an array of strings.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#51
Toys::Context::Key::ARGS = T.let(T.unsafe(nil), Object)
# Context key for the currently running {Toys::CLI}. You can use the
# value to run other tools from your tool by calling {Toys::CLI#run}.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#58
Toys::Context::Key::CLI = T.let(T.unsafe(nil), Object)
# Context key for the context directory path. The value is a string
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#64
Toys::Context::Key::CONTEXT_DIRECTORY = T.let(T.unsafe(nil), Object)
# Context key for the context from which the current call was delegated.
# The value is either another context object, or `nil` if the current
# call is not delegated.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#72
Toys::Context::Key::DELEGATED_FROM = T.let(T.unsafe(nil), Object)
# Context key for the active `Logger` object.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#78
Toys::Context::Key::LOGGER = T.let(T.unsafe(nil), Object)
# Context key for the {Toys::ToolDefinition} object being executed.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#84
Toys::Context::Key::TOOL = T.let(T.unsafe(nil), Object)
# Context key for the full name of the tool being executed. Value is an
# array of strings.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#91
Toys::Context::Key::TOOL_NAME = T.let(T.unsafe(nil), Object)
# Context key for the {Toys::SourceInfo} describing the source of this
# tool.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#98
Toys::Context::Key::TOOL_SOURCE = T.let(T.unsafe(nil), Object)
# Context key for all unmatched args in order. The value is an array of
# strings.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#105
Toys::Context::Key::UNMATCHED_ARGS = T.let(T.unsafe(nil), Object)
# Context key for unmatched flags. The value is an array of strings.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#111
Toys::Context::Key::UNMATCHED_FLAGS = T.let(T.unsafe(nil), Object)
# Context key for unmatched positional args. The value is an array of
# strings.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#118
Toys::Context::Key::UNMATCHED_POSITIONAL = T.let(T.unsafe(nil), Object)
# Context key for the list of usage errors raised. The value is an array
# of {Toys::ArgParser::UsageError}.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#125
Toys::Context::Key::USAGE_ERRORS = T.let(T.unsafe(nil), Object)
# Context key for the verbosity value. The value is an integer defaulting
# to 0, with higher values meaning more verbose and lower meaning more
# quiet.
#
# @return [Object]
#
# source://toys-core//lib/toys/context.rb#133
Toys::Context::Key::VERBOSITY = T.let(T.unsafe(nil), Object)
# A wrapper exception used to provide user-oriented context for an error
# thrown during tool execution.
#
# source://toys-core//lib/toys/errors.rb#46
class Toys::ContextualError < ::StandardError
# Construct a ContextualError. This exception type is thrown from
# {ContextualError.capture} and {ContextualError.capture_path} and should
# not be constructed directly.
#
# @private This interface is internal and subject to change without warning.
# @return [ContextualError] a new instance of ContextualError
#
# source://toys-core//lib/toys/errors.rb#54
def initialize(cause, banner, config_path: T.unsafe(nil), config_line: T.unsafe(nil), tool_name: T.unsafe(nil), tool_args: T.unsafe(nil)); end
# An overall banner message
#
# @return [String]
#
# source://toys-core//lib/toys/errors.rb#77
def banner; end
# The underlying exception
#
# @return [::StandardError]
#
# source://toys-core//lib/toys/errors.rb#71
def cause; end
# The line number in the toys config file in which the error was detected
#
# @return [Integer]
#
# source://toys-core//lib/toys/errors.rb#89
def config_line; end
# @private
#
# source://toys-core//lib/toys/errors.rb#111
def config_line=(_arg0); end
# The path to the toys config file in which the error was detected
#
# @return [String]
#
# source://toys-core//lib/toys/errors.rb#83
def config_path; end
# @private
#
# source://toys-core//lib/toys/errors.rb#106
def config_path=(_arg0); end
# The arguments passed to the tool that was running when the error occurred
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/errors.rb#101
def tool_args; end
# @private
#
# source://toys-core//lib/toys/errors.rb#121
def tool_args=(_arg0); end
# The full name of the tool that was running when the error occurred
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/errors.rb#95
def tool_name; end
# @private
#
# source://toys-core//lib/toys/errors.rb#116
def tool_name=(_arg0); end
class << self
# Execute the given block, and wrap any exceptions thrown with a
# ContextualError.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/errors.rb#156
def capture(banner, **opts); end
# Execute the given block, and wrap any exceptions thrown with a
# ContextualError. This is intended for loading a config file from the
# given path, and wraps any Ruby parsing errors.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/errors.rb#131
def capture_path(banner, path, **opts); end
private
# source://toys-core//lib/toys/errors.rb#173
def add_config_path_if_missing(error, path); end
# source://toys-core//lib/toys/errors.rb#167
def add_fields_if_missing(error, opts); end
end
end
# The core Toys classes.
#
# source://toys-core//lib/toys/core.rb#7
module Toys::Core; end
# Current version of Toys core.
#
# @return [String]
#
# source://toys-core//lib/toys/core.rb#12
Toys::Core::VERSION = T.let(T.unsafe(nil), String)
# Namespace for DSL classes. These classes provide the directives that can be
# used in configuration files.
#
# DSL directives that can appear at the top level of Toys files and tool
# blocks are defined by the {Toys::DSL::Tool} module.
#
# Directives that can appear within a block passed to {Toys::DSL::Tool#flag}
# are defined by the {Toys::DSL::Flag} class.
#
# Directives that can appear within a {Toys::DSL::Tool#flag_group} block or
# any of its related directives, are defined by the {Toys::DSL::FlagGroup}
# class.
#
# Directives that can appear within a {Toys::DSL::Tool#required_arg},
# {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args} block,
# are defined by the {Toys::DSL::PositionalArg} class.
#
# source://toys-core//lib/toys-core.rb#61
module Toys::DSL; end
# DSL for a flag definition block. Lets you set flag attributes in a block
# instead of a long series of keyword arguments.
#
# These directives are available inside a block passed to
# {Toys::DSL::Tool#flag}.
#
# ### Example
#
# tool "mytool" do
# flag :value do
# # The directives in here are defined by this class
# flags "--value=VAL"
# accept Integer
# desc "An integer value"
# end
# # ...
# end
#
# source://toys-core//lib/toys/dsl/flag.rb#24
class Toys::DSL::Flag
# Called only from DSL::Tool
#
# @private
# @return [Flag] a new instance of Flag
#
# source://toys-core//lib/toys/dsl/flag.rb#306
def initialize(flags, acceptor, default, handler, flag_completion, value_completion, report_collisions, group, desc, long_desc, display_name, method_flag); end
# @private
#
# source://toys-core//lib/toys/dsl/flag.rb#325
def _add_to(tool, key); end
# @private
#
# source://toys-core//lib/toys/dsl/flag.rb#336
def _get_add_method; end
# Set the acceptor for this flag's values.
# You can pass either the string name of an acceptor defined in this tool
# or any of its ancestors, or any other specification recognized by
# {Toys::Acceptor.create}.
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#100
def accept(spec = T.unsafe(nil), **options, &block); end
# Specify whether to add a method for this flag.
#
# Recognized values are true to force creation of a method, false to
# disable method creation, and nil for the default behavior. The default
# checks the name and adds a method if the name is a symbol representing
# a legal method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
#
# @param value [true, false, nil]
#
# source://toys-core//lib/toys/dsl/flag.rb#290
def add_method(value); end
# Set the shell completion strategy for flag names.
# You can pass one of the following:
#
# * The string name of a completion defined in this tool or any of its
# ancestors.
# * A hash of options to pass to the constructor of
# {Toys::Flag::DefaultCompletion}.
# * `nil` or `:default` to select the standard completion strategy
# (which is {Toys::Flag::DefaultCompletion} with no extra options).
# * Any other specification recognized by {Toys::Completion.create}.
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#156
def complete_flags(spec = T.unsafe(nil), **options, &block); end
# Set the shell completion strategy for flag values.
# You can pass either the string name of a completion defined in this
# tool or any of its ancestors, or any other specification recognized by
# {Toys::Completion.create}.
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#172
def complete_values(spec = T.unsafe(nil), **options, &block); end
# Set the default value.
#
# @param default [Object]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#111
def default(default); end
# Set the short description for the current flag. The short description
# is displayed with the flag in online help.
#
# The description is a {Toys::WrappableString}, which may be word-wrapped
# when displayed in a help screen. You may pass a {Toys::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."]
#
# @param desc [String, Array<String>, Toys::WrappableString]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#221
def desc(desc); end
# Set the display name for this flag. This may be used in help text and
# error messages.
#
# @param display_name [String]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#273
def display_name(display_name); end
# Add flags in OptionParser format. This may be called multiple times,
# and the results are cumulative.
#
# Following are examples of valid syntax.
#
# * `-a` : A short boolean switch. When this appears as an argument,
# the value is set to `true`.
# * `--abc` : A long boolean switch. When this appears as an argument,
# the value is set to `true`.
# * `-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 to `true`. 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 to `true`. (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 to `true`. 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 to `true`. (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 to `true`, and `--no-abc` which sets the falue to `false`.
#
# @param flags [String...]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#84
def flags(*flags); end
# Set the group. A group may be set by name or group object. Setting
# `nil` selects the default group.
#
# @param group [String, Symbol, Toys::FlagGroup, nil]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#261
def group(group); end
# Set the optional handler for setting/updating the value when a flag is
# parsed. A handler should be a Proc taking two arguments, the new given
# value and the previous value, and it should return the new value that
# should be set. You may pass the handler as a Proc (or an object
# responding to the `call` method) or you may pass a block.
#
# You can also pass one of the special values `:set` or `:push` as the
# handler. The `:set` handler replaces the previous value (equivalent to
# `-> (val, _prev) { val }`.) The `:push` handler expects the previous
# value to be an array and pushes the given value onto it; it should be
# combined with setting the default value to `[]` and is intended for
# "multi-valued" flags.
#
# @param handler [Proc, :set, :push]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#134
def handler(handler = T.unsafe(nil), &block); end
# Add to the long description for the current flag. The long description
# is displayed with the flag in online help. 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."
#
# @param long_desc [String, Array<String>, Toys::WrappableString...]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#249
def long_desc(*long_desc); end
# Set whether to raise an exception if a flag is requested that is
# already in use or marked as disabled.
#
# @param setting [Boolean]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag.rb#184
def report_collisions(setting); end
end
# DSL for a flag group definition block. Lets you create flags in a group.
#
# These directives are available inside a block passed to
# {Toys::DSL::Tool#flag_group}, {Toys::DSL::Tool#all_required},
# {Toys::DSL::Tool#at_most_one}, {Toys::DSL::Tool#at_least_one}, or
# {Toys::DSL::Tool#exactly_one}.
#
# ### Example
#
# tool "login" do
# all_required do
# # The directives in here are defined by this class
# flag :username, "--username=VAL", desc: "Set username (required)"
# flag :password, "--password=VAL", desc: "Set password (required)"
# end
# # ...
# end
#
# source://toys-core//lib/toys/dsl/flag_group.rb#24
class Toys::DSL::FlagGroup
# Called only from DSL::Tool.
#
# @private
# @return [FlagGroup] a new instance of FlagGroup
#
# source://toys-core//lib/toys/dsl/flag_group.rb#280
def initialize(tool_dsl, tool, flag_group); end
# Set the short description for the current flag group. The short
# description is displayed as the group title in online help.
#
# The description is a {Toys::WrappableString}, which may be word-wrapped
# when displayed in a help screen. You may pass a {Toys::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."]
#
# @param desc [String, Array<String>, Toys::WrappableString]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag_group.rb#242
def desc(desc); end
# Add a flag to the current group. 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 {Toys::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 {Toys::DSL::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 to `true`.
# * `--abc` : A long boolean switch. When this appears as an argument,
# the value is set to `true`.
# * `-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 to `true`. 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 to `true`. (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 to `true`. 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 to `true`. (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 to `true`, and `--no-abc` which sets the falue to `false`.
#
# ### 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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param flags [String...] The flags in OptionParser format.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, or one of the default acceptors provided by OptionParser.
# Optional. If not specified, accepts any value as a string.
# @param default [Object] The default value. This is the value that will
# be set in the context if this flag is not provided on the command
# line. Defaults to `nil`.
# @param handler [Proc, nil, :set, :push] An optional handler for
# setting/updating the value. A handler is a proc taking two
# arguments, the given value and the previous value, returning the
# new value that should be set. You may also specify a predefined
# named handler. The `:set` handler (the default) replaces the
# previous value (effectively `-> (val, _prev) { val }`). The
# `:push` handler expects the previous value to be an array and
# pushes the given value onto it; it should be combined with setting
# `default: []` and is intended for "multi-valued" flags.
# @param complete_flags [Object] A specifier for shell tab completion
# for flag names associated with this flag. By default, a
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
# names as completion candidates. To customize completion, set this
# to the name of a previously defined completion, a hash of options
# to pass to the constructor for {Toys::Flag::DefaultCompletion}, or
# any other spec recognized by {Toys::Completion.create}.
# @param complete_values [Object] A specifier for shell tab completion
# for flag values associated with this flag. This is the empty
# completion by default. To customize completion, set this to the
# name of a previously defined completion, or any spec recognized by
# {Toys::Completion.create}.
# @param report_collisions [Boolean] Raise an exception if a flag is
# requested that is already in use or marked as unusable. Default is
# true.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param display_name [String] A display name for this flag, used in help
# text and error messages.
# @param add_method [true, false, nil] Whether to add a method for this
# flag. If omitted or set to nil, uses the default behavior, which
# adds the method if the key is a symbol representing a legal method
# name that starts with a letter and does not override any public
# method in the Ruby Object class or collide with any method directly
# defined in the tool class.
# @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
# directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag_group.rb#194
def flag(key, *flags, accept: T.unsafe(nil), default: T.unsafe(nil), handler: T.unsafe(nil), complete_flags: T.unsafe(nil), complete_values: T.unsafe(nil), report_collisions: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), display_name: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# Add to the long description for the current flag group. The long
# description is displayed with the flag group in online help. 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."
#
# @param long_desc [String, Array<String>, Toys::WrappableString...]
# @return [self]
#
# source://toys-core//lib/toys/dsl/flag_group.rb#270
def long_desc(*long_desc); end
end
# Internal utility calls used by the DSL.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#10
module Toys::DSL::Internal
class << self
# Called by the DSL implementation to analyze the name of a new tool
# definition in context.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#85
def analyze_name(tool_class, words); end
# Called by the Tool base class to set config values for a subclass.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#166
def configure_class(tool_class, given_name = T.unsafe(nil)); end
# Called by the DSL implementation to get, and optionally activate, the
# current tool.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#57
def current_tool(tool_class, activate); end
# Called by the DSL implementation to load a long description from a
# file.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#146
def load_long_desc_file(path); end
# Called by the DSL implementation to add a getter to the tool class.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#102
def maybe_add_getter(tool_class, key, force); end
# Called by the Loader and InputFile to prepare a tool class for running
# the DSL.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#26
def prepare(tool_class, words, priority, remaining_words, source, loader); end
# Called by the DSL implementation to find a named mixin.
#
# @private
# @raise [ToolDefinitionError]
#
# source://toys-core//lib/toys/dsl/internal.rb#126
def resolve_mixin(mixin, cur_tool, loader); end
# Called by the Tool base class to add the DSL to a subclass.
#
# @private
#
# source://toys-core//lib/toys/dsl/internal.rb#197
def setup_class_dsl(tool_class); end
private
# source://toys-core//lib/toys/dsl/internal.rb#207
def class_name_to_tool_name(class_name); end
# source://toys-core//lib/toys/dsl/internal.rb#226
def current_source_from_context; end
# source://toys-core//lib/toys/dsl/internal.rb#213
def parent_from_mod_name_segments(mod_names); end
end
end
# @private A list of method names to avoid using as getters
#
# source://toys-core//lib/toys/dsl/internal.rb#14
Toys::DSL::Internal::AVOID_GETTERS = T.let(T.unsafe(nil), Hash)
# DSL for an arg definition block. Lets you set arg attributes in a block
# instead of a long series of keyword arguments.
#
# These directives are available inside a block passed to
# {Toys::DSL::Tool#required_arg}, {Toys::DSL::Tool#optional_arg}, or
# {Toys::DSL::Tool#remaining_args}.
#
# ### Example
#
# tool "mytool" do
# optional_arg :value do
# # The directives in here are defined by this class
# accept Integer
# desc "An integer value"
# end
# # ...
# end
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#24
class Toys::DSL::PositionalArg
# Called only from DSL::Tool
#
# @private
# @return [PositionalArg] a new instance of PositionalArg
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#172
def initialize(acceptor, default, completion, display_name, desc, long_desc, method_flag); end
# @private
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#194
def _add_optional_to(tool, key); end
# @private
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#185
def _add_required_to(tool, key); end
# @private
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#212
def _get_add_method; end
# @private
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#203
def _set_remaining_on(tool, key); end
# Set the acceptor for this argument's values.
# You can pass either the string name of an acceptor defined in this tool
# or any of its ancestors, or any other specification recognized by
# {Toys::Acceptor.create}.
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#36
def accept(spec = T.unsafe(nil), **options, &block); end
# Specify whether to add a method for this argument.
#
# Recognized values are true to force creation of a method, false to
# disable method creation, and nil for the default behavior. The default
# checks the name and adds a method if the name is a symbol representing
# a legal method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
#
# @param value [true, false, nil]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#156
def add_method(value); end
# Set the shell completion strategy for arg values.
# You can pass either the string name of a completion defined in this
# tool or any of its ancestors, or any other specification recognized by
# {Toys::Completion.create}.
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#63
def complete(spec = T.unsafe(nil), **options, &block); end
# Set the default value.
#
# @param default [Object]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#47
def default(default); end
# Set the short description for the current positional argument. The
# short description is displayed with the argument in online help.
#
# The description is a {Toys::WrappableString}, which may be word-wrapped
# when displayed in a help screen. You may pass a {Toys::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."]
#
# @param desc [String, Array<String>, Toys::WrappableString]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#111
def desc(desc); end
# Set the name of this arg as it appears in help screens.
#
# @param display_name [String]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#74
def display_name(display_name); end
# Add to the long description for the current positional argument. The
# long description is displayed with the argument in online help. 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."
#
# @param long_desc [String, Array<String>, Toys::WrappableString...]
# @return [self]
#
# source://toys-core//lib/toys/dsl/positional_arg.rb#139
def long_desc(*long_desc); end
end
# This module 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
#
# The DSL directives `tool`, `desc`, `optional_arg`, and others are defined
# in this module.
#
# Now you can execute it using:
#
# toys greet
#
# or try:
#
# toys greet rubyists
#
# source://toys-core//lib/toys/dsl/tool.rb#39
module Toys::DSL::Tool
# 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 uses the acceptor 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
#
# @param name [String] The acceptor name.
# @param spec [Object] See the description for recognized values.
# @param type_desc [String] Type description string, shown in help.
# Defaults to the acceptor name.
# @param block [Proc] See the description for recognized forms.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#105
def acceptor(name, spec = T.unsafe(nil), type_desc: T.unsafe(nil), &block); end
# Create an alias, representing an "alternate name" for a tool.
#
# Note: This is functionally equivalent to creating a tool with the
# `:delegate_relative` option. As such, `alias_tool` is considered
# deprecated.
#
# ### 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"
# # Note: the following is preferred over alias_tool:
# # tool "t", delegate_relative: "test"
#
# @deprecated Use {#tool} and pass `:delegate_relative` instead
# @param word [String] The name of the alias
# @param target [String, Array<String>] Relative path to the target of the
# alias. This path may be given as an array of strings, or a single
# string possibly delimited by path separators.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#368
def alias_tool(word, target); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#685
def all_required(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#772
def at_least_one(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#772
def at_least_one_required(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#728
def at_most_one(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#728
def at_most_one_required(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
# {Toys::ToolDefinition::DefaultCompletion}.
# * `nil` or `:default` to select the standard completion strategy
# (which is {Toys::ToolDefinition::DefaultCompletion} with no extra
# options).
# * Any other specification recognized by {Toys::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
#
# @param spec [Object]
# @param options [Hash]
# @param block [Proc]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1444
def complete_tool_args(spec = T.unsafe(nil), **options, &block); end
# 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 {Toys::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
#
# @param name [String] Name of the completion
# @param spec [Object] See the description for recognized values.
# @param options [Hash] Additional options to pass to the completion.
# @param block [Proc] See the description for recognized forms.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#259
def completion(name, spec = T.unsafe(nil), **options, &block); end
# 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.
#
# @return [String] Context directory path
# @return [nil] if there is no context.
#
# source://toys-core//lib/toys/dsl/tool.rb#1703
def context_directory; end
# Return the current tool config. This object can be queried to determine
# such information as the name, but it should not be altered.
#
# @return [Toys::ToolDefinition]
#
# source://toys-core//lib/toys/dsl/tool.rb#1714
def current_tool; end
# Causes the current tool to delegate to another tool, specified by the
# full tool name. 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
#
# @param target [String, Array<String>] The full path to the delegate
# tool. This path may be given as an array of strings, or a single
# string possibly delimited by path separators.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#399
def delegate_to(target); end
# 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 {Toys::WrappableString}, which may be word-wrapped
# when displayed in a help screen. You may pass a {Toys::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."]
#
# @param str [Toys::WrappableString, String, Array<String>]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#546
def desc(str); end
# 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 {Toys::Context#args}.
#
# This directive is mutually exclusive with any of the directives that
# declare arguments or flags.
#
# ### Example
#
# tool "mytool" do
# disable_argument_parsing
# def run
# puts "Arguments passed: #{args}"
# end
# end
#
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1378
def disable_argument_parsing; end
# 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
#
# @param flags [String...] The flags to disable
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1405
def disable_flag(*flags); end
# 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.
#
# @param state [Boolean]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1336
def enforce_flags_before_args(state = T.unsafe(nil)); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#816
def exactly_one(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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
#
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#816
def exactly_one_required(desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# 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, message)
# @name = name
# @message = message
# end
# attr_reader :name, :message
# expansion do |template|
# tool template.name do
# to_run do
# puts template.message
# end
# end
# end
# end
#
# expand "hello-generator", "mytool", "mytool is running!"
#
# @param template_class [Class, String, Symbol] The template, either as a
# class or a well-known name.
# @param args [Object...] Template arguments
# @return [self]
# @yield [template]
#
# source://toys-core//lib/toys/dsl/tool.rb#494
def expand(template_class, *args, **kwargs); end
# 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
#
# @param path [String] The path to find
# @param type [nil, :file, :directory] Type of file system object to find.
# Default is `nil`, indicating any type.
# @return [String] Absolute path of the data.
# @return [nil] if the given data path is not found.
#
# source://toys-core//lib/toys/dsl/tool.rb#1690
def find_data(path, type: T.unsafe(nil)); end
# 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 {Toys::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 {Toys::DSL::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 to `true`.
# * `--abc` : A long boolean switch. When this appears as an argument,
# the value is set to `true`.
# * `-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 to `true`. 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 to `true`. (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 to `true`. 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 to `true`. (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 to `true`, and `--no-abc` which sets the falue to `false`.
#
# ### 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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param flags [String...] The flags in OptionParser format.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param default [Object] The default value. This is the value that will
# be set in the context if this flag is not provided on the command
# line. Defaults to `nil`.
# @param handler [Proc, nil, :set, :push] An optional handler for
# setting/updating the value. A handler is a proc taking two
# arguments, the given value and the previous value, returning the
# new value that should be set. You may also specify a predefined
# named handler. The `:set` handler (the default) replaces the
# previous value (effectively `-> (val, _prev) { val }`). The
# `:push` handler expects the previous value to be an array and
# pushes the given value onto it; it should be combined with setting
# `default: []` and is intended for "multi-valued" flags.
# @param complete_flags [Object] A specifier for shell tab completion
# for flag names associated with this flag. By default, a
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
# names as completion candidates. To customize completion, set this
# to the name of a previously defined completion, a hash of options
# to pass to the constructor for {Toys::Flag::DefaultCompletion}, or
# any other spec recognized by {Toys::Completion.create}.
# @param complete_values [Object] A specifier for shell tab completion
# for flag values associated with this flag. This is the empty
# completion by default. To customize completion, set this to the
# name of a previously defined completion, or any spec recognized by
# {Toys::Completion.create}.
# @param report_collisions [Boolean] Raise an exception if a flag is
# requested that is already in use or marked as unusable. Default is
# true.
# @param group [Toys::FlagGroup, String, Symbol, nil] Group for this flag.
# You may provide a group name, a FlagGroup object, or `nil` which
# denotes the default group.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param display_name [String] A display name for this flag, used in help
# text and error messages.
# @param add_method [true, false, nil] Whether to add a method for this
# flag. If omitted or set to nil, uses the default behavior, which
# adds the method if the key is a symbol representing a legal method
# name that starts with a letter and does not override any public
# method in the Ruby Object class or collide with any method directly
# defined in the tool class.
# @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
# directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#996
def flag(key, *flags, accept: T.unsafe(nil), default: T.unsafe(nil), handler: T.unsafe(nil), complete_flags: T.unsafe(nil), complete_values: T.unsafe(nil), report_collisions: T.unsafe(nil), group: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), display_name: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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
#
# @param type [Symbol] The type of group. Allowed values: `:required`,
# `:optional`, `:exactly_one`, `:at_most_one`, `:at_least_one`.
# Default is `:optional`.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::DSL::Tool#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::DSL::Tool#long_desc} for a description of allowed formats.
# Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [Boolean] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [Boolean] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
# for the directives that can be called in this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#638
def flag_group(type: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil), &block); end
# Specify that the given module should be mixed into this tool, and its
# methods made available when running the tool.
#
# You can 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
#
# @param mixin [Module, Symbol, String] Module or module name.
# @param args [Object...] Arguments to pass to the initializer
# @param kwargs [keywords] Keyword arguments to pass to the initializer
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1627
def include(mixin, *args, **kwargs); end
# Determine if the given module/mixin has already been included.
#
# You can 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.
#
# @param mod [Module, Symbol, String] Module or module name.
# @return [Boolean] Whether the mixin is included
# @return [nil] if the current tool is not active.
#
# source://toys-core//lib/toys/dsl/tool.rb#1647
def include?(mod); end
# Include the tool name in the class inspection dump.
#
# @private
#
# source://toys-core//lib/toys/dsl/tool.rb#1843
def inspect; end
# Load another config file or directory, as if its contents were inserted
# at the current location.
#
# @param path [String] The file or directory to load.
# @param as [String] Load into the given tool/namespace. If omitted,
# configuration will be loaded into the current namespace.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#416
def load(path, as: T.unsafe(nil)); end
# Load configuration from a public git repository, as if its contents
# were inserted at the current location.
#
# @param remote [String] The URL of the git repository. Defaults to the
# current repository if already loading from git.
# @param path [String] The path within the repo to the file or directory
# to load. Defaults to the root of the repo.
# @param commit [String] The commit branch, tag, or sha. Defaults to the
# current commit if already loading from git, or to `HEAD`.
# @param as [String] Load into the given tool/namespace. If omitted,
# configuration will be loaded into the current namespace.
# @param update [Boolean] Force-fetch from the remote (unless the commit
# is a SHA). This will ensure that symbolic commits, such as branch
# names, are up to date. Default is false.
# @raise [ToolDefinitionError]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#445
def load_git(remote: T.unsafe(nil), path: T.unsafe(nil), commit: T.unsafe(nil), as: T.unsafe(nil), update: T.unsafe(nil)); end
# 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."
#
# @param strs [Toys::WrappableString, String, Array<String>...]
# @param file [String] Optional. Read the description from the given file
# provided relative to the current toys file. The file must be a
# plain text file whose suffix is `.txt`.
# @param data [String] Optional. Read the description from the given data
# file. The file must be a plain text file whose suffix is `.txt`.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#582
def long_desc(*strs, file: T.unsafe(nil), data: T.unsafe(nil)); end
# Notify the tool definition when a method is defined in this tool class.
#
# @private
#
# source://toys-core//lib/toys/dsl/tool.rb#1833
def method_added(_meth); end
# 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 message
# logger.error "An error occurred: #{message}"
# exit 1
# end
# end
#
# tool "build" do
# include "error-reporter"
# def run
# puts "Building..."
# error "Build failed!"
# end
# end
#
# @param name [String] Name of the mixin
# @param mixin_module [Module] Module to use as the mixin. Optional.
# Either pass a module here, *or* provide a block and define the
# mixin within the block.
# @param block [Proc] Defines the mixin module.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#149
def mixin(name, mixin_module = T.unsafe(nil), &block); end
# Specify how to handle interrupts.
#
# You can provide either a block to be called, a Proc to be called, or
# the name of a method to be called. In each case, the block, Proc, or
# method can optionally take one argument, the Interrupt exception that
# was raised.
#
# Note: this is equivalent to `on_signal("SIGINT")`.
#
# ### Example
#
# tool "foo" do
# def run
# sleep 10
# end
# on_interrupt do
# puts "I was interrupted."
# end
# end
#
# @param handler [Proc, Symbol, nil] The interrupt callback proc or method
# name. Pass nil to disable interrupt handling.
# @param block [Proc] The interrupt callback as a block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1531
def on_interrupt(handler = T.unsafe(nil), &block); end
# Specify how to run this tool.
#
# Typically the entrypoint for a tool is a method named `run`. However,
# you can change this by passing a different method name, as a symbol, to
# {#to_run}.
#
# You can also alternatively pass a block to {#to_run}. You might 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 those
# values in the context.
#
# ### Examples
#
# # Set a different method name as the entrypoint:
#
# tool "foo" do
# to_run :foo
# def foo
# puts "The foo tool ran!"
# end
# end
#
# # Use a block to retain access to the enclosing lexical scope from
# # the run method:
#
# tool "foo" do
# cur_time = Time.now
# to_run do
# puts "The time at tool definition was #{cur_time}"
# end
# end
#
# # But the following is approximately equivalent:
#
# tool "foo" do
# static :cur_time, Time.now
# def run
# puts "The time at tool definition was #{cur_time}"
# end
# end
#
# @param handler [Proc, Symbol, nil] The run handler as a method name
# symbol or a proc, or nil to explicitly set as non-runnable.
# @param block [Proc] The run handler as a block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1498
def on_run(handler = T.unsafe(nil), &block); end
# Specify how to handle the given signal.
#
# You can provide either a block to be called, a Proc to be called, or
# the name of a method to be called. In each case, the block, Proc, or
# method can optionally take one argument, the SignalException that was
# raised.
#
# ### Example
#
# tool "foo" do
# def run
# sleep 10
# end
# on_signal("QUIT") do |e|
# puts "Signal caught: #{e.signm}."
# end
# end
#
# @param signal [Integer, String, Symbol] The signal name or number
# @param handler [Proc, Symbol, nil] The signal callback proc or method
# name. Pass nil to disable signal handling.
# @param block [Proc] The signal callback as a block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1562
def on_signal(signal, handler = T.unsafe(nil), &block); end
# Specify how to handle usage errors.
#
# You can provide either a block to be called, a Proc to be called, or
# the name of a method to be called. In each case, the block, Proc, or
# method can optionally take one argument, the array of usage errors
# reported.
#
# ### Example
#
# This tool runs even if a usage error is encountered, by setting the
# `run` method as the usage error handler.
#
# tool "foo" do
# def run
# puts "Errors: #{usage_errors.join("\n")}"
# end
# on_usage_error :run
# end
#
# @param handler [Proc, Symbol, nil] The interrupt callback proc or method
# name. Pass nil to disable interrupt handling.
# @param block [Proc] The interrupt callback as a block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1593
def on_usage_error(handler = T.unsafe(nil), &block); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if this argument is not provided on the
# command line. Defaults to `nil`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for this
# argument. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1152
def optional(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if this argument is not provided on the
# command line. Defaults to `nil`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for this
# argument. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1152
def optional_arg(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if no unmatched arguments are provided on the
# command line. Defaults to the empty array `[]`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for these
# arguments. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1231
def remaining(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if no unmatched arguments are provided on the
# command line. Defaults to the empty array `[]`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for these
# arguments. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1231
def remaining_args(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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.
#
# @param state [Boolean]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1353
def require_exact_flag_match(state = T.unsafe(nil)); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for this
# argument. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1073
def required(key, accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# 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 {Toys::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 {Toys::DSL::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
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, one of the default acceptors provided by OptionParser, or
# any other specification recognized by {Toys::Acceptor.create}.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion for
# values of this arg. This is the empty completion by default. To
# customize completion, set this to the name of a previously defined
# completion, or any spec recognized by {Toys::Completion.create}.
# @param display_name [String] A name to use for display (in help text
# and error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::DSL::Tool#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::DSL::Tool#long_desc} for
# a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @param add_method [true, false, nil] Whether to add a method for this
# argument. If omitted or set to nil, uses the default behavior,
# which adds the method if the key is a symbol representing a legal
# method name that starts with a letter and does not override any
# public method in the Ruby Object class or collide with any method
# directly defined in the tool class.
# @param block [Proc] Configures the positional argument. See
# {Toys::DSL::PositionalArg} for the directives that can be called in
# this block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1073
def required_arg(key, accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), add_method: T.unsafe(nil), &block); end
# Set option values statically without creating helper methods.
#
# ### Example
#
# tool "hello" do
# set :greeting, "Hi there"
# def run
# puts "#{get(:greeting)}, world!"
# end
# end
#
# @overload set
# @overload set
#
# source://toys-core//lib/toys/dsl/tool.rb#1314
def set(key, value = T.unsafe(nil)); end
# Set a custom context directory for this tool.
#
# @param dir [String] Context directory
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1724
def set_context_directory(dir); end
# Get the settings for this tool.
#
# @return [Toys::ToolDefinition::Settings] Tool-specific settings.
#
# source://toys-core//lib/toys/dsl/tool.rb#1791
def settings; end
# 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 {Toys::WrappableString}, which may be word-wrapped
# when displayed in a help screen. You may pass a {Toys::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."]
#
# @param str [Toys::WrappableString, String, Array<String>]
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#546
def short_desc(str); end
# Return the current source info object.
#
# @return [Toys::SourceInfo] Source info.
#
# source://toys-core//lib/toys/dsl/tool.rb#1658
def source_info; end
# Set option values statically and create helper methods.
#
# 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 {Toys::Context#get}.
#
# ### Example
#
# tool "hello" do
# static :greeting, "Hi there"
# def run
# puts "#{greeting}, world!"
# end
# end
#
# @overload static
# @overload static
#
# source://toys-core//lib/toys/dsl/tool.rb#1275
def static(key, value = T.unsafe(nil)); end
# 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
#
# source://toys-core//lib/toys/dsl/tool.rb#1762
def subtool_apply(&block); end
# 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.
#
# A template is an object that defines an `expansion` procedure. This
# procedure generates the DSL directives implemented by the template. The
# template object typically also includes attributes that are used to
# configure the expansion.
#
# The simplest way to define a template is to pass a block to the
# {#template} directive. In the block, define an `initialize` method that
# accepts any arguments that may be passed to the template when it is
# instantiated and are used to configure the template. Define
# `attr_reader`s or other methods to make this configuration accessible
# from the object. Then define an `on_expand` block that implements the
# template's expansion. The template object is passed as an object to the
# `on_expand` block.
#
# Alternately, you can create a template class separately and pass it
# directly. See {Toys::Template} for details on creating a template
# class.
#
# ### Example
#
# The following example creates and uses a simple template. The template
# defines a tool, with a configurable name, that simply prints out a
# configurable message.
#
# template "hello-generator" do
# def initialize(name, message)
# @name = name
# @message = message
# end
# attr_reader :name, :message
# on_expand do |template|
# tool template.name do
# to_run do
# puts template.message
# end
# end
# end
# end
#
# expand "hello-generator", "mytool", "mytool is running!"
#
# @param name [String] Name of the template
# @param template_class [Class] Module to use as the mixin. Optional.
# Either pass a module here, *or* provide a block and define the
# mixin within the block.
# @param block [Proc] Defines the template class.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#211
def template(name, template_class = T.unsafe(nil), &block); end
# Specify how to run this tool.
#
# Typically the entrypoint for a tool is a method named `run`. However,
# you can change this by passing a different method name, as a symbol, to
# {#to_run}.
#
# You can also alternatively pass a block to {#to_run}. You might 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 those
# values in the context.
#
# ### Examples
#
# # Set a different method name as the entrypoint:
#
# tool "foo" do
# to_run :foo
# def foo
# puts "The foo tool ran!"
# end
# end
#
# # Use a block to retain access to the enclosing lexical scope from
# # the run method:
#
# tool "foo" do
# cur_time = Time.now
# to_run do
# puts "The time at tool definition was #{cur_time}"
# end
# end
#
# # But the following is approximately equivalent:
#
# tool "foo" do
# static :cur_time, Time.now
# def run
# puts "The time at tool definition was #{cur_time}"
# end
# end
#
# @param handler [Proc, Symbol, nil] The run handler as a method name
# symbol or a proc, or nil to explicitly set as non-runnable.
# @param block [Proc] The run handler as a block.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1498
def to_run(handler = T.unsafe(nil), &block); end
# 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 uses `delegate_to` to define 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
#
# @param words [String, Array<String>] The name of the subtool
# @param if_defined [:combine, :reset, :ignore] What to do if a definition
# already exists for this tool. Possible values are `:combine` (the
# default) indicating the definition should be combined with the
# existing definition, `:reset` indicating the earlier definition
# should be reset and the new definition applied instead, or
# `:ignore` indicating the new definition should be ignored.
# @param delegate_to [String, Array<String>] Optional. This tool should
# delegate to another tool, specified by the full path. This path may
# be given as an array of strings, or a single string possibly
# delimited by path separators.
# @param delegate_relative [String, Array<String>] Optional. Similar to
# delegate_to, but takes a delegate name relative to the context in
# which this tool is being defined.
# @param block [Proc] Defines the subtool.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#314
def tool(words, if_defined: T.unsafe(nil), delegate_to: T.unsafe(nil), delegate_relative: T.unsafe(nil), &block); end
# Asserts that the current Toys version against the given requirements,
# raising an exception if not.
#
# @raise [Toys::ToolDefinitionError] if the current Toys version does not
# satisfy the requirements.
# @return [self]
#
# source://toys-core//lib/toys/dsl/tool.rb#1817
def toys_version!(*requirements); end
# Determines whether the current Toys version satisfies the given
# requirements.
#
# @return [Boolean] whether or not the requirements are satisfied
#
# source://toys-core//lib/toys/dsl/tool.rb#1801
def toys_version?(*requirements); end
# 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.
#
# @raise [Toys::ToolDefinitionError] if any lower-priority tools have
# already been loaded.
#
# source://toys-core//lib/toys/dsl/tool.rb#1779
def truncate_load_path!; end
end
# Representation of a formal set of flags that set a particular context
# key. The flags within a single Flag definition are synonyms.
#
# source://toys-core//lib/toys/flag.rb#8
class Toys::Flag
# Create a Flag definition.
# This argument list is subject to change. Use {Toys::Flag.create} instead
# for a more stable interface.
#
# @private
# @return [Flag] a new instance of Flag
#
# source://toys-core//lib/toys/flag.rb#684
def initialize(key, flags, used_flags, report_collisions, acceptor, handler, default, flag_completion, value_completion, desc, long_desc, display_name, group); end
# Returns the effective acceptor.
#
# @return [Toys::Acceptor::Base]
#
# source://toys-core//lib/toys/flag.rb#467
def acceptor; end
# Whether this flag is active--that is, it has a nonempty flags list.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#637
def active?; end
# 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.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
# @return [self]
#
# source://toys-core//lib/toys/flag.rb#672
def append_long_desc(long_desc); end
# A list of canonical flag syntax strings.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/flag.rb#628
def canonical_syntax_strings; end
# Returns the default value, which may be `nil`.
#
# @return [Object]
#
# source://toys-core//lib/toys/flag.rb#473
def default; end
# The short description string.
#
# When reading, this is always returned as a {Toys::WrappableString}.
#
# When setting, the description may be provided as any of the following:
# * A {Toys::WrappableString}.
# * A normal String, which will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String, which will be transformed into a
# {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Toys::WrappableString]
#
# source://toys-core//lib/toys/flag.rb#490
def desc; end
# Set the short description string.
#
# See {#desc} for details.
#
# @param desc [Toys::WrappableString, String, Array<String>]
#
# source://toys-core//lib/toys/flag.rb#648
def desc=(desc); end
# The display name of this flag.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#567
def display_name; end
# The list of all effective flags used.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/flag.rb#595
def effective_flags; end
# The proc that determines shell completions for the flag.
#
# @return [Proc, Toys::Completion::Base]
#
# source://toys-core//lib/toys/flag.rb#521
def flag_completion; end
# Returns an array of Flag::Syntax for the flags.
#
# @return [Array<Toys::Flag::Syntax>]
#
# source://toys-core//lib/toys/flag.rb#461
def flag_syntax; end
# The type of flag.
#
# @return [:boolean] if the flag is a simple boolean switch
# @return [:value] if the flag sets a value
#
# source://toys-core//lib/toys/flag.rb#535
def flag_type; end
# Returns the flag group containing this flag
#
# @return [Toys::FlagGroup]
#
# source://toys-core//lib/toys/flag.rb#449
def group; end
# The handler for setting/updating the value.
#
# @return [Proc]
#
# source://toys-core//lib/toys/flag.rb#515
def handler; end
# Returns the key.
#
# @return [Symbol]
#
# source://toys-core//lib/toys/flag.rb#455
def key; end
# The long description strings.
#
# When reading, this is returned as an Array of {Toys::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 {Toys::WrappableString} representing one line.
# * A normal String representing a line. This will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String representing a line. This will be transformed into
# a {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Array<Toys::WrappableString>]
#
# source://toys-core//lib/toys/flag.rb#509
def long_desc; end
# Set the long description strings.
#
# See {#long_desc} for details.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
#
# source://toys-core//lib/toys/flag.rb#659
def long_desc=(long_desc); end
# An array of Flag::Syntax including only long (double-dash) flags.
#
# @return [Array<Flag::Syntax>]
#
# source://toys-core//lib/toys/flag.rb#587
def long_flag_syntax; end
# Look up the flag by string. Returns an object that indicates whether
# the given string matched this flag, whether the match was unique, and
# other pertinent information.
#
# @param str [String] Flag string to look up
# @return [Toys::Flag::Resolution] Information about the match.
#
# source://toys-core//lib/toys/flag.rb#607
def resolve(str); end
# An array of Flag::Syntax including only short (single dash) flags.
#
# @return [Array<Flag::Syntax>]
#
# source://toys-core//lib/toys/flag.rb#579
def short_flag_syntax; end
# A string that can be used to sort this flag
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#573
def sort_str; end
# The proc that determines shell completions for the value.
#
# @return [Proc, Toys::Completion::Base]
#
# source://toys-core//lib/toys/flag.rb#527
def value_completion; end
# The value delimiter, which may be `""`, `" "`, or `"="`.
#
# @return [String] The delimiter
# @return [nil] if the flag type is not `:value`.
#
# source://toys-core//lib/toys/flag.rb#561
def value_delim; end
# The string label for the value as it should display in help.
#
# @return [String] The label
# @return [nil] if the flag type is not `:value`.
#
# source://toys-core//lib/toys/flag.rb#553
def value_label; end
# The type of value.
#
# @return [:required] if the flag type is `:value` and the value is
# required.
# @return [:optional] if the flag type is `:value` and the value is
# optional.
# @return [nil] if the flag type is not `:value`.
#
# source://toys-core//lib/toys/flag.rb#546
def value_type; end
private
# source://toys-core//lib/toys/flag.rb#791
def analyze_flag_syntax(flag); end
# source://toys-core//lib/toys/flag.rb#766
def canonicalize; end
# source://toys-core//lib/toys/flag.rb#733
def create_default_flag; end
# source://toys-core//lib/toys/flag.rb#720
def create_flag_completion(spec); end
# source://toys-core//lib/toys/flag.rb#751
def remove_used_flags(used_flags, report_collisions); end
# source://toys-core//lib/toys/flag.rb#705
def resolve_handler(handler); end
# source://toys-core//lib/toys/flag.rb#807
def summarize(name); end
class << self
# Create a flag definition.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param flags [Array<String>] The flags in OptionParser format. If empty,
# a flag will be inferred from the key.
# @param accept [Object] An acceptor that validates and/or converts the
# value. See {Toys::Acceptor.create} for recognized formats. Optional.
# If not specified, defaults to {Toys::Acceptor::DEFAULT}.
# @param default [Object] The default value. This is the value that will
# be set in the context if this flag is not provided on the command
# line. Defaults to `nil`.
# @param handler [Proc, nil, :set, :push] An optional handler for
# setting/updating the value. A handler is a proc taking two
# arguments, the given value and the previous value, returning the
# new value that should be set. You may also specify a predefined
# named handler. The `:set` handler (the default) replaces the
# previous value (effectively `-> (val, _prev) { val }`). The
# `:push` handler expects the previous value to be an array and
# pushes the given value onto it; it should be combined with setting
# `default: []` and is intended for "multi-valued" flags.
# @param complete_flags [Object] A specifier for shell tab completion for
# flag names associated with this flag. By default, a
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
# names as completion candidates. To customize completion, set this to
# a hash of options to pass to the constructor for
# {Toys::Flag::DefaultCompletion}, or pass any other spec recognized
# by {Toys::Completion.create}.
# @param complete_values [Object] A specifier for shell tab completion for
# flag values associated with this flag. Pass any spec recognized by
# {Toys::Completion.create}.
# @param report_collisions [Boolean] Raise an exception if a flag is
# requested that is already in use or marked as disabled. Default is
# true.
# @param group [Toys::FlagGroup] Group containing this flag.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::ToolDefinition#long_desc}
# for a description of allowed formats. Defaults to the empty array.
# @param display_name [String] A display name for this flag, used in help
# text and error messages.
# @param used_flags [Array<String>] An array of flags already in use.
#
# source://toys-core//lib/toys/flag.rb#437
def create(key, flags = T.unsafe(nil), used_flags: T.unsafe(nil), report_collisions: T.unsafe(nil), accept: T.unsafe(nil), handler: T.unsafe(nil), default: T.unsafe(nil), complete_flags: T.unsafe(nil), complete_values: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), group: T.unsafe(nil)); end
end
end
# The default handler is the set handler, replacing the previous value.
#
# @return [Proc]
#
# source://toys-core//lib/toys/flag.rb#389
Toys::Flag::DEFAULT_HANDLER = T.let(T.unsafe(nil), Proc)
# A Completion that returns all possible flags associated with a
# {Toys::Flag}.
#
# source://toys-core//lib/toys/flag.rb#294
class Toys::Flag::DefaultCompletion < ::Toys::Completion::Base
# Create a completion given configuration options.
#
# @param flag [Toys::Flag] The flag definition.
# @param include_short [Boolean] Whether to include short flags.
# @param include_long [Boolean] Whether to include long flags.
# @param include_negative [Boolean] Whether to include `--no-*` forms.
# @return [DefaultCompletion] a new instance of DefaultCompletion
#
# source://toys-core//lib/toys/flag.rb#303
def initialize(flag:, include_short: T.unsafe(nil), include_long: T.unsafe(nil), include_negative: T.unsafe(nil)); end
# Returns candidates for the current completion.
#
# @param context [Toys::Completion::Context] the current completion
# context including the string fragment.
# @return [Array<Toys::Completion::Candidate>] an array of candidates
#
# source://toys-core//lib/toys/flag.rb#342
def call(context); end
# Whether to include long flags
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#323
def include_long?; end
# Whether to include negative long flags
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#331
def include_negative?; end
# Whether to include short flags
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#315
def include_short?; end
private
# source://toys-core//lib/toys/flag.rb#356
def collect_results; end
end
# The push handler pushes the given value using the `<<` operator.
#
# @return [Proc]
#
# source://toys-core//lib/toys/flag.rb#383
Toys::Flag::PUSH_HANDLER = T.let(T.unsafe(nil), Proc)
# The result of looking up a flag by name.
#
# source://toys-core//lib/toys/flag.rb#173
class Toys::Flag::Resolution
# @private
# @return [Resolution] a new instance of Resolution
#
# source://toys-core//lib/toys/flag.rb#177
def initialize(str); end
# @private
#
# source://toys-core//lib/toys/flag.rb#269
def add!(flag, flag_syntax, negative, exact); end
# The number of matches that were found.
#
# @return [Integer]
#
# source://toys-core//lib/toys/flag.rb#201
def count; end
# Whether an exact match of the string was found
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#193
def found_exact?; end
# Whether multiple matches were found (i.e. ambiguous input).
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#225
def found_multiple?; end
# Whether a single unique match was found.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#209
def found_unique?; end
# Returns an array of the matching full flag strings.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/flag.rb#260
def matching_flag_strings; end
# @private
#
# source://toys-core//lib/toys/flag.rb#281
def merge!(other); end
# Whether no matches were found.
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag.rb#217
def not_found?; end
# The flag string that was looked up
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#187
def string; end
# Return the unique {Toys::Flag}, or `nil` if not found or
# not unique.
#
# @return [Toys::Flag, nil]
#
# source://toys-core//lib/toys/flag.rb#234
def unique_flag; end
# Return whether the unique match was a hit on the negative (`--no-*`)
# case, or `nil` if not found or not unique.
#
# @return [Boolean, nil]
#
# source://toys-core//lib/toys/flag.rb#252
def unique_flag_negative?; end
# Return the unique {Toys::Flag::Syntax}, or `nil` if not found
# or not unique.
#
# @return [Toys::Flag::Syntax, nil]
#
# source://toys-core//lib/toys/flag.rb#243
def unique_flag_syntax; end
end
# The set handler replaces the previous value.
#
# @return [Proc]
#
# source://toys-core//lib/toys/flag.rb#377
Toys::Flag::SET_HANDLER = T.let(T.unsafe(nil), Proc)
# Representation of a single flag.
#
# source://toys-core//lib/toys/flag.rb#12
class Toys::Flag::Syntax
# Parse flag syntax
#
# @param str [String] syntax.
# @return [Syntax] a new instance of Syntax
#
# source://toys-core//lib/toys/flag.rb#19
def initialize(str); end
# A canonical string representing this flag's syntax, normalized to match
# the type, delimiters, etc. settings of other flag syntaxes. This is
# generally used in help strings to represent this flag.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#129
def canonical_str; end
# This method is accessible for testing only.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/flag.rb#136
def configure_canonical(canonical_flag_type, canonical_value_type, canonical_value_label, canonical_value_delim); end
# The style of flag (`:long` or `:short`).
#
# @return [:long] if this is a long flag (i.e. double hyphen)
# @return [:short] if this is a short flag (i.e. single hyphen with one
# character).
#
# source://toys-core//lib/toys/flag.rb#89
def flag_style; end
# The type of flag (`:boolean` or `:value`)
#
# @return [:boolean] if this is a boolean flag (i.e. no value)
# @return [:value] if this flag takes a value (even if optional)
# @return [nil] if this flag is indeterminate
#
# source://toys-core//lib/toys/flag.rb#97
def flag_type; end
# The flags (without values) corresponding to this syntax.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/flag.rb#52
def flags; end
# The flag (without values) corresponding to the "negative" form of this
# flag, if any. i.e. if the original string was `"--[no-]abc"`, the
# negative flag is `"--no-abc"`.
#
# @return [String] The negative form.
# @return [nil] if the flag has no negative form.
#
# source://toys-core//lib/toys/flag.rb#68
def negative_flag; end
# The original string that was parsed to produce this syntax.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#46
def original_str; end
# The flag (without values) corresponding to the normal "positive" form
# of this flag.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#59
def positive_flag; end
# A string used to sort this flag compared with others.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#81
def sort_str; end
# The original string with the value (if any) stripped, but retaining
# the `[no-]` prefix if present.
#
# @return [String]
#
# source://toys-core//lib/toys/flag.rb#75
def str_without_value; end
# The default delimiter used for the value of this flag. This could be
# `""` or `" "` for a short flag, or `" "` or `"="` for a long flag.
#
# @return [String] delimiter
# @return [nil] if this flag is a boolean flag
#
# source://toys-core//lib/toys/flag.rb#113
def value_delim; end
# The default "label" for the value. e.g. in `--abc=VAL` the label is
# `"VAL"`.
#
# @return [String] the label
# @return [nil] if this flag is a boolean flag
#
# source://toys-core//lib/toys/flag.rb#121
def value_label; end
# The type of value (`:required` or `:optional`)
#
# @return [:required] if this flag takes a required value
# @return [:optional] if this flag takes an optional value
# @return [nil] if this flag is a boolean flag
#
# source://toys-core//lib/toys/flag.rb#105
def value_type; end
private
# source://toys-core//lib/toys/flag.rb#152
def setup(original_str, positive_flag, negative_flag, str_without_value, sort_str, flag_style, flag_type, value_type, value_delim, value_label); end
end
# A FlagGroup is a group of flags with the same requirement settings.
#
# source://toys-core//lib/toys/flag_group.rb#7
module Toys::FlagGroup
class << self
# Create a flag group object of the given type.
#
# 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
#
# @param type [Symbol] The type of group. Default is `:optional`.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::ToolDefinition#long_desc} for a description of allowed
# formats. Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @return [Toys::FlagGroup::Base] A flag group of the correct subclass.
#
# source://toys-core//lib/toys/flag_group.rb#30
def create(type: T.unsafe(nil), name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil)); end
end
end
# A FlagGroup in which at least one flag must be set
#
# source://toys-core//lib/toys/flag_group.rb#262
class Toys::FlagGroup::AtLeastOne < ::Toys::FlagGroup::Base
# @private
#
# source://toys-core//lib/toys/flag_group.rb#266
def validation_errors(seen); end
end
# A FlagGroup in which at most one flag must be set
#
# source://toys-core//lib/toys/flag_group.rb#240
class Toys::FlagGroup::AtMostOne < ::Toys::FlagGroup::Base
# @private
#
# source://toys-core//lib/toys/flag_group.rb#244
def validation_errors(seen); end
end
# The base class of a FlagGroup, implementing everything except validation.
# The base class effectively behaves as an Optional group. And the default
# group that contains flags not otherwise assigned to a group, is of this
# type. However, you should use {Toys::FlagGroup::Optional} when creating
# an explicit optional group.
#
# source://toys-core//lib/toys/flag_group.rb#54
class Toys::FlagGroup::Base
# Create a flag group.
# This argument list is subject to change. Use {Toys::FlagGroup.create}
# instead for a more stable interface.
#
# @private
# @return [Base] a new instance of Base
#
# source://toys-core//lib/toys/flag_group.rb#62
def initialize(name, desc, long_desc); end
# @private
#
# source://toys-core//lib/toys/flag_group.rb#175
def <<(flag); end
# 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.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
# @return [self]
#
# source://toys-core//lib/toys/flag_group.rb#167
def append_long_desc(long_desc); end
# The short description string.
#
# When reading, this is always returned as a {Toys::WrappableString}.
#
# When setting, the description may be provided as any of the following:
# * A {Toys::WrappableString}.
# * A normal String, which will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String, which will be transformed into a
# {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Toys::WrappableString]
#
# source://toys-core//lib/toys/flag_group.rb#90
def desc; end
# Set the short description string.
#
# See {#desc} for details.
#
# @param desc [Toys::WrappableString, String, Array<String>]
#
# source://toys-core//lib/toys/flag_group.rb#143
def desc=(desc); end
# Returns true if this group is empty
#
# @return [Boolean]
#
# source://toys-core//lib/toys/flag_group.rb#122
def empty?; end
# An array of flags that are in this group.
# Do not modify the returned array.
#
# @return [Array<Toys::Flag>]
#
# source://toys-core//lib/toys/flag_group.rb#116
def flags; end
# The long description strings.
#
# When reading, this is returned as an Array of {Toys::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 {Toys::WrappableString} representing one line.
# * A normal String representing a line. This will be transformed into
# a {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String representing a line. This will be transformed
# into a {Toys::WrappableString} where each array element represents
# an individual word for wrapping.
#
# @return [Array<Toys::WrappableString>]
#
# source://toys-core//lib/toys/flag_group.rb#109
def long_desc; end
# Set the long description strings.
#
# See {#long_desc} for details.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
#
# source://toys-core//lib/toys/flag_group.rb#154
def long_desc=(long_desc); end
# The symbolic name for this group
#
# @return [String, Symbol, nil]
#
# source://toys-core//lib/toys/flag_group.rb#73
def name; end
# Returns a string summarizing this group. This is generally either the
# short description or a representation of all the flags included.
#
# @return [String]
#
# source://toys-core//lib/toys/flag_group.rb#131
def summary; end
# @private
#
# source://toys-core//lib/toys/flag_group.rb#182
def validation_errors(_seen); end
end
# A FlagGroup in which exactly one flag must be set
#
# source://toys-core//lib/toys/flag_group.rb#215
class Toys::FlagGroup::ExactlyOne < ::Toys::FlagGroup::Base
# @private
#
# source://toys-core//lib/toys/flag_group.rb#219
def validation_errors(seen); end
end
# A FlagGroup containing all optional flags
#
# source://toys-core//lib/toys/flag_group.rb#209
class Toys::FlagGroup::Optional < ::Toys::FlagGroup::Base; end
# A FlagGroup containing all required flags
#
# source://toys-core//lib/toys/flag_group.rb#190
class Toys::FlagGroup::Required < ::Toys::FlagGroup::Base
# @private
#
# source://toys-core//lib/toys/flag_group.rb#194
def validation_errors(seen); end
end
# This module is the root namespace for tool definitions loaded from files.
# Whenever a toys configuration file is parsed, a module is created under this
# parent for that file's contents. Tool classes defined in that file, along
# with mixins and templates, and any other classes, modules, and constants
# defined, are located within that file's module.
#
# source://toys-core//lib/toys/input_file.rb#10
module Toys::InputFile
class << self
# @private
#
# source://toys-core//lib/toys/input_file.rb#39
def __binding; end
# @private
#
# source://toys-core//lib/toys/input_file.rb#46
def build_eval_string(module_name, string); end
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/input_file.rb#14
def evaluate(tool_class, words, priority, remaining_words, source, loader); end
end
end
# The Loader service loads tools from configuration files, and finds the
# appropriate tool given a set of command line arguments.
#
# source://toys-core//lib/toys/loader.rb#8
class Toys::Loader
# Create a Loader
#
# @param index_file_name [String, nil] A file with this name that appears
# in any configuration directory (not just a toplevel directory) is
# loaded first as a standalone configuration file. If not provided,
# standalone configuration files are disabled.
# @param preload_file_name [String, nil] A file with this name that appears
# in any configuration directory is preloaded before any tools in that
# configuration directory are defined.
# @param preload_dir_name [String, nil] A directory with this name that
# appears in any configuration directory is searched for Ruby files,
# which are preloaded before any tools in that configuration directory
# are defined.
# @param data_dir_name [String, nil] A directory with this name that appears
# in any configuration directory is added to the data directory search
# path for any tool file in that directory.
# @param lib_dir_name [String, nil] A directory with this name that appears
# in any configuration directory is added to the Ruby load path for any
# tool file in that directory.
# @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
# middleware that will be used by default for all tools loaded by this
# loader.
# @param extra_delimiters [String] A string containing characters that can
# function as delimiters in a tool name. Defaults to empty. Allowed
# characters are period, colon, and slash.
# @param mixin_lookup [Toys::ModuleLookup] A lookup for well-known
# mixin modules. Defaults to an empty lookup.
# @param middleware_lookup [Toys::ModuleLookup] A lookup for
# well-known middleware classes. Defaults to an empty lookup.
# @param template_lookup [Toys::ModuleLookup] A lookup for
# well-known template classes. Defaults to an empty lookup.
# @return [Loader] a new instance of Loader
#
# source://toys-core//lib/toys/loader.rb#42
def initialize(index_file_name: T.unsafe(nil), preload_dir_name: T.unsafe(nil), preload_file_name: T.unsafe(nil), data_dir_name: T.unsafe(nil), lib_dir_name: T.unsafe(nil), middleware_stack: T.unsafe(nil), extra_delimiters: T.unsafe(nil), mixin_lookup: T.unsafe(nil), middleware_lookup: T.unsafe(nil), template_lookup: T.unsafe(nil), git_cache: T.unsafe(nil)); end
# Returns the active tool specified by the given words, with the given
# priority, without doing any loading. If the given priority matches the
# currently active tool, returns it. If the given priority is lower than
# the active priority, returns `nil`. If the given priority is higher than
# the active priority, returns and activates a new tool.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#350
def activate_tool(words, priority); end
# Add a configuration block to the loader.
#
# @param high_priority [Boolean] If true, add this block at the top of the
# priority list. Defaults to false, indicating the block should be at
# the bottom of the priority list.
# @param source_name [String] The source name that will be shown in
# documentation for tools defined in this block. If omitted, a default
# unique string will be generated.
# @param block [Proc] The block of configuration, executed in the context
# of the tool DSL {Toys::DSL::Tool}.
# @param context_directory [String, nil] The context directory for tools
# loaded from this block. You can pass a directory path as a string, or
# `nil` to denote no context. Defaults to `nil`.
# @return [self]
#
# source://toys-core//lib/toys/loader.rb#167
def add_block(high_priority: T.unsafe(nil), source_name: T.unsafe(nil), context_directory: T.unsafe(nil), &block); end
# Add a configuration git source to the loader.
#
# @param git_remote [String] The git repo URL
# @param git_path [String] The path to the relevant file or directory in
# the repo. Specify the empty string to use the entire repo.
# @param git_commit [String] The git ref (i.e. SHA, tag, or branch name)
# @param high_priority [Boolean] If true, add this path at the top of the
# priority list. Defaults to false, indicating the new path should be
# at the bottom of the priority list.
# @param update [Boolean] If the commit is not a SHA, pulls any updates
# from the remote. Defaults to false, which uses a local cache and does
# not update if the commit has been fetched previously.
# @param context_directory [String, nil] The context directory for tools
# loaded from this source. You can pass a directory path as a string,
# or `nil` to denote no context. Defaults to `nil`.
# @return [self]
#
# source://toys-core//lib/toys/loader.rb#203
def add_git(git_remote, git_path, git_commit, high_priority: T.unsafe(nil), update: T.unsafe(nil), context_directory: T.unsafe(nil)); end
# Add a configuration file/directory to the loader.
#
# @param path [String] A single path to add.
# @param high_priority [Boolean] If true, add this path at the top of the
# priority list. Defaults to false, indicating the new path should be
# at the bottom of the priority list.
# @param source_name [String] A custom name for the root source. Optional.
# @param context_directory [String, nil, :path, :parent] The context directory
# for tools loaded from this path. You can pass a directory path as a
# string, `:path` to denote the given path, `:parent` to denote the
# given path's parent directory, or `nil` to denote no context.
# Defaults to `:parent`.
# @return [self]
#
# source://toys-core//lib/toys/loader.rb#94
def add_path(path, high_priority: T.unsafe(nil), source_name: T.unsafe(nil), context_directory: T.unsafe(nil)); end
# Add a set of configuration files/directories from a common directory to
# the loader. The set of paths will be added at the same priority level and
# will share a root.
#
# @param root_path [String] A root path to be seen as the root source. This
# should generally be a directory containing the paths to add.
# @param relative_paths [String, Array<String>] One or more paths to add, as
# relative paths from the common root.
# @param high_priority [Boolean] If true, add the paths at the top of the
# priority list. Defaults to false, indicating the new paths should be
# at the bottom of the priority list.
# @param context_directory [String, nil, :path, :parent] The context directory
# for tools loaded from this path. You can pass a directory path as a
# string, `:path` to denote the given root path, `:parent` to denote
# the given root path's parent directory, or `nil` to denote no context.
# Defaults to `:path`.
# @return [self]
#
# source://toys-core//lib/toys/loader.rb#131
def add_path_set(root_path, relative_paths, high_priority: T.unsafe(nil), context_directory: T.unsafe(nil)); end
# Build a new tool.
# Called only from ToolData.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#372
def build_tool(words, priority, tool_class = T.unsafe(nil)); end
# Get or create the tool definition for the given name and priority.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#335
def get_tool(words, priority, tool_class = T.unsafe(nil)); end
# Returns true if the given path has at least one subtool, even if they are
# hidden or non-runnable. Loads from the configuration if necessary.
#
# @param words [Array<String>] The name of the parent tool
# @return [Boolean]
#
# source://toys-core//lib/toys/loader.rb#306
def has_subtools?(words); end
# Returns a list of subtools for the given path, loading from the
# configuration if necessary. The list will be sorted by name.
#
# @param words [Array<String>] The name of the parent tool
# @param recursive [Boolean] If true, return all subtools recursively
# rather than just the immediate children (the default)
# @param include_hidden [Boolean] If true, include hidden subtools,
# i.e. names beginning with underscores. Defaults to false.
# @param include_namespaces [Boolean] If true, include namespaces,
# i.e. tools that are not runnable but have descendents that would have
# been listed by the current filters. Defaults to false.
# @param include_non_runnable [Boolean] If true, include tools that have
# no children and are not runnable. Defaults to false.
# @return [Array<Toys::ToolDefinition>] An array of subtools.
#
# source://toys-core//lib/toys/loader.rb#281
def list_subtools(words, recursive: T.unsafe(nil), include_hidden: T.unsafe(nil), include_namespaces: T.unsafe(nil), include_non_runnable: T.unsafe(nil)); end
# Load a subtool block. Called from the `tool` directive in the DSL.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#472
def load_block(parent_source, block, words, remaining_words, priority); end
# Loads the subtree under the given prefix.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#398
def load_for_prefix(prefix); end
# Load configuration from the given git remote. This is called from the
# `load_git` directive in the DSL.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#457
def load_git(parent_source, git_remote, git_path, git_commit, words, remaining_words, priority, update: T.unsafe(nil)); end
# Load configuration from the given path. This is called from the `load`
# directive in the DSL.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#440
def load_path(parent_source, path, words, remaining_words, priority); end
# Given a list of command line arguments, find the appropriate tool to
# handle the command, loading it from the configuration if necessary.
# This always returns a tool. If the specific tool path is not defined and
# cannot be found in any configuration, it finds the nearest namespace that
# *would* contain that tool, up to the root tool.
#
# Returns a tuple of the found tool, and the array of remaining arguments
# that are not part of the tool name and should be passed as tool args.
#
# @param args [Array<String>] Command line arguments
# @return [Array(Toys::ToolDefinition,Array<String>)]
#
# source://toys-core//lib/toys/loader.rb#235
def lookup(args); end
# Given a tool name, looks up the specific tool, loading it from the
# configuration if necessary.
#
# If there is an active tool, returns it; otherwise, returns the highest
# priority tool that has been defined. If no tool has been defined with
# the given name, returns `nil`.
#
# @param words [Array<String>] The tool name
# @return [Toys::ToolDefinition] if the tool was found
# @return [nil] if no such tool exists
#
# source://toys-core//lib/toys/loader.rb#257
def lookup_specific(words); end
# Attempt to get a well-known mixin module for the given symbolic name.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#421
def resolve_standard_mixin(name); end
# Attempt to get a well-known template class for the given symbolic name.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#430
def resolve_standard_template(name); end
# Splits the given path using the delimiters configured in this Loader.
# You may pass in either an array of strings, or a single string possibly
# delimited by path separators. Always returns an array of strings.
#
# @param str [String, Symbol, Array<String,Symbol>] The path to split.
# @return [Array<String>]
#
# source://toys-core//lib/toys/loader.rb#323
def split_path(str); end
# Stop search at the given priority. Returns true if successful.
# Called only from the DSL.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#385
def stop_loading_at_priority(priority); end
# Returns true if the given tool name currently exists in the loader.
# Does not load the tool if not found.
#
# @private This interface is internal and subject to change without warning.
# @return [Boolean]
#
# source://toys-core//lib/toys/loader.rb#362
def tool_defined?(words); end
private
# Return a snapshot of all the current tool definitions that have been
# loaded. No additional loading is done. The returned array is not in any
# particular order.
#
# source://toys-core//lib/toys/loader.rb#648
def all_cur_definitions; end
# source://toys-core//lib/toys/loader.rb#794
def calc_remaining_words(words1, words2); end
# Look for and require any preloads.
#
# source://toys-core//lib/toys/loader.rb#767
def do_preload(path); end
# Given a sorted list of tools, filter out non-runnable tools, subject to
# the given settings.
#
# source://toys-core//lib/toys/loader.rb#808
def filter_non_runnable_tools(tools, include_namespaces, include_non_runnable); end
# Finishes all tool definitions under the given path. This generally means
# installing middleware.
#
# source://toys-core//lib/toys/loader.rb#671
def finish_definitions_in_tree(words); end
# Get or create the ToolData for the given name.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#663
def get_tool_data(words, create); end
# Load non-index file in a directory source.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#744
def load_child_in(source, child, words, remaining_words, priority); end
# Load an index file in a directory source.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#734
def load_index_in(source, words, remaining_words, priority); end
# Loads from a proc source.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#685
def load_proc(source, words, remaining_words, priority); end
# Load from a file path source that is known to exist and is known to be
# relevant to the current load request.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#716
def load_relevant_path(source, words, remaining_words, priority); end
# Load from a file path source that is known to exist.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#703
def load_validated_path(source, words, remaining_words, priority); end
# Require the contents of the given directory.
#
# source://toys-core//lib/toys/loader.rb#785
def require_dir_contents(preload_dir); end
# Update min_loaded_priority to the given value.
# Caller must own the mutex.
#
# source://toys-core//lib/toys/loader.rb#760
def update_min_loaded_priority(priority); end
class << self
# Get a global default GitCache.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#487
def default_git_cache; end
# Determine the next setting for remaining_words, given a word.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/loader.rb#501
def next_remaining_words(remaining_words, word); end
end
end
# An object that handles name delimiting.
#
# @private
#
# source://toys-core//lib/toys/loader.rb#608
class Toys::Loader::DelimiterHandler
# @private
# @return [DelimiterHandler] a new instance of DelimiterHandler
#
# source://toys-core//lib/toys/loader.rb#612
def initialize(extra_delimiters); end
# @private
#
# source://toys-core//lib/toys/loader.rb#630
def find_orig_prefix(args); end
# @private
#
# source://toys-core//lib/toys/loader.rb#623
def split_path(str); end
end
# An internal object managing the various definitions for a specific tool
# tool name and their priorities, and tracking which, if any, has been
# activated.
#
# This class is not thread-safe by itself. The caller must protect access
# with a mutex.
#
# @private
#
# source://toys-core//lib/toys/loader.rb#521
class Toys::Loader::ToolData
# Create an empty tool data with no definitions.
#
# @private
# @return [ToolData] a new instance of ToolData
#
# source://toys-core//lib/toys/loader.rb#527
def initialize(words); end
# Attempt to activate the tool with the given priority, and return it.
# If the given priority tool is already active, returns it.
# If a lower priority tool is already active, activates the given higher
# priority tool and returns it.
# If a higher priority tool is already active, does nothing and returns
# nil.
#
# @private
#
# source://toys-core//lib/toys/loader.rb#577
def activate_tool(priority, loader); end
# Return the current "best" definition, which is either the active
# definition, or, if none, the current highest-priority definition.
#
# @private
#
# source://toys-core//lib/toys/loader.rb#539
def cur_definition; end
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/loader.rb#546
def empty?; end
# Ensure there is a tool definition of the given priority, creating it if
# needed, and return it. A tool class may be provided, but only if the
# tool definition has not yet been created.
#
# @private
#
# source://toys-core//lib/toys/loader.rb#557
def get_tool(priority, loader, tool_class = T.unsafe(nil)); end
private
# source://toys-core//lib/toys/loader.rb#598
def active_definition; end
# source://toys-core//lib/toys/loader.rb#594
def top_definition; end
# source://toys-core//lib/toys/loader.rb#586
def validate_words(words); end
end
# An exception indicating a problem during tool lookup
#
# source://toys-core//lib/toys/errors.rb#39
class Toys::LoaderError < ::StandardError; end
# A middleware is an object that has the opportunity to alter the
# configuration and runtime behavior of each tool in a Toys CLI. A CLI
# contains an ordered list of middleware, known as the *middleware stack*,
# that together define the CLI's default behavior.
#
# Specifically, a middleware can perform two functions.
#
# First, it can modify the configuration of a tool. After tools are defined
# from configuration, the middleware stack can make modifications to each
# tool. A middleware can add flags and arguments to the tool, modify the
# description, or make any other changes to how the tool is set up.
#
# Second, a middleware can intercept and change tool execution. Like a Rack
# middleware, a Toys middleware can wrap execution with its own code,
# replace it outright, or leave it unmodified.
#
# Generally, a middleware is a class that implements one or more of the
# methods defined in this module: {Toys::Middleware#config}, and
# {Toys::Middleware#run}. This module provides default implementations that
# do nothing, but it is not required to include this module, or even to
# define both methods. Middleware objects need respond only to methods they
# care about.
#
# source://toys-core//lib/toys/middleware.rb#28
module Toys::Middleware
# This method is called *after* a tool has been defined, and gives this
# middleware the opportunity to modify the tool definition. It is passed
# the tool definition object and the loader, and can make any changes to
# the tool definition. In most cases, this method should also call
# `yield`, which passes control to the next middleware in the stack. A
# middleware can disable modifications done by subsequent middleware by
# omitting the `yield` call, but this is uncommon.
#
# This basic implementation does nothing and simply yields to the next
# middleware.
#
# @param tool [Toys::ToolDefinition] The tool definition to modify.
# @param loader [Toys::Loader] The loader that loaded this tool.
# @return [void]
#
# source://toys-core//lib/toys/middleware.rb#45
def config(tool, loader); end
# This method is called when the tool is run. It gives the middleware an
# opportunity to modify the runtime behavior of the tool. It is passed
# the tool instance (i.e. the object that hosts a tool's `run` method),
# and you can use this object to access the tool's options and other
# context data. In most cases, this method should also call `yield`,
# which passes control to the next middleware in the stack. A middleware
# can "wrap" normal execution by calling `yield` somewhere in its
# implementation of this method, or it can completely replace the
# execution behavior by not calling `yield` at all.
#
# Like a tool's `run` method, this method's return value is unused. If
# you want to output from a tool, write to stdout or stderr. If you want
# to set the exit status code, call {Toys::Context#exit} on the context.
#
# This basic implementation does nothing and simply yields to the next
# middleware.
#
# @param context [Toys::Context] The tool execution context.
# @return [void]
#
# source://toys-core//lib/toys/middleware.rb#70
def run(context); end
class << self
# Create a middleware spec.
#
# @overload spec
# @overload spec
# @overload spec
#
# source://toys-core//lib/toys/middleware.rb#107
def spec(middleware, *args, **kwargs, &block); end
# Create a spec from an array specification.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/middleware.rb#149
def spec_from_array(array); end
# Create a {Toys::Middleware::Stack} from an array of middleware specs.
# Each element may be one of the following:
#
# * A {Toys::Middleware} object
# * A {Toys::Middleware::Spec}
# * An array whose first element is a middleware name or class, and the
# subsequent elements are params that define what to pass to the class
# constructor (see {Toys::Middleware.spec})
#
# @param input [Array<Toys::Middleware,Toys::Middleware::Spec,Array>]
# @return [Toys::Middleware::Stack]
#
# source://toys-core//lib/toys/middleware.rb#133
def stack(input); end
end
end
# A base class that provides default no-op implementation of the middleware
# interface. This base class may optionally be subclassed by a middleware
# implementation.
#
# source://toys-core//lib/toys/middleware.rb#178
class Toys::Middleware::Base
include ::Toys::Middleware
end
# A middleware specification, including the middleware class and the
# arguments to pass to the constructor.
#
# Use {Toys::Middleware.spec} to create a middleware spec.
#
# source://toys-core//lib/toys/middleware.rb#188
class Toys::Middleware::Spec
# Internal constructor. Use {Toys::Middleware.spec} instead.
#
# @private This interface is internal and subject to change without warning.
# @return [Spec] a new instance of Spec
#
# source://toys-core//lib/toys/middleware.rb#276
def initialize(object, name, args, kwargs, block); end
# Equality check
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/middleware.rb#252
def ==(other); end
# @return [Array] the positional arguments to be passed to a middleware
# class constructor, or the empty array if there are no positional
# arguments
# @return [nil] if this spec wraps a middleware object
#
# source://toys-core//lib/toys/middleware.rb#229
def args; end
# @return [Proc] if there is a block argument to be passed to a
# middleware class constructor
# @return [nil] if there is no block argument, or this spec wraps a
# middleware object
#
# source://toys-core//lib/toys/middleware.rb#244
def block; end
# Builds a middleware for this spec, given a ModuleLookup for middleware.
#
# If this spec wraps an existing middleware object, returns that object.
# Otherwise, constructs a middleware object from the spec.
#
# @param lookup [Toys::ModuleLookup] A module lookup to resolve
# middleware names
# @return [Toys::Middleware] The middleware
#
# source://toys-core//lib/toys/middleware.rb#199
def build(lookup); end
# Equality check
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/middleware.rb#252
def eql?(other); end
# Return the hash code
#
# @return [Integer]
#
# source://toys-core//lib/toys/middleware.rb#267
def hash; end
# @return [Hash] the keyword arguments to be passed to a middleware class
# constructor, or the empty hash if there are no keyword arguments
# @return [nil] if this spec wraps a middleware object
#
# source://toys-core//lib/toys/middleware.rb#236
def kwargs; end
# @return [String, Symbol] if this spec represents a middleware name
# @return [Class] if this spec represents a middleware class
# @return [nil] if this spec wraps a middleware object
#
# source://toys-core//lib/toys/middleware.rb#221
def name; end
# @return [Toys::Middleware] if this spec wraps a middleware object
# @return [nil] if this spec represents a class to instantiate
#
# source://toys-core//lib/toys/middleware.rb#214
def object; end
end
# A stack of middleware specs, which can be applied in order to a tool.
#
# A middleware stack is separated into three groups:
#
# * {#pre_specs}, which are applied first.
# * {#default_specs}, which are applied next. The default specs are set
# when the stack is created and are generally not modified.
# * {#post_specs}, which are applied third.
#
# When adding middleware to a stack, you should normally add them to the
# pre or post specs. By default, {Stack#add} appends to the pre specs,
# inserting new middleware just before the defaults.
#
# Use {Toys::Middleware.stack} to create a middleware stack.
#
# source://toys-core//lib/toys/middleware.rb#301
class Toys::Middleware::Stack
# Internal constructor. Use {Toys::Middleware.stack} instead.
#
# @private This interface is internal and subject to change without warning.
# @return [Stack] a new instance of Stack
#
# source://toys-core//lib/toys/middleware.rb#381
def initialize(default_specs: T.unsafe(nil), pre_specs: T.unsafe(nil), post_specs: T.unsafe(nil)); end
# Equality check
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/middleware.rb#359
def ==(other); end
# Add a middleware spec to the stack, in the default location, which is
# at the end of pre_specs). See {Toys::Middleware.spec} for a description
# of the arguments you can pass.
#
# @overload add
# @overload add
# @overload add
#
# source://toys-core//lib/toys/middleware.rb#329
def add(middleware, *args, **kwargs, &block); end
# Build the middleware in this stack.
#
# @return [Array<Toys::Middleware>]
#
# source://toys-core//lib/toys/middleware.rb#349
def build(middleware_lookup); end
# The default set of middleware specs.
#
# @return [Array<Toys::Middleware:Spec>]
#
# source://toys-core//lib/toys/middleware.rb#312
def default_specs; end
# Duplicate this stack.
#
# @return [Toys::Middleware::Stack]
#
# source://toys-core//lib/toys/middleware.rb#338
def dup; end
# Equality check
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/middleware.rb#359
def eql?(other); end
# Return the hash code
#
# @return [Integer]
#
# source://toys-core//lib/toys/middleware.rb#372
def hash; end
# The middleware specs that follow the default set.
#
# @return [Array<Toys::Middleware:Spec>]
#
# source://toys-core//lib/toys/middleware.rb#318
def post_specs; end
# The middleware specs that precede the default set.
#
# @return [Array<Toys::Middleware:Spec>]
#
# source://toys-core//lib/toys/middleware.rb#306
def pre_specs; end
end
# A mixin definition. Mixin modules should include this module.
#
# A mixin is a collection of methods that are available to be called from a
# tool implementation (i.e. its run method). The mixin is added to the tool
# class, so it has access to the same methods that can be called by the tool,
# such as {Toys::Context#get}.
#
# ### Usage
#
# To create a mixin, define a module, and include this module. Then define
# the methods you want to be available.
#
# If you want to perform some initialization specific to the mixin, you can
# provide an *initializer* block and/or an *inclusion* block. These can be
# specified by calling the module methods defined in
# {Toys::Mixin::ModuleMethods}.
#
# The initializer block is called when the tool context is instantiated
# in preparation for execution. It has access to context methods such as
# {Toys::Context#get}, and can perform setup for the tool execution itself,
# such as initializing some persistent state and storing it in the tool using
# {Toys::Context#set}. The initializer block is passed any extra arguments
# that were provided to the `include` directive. Define the initializer by
# calling {Toys::Mixin::ModuleMethods#on_initialize}.
#
# The inclusion block is called in the context of your tool class when your
# mixin is included. It is also passed any extra arguments that were provided
# to the `include` directive. It can be used to issue directives to define
# tools or other objects in the DSL, or even enhance the DSL by defining DSL
# methods specific to the mixin. Define the inclusion block by calling
# {Toys::Mixin::ModuleMethods#on_include}.
#
# ### Example
#
# This is an example that implements a simple counter. Whenever the counter
# is incremented, a log message is emitted. The tool can also retrieve the
# final counter value.
#
# # Define a mixin by creating a module that includes Toys::Mixin
# module MyCounterMixin
# include Toys::Mixin
#
# # Initialize the counter. Notice that the initializer is evaluated
# # in the context of the runtime context, so has access to the runtime
# # context state.
# on_initialize do |start = 0|
# set(:counter_value, start)
# end
#
# # Mixin methods are evaluated in the runtime context and so have
# # access to the runtime context state, just as if you had defined
# # them in your tool.
# def counter_value
# get(:counter_value)
# end
#
# def increment
# set(:counter_value, counter_value + 1)
# logger.info("Incremented counter")
# end
# end
#
# Now we can use it from a tool:
#
# tool "count-up" do
# # Pass 1 as an extra argument to the mixin initializer
# include MyCounterMixin, 1
#
# def run
# # Mixin methods can be called.
# 5.times { increment }
# puts "Final value is #{counter_value}"
# end
# end
#
# source://toys-core//lib/toys/mixin.rb#80
module Toys::Mixin
mixes_in_class_methods ::Toys::Mixin::ModuleMethods
class << self
# Create a mixin module with the given block.
#
# @param block [Proc] Defines the mixin module.
# @return [Class]
#
# source://toys-core//lib/toys/mixin.rb#87
def create(&block); end
# @private
# @private
#
# source://toys-core//lib/toys/mixin.rb#149
def included(mod); end
end
end
# Methods that will be added to a mixin module object.
#
# source://toys-core//lib/toys/mixin.rb#98
module Toys::Mixin::ModuleMethods
# The inclusion proc for this mixin. This block is evaluated in the tool
# class immediately after the mixin is included, and is passed any
# arguments provided to the `include` directive.
#
# @return [Proc] The inclusion procedure for this mixin.
#
# source://toys-core//lib/toys/mixin.rb#143
def inclusion; end
# The inclusion proc for this mixin. This block is evaluated in the tool
# class immediately after the mixin is included, and is passed any
# arguments provided to the `include` directive.
#
# @return [Proc] The inclusion procedure for this mixin.
#
# source://toys-core//lib/toys/mixin.rb#143
def inclusion=(_arg0); end
# The initializer proc for this mixin. This proc is evaluated in the
# runtime context before execution, and is passed any arguments provided
# to the `include` directive. It can perform any runtime initialization
# needed by the mixin.
#
# @return [Proc] The iniitiliazer for this mixin.
#
# source://toys-core//lib/toys/mixin.rb#121
def initializer; end
# The initializer proc for this mixin. This proc is evaluated in the
# runtime context before execution, and is passed any arguments provided
# to the `include` directive. It can perform any runtime initialization
# needed by the mixin.
#
# @return [Proc] The iniitiliazer for this mixin.
#
# source://toys-core//lib/toys/mixin.rb#121
def initializer=(_arg0); end
# Set an inclusion proc for this mixin. This block is evaluated in the
# tool class immediately after the mixin is included, and is passed any
# arguments provided to the `include` directive.
#
# @param block [Proc] Sets the inclusion proc.
# @return [self]
#
# source://toys-core//lib/toys/mixin.rb#131
def on_include(&block); end
# Set the initializer for this mixin. This block is evaluated in the
# runtime context before execution, and is passed any arguments provided
# to the `include` directive. It can perform any runtime initialization
# needed by the mixin.
#
# @param block [Proc] Sets the initializer proc.
# @return [self]
#
# source://toys-core//lib/toys/mixin.rb#108
def on_initialize(&block); end
end
# A helper module that provides methods to do module lookups. This is
# used to obtain named helpers, middleware, and templates from the
# respective modules.
#
# source://toys-core//lib/toys/module_lookup.rb#9
class Toys::ModuleLookup
# Create an empty ModuleLookup
#
# @return [ModuleLookup] a new instance of ModuleLookup
#
# source://toys-core//lib/toys/module_lookup.rb#56
def initialize; end
# Add a lookup path for modules.
#
# @param path_base [String] The base require path
# @param module_base [Module] The base module, or `nil` (the default) to
# infer a default from the path base.
# @param high_priority [Boolean] If true, add to the head of the lookup
# path, otherwise add to the end.
# @return [self]
#
# source://toys-core//lib/toys/module_lookup.rb#73
def add_path(path_base, module_base: T.unsafe(nil), high_priority: T.unsafe(nil)); end
# Obtain a named module. Returns `nil` if the name is not present.
#
# @param name [String, Symbol] The name of the module to return.
# @return [Module] The specified module
#
# source://toys-core//lib/toys/module_lookup.rb#92
def lookup(name); end
class << self
# Given a require path, return the module expected to be defined.
#
# @param path [String] File path, delimited by forward slash
# @return [Module] The module loaded from that path
#
# source://toys-core//lib/toys/module_lookup.rb#42
def path_to_module(path); end
# Convert the given string to a module name. Specifically, converts
# to `UpperCamelCase`, and then to a symbol.
#
# @param str [String, Symbol] String to convert.
# @return [Symbol] Converted name
#
# source://toys-core//lib/toys/module_lookup.rb#31
def to_module_name(str); end
# Convert the given string to a path element. Specifically, converts
# to `lower_snake_case`.
#
# @param str [String, Symbol] String to convert.
# @return [String] Converted string
#
# source://toys-core//lib/toys/module_lookup.rb#18
def to_path_name(str); end
end
end
# An exception indicating that a tool has no run method.
#
# source://toys-core//lib/toys/errors.rb#13
class Toys::NotRunnableError < ::StandardError; end
# Representation of a formal positional argument
#
# source://toys-core//lib/toys/positional_arg.rb#7
class Toys::PositionalArg
# Create a PositionalArg definition.
# This argument list is subject to change. Use {Toys::PositionalArg.create}
# instead for a more stable interface.
#
# @private
# @return [PositionalArg] a new instance of PositionalArg
#
# source://toys-core//lib/toys/positional_arg.rb#153
def initialize(key, type, acceptor, default, completion, desc, long_desc, display_name); end
# The effective acceptor.
#
# @return [Toys::Acceptor::Base]
#
# source://toys-core//lib/toys/positional_arg.rb#54
def acceptor; end
# The effective acceptor.
#
# @return [Toys::Acceptor::Base]
#
# source://toys-core//lib/toys/positional_arg.rb#54
def acceptor=(_arg0); end
# 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.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
# @return [self]
#
# source://toys-core//lib/toys/positional_arg.rb#141
def append_long_desc(long_desc); end
# The proc that determines shell completions for the value.
#
# @return [Proc, Toys::Completion::Base]
#
# source://toys-core//lib/toys/positional_arg.rb#66
def completion; end
# The default value, which may be `nil`.
#
# @return [Object]
#
# source://toys-core//lib/toys/positional_arg.rb#60
def default; end
# The short description string.
#
# When reading, this is always returned as a {Toys::WrappableString}.
#
# When setting, the description may be provided as any of the following:
# * A {Toys::WrappableString}.
# * A normal String, which will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String, which will be transformed into a
# {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Toys::WrappableString]
#
# source://toys-core//lib/toys/positional_arg.rb#83
def desc; end
# Set the short description string.
#
# See {#desc} for details.
#
# @param desc [Toys::WrappableString, String, Array<String>]
#
# source://toys-core//lib/toys/positional_arg.rb#117
def desc=(desc); end
# The displayable name.
#
# @return [String]
#
# source://toys-core//lib/toys/positional_arg.rb#108
def display_name; end
# The displayable name.
#
# @return [String]
#
# source://toys-core//lib/toys/positional_arg.rb#108
def display_name=(_arg0); end
# The key for this arg.
#
# @return [Symbol]
#
# source://toys-core//lib/toys/positional_arg.rb#42
def key; end
# The long description strings.
#
# When reading, this is returned as an Array of {Toys::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 {Toys::WrappableString} representing one line.
# * A normal String representing a line. This will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String representing a line. This will be transformed into
# a {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Array<Toys::WrappableString>]
#
# source://toys-core//lib/toys/positional_arg.rb#102
def long_desc; end
# Set the long description strings.
#
# See {#long_desc} for details.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
#
# source://toys-core//lib/toys/positional_arg.rb#128
def long_desc=(long_desc); end
# Type of this argument.
#
# @return [:required, :optional, :remaining]
#
# source://toys-core//lib/toys/positional_arg.rb#48
def type; end
class << self
# Create a PositionalArg definition.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param type [Symbol] The type of arg. Valid values are `:required`,
# `:optional`, and `:remaining`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. See {Toys::Acceptor.create} for recognized formats. Optional.
# If not specified, defaults to {Toys::Acceptor::DEFAULT}.
# @param complete [Object] A specifier for shell tab completion. See
# {Toys::Completion.create} for recognized formats.
# @param display_name [String] A name to use for display (in help text and
# error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::ToolDefintion#desc} for a
# description of the allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::ToolDefintion#long_desc}
# for a description of the allowed formats. (But note that this param
# takes an Array of description lines, rather than a series of
# arguments.) Defaults to the empty array.
# @return [Toys::PositionalArg]
#
# source://toys-core//lib/toys/positional_arg.rb#32
def create(key, type, accept: T.unsafe(nil), default: T.unsafe(nil), complete: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), display_name: T.unsafe(nil)); end
end
end
# A settings class defines the structure of application settings, i.e. the
# various fields that can be set, and their types. You can define a settings
# structure by subclassing this base class, and using the provided methods.
#
# ### Attributes
#
# To define an attribute, use the {Settings.settings_attr} declaration.
#
# Example:
#
# class ServiceSettings < Toys::Settings
# settings_attr :endpoint, default: "api.example.com"
# end
#
# my_settings = ServiceSettings.new
# my_settings.endpoint_set? # => false
# my_settings.endpoint # => "api.example.com"
# my_settings.endpoint = "rest.example.com"
# my_settings.endpoint_set? # => true
# my_settings.endpoint # => "rest.example.com"
# my_settings.endpoint_unset!
# my_settings.endpoint_set? # => false
# my_settings.endpoint # => "api.example.com"
#
# An attribute has a name, a default value, and a type specification. The
# name is used to define methods for getting and setting the attribute. The
# default is returned if no value is set. (See the section below on parents
# and defaults for more information.) The type specification governs what
# values are allowed. (See the section below on type specifications.)
#
# Attribute names must start with an ascii letter, and may contain only ascii
# letters, digits, and underscores. Unlike method names, they may not include
# non-ascii unicode characters, nor may they end with `!` or `?`.
# Additionally, the name `method_missing` is not allowed because of its
# special behavior in Ruby.
#
# Each attribute defines four methods: a getter, a setter, an unsetter, and a
# set detector. In the above example, the attribute named `:endpoint` creates
# the following four methods:
#
# * `endpoint` - retrieves the attribute value, or a default if not set.
# * `endpoint=(value)` - sets a new attribute value.
# * `endpoint_unset!` - unsets the attribute, reverting to a default.
# * `endpoint_set?` - returns a boolean, whether the attribute is set.
#
# ### Groups
#
# A group is a settings field that itself is a Settings object. You can use
# it to group settings fields in a hierarchy.
#
# Example:
#
# class ServiceSettings < Toys::Settings
# settings_attr :endpoint, default: "api.example.com"
# settings_group :service_flags do
# settings_attr :verbose, default: false
# settings_attr :use_proxy, default: false
# end
# end
#
# my_settings = ServiceSettings.new
# my_settings.service_flags.verbose # => false
# my_settings.service_flags.verbose = true
# my_settings.service_flags.verbose # => true
# my_settings.endpoint # => "api.example.com"
#
# You can define a group inline, as in the example above, or create an
# explicit settings class and use it for the group. For example:
#
# class Flags < Toys::Settings
# settings_attr :verbose, default: false
# settings_attr :use_proxy, default: false
# end
# class ServiceSettings < Toys::Settings
# settings_attr :endpoint, default: "api.example.com"
# settings_group :service_flags, Flags
# end
#
# my_settings = ServiceSettings.new
# my_settings.service_flags.verbose = true
#
# If the module enclosing a subclass of `Settings` is itself a subclass of
# `Settings`, then the class is automatically added to its enclosing class as
# a group. For example:
#
# class ServiceSettings < Toys::Settings
# settings_attr :endpoint, default: "api.example.com"
# # Automatically adds this as the group service_flags.
# # The name is inferred (snake_cased) from the class name.
# class ServiceFlags < Toys::Settings
# settings_attr :verbose, default: false
# settings_attr :use_proxy, default: false
# end
# end
#
# my_settings = ServiceSettings.new
# my_settings.service_flags.verbose = true
#
# ### Type specifications
#
# A type specification is a restriction on the types of values allowed for a
# settings field. Every attribute has a type specification. You can set it
# explicitly by providing a `:type` argument or a block. If a type
# specification is not provided explicitly, it is inferred from the default
# value of the attribute.
#
# Type specifications can be any of the following:
#
# * A Module, restricting values to those that include the module.
#
# For example, a type specification of `Enumerable` would accept `[123]`
# but not `123`.
#
# * A Class, restricting values to that class or any subclass.
#
# For example, a type specification of `Time` would accept `Time.now` but
# not `DateTime.now`.
#
# Note that some classes will convert (i.e. parse) strings. For example,
# a type specification of `Integer` will accept the string `"-123"`` and
# convert it to the value `-123`. Classes that support parsing include:
#
# * `Date`
# * `DateTime`
# * `Float`
# * `Integer`
# * `Regexp`
# * `Symbol`
# * `Time`
#
# * A Regexp, restricting values to strings matching the regexp.
#
# For example, a type specification of `/^\w+$/` would match `"abc"` but
# not `"abc!"`.
#
# * A Range, restricting values to objects that fall in the range and are
# of the same class (or a subclass) as the endpoints. String values are
# accepted if they can be converted to the endpoint class as specified by
# a class type specification.
#
# For example, a type specification of `(1..5)` would match `5` but not
# `6`. It would also match `"5"` because the String can be parsed into an
# Integer in the range.
#
# * A specific value, any Symbol, String, Numeric, or the values `nil`,
# `true`, or `false`, restricting the value to only that given value.
#
# For example, a type specification of `:foo` would match `:foo` but not
# `:bar`.
#
# (It might not seem terribly useful to have an attribute that can take
# only one value, but this type is generally used as part of a union
# type, described below, to implement an enumeration.)
#
# * An Array representing a union type, each of whose elements is one of
# the above types. Values are accepted if they match any of the elements.
#
# For example, a type specification of `[:a, :b :c]` would match `:a` but
# not `"a"`. Similarly, a type specification of `[String, Integer, nil]`
# would match `"hello"`, `123`, or `nil`, but not `123.4`.
#
# * A Proc that takes the proposed value and returns either the value if it
# is legal, the converted value if it can be converted to a legal value,
# or the constant {Toys::Settings::ILLEGAL_VALUE} if it cannot be
# converted to a legal value. You may also pass a block to
# `settings_attr` to set a Proc type specification.
#
# * A {Toys::Settings::Type} that checks and converts values.
#
# If you do not explicitly provide a type specification, one is inferred from
# the attribute's default value. The rules are:
#
# * If the default value is `true` or `false`, then the type specification
# inferred is `[true, false]`.
#
# * If the default value is `nil` or not provided, then the type
# specification allows any object (i.e. is equivalent to `Object`).
#
# * Otherwise, the type specification allows any value of the same class as
# the default value. For example, if the default value is `""`, the
# effective type specification is `String`.
#
# Examples:
#
# class ServiceSettings < Toys::Settings
# # Allows only strings because the default is a string.
# settings_attr :endpoint, default: "example.com"
# end
#
# class ServiceSettings < Toys::Settings
# # Allows strings or nil.
# settings_attr :endpoint, default: "example.com", type: [String, nil]
# end
#
# class ServiceSettings < Toys::Settings
# # Raises ArgumentError because the default is nil, which does not
# # match the type specification. (You should either allow nil
# # explicitly with `type: [String, nil]` or set the default to a
# # suitable string such as the empty string "".)
# settings_attr :endpoint, type: String
# end
#
# ### Settings parents
#
# A settings object can have a "parent" which provides the values if they are
# not set in the settings object. This lets you organize settings as
# "defaults" and "overrides". A parent settings object provides the defaults,
# and a child can selectively override certain values.
#
# To set the parent for a settings object, pass it as the argument to the
# Settings constructor. When a field in a settings object is queried, it
# looks up the value as follows:
#
# * If a field value is explicitly set in the settings object, that value
# is returned.
# * If the field is not set in the settings object, but the settings object
# has a parent, the parent is queried. If that parent also does not have
# a value for the field, it may query its parent in turn, and so forth.
# * If we encounter a root settings with no parent, and still no value is
# set for the field, the default for the *original* setting is returned.
#
# Example:
#
# class MySettings < Toys::Settings
# settings_attr :str, default: "default"
# end
#
# root_settings = MySettings.new
# child_settings = MySettings.new(root_settings)
# child_settings.str # => "default"
# root_settings.str = "value_from_root"
# child_settings.str # => "value_from_root"
# child_settings.str = "value_from_child"
# child_settings.str # => "value_from_child"
# child_settings.str_unset!
# child_settings.str # => "value_from_root"
# root_settings.str_unset!
# child_settings.str # => "default"
#
# Parents are honored through groups as well. For example:
#
# class MySettings < Toys::Settings
# settings_group :flags do
# settings_attr :verbose, default: false
# settings_attr :force, default: false
# end
# end
#
# root_settings = MySettings.new
# child_settings = MySettings.new(root_settings)
# child_settings.flags.verbose # => false
# root_settings.flags.verbose = true
# child_settings.flags.verbose # => true
#
# Usually, a settings and its parent (and its parent, and so forth) should
# have the same class. This guarantees that they define the same fields with
# the same type specifications. However, this is not required. If a parent
# does not define a particular field, it is treated as if that field is
# unset, and lookup proceeds to its parent. To illustrate:
#
# class Settings1 < Toys::Settings
# settings_attr :str, default: "default"
# end
# class Settings2 < Toys::Settings
# end
#
# root_settings = Settings1.new
# child_settings = Settings2.new(root_settings) # does not have str
# grandchild_settings = Settings1.new(child_settings)
#
# grandchild_settings.str # => "default"
# root_settings.str = "value_from_root"
# grandchild_settings.str # => "value_from_root"
#
# Type specifications are enforced when falling back to parent values. If a
# parent provides a value that is not allowed, it is treated as if the field
# is unset, and lookup proceeds to its parent.
#
# class Settings1 < Toys::Settings
# settings_attr :str, default: "default" # type spec is String
# end
# class Settings2 < Toys::Settings
# settings_attr :str, default: 0 # type spec is Integer
# end
#
# root_settings = Settings1.new
# child_settings = Settings2.new(root_settings)
# grandchild_settings = Settings1.new(child_settings)
#
# grandchild_settings.str # => "default"
# child_settings.str = 123 # does not match grandchild's type
# root_settings.str = "value_from_root"
# grandchild_settings.str # => "value_from_root"
#
# source://toys-core//lib/toys/settings.rb#299
class Toys::Settings
# Create a settings instance.
#
# @param parent [Settings, nil] Optional parent settings.
# @return [Settings] a new instance of Settings
#
# source://toys-core//lib/toys/settings.rb#580
def initialize(parent: T.unsafe(nil)); end
# Internal get field value, with fallback to parents.
#
# @private
#
# source://toys-core//lib/toys/settings.rb#679
def get!(field); end
# Load the given hash of data into this settings object.
#
# @param data [Hash] The data as a hash of key-value pairs.
# @param raise_on_failure [boolean] If `true`, raises an exception on the
# first error encountered. If `false`, continues parsing and returns an
# array of the errors raised.
# @return [Array<FieldError>] An array of errors.
#
# source://toys-core//lib/toys/settings.rb#599
def load_data!(data, raise_on_failure: T.unsafe(nil)); end
# Parse the given JSON string and load the data into this settings object.
#
# @param str [String] The JSON-formatted string.
# @param raise_on_failure [boolean] If `true`, raises an exception on the
# first error encountered. If `false`, continues parsing and returns an
# array of the errors raised.
# @return [Array<FieldError>] An array of errors.
#
# source://toys-core//lib/toys/settings.rb#656
def load_json!(str, raise_on_failure: T.unsafe(nil), **json_opts); end
# Parse the given JSON file and load the data into this settings object.
#
# @param filename [String] The path to the JSON-formatted file.
# @param raise_on_failure [boolean] If `true`, raises an exception on the
# first error encountered. If `false`, continues parsing and returns an
# array of the errors raised.
# @return [Array<FieldError>] An array of errors.
#
# source://toys-core//lib/toys/settings.rb#670
def load_json_file!(filename, raise_on_failure: T.unsafe(nil), **json_opts); end
# Parse the given YAML string and load the data into this settings object.
#
# @param str [String] The YAML-formatted string.
# @param raise_on_failure [boolean] If `true`, raises an exception on the
# first error encountered. If `false`, continues parsing and returns an
# array of the errors raised.
# @return [Array<FieldError>] An array of errors.
#
# source://toys-core//lib/toys/settings.rb#629
def load_yaml!(str, raise_on_failure: T.unsafe(nil)); end
# Parse the given YAML file and load the data into this settings object.
#
# @param filename [String] The path to the YAML-formatted file.
# @param raise_on_failure [boolean] If `true`, raises an exception on the
# first error encountered. If `false`, continues parsing and returns an
# array of the errors raised.
# @return [Array<FieldError>] An array of errors.
#
# source://toys-core//lib/toys/settings.rb#643
def load_yaml_file!(filename, raise_on_failure: T.unsafe(nil)); end
# Internal set field value, with validation.
#
# @private
#
# source://toys-core//lib/toys/settings.rb#707
def set!(field, value); end
# Internal determine if the field is set locally.
#
# @private
# @return [Boolean]
#
# source://toys-core//lib/toys/settings.rb#719
def set?(field); end
# Internal unset field value.
#
# @private
#
# source://toys-core//lib/toys/settings.rb#730
def unset!(field); end
class << self
# Returns the fields hash. This is shared between the settings class and
# all its instances.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/settings.rb#841
def fields; end
# When this base class is inherited, if its enclosing module is also a
# Settings, add the new class as a group in the enclosing class.
#
# @private
#
# source://toys-core//lib/toys/settings.rb#851
def inherited(subclass); end
# Add an attribute field.
#
# @param name [Symbol, String] The name of the attribute.
# @param default [Object] Optional. The final default value if the field
# is not set in this settings object or any of its ancestors. If not
# provided, `nil` is used.
# @param type [Object] Optional. The type specification. If not provided,
# one is inferred from the default value.
#
# source://toys-core//lib/toys/settings.rb#796
def settings_attr(name, default: T.unsafe(nil), type: T.unsafe(nil), &block); end
# Add a group field.
#
# Specify the group's structure by passing either a class (which must
# subclass Settings) or a block (which will be called on the group's
# class.)
#
# @param name [Symbol, String] The name of the group.
# @param klass [Class] Optional. The class of the group (which must
# subclass Settings). If not present, an anonymous subclass will be
# created, and you must provide a block to configure it.
#
# source://toys-core//lib/toys/settings.rb#819
def settings_group(name, klass = T.unsafe(nil), &block); end
private
# source://toys-core//lib/toys/settings.rb#887
def create_getter(field); end
# source://toys-core//lib/toys/settings.rb#899
def create_set_detect(field); end
# source://toys-core//lib/toys/settings.rb#893
def create_setter(field); end
# source://toys-core//lib/toys/settings.rb#905
def create_unsetter(field); end
# source://toys-core//lib/toys/settings.rb#874
def interpret_name(name); end
# source://toys-core//lib/toys/settings.rb#870
def to_class_name(str); end
# source://toys-core//lib/toys/settings.rb#864
def to_field_name(str); end
end
end
# A special type specification indicating infer from the default value.
#
# source://toys-core//lib/toys/settings.rb#304
Toys::Settings::DEFAULT_TYPE = T.let(T.unsafe(nil), Object)
# @private
#
# source://toys-core//lib/toys/settings.rb#746
class Toys::Settings::Field
# @return [Field] a new instance of Field
#
# source://toys-core//lib/toys/settings.rb#747
def initialize(container, name, type_spec, default_or_group_class); end
# Returns the value of attribute container.
#
# source://toys-core//lib/toys/settings.rb#766
def container; end
# Returns the value of attribute default.
#
# source://toys-core//lib/toys/settings.rb#769
def default; end
# @return [Boolean]
#
# source://toys-core//lib/toys/settings.rb#772
def group?; end
# Returns the value of attribute group_class.
#
# source://toys-core//lib/toys/settings.rb#770
def group_class; end
# Returns the value of attribute name.
#
# source://toys-core//lib/toys/settings.rb#767
def name; end
# Returns the value of attribute type.
#
# source://toys-core//lib/toys/settings.rb#768
def type; end
# source://toys-core//lib/toys/settings.rb#776
def validate(value); end
end
# Error raised when a value does not match the type constraint.
#
# source://toys-core//lib/toys/settings.rb#309
class Toys::Settings::FieldError < ::StandardError
# @private This interface is internal and subject to change without warning.
# @return [FieldError] a new instance of FieldError
#
# source://toys-core//lib/toys/settings.rb#337
def initialize(value, settings_class, field_name, type_description); end
# The field that rejected the value
#
# @return [Symbol]
#
# source://toys-core//lib/toys/settings.rb#326
def field_name; end
# The settings class that rejected the value
#
# @return [Class]
#
# source://toys-core//lib/toys/settings.rb#320
def settings_class; end
# A description of the type constraint, or nil if the field didn't exist.
#
# @return [String, nil]
#
# source://toys-core//lib/toys/settings.rb#332
def type_description; end
# The value that did not match
#
# @return [Object]
#
# source://toys-core//lib/toys/settings.rb#314
def value; end
end
# A special value indicating a type check failure.
#
# source://toys-core//lib/toys/settings.rb#301
Toys::Settings::ILLEGAL_VALUE = T.let(T.unsafe(nil), Object)
# @private
#
# source://toys-core//lib/toys/settings.rb#739
Toys::Settings::SETTINGS_TYPE = T.let(T.unsafe(nil), Toys::Settings::Type)
# A type object that checks values.
#
# A Type includes a description string and a testing function. The testing
# function takes a proposed value and returns either the value itself if it
# is valid, a converted value if the value can be converted to a valid
# value, or {ILLEGAL_VALUE} if the type check failed.
#
# source://toys-core//lib/toys/settings.rb#361
class Toys::Settings::Type
# Create a new Type.
#
# @param description [String] Name of the type.
# @param block [Proc] A testing function.
# @return [Type] a new instance of Type
#
# source://toys-core//lib/toys/settings.rb#368
def initialize(description, &block); end
# Test a value, possibly converting to a legal value.
#
# @param val [Object] The value to be tested.
# @return [Object] The validated value, the value converted to a legal
# value, or {ILLEGAL_VALUE} if the type check is unsuccessful.
#
# source://toys-core//lib/toys/settings.rb#386
def call(val); end
# The name of the type.
#
# @return [String]
#
# source://toys-core//lib/toys/settings.rb#377
def description; end
class << self
# Create and return a Type given a default value. See the {Settings}
# class documentation for the rules.
#
# @param value [Object]
# @return [Type]
#
# source://toys-core//lib/toys/settings.rb#427
def for_default_value(value); end
# Create and return a Type given a type specification. See the
# {Settings} class documentation for valid type specifications.
#
# @param type_spec [Object]
# @raise [ArgumentError] if the type specification is invalid.
# @return [Type]
#
# source://toys-core//lib/toys/settings.rb#399
def for_type_spec(type_spec); end
private
# source://toys-core//lib/toys/settings.rb#486
def convert(val, klass); end
# source://toys-core//lib/toys/settings.rb#440
def for_module(klass); end
# source://toys-core//lib/toys/settings.rb#446
def for_range(range); end
# source://toys-core//lib/toys/settings.rb#454
def for_regexp(regexp); end
# source://toys-core//lib/toys/settings.rb#480
def for_scalar(value); end
# source://toys-core//lib/toys/settings.rb#462
def for_union(array); end
end
end
# @private
#
# source://toys-core//lib/toys/settings.rb#564
Toys::Settings::Type::CONVERTERS = T.let(T.unsafe(nil), Hash)
# Information about the source of a tool, such as the file, git repository,
# or block that defined it.
#
# This object represents a source of tool information and definitions. Such a
# source could include:
#
# * A toys directory
# * A single toys file
# * A file or directory loaded from git
# * A config block passed directly to the CLI
# * A tool block within a toys file
#
# The SourceInfo provides information such as the tool's context directory,
# and locates data and lib directories appropriate to the tool. It also
# locates the tool's source code so it can be reported when an error occurs.
#
# Each tool has a unique SourceInfo with all the information specific to that
# tool. Additionally, SourceInfo objects are arranged in a containment
# hierarchy. For example, a SourceInfo object representing a toys files could
# have a parent representing a toys directory, and an object representing a
# tool block could have a parent representing an enclosing block or a file.
#
# Child SourceInfo objects generally inherit some attributes of their parent.
# For example, the `.toys` directory in a project directory defines the
# context directory as that project directory. Then all tools defined under
# that directory will share that context directory, so all SourceInfo objects
# descending from that root will inherit that value (unless it's changed
# explicitly).
#
# SourceInfo objects can be obtained in the DSL from
# {Toys::DSL::Tool#source_info} or at runtime by getting the
# {Toys::Context::Key::TOOL_SOURCE} key. However, they are created internally
# by the Loader and should not be created manually.
#
# source://toys-core//lib/toys/source_info.rb#39
class Toys::SourceInfo
# Create a SourceInfo.
#
# @private This interface is internal and subject to change without warning.
# @return [SourceInfo] a new instance of SourceInfo
#
# source://toys-core//lib/toys/source_info.rb#194
def initialize(parent, priority, context_directory, source_type, source_path, source_proc, git_remote, git_path, git_commit, source_name, data_dir_name, lib_dir_name); end
# Create a child SourceInfo with an absolute path.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#243
def absolute_child(child_path, source_name: T.unsafe(nil)); end
# Apply all lib paths in order from high to low priority
#
# @return [self]
#
# source://toys-core//lib/toys/source_info.rb#183
def apply_lib_paths; end
# The context directory path (normally the directory containing the
# toplevel toys file or directory).
#
# This is not affected by setting a custom context directory for a tool.
#
# @return [String] The context directory path.
# @return [nil] if there is no context directory (perhaps because the root
# source was a block)
#
# source://toys-core//lib/toys/source_info.rb#74
def context_directory; end
# Locate the given data file or directory and return an absolute path.
#
# @param path [String] The relative path to find
# @param type [nil, :file, :directory] Type of file system object to find,
# or nil (the default) to return any type.
# @return [String] Absolute path of the resulting data.
# @return [nil] if the data was not found.
#
# source://toys-core//lib/toys/source_info.rb#163
def find_data(path, type: T.unsafe(nil)); end
# Create a child SourceInfo with a git source.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#255
def git_child(child_git_remote, child_git_path, child_git_commit, child_path, source_name: T.unsafe(nil)); end
# The git commit. This is set if the source, or one of its ancestors, comes
# from git.
#
# @return [String] The git commit.
# @return [nil] if this source is not fron git.
#
# source://toys-core//lib/toys/source_info.rb#144
def git_commit; end
# The git path. This is set if the source, or one of its ancestors, comes
# from git.
#
# @return [String] The git path. This could be the empty string.
# @return [nil] if this source is not fron git.
#
# source://toys-core//lib/toys/source_info.rb#135
def git_path; end
# The git remote. This is set if the source, or one of its ancestors, comes
# from git.
#
# @return [String] The git remote
# @return [nil] if this source is not fron git.
#
# source://toys-core//lib/toys/source_info.rb#126
def git_remote; end
# The parent of this SourceInfo.
#
# @return [Toys::SourceInfo] The parent.
# @return [nil] if this SourceInfo is a root.
#
# source://toys-core//lib/toys/source_info.rb#46
def parent; end
# The priority of tools defined by this source. Higher values indicate a
# higher priority. Lower priority values could be negative.
#
# @return [Integer] The priority.
#
# source://toys-core//lib/toys/source_info.rb#62
def priority; end
# Create a proc child SourceInfo
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#270
def proc_child(child_proc, source_name: T.unsafe(nil)); end
# Create a child SourceInfo relative to the parent path.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#219
def relative_child(filename, source_name: T.unsafe(nil)); end
# The root ancestor of this SourceInfo. This generally represents a source
# that was added directly to a CLI in code.
#
# @return [Toys::SourceInfo] The root ancestor.
#
# source://toys-core//lib/toys/source_info.rb#54
def root; end
# The source, which may be a path or a proc depending on the {#source_type}.
#
# @return [String] Path to the source file or directory.
# @return [Proc] The block serving as the source.
#
# source://toys-core//lib/toys/source_info.rb#82
def source; end
# A user-visible name of this source.
#
# @return [String]
#
# source://toys-core//lib/toys/source_info.rb#151
def source_name; end
# The path of the current source file or directory.
#
# This could be set even if {#source_type} is `:proc`, if that proc is
# defined within a toys file. The only time this is not set is if the
# source is added directly to a CLI in a code block.
#
# @return [String] The source path
# @return [nil] if this source has no file system path.
#
# source://toys-core//lib/toys/source_info.rb#109
def source_path; end
# The source proc. This is set if {#source_type} is `:proc`.
#
# @return [Proc] The source proc
# @return [nil] if this source has no proc.
#
# source://toys-core//lib/toys/source_info.rb#117
def source_proc; end
# The type of source. This could be:
#
# * `:file`, representing a single toys file. The {#source} will be the
# filesystem path to that file.
# * `:directory`, representing a toys directory. The {#source} will be the
# filesystem path to that directory.
# * `:proc`, representing a proc, which could be a toplevel block added
# directly to a CLI, a `tool` block within a toys file, or a block within
# another block. The {#source} will be the proc itself.
#
# @return [:file, :directory, :proc]
#
# source://toys-core//lib/toys/source_info.rb#97
def source_type; end
# A user-visible name of this source.
#
# @return [String]
#
# source://toys-core//lib/toys/source_info.rb#151
def to_s; end
private
# source://toys-core//lib/toys/source_info.rb#357
def find_special_dir(dir_name); end
class << self
# Check a path and determine the canonical path and type.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#335
def check_path(path, lenient); end
# Create a root source info for a cached git repo.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#304
def create_git_root(git_remote, git_path, git_commit, source_path, priority, context_directory: T.unsafe(nil), data_dir_name: T.unsafe(nil), lib_dir_name: T.unsafe(nil), source_name: T.unsafe(nil)); end
# Create a root source info for a file path.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#282
def create_path_root(source_path, priority, context_directory: T.unsafe(nil), data_dir_name: T.unsafe(nil), lib_dir_name: T.unsafe(nil), source_name: T.unsafe(nil)); end
# Create a root source info for a proc.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/source_info.rb#320
def create_proc_root(source_proc, priority, context_directory: T.unsafe(nil), data_dir_name: T.unsafe(nil), lib_dir_name: T.unsafe(nil), source_name: T.unsafe(nil)); end
end
end
# Namespace for standard middleware classes.
#
# These middleware are provided by Toys-Core and can be referenced by name
# when creating a {Toys::CLI}.
#
# source://toys-core//lib/toys-core.rb#70
module Toys::StandardMiddleware
class << self
# @private
#
# source://toys-core//lib/toys-core.rb#79
def append_common_flag_group(tool); end
end
end
# @private
#
# source://toys-core//lib/toys-core.rb#74
Toys::StandardMiddleware::COMMON_FLAG_GROUP = T.let(T.unsafe(nil), Symbol)
# Namespace for standard mixin classes.
#
# These mixins are provided by Toys-Core and can be included by name by
# passing a symbol to {Toys::DSL::Tool#include}.
#
# source://toys-core//lib/toys-core.rb#92
module Toys::StandardMixins; end
# A template definition. Template classes should include this module.
#
# A template is a configurable set of DSL code that can be run in a toys
# configuration to automate tool defintion. For example, toys provides a
# "minitest" template that generates a "test" tool that invokes minitest.
# Templates will often support configuration; for example the minitest
# template lets you configure the paths to the test files.
#
# ### Usage
#
# To create a template, define a class and include this module.
# The class defines the "configuration" of the template. If your template
# has options/parameters, you should provide a constructor, and methods
# appropriate to edit those options. The arguments given to the
# {Toys::DSL::Tool#expand} method are passed to your constructor, and your
# template object is passed to any block given to {Toys::DSL::Tool#expand}.
#
# Next, in your template class, call the `on_expand` method, which is defined
# in {Toys::Template::ClassMethods#on_expand}. Pass this a block which
# defines the implementation of the template. Effectively, the contents of
# this block are "inserted" into the user's configuration. The template
# object is passed to the block so you have access to the template options.
#
# ### Example
#
# This is a simple template that generates a "hello" tool. The tool simply
# prints a `"Hello, #{name}!"` greeting. The name is set as a template
# option; it is defined when the template is expanded in a toys
# configuration.
#
# # Define a template by creating a class that includes Toys::Template.
# class MyHelloTemplate
# include Toys::Template
#
# # A user of the template may pass an optional name as a parameter to
# # `expand`, or leave it as the default of "world".
# def initialize(name: "world")
# @name = name
# end
#
# # The template is passed to the expand block, so a user of the
# # template may also call this method to set the name.
# attr_accessor :name
#
# # The following block is inserted when the template is expanded.
# on_expand do |template|
# desc "Prints a greeting to #{template.name}"
# tool "templated-greeting" do
# to_run do
# puts "Hello, #{template.name}!"
# end
# end
# end
# end
#
# Now you can use the template in your `.toys.rb` file like this:
#
# expand(MyHelloTemplate, name: "rubyists")
#
# or alternately:
#
# expand(MyHelloTemplate) do |template|
# template.name = "rubyists"
# end
#
# And it will create a tool called "templated-greeting".
#
# source://toys-core//lib/toys/template.rb#72
module Toys::Template
include ::Toys::Context::Key
mixes_in_class_methods ::Toys::Template::ClassMethods
class << self
# Create a template class with the given block.
#
# @param block [Proc] Defines the template class.
# @return [Class]
#
# source://toys-core//lib/toys/template.rb#79
def create(&block); end
# @private
# @private
#
# source://toys-core//lib/toys/template.rb#118
def included(mod); end
end
end
# Class methods that will be added to a template class.
#
# source://toys-core//lib/toys/template.rb#90
module Toys::Template::ClassMethods
# The template expansion proc. This proc is passed the template object,
# and is evaluted in the tool class. It should invoke directives to
# create tools and other objects.
#
# @return [Proc] The expansion of this template.
#
# source://toys-core//lib/toys/template.rb#112
def expansion; end
# The template expansion proc. This proc is passed the template object,
# and is evaluted in the tool class. It should invoke directives to
# create tools and other objects.
#
# @return [Proc] The expansion of this template.
#
# source://toys-core//lib/toys/template.rb#112
def expansion=(_arg0); end
# Define how to expand this template. The given block is passed the
# template object, and is evaluated in the tool class. It should invoke
# directives to create tools and other objects.
#
# @param block [Proc] The expansion of this template.
# @return [self]
#
# source://toys-core//lib/toys/template.rb#99
def on_expand(&block); end
# Define how to expand this template. The given block is passed the
# template object, and is evaluated in the tool class. It should invoke
# directives to create tools and other objects.
#
# @param block [Proc] The expansion of this template.
# @return [self]
#
# source://toys-core//lib/toys/template.rb#99
def to_expand(&block); end
end
# Base class for defining tools
#
# This base class provides an alternative to the {Toys::DSL::Tool#tool}
# directive for defining tools in the Toys DSL. Creating a subclass of
# `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
# name. Subclasses can be created only in the context of a tool configuration
# DSL. Furthermore, a class-defined tool can be created only at the top level
# of a configuration file, or within another class-defined tool. It cannot
# be a subtool of a tool block.
#
# ### Example
#
# class FooBar < Toys::Tool
# desc "This is a tool called foo-bar"
#
# def run
# puts "foo-bar called"
# end
# end
#
# source://toys-core//lib/toys/dsl/base.rb#77
class Toys::Tool < ::Toys::Context
class << self
# @private
# @private
#
# source://toys-core//lib/toys/dsl/base.rb#81
def inherited(tool_class); end
end
end
# 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.
#
# source://toys-core//lib/toys/tool_definition.rb#11
class Toys::ToolDefinition
# Create a new tool.
# Should be created only from the DSL via the Loader.
#
# @private This interface is internal and subject to change without warning.
# @return [ToolDefinition] a new instance of ToolDefinition
#
# source://toys-core//lib/toys/tool_definition.rb#219
def initialize(parent, full_name, priority, source_root, middleware_stack, middleware_lookup, tool_class = T.unsafe(nil)); end
# Add a named acceptor to the tool. This acceptor may be refereneced by
# name when adding a flag or an arg. See {Toys::Acceptor.create} for
# detailed information on how to specify an acceptor.
#
# @param name [String] The name of the acceptor.
# @param acceptor [Toys::Acceptor::Base, Object] The acceptor to add. You
# can provide either an acceptor object, or a spec understood by
# {Toys::Acceptor.create}.
# @param type_desc [String] Type description string, shown in help.
# Defaults to the acceptor name.
# @param block [Proc] Optional block used to create an acceptor. See
# {Toys::Acceptor.create}.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#827
def add_acceptor(name, acceptor = T.unsafe(nil), type_desc: T.unsafe(nil), &block); end
# Add a named completion proc to this tool. The completion may be
# referenced by name when adding a flag or an arg. See
# {Toys::Completion.create} for detailed information on how to specify a
# completion.
#
# @param name [String] The name of the completion.
# @param completion [Proc, Toys::Completion::Base, Object] The completion to
# add. You can provide either a completion object, or a spec understood
# by {Toys::Completion.create}.
# @param options [Hash] Additional options to pass to the completion.
# @param block [Proc] Optional block used to create a completion. See
# {Toys::Completion.create}.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#874
def add_completion(name, completion = T.unsafe(nil), **options, &block); end
# 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.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param flags [Array<String>] The flags in OptionParser format. If empty,
# a flag will be inferred from the key.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, or one of the default acceptors provided by OptionParser.
# Optional. If not specified, accepts any value as a string.
# @param default [Object] The default value. This is the value that will
# be set in the context if this flag is not provided on the command
# line. Defaults to `nil`.
# @param handler [Proc, nil, :set, :push] An optional handler for
# setting/updating the value. A handler is a proc taking two
# arguments, the given value and the previous value, returning the
# new value that should be set. You may also specify a predefined
# named handler. The `:set` handler (the default) replaces the
# previous value (effectively `-> (val, _prev) { val }`). The
# `:push` handler expects the previous value to be an array and
# pushes the given value onto it; it should be combined with setting
# `default: []` and is intended for "multi-valued" flags.
# @param complete_flags [Object] A specifier for shell tab completion
# for flag names associated with this flag. By default, a
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
# names as completion candidates. To customize completion, set this to
# a hash of options to pass to the constructor for
# {Toys::Flag::DefaultCompletion}, or pass any other spec recognized
# by {Toys::Completion.create}.
# @param complete_values [Object] A specifier for shell tab completion
# for flag values associated with this flag. Pass any spec
# recognized by {Toys::Completion.create}.
# @param report_collisions [true, false] Raise an exception if a flag is
# requested that is already in use or marked as disabled. Default is
# true.
# @param group [Toys::FlagGroup, String, Symbol, nil] Group for
# this flag. You may provide a group name, a FlagGroup object, or
# `nil` which denotes the default group.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the flag. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag. See {Toys::ToolDefinition#long_desc}
# for a description of allowed formats. Defaults to the empty array.
# @param display_name [String] A display name for this flag, used in help
# text and error messages.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1052
def add_flag(key, flags = T.unsafe(nil), accept: T.unsafe(nil), default: T.unsafe(nil), handler: T.unsafe(nil), complete_flags: T.unsafe(nil), complete_values: T.unsafe(nil), report_collisions: T.unsafe(nil), group: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), display_name: T.unsafe(nil)); end
# 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
#
# @param type [Symbol] The type of group. Default is `:optional`.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the group. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to `"Flags"`.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the flag group. See
# {Toys::ToolDefinition#long_desc} for a description of allowed
# formats. Defaults to the empty array.
# @param name [String, Symbol, nil] The name of the group, or nil for no
# name.
# @param report_collisions [true, false] If `true`, raise an exception if a
# the given name is already taken. If `false`, ignore. Default is
# `true`.
# @param prepend [true, false] If `true`, prepend rather than append the
# group to the list. Default is `false`.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#985
def add_flag_group(type: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil), name: T.unsafe(nil), report_collisions: T.unsafe(nil), prepend: T.unsafe(nil)); end
# Add an initializer.
#
# @param proc [Proc] The initializer block
# @param args [Object...] Arguments to pass to the initializer
# @param kwargs [keywords] Keyword arguments to pass to the initializer
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1283
def add_initializer(proc, *args, **kwargs); end
# Add a named mixin module to this tool.
# You may provide a mixin module or a block that configures one.
#
# @param name [String] The name of the mixin.
# @param mixin_module [Module] The mixin module.
# @param block [Proc] Define the mixin module here if a `mixin_module` is
# not provided directly.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#848
def add_mixin(name, mixin_module = T.unsafe(nil), &block); end
# 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.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if this argument is not provided on the command
# line. Defaults to `nil`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, or one of the default acceptors provided by OptionParser.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion. See
# {Toys::Completion.create} for recognized formats.
# @param display_name [String] A name to use for display (in help text and
# error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the arg. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the arg. See {Toys::ToolDefinition#long_desc}
# for a description of allowed formats. Defaults to the empty array.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1155
def add_optional_arg(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil)); end
# 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.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, or one of the default acceptors provided by OptionParser.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion. See
# {Toys::Completion.create} for recognized formats.
# @param display_name [String] A name to use for display (in help text and
# error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the arg. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the arg. See {Toys::ToolDefinition#long_desc}
# for a description of allowed formats. Defaults to the empty array.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1117
def add_required_arg(key, accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil)); end
# Add a named template class to this tool.
# You may provide a template class or a block that configures one.
#
# @param name [String] The name of the template.
# @param template_class [Class] The template class.
# @param block [Proc] Define the template class here if a `template_class`
# is not provided directly.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#895
def add_template(name, template_class = T.unsafe(nil), &block); end
# 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.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#806
def append_long_desc(long_desc); end
# Returns true if this tool has disabled argument parsing.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#637
def argument_parsing_disabled?; end
# The stack of built middleware specs for this tool.
#
# @return [Array<Toys::Middleware>]
#
# source://toys-core//lib/toys/tool_definition.rb#418
def built_middleware; end
# Check that the tool can still be defined. Should be called internally
# or from the DSL only.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#1427
def check_definition_state(is_arg: T.unsafe(nil), is_method: T.unsafe(nil)); end
# The completion strategy for this tool.
#
# When reading, this may return an instance of one of the subclasses of
# {Toys::Completion::Base}, or a Proc that duck-types it. Generally, this
# defaults to a {Toys::ToolDefinition::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
# {Toys::ToolDefinition::DefaultCompletion} constructor.
# * Any other form recognized by {Toys::Completion.create}.
#
# @return [Toys::Completion::Base, Proc]
#
# source://toys-core//lib/toys/tool_definition.rb#453
def completion; end
# Set the completion strategy for this ToolDefinition.
#
# See {#completion} for details.
#
# @param spec [Object]
#
# source://toys-core//lib/toys/tool_definition.rb#1308
def completion=(spec); end
# 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.
#
# @return [String] The effective context directory path.
# @return [nil] if there is no effective context directory.
#
# source://toys-core//lib/toys/tool_definition.rb#1333
def context_directory; end
# The custom context directory set for this tool.
#
# @return [String] The directory path
# @return [nil] if no custom context directory is set.
#
# source://toys-core//lib/toys/tool_definition.rb#434
def custom_context_directory; end
# Set the custom context directory.
#
# See {#custom_context_directory} for details.
#
# @param dir [String]
#
# source://toys-core//lib/toys/tool_definition.rb#1296
def custom_context_directory=(dir); end
# The default context data set by arguments.
#
# @return [Hash]
#
# source://toys-core//lib/toys/tool_definition.rb#402
def default_data; end
# Returns true if this tool's definition has been finished and is locked.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#629
def definition_finished?; end
# The full name of the delegate target, if any.
#
# @return [Array<String>] if this tool delegates
# @return [nil] if this tool does not delegate
#
# source://toys-core//lib/toys/tool_definition.rb#493
def delegate_target; end
# Causes this tool to delegate to another tool.
#
# @param target [Array<String>] The full path to the delegate tool.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1343
def delegate_to(target); end
# The short description string.
#
# When reading, this is always returned as a {Toys::WrappableString}.
#
# When setting, the description may be provided as any of the following:
# * A {Toys::WrappableString}.
# * A normal String, which will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String, which will be transformed into a
# {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Toys::WrappableString]
#
# source://toys-core//lib/toys/tool_definition.rb#333
def desc; end
# Set the short description string.
#
# See {#desc} for details.
#
# @param desc [Toys::WrappableString, String, Array<String>]
#
# source://toys-core//lib/toys/tool_definition.rb#780
def desc=(desc); end
# Disable argument parsing for this tool.
#
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#911
def disable_argument_parsing; end
# 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.
#
# @param flags [String...] The flags to disable
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1083
def disable_flag(*flags); end
# A displayable name of this tool, generally the full name delimited by
# spaces.
#
# @return [String]
#
# source://toys-core//lib/toys/tool_definition.rb#510
def display_name; end
# Enforce that flags must come before args for this tool.
# You may disable enforcement by passoing `false` for the state.
#
# @param state [true, false]
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#929
def enforce_flags_before_args(state = T.unsafe(nil)); end
# Returns true if this tool requires exact flag matches.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#653
def exact_flag_match_required?; end
# Complete definition and run middleware configs. Should be called from
# the Loader only.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#1393
def finish_definition(loader); end
# A list of all defined flag groups, in order.
#
# @return [Array<Toys::FlagGroup>]
#
# source://toys-core//lib/toys/tool_definition.rb#359
def flag_groups; end
# A list of all defined flags.
#
# @return [Array<Toys::Flag>]
#
# source://toys-core//lib/toys/tool_definition.rb#366
def flags; end
# Returns true if this tool enforces flags before args.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#645
def flags_before_args_enforced?; end
# The name of the tool as an array of strings.
# This array may not be modified.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/tool_definition.rb#295
def full_name; end
# Returns true if this tool handles interrupts. This is equivalent to
# `handles_signal?(2)`.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#566
def handles_interrupts?; end
# Returns true if this tool handles the given signal.
#
# @param signal [Integer, String, Symbol] The signal number or name
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#576
def handles_signal?(signal); end
# Returns true if this tool handles usage errors.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#585
def handles_usage_errors?; end
# 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.
#
# @param mod [Module] The mixin module
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#738
def include_mixin(mod, *args, **kwargs); end
# Returns true if at least one flag or positional argument is defined
# for this tool.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#610
def includes_arguments?; end
# Returns true if this tool has any definition information.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#620
def includes_definition?; end
# Returns true if there is a specific description set for this tool.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#601
def includes_description?; end
# Returns true if this tool has at least one included module.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#593
def includes_modules?; end
# Return the interrupt handler. This is equivalent to `signal_handler(2)`.
#
# @return [Proc] if the interrupt signal handler is defined as a Proc
# @return [Symbol] if the interrupt signal handler is defined as a method
# @return [nil] if there is no handler for the interrupt signals
#
# source://toys-core//lib/toys/tool_definition.rb#538
def interrupt_handler; end
# Set the interrupt handler. This is equivalent to calling
# {#set_signal_handler} for the `SIGINT` signal.
#
# @param handler [Proc, Symbol] The interrupt signal handler
#
# source://toys-core//lib/toys/tool_definition.rb#1232
def interrupt_handler=(handler); end
# 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.
#
# @param source [Toys::SourceInfo] Source info
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#768
def lock_source(source); end
# The long description strings.
#
# When reading, this is returned as an Array of {Toys::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 {Toys::WrappableString} representing one line.
# * A normal String representing a line. This will be transformed into a
# {Toys::WrappableString} using spaces as word delimiters.
# * An Array of String representing a line. This will be transformed into
# a {Toys::WrappableString} where each array element represents an
# individual word for wrapping.
#
# @return [Array<Toys::WrappableString>]
#
# source://toys-core//lib/toys/tool_definition.rb#352
def long_desc; end
# Set the long description strings.
#
# See {#long_desc} for details.
#
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
#
# source://toys-core//lib/toys/tool_definition.rb#792
def long_desc=(long_desc); end
# Get the named acceptor from this tool or its ancestors.
#
# @param name [String] The acceptor name.
# @return [Toys::Acceptor::Base] The acceptor.
# @return [nil] if no acceptor of the given name is found.
#
# source://toys-core//lib/toys/tool_definition.rb#692
def lookup_acceptor(name); end
# Get the named completion from this tool or its ancestors.
#
# @param name [String] The completion name
# @return [Toys::Completion::Base, Proc] The completion proc.
# @return [nil] if no completion of the given name is found.
#
# source://toys-core//lib/toys/tool_definition.rb#725
def lookup_completion(name); end
# Lookup the custom context directory in this tool and its ancestors.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#1372
def lookup_custom_context_directory; end
# Get the named mixin from this tool or its ancestors.
#
# @param name [String] The mixin name.
# @return [Module] The mixin module.
# @return [nil] if no mixin of the given name is found.
#
# source://toys-core//lib/toys/tool_definition.rb#714
def lookup_mixin(name); end
# Get the named template from this tool or its ancestors.
#
# @param name [String] The template name.
# @return [Class, nil] The template class.
# @return [nil] if no template of the given name is found.
#
# source://toys-core//lib/toys/tool_definition.rb#703
def lookup_template(name); end
# Mark this tool as having at least one module included.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#1381
def mark_includes_modules; end
# A list of all defined optional positional arguments.
#
# @return [Array<Toys::PositionalArg>]
#
# source://toys-core//lib/toys/tool_definition.rb#380
def optional_args; end
# All arg definitions in order: required, optional, remaining.
#
# @return [Array<Toys::PositionalArg>]
#
# source://toys-core//lib/toys/tool_definition.rb#662
def positional_args; end
# The priority of this tool definition.
#
# @return [Integer]
#
# source://toys-core//lib/toys/tool_definition.rb#302
def priority; end
# The remaining arguments specification.
#
# @return [Toys::PositionalArg] The argument definition
# @return [nil] if remaining arguments are not supported by this tool.
#
# source://toys-core//lib/toys/tool_definition.rb#388
def remaining_arg; end
# Require that flags must match exactly. (If false, flags can match an
# unambiguous substring.)
#
# @param state [true, false]
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#947
def require_exact_flag_match(state = T.unsafe(nil)); end
# A list of all defined required positional arguments.
#
# @return [Array<Toys::PositionalArg>]
#
# source://toys-core//lib/toys/tool_definition.rb#373
def required_args; end
# Reset the definition of this tool, deleting all definition data but
# leaving named acceptors, mixins, and templates intact.
# Should be called only from the DSL.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#246
def reset_definition; end
# 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.
#
# @param str [String] Flag string
# @return [Toys::Flag::Resolution]
#
# source://toys-core//lib/toys/tool_definition.rb#677
def resolve_flag(str); end
# Returns true if this tool is a root tool.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#546
def root?; end
# The run handler.
#
# This handler is called to run the tool. Normally it is a method name,
# represented by a symbol. (The default is `:run`.) It can be set to a
# different method name, or to a proc that will be called with `self` set
# to the tool context. Either way, it takes no arguments. The run handler
# can also be explicitly set to `nil` indicating a non-runnable tool;
# however, typically a tool is made non-runnable simply by leaving the run
# handler set to `:run` and not defining the method.
#
# @return [Proc] if the run handler is defined as a Proc
# @return [Symbol] if the run handler is defined as a method
# @return [nil] if the tool is explicitly made non-runnable
#
# source://toys-core//lib/toys/tool_definition.rb#470
def run_handler; end
# Set the run handler.
#
# This handler is called to run the tool. Normally it is a method name,
# represented by a symbol. (The default is `:run`.) It can be set to a
# different method name, or to a proc that will be called with `self` set
# to the tool context. Either way, it takes no arguments. The run handler
# can also be explicitly set to `nil` indicating a non-runnable tool;
# however, typically a tool is made non-runnable simply by leaving the run
# handler set to `:run` and not defining the method.
#
# @param handler [Proc, Symbol, nil] the run handler
#
# source://toys-core//lib/toys/tool_definition.rb#1218
def run_handler=(handler); end
# Run all initializers against a context. Called from the Runner.
#
# @private This interface is internal and subject to change without warning.
#
# source://toys-core//lib/toys/tool_definition.rb#1415
def run_initializers(context); end
# Returns true if this tool is marked as runnable.
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#554
def runnable?; end
# 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.
#
# @param key [String, Symbol] The key to use to retrieve the value from
# the execution context.
# @param default [Object] The default value. This is the value that will
# be set in the context if no unmatched arguments are provided on the
# command line. Defaults to the empty array `[]`.
# @param accept [Object] An acceptor that validates and/or converts the
# value. You may provide either the name of an acceptor you have
# defined, or one of the default acceptors provided by OptionParser.
# Optional. If not specified, accepts any value as a string.
# @param complete [Object] A specifier for shell tab completion. See
# {Toys::Completion.create} for recognized formats.
# @param display_name [String] A name to use for display (in help text and
# error reports). Defaults to the key in upper case.
# @param desc [String, Array<String>, Toys::WrappableString] Short
# description for the arg. See {Toys::ToolDefinition#desc} for a
# description of allowed formats. Defaults to the empty string.
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>] Long description for the arg. See {Toys::ToolDefinition#long_desc}
# for a description of allowed formats. Defaults to the empty array.
# @return [self]
#
# source://toys-core//lib/toys/tool_definition.rb#1193
def set_remaining_args(key, default: T.unsafe(nil), accept: T.unsafe(nil), complete: T.unsafe(nil), display_name: T.unsafe(nil), desc: T.unsafe(nil), long_desc: T.unsafe(nil)); end
# Set the handler for the given signal.
#
# This handler is called when the given signal is received, immediately
# taking over the execution as if it were the new `run` method. The signal
# handler can be specified as a Proc, or a Symbol indicating a method to
# call. It optionally takes the `SignalException` as the sole argument.
#
# @param signal [Integer, String, Symbol] The signal number or name
# @param handler [Proc, Symbol] The signal handler
#
# source://toys-core//lib/toys/tool_definition.rb#1247
def set_signal_handler(signal, handler); end
# Settings for this tool
#
# @return [Toys::ToolDefinition::Settings]
#
# source://toys-core//lib/toys/tool_definition.rb#287
def settings; end
# Return the signal handler for the given signal.
#
# This handler is called when the given signal is received, immediately
# taking over the execution as if it were the new run handler. The signal
# handler can be specified as a Proc, or a Symbol indicating a method to
# call. It optionally takes the `SignalException` as the sole argument.
#
# @param signal [Integer, String, Symbol] The signal number or name
# @return [Proc] if the signal handler is defined as a Proc
# @return [Symbol] if the signal handler is defined as a method
# @return [nil] if there is no handler for the given signal
#
# source://toys-core//lib/toys/tool_definition.rb#527
def signal_handler(signal); end
# The local name of this tool, i.e. the last element of the full name.
#
# @return [String]
#
# source://toys-core//lib/toys/tool_definition.rb#500
def simple_name; end
# Info on the source of this tool.
#
# @return [Toys::SourceInfo] The source info
# @return [nil] if the source is not defined.
#
# source://toys-core//lib/toys/tool_definition.rb#426
def source_info; end
# The root source info defining this tool, or nil if there is no source.
#
# @return [Toys::SourceInfo, nil]
#
# source://toys-core//lib/toys/tool_definition.rb#309
def source_root; end
# The stack of middleware specs used for subtools.
#
# This array may be modified in place.
#
# @return [Array<Toys::Middleware::Spec>]
#
# source://toys-core//lib/toys/tool_definition.rb#411
def subtool_middleware_stack; end
# The tool class.
#
# @return [Class]
#
# source://toys-core//lib/toys/tool_definition.rb#316
def tool_class; end
# The usage error handler.
#
# This handler is called when at least one usage error is detected during
# argument parsing, and is called instead of the `run` method. It can be
# specified as a Proc, or a Symbol indicating a method to call. It
# optionally takes an array of {Toys::ArgParser::UsageError} as the sole
# argument.
#
# @return [Proc] if the usage error handler is defined as a Proc
# @return [Symbol] if the user error handler is defined as a method
# @return [nil] if there is no usage error handler
#
# source://toys-core//lib/toys/tool_definition.rb#485
def usage_error_handler; end
# Set the usage error handler.
#
# This handler is called when at least one usage error is detected during
# argument parsing, and is called instead of the `run` method. It can be
# specified as a Proc, or a Symbol indicating a method to call. It
# optionally takes an array of {Toys::ArgParser::UsageError} as the sole
# argument.
#
# @param handler [Proc, Symbol] The usage error handler
#
# source://toys-core//lib/toys/tool_definition.rb#1267
def usage_error_handler=(handler); end
# A list of flags that have been used in the flag definitions.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/tool_definition.rb#395
def used_flags; end
private
# @raise [::ArgumentError]
#
# source://toys-core//lib/toys/tool_definition.rb#1492
def canonicalize_signal(signal); end
# source://toys-core//lib/toys/tool_definition.rb#1445
def create_class; end
# source://toys-core//lib/toys/tool_definition.rb#1449
def make_config_proc(middleware, loader, next_config); end
# source://toys-core//lib/toys/tool_definition.rb#1457
def make_delegation_run_handler(target); end
# @raise [ToolDefinitionError]
#
# source://toys-core//lib/toys/tool_definition.rb#1478
def resolve_acceptor_name(name); end
# @raise [ToolDefinitionError]
#
# source://toys-core//lib/toys/tool_definition.rb#1485
def resolve_completion_name(name); end
end
# A Completion that implements the default algorithm for a tool.
#
# source://toys-core//lib/toys/tool_definition.rb#15
class Toys::ToolDefinition::DefaultCompletion < ::Toys::Completion::Base
# Create a completion given configuration options.
#
# @param complete_subtools [true, false] Whether to complete subtool names
# @param include_hidden_subtools [true, false] Whether to include hidden
# subtools (i.e. those beginning with an underscore)
# @param complete_args [true, false] Whether to complete positional args
# @param complete_flags [true, false] Whether to complete flag names
# @param complete_flag_values [true, false] Whether to complete flag values
# @param delegation_target [Array<String>, nil] Delegation target, or
# `nil` if none.
# @return [DefaultCompletion] a new instance of DefaultCompletion
#
# source://toys-core//lib/toys/tool_definition.rb#28
def initialize(complete_subtools: T.unsafe(nil), include_hidden_subtools: T.unsafe(nil), complete_args: T.unsafe(nil), complete_flags: T.unsafe(nil), complete_flag_values: T.unsafe(nil), delegation_target: T.unsafe(nil)); end
# Returns candidates for the current completion.
#
# @param context [Toys::Completion::Context] the current completion
# context including the string fragment.
# @return [Array<Toys::Completion::Candidate>] an array of candidates
#
# source://toys-core//lib/toys/tool_definition.rb#94
def call(context); end
# Whether to complete positional args
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#68
def complete_args?; end
# Whether to complete flag values
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#76
def complete_flag_values?; end
# Whether to complete flags
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#60
def complete_flags?; end
# Whether to complete subtool names
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#44
def complete_subtools?; end
# Delegation target, or nil for none.
#
# @return [Array<String>] if there is a delegation target
# @return [nil] if there is no delegation target
#
# source://toys-core//lib/toys/tool_definition.rb#85
def delegation_target; end
# Delegation target, or nil for none.
#
# @return [Array<String>] if there is a delegation target
# @return [nil] if there is no delegation target
#
# source://toys-core//lib/toys/tool_definition.rb#85
def delegation_target=(_arg0); end
# Whether to include hidden subtools
#
# @return [true, false]
#
# source://toys-core//lib/toys/tool_definition.rb#52
def include_hidden_subtools?; end
private
# source://toys-core//lib/toys/tool_definition.rb#149
def analyze_subtool_fragment(context); end
# source://toys-core//lib/toys/tool_definition.rb#171
def arg_candidates(context); end
# source://toys-core//lib/toys/tool_definition.rb#190
def flag_value_candidates(context); end
# source://toys-core//lib/toys/tool_definition.rb#178
def plain_flag_candidates(context); end
# source://toys-core//lib/toys/tool_definition.rb#132
def subtool_candidates(context); end
# source://toys-core//lib/toys/tool_definition.rb#126
def subtool_or_arg_candidates(context); end
# source://toys-core//lib/toys/tool_definition.rb#112
def valued_flag_candidates(context); end
end
# Tool-based settings class.
#
# The following settings are supported:
#
# * `propagate_helper_methods` (_boolean_) - Whether subtools should
# inherit methods defined by parent tools. Defaults to `false`.
#
# source://toys-core//lib/toys/tool_definition.rb#209
class Toys::ToolDefinition::Settings < ::Toys::Settings
# source://toys-core//lib/toys/settings.rb#888
def propagate_helper_methods; end
# source://toys-core//lib/toys/settings.rb#894
def propagate_helper_methods=(val); end
# source://toys-core//lib/toys/settings.rb#900
def propagate_helper_methods_set?; end
# source://toys-core//lib/toys/settings.rb#906
def propagate_helper_methods_unset!; end
end
# An exception indicating an error in a tool definition.
#
# source://toys-core//lib/toys/errors.rb#7
class Toys::ToolDefinitionError < ::StandardError; end
# Namespace for common utility classes.
#
# These classes are not loaded by default, and must be required explicitly.
# For example, before using {Toys::Utils::Exec}, you must:
#
# require "toys/utils/exec"
#
# source://toys-core//lib/toys-core.rb#103
module Toys::Utils; end
# A string intended for word-wrapped display.
#
# A WrappableString is an array of string "fragments" representing the atomic
# units that should not be split when word-wrapping. It should be possible to
# reconstruct the original string by joining these fragments with whitespace.
#
# source://toys-core//lib/toys/wrappable_string.rb#11
class Toys::WrappableString
# Create a wrapped string.
#
# You can pass either:
#
# * A single String, which will be split into fragments by whitespace.
# * An array of Strings representing the fragments explicitly.
#
# @param string [String, Array<String>] The string or array of string
# fragments
# @return [WrappableString] a new instance of WrappableString
#
# source://toys-core//lib/toys/wrappable_string.rb#23
def initialize(string = T.unsafe(nil)); end
# Returns a new WrappaableString whose content is the concatenation of this
# WrappableString with another WrappableString.
#
# @param other [WrappableString]
# @return [WrappableString]
#
# source://toys-core//lib/toys/wrappable_string.rb#41
def +(other); end
# Tests two wrappable strings for equality
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/wrappable_string.rb#70
def ==(other); end
# Returns true if the string is empty (i.e. has no fragments)
#
# @return [Boolean]
#
# source://toys-core//lib/toys/wrappable_string.rb#51
def empty?; end
# Tests two wrappable strings for equality
#
# @param other [Object]
# @return [Boolean]
#
# source://toys-core//lib/toys/wrappable_string.rb#70
def eql?(other); end
# Returns the string fragments, i.e. the individual "words" for wrapping.
#
# @return [Array<String>]
#
# source://toys-core//lib/toys/wrappable_string.rb#32
def fragments; end
# Returns a hash code for this object
#
# @return [Integer]
#
# source://toys-core//lib/toys/wrappable_string.rb#80
def hash; end
# Returns the string without any wrapping
#
# @return [String]
#
# source://toys-core//lib/toys/wrappable_string.rb#60
def string; end
# Returns the string without any wrapping
#
# @return [String]
#
# source://toys-core//lib/toys/wrappable_string.rb#60
def to_s; end
# Wraps the string to the given width.
#
# @param width [Integer, nil] Width in characters, or `nil` for infinite.
# @param width2 [Integer, nil] Width in characters for the second and
# subsequent lines, or `nil` to use the same as width.
# @return [Array<String>] Wrapped lines
#
# source://toys-core//lib/toys/wrappable_string.rb#93
def wrap(width, width2 = T.unsafe(nil)); end
class << self
# Make the given object a WrappableString.
# If the object is already a WrappableString, return it. Otherwise,
# treat it as a string or an array of strings and wrap it in a
# WrappableString.
#
# @param obj [Toys::WrappableString, String, Array<String>]
# @return [Toys::WrappableString]
#
# source://toys-core//lib/toys/wrappable_string.rb#146
def make(obj); end
# Make the given object an array of WrappableString.
#
# @param objs [Array<Toys::WrappableString,String,Array<String>>]
# @return [Array<Toys::WrappableString>]
#
# source://toys-core//lib/toys/wrappable_string.rb#156
def make_array(objs); end
# Wraps an array of lines to the given width.
#
# @param strs [Array<WrappableString>] Array of strings to wrap.
# @param width [Integer, nil] Width in characters, or `nil` for infinite.
# @param width2 [Integer, nil] Width in characters for the second and
# subsequent lines, or `nil` to use the same as width.
# @return [Array<String>] Wrapped lines
#
# source://toys-core//lib/toys/wrappable_string.rb#126
def wrap_lines(strs, width, width2 = T.unsafe(nil)); end
end
end