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(code = 0) click to toggle source

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
new(data) click to toggle source

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

[](key) click to toggle source

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
Also aliased as: get, __get
[]=(key, value) click to toggle source

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
__get(key)
Alias for: []
args() click to toggle source

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
cli() click to toggle source

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
context_directory() click to toggle source

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(code = 0) click to toggle source

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_data(path, type: nil) click to toggle source

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
get(key)
Alias for: []
inspect() click to toggle source

@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
logger() click to toggle source

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
options() click to toggle source

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(key, value = nil) click to toggle source

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
tool_name() click to toggle source

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
tool_source() click to toggle source

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
usage_errors() click to toggle source

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
verbosity() click to toggle source

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