class Toys::Context
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.
Public Class Methods
Exit immediately with the given status code
@param code [Integer] The status code, which should be 0 for no error,
or nonzero for an error condition. Default is 0.
@return [void]
# File lib/toys/context.rb, line 342 def self.exit(code = 0) throw :result, code end
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.
@private
@param data [Hash]
# File lib/toys/context.rb, line 145 def initialize(data) @__data = data end
Public Instance Methods
Fetch an option or other piece of data by key.
@param key [Symbol] @return [Object]
# File lib/toys/context.rb, line 255 def [](key) @__data[key] end
Set an option or other piece of context data by key.
@param key [Symbol] @param value [Object]
# File lib/toys/context.rb, line 267 def []=(key, value) @__data[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}.
@return [Array<String>]
# File lib/toys/context.rb, line 164 def args @__data[Key::ARGS] end
The currently running CLI
.
This is a convenience getter for {Toys::Context::Key::CLI}.
@return [Toys::CLI]
# File lib/toys/context.rb, line 175 def cli @__data[Key::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}.
@return [String] Context
directory path @return [nil] if there is no context.
# File lib/toys/context.rb, line 190 def context_directory @__data[Key::CONTEXT_DIRECTORY] end
Exit immediately with the given status code
@param code [Integer] The status code, which should be 0 for no error,
or nonzero for an error condition. Default is 0.
@return [void]
# File lib/toys/context.rb, line 331 def exit(code = 0) throw :result, code end
Find the given data file or directory in this tool's search path.
@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.
# File lib/toys/context.rb, line 320 def find_data(path, type: nil) @__data[Key::TOOL_SOURCE].find_data(path, type: type) end
@private
# File lib/toys/context.rb, line 150 def inspect name = Array(@__data[Key::TOOL_NAME]).join(" ") id = object_id.to_s(16) "#<Toys::Context id=0x#{id} #{name}>" end
The logger for this execution.
This is a convenience getter for {Toys::Context::Key::LOGGER}.
@return [Logger]
# File lib/toys/context.rb, line 201 def logger @__data[Key::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.
@return [Hash]
# File lib/toys/context.rb, line 304 def options @__data.select do |k, _v| k.is_a?(::Symbol) || k.is_a?(::String) end end
Set one or more options or other context data by key.
@return [self]
@overload set(key, value)
Set an option or other piece of context data by key. @param key [Symbol] @param value [Object] @return [self]
@overload set(hash)
Set multiple content data keys and values @param hash [Hash] The keys and values to set @return [self]
# File lib/toys/context.rb, line 287 def set(key, value = nil) if key.is_a?(::Hash) @__data.merge!(key) else @__data[key] = value end self 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}.
@return [Array<String>]
# File lib/toys/context.rb, line 212 def tool_name @__data[Key::TOOL_NAME] end
The source of the tool being executed.
This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
@return [Toys::SourceInfo]
# File lib/toys/context.rb, line 223 def tool_source @__data[Key::TOOL_SOURCE] end
The (possibly empty) array of errors detected during argument parsing.
This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
@return [Array<Toys::ArgParser::UsageError>]
# File lib/toys/context.rb, line 234 def usage_errors @__data[Key::USAGE_ERRORS] end
The current verbosity setting as an integer.
This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
@return [Integer]
# File lib/toys/context.rb, line 245 def verbosity @__data[Key::VERBOSITY] end