Class: Toys::Context
- Inherits:
-
Object
- Object
- Toys::Context
- Defined in:
- lib/toys/context.rb
Overview
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 #get method.
Additionally, convenience methods are provided for many of the well-known
keys. For instance, you can call #verbosity to obtain the
value for the key 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 Key::VERBOSITY, or should be used for internal private information needed by middleware and mixins. The module Key defines a number of well-known keys as constants.
Direct Known Subclasses
Defined Under Namespace
Modules: Key
Class Method Summary collapse
-
.exit(code = 0) ⇒ void
Exit immediately with the given status code.
Instance Method Summary collapse
-
#[](key) ⇒ Object
(also: #get, #__get)
Fetch an option or other piece of data by key.
-
#[]=(key, value) ⇒ Object
Set an option or other piece of context data by key.
-
#args ⇒ Array<String>
The raw arguments passed to the tool, as an array of strings.
-
#cli ⇒ Toys::CLI
The currently running CLI.
-
#context_directory ⇒ String?
Return the context directory for this tool.
-
#exit(code = 0) ⇒ void
Exit immediately with the given status code.
-
#find_data(path, type: nil) ⇒ String?
Find the given data file or directory in this tool's search path.
-
#logger ⇒ Logger
The logger for this execution.
-
#options ⇒ Hash
The subset of the context that uses string or symbol keys.
-
#set(key, value = nil) ⇒ self
Set one or more options or other context data by key.
-
#tool_name ⇒ Array<String>
The full name of the tool being executed, as an array of strings.
-
#tool_source ⇒ Toys::SourceInfo
The source of the tool being executed.
-
#usage_errors ⇒ Array<Toys::ArgParser::UsageError>
The (possibly empty) array of errors detected during argument parsing.
-
#verbosity ⇒ Integer
The current verbosity setting as an integer.
Class Method Details
.exit(code = 0) ⇒ void
This method returns an undefined value.
Exit immediately with the given status code
342 343 344 |
# File 'lib/toys/context.rb', line 342 def self.exit(code = 0) throw :result, code end |
Instance Method Details
#[](key) ⇒ Object Also known as: get, __get
Fetch an option or other piece of data by key.
255 256 257 |
# File 'lib/toys/context.rb', line 255 def [](key) @__data[key] end |
#[]=(key, value) ⇒ Object
Set an option or other piece of context data by key.
267 268 269 |
# File 'lib/toys/context.rb', line 267 def []=(key, value) @__data[key] = value end |
#args ⇒ Array<String>
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.
164 165 166 |
# File 'lib/toys/context.rb', line 164 def args @__data[Key::ARGS] end |
#cli ⇒ Toys::CLI
The currently running CLI.
This is a convenience getter for Toys::Context::Key::CLI.
175 176 177 |
# File 'lib/toys/context.rb', line 175 def cli @__data[Key::CLI] end |
#context_directory ⇒ String?
Return the context directory for this tool. Generally, this defaults to the directory containing the toys config directory structure being read, but it may be changed by setting a different context directory for the tool.
This is a convenience getter for Toys::Context::Key::CONTEXT_DIRECTORY.
190 191 192 |
# File 'lib/toys/context.rb', line 190 def context_directory @__data[Key::CONTEXT_DIRECTORY] end |
#exit(code = 0) ⇒ void
This method returns an undefined value.
Exit immediately with the given status code
331 332 333 |
# File 'lib/toys/context.rb', line 331 def exit(code = 0) throw :result, code end |
#find_data(path, type: nil) ⇒ String?
Find the given data file or directory in this tool's search path.
320 321 322 |
# File 'lib/toys/context.rb', line 320 def find_data(path, type: nil) @__data[Key::TOOL_SOURCE].find_data(path, type: type) end |
#logger ⇒ Logger
The logger for this execution.
This is a convenience getter for Toys::Context::Key::LOGGER.
201 202 203 |
# File 'lib/toys/context.rb', line 201 def logger @__data[Key::LOGGER] end |
#options ⇒ Hash
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.
304 305 306 307 308 |
# File 'lib/toys/context.rb', line 304 def @__data.select do |k, _v| k.is_a?(::Symbol) || k.is_a?(::String) end end |
#set(key, value) ⇒ self #set(hash) ⇒ self
Set one or more options or other context data by key.
287 288 289 290 291 292 293 294 |
# 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 ⇒ Array<String>
The full name of the tool being executed, as an array of strings.
This is a convenience getter for Toys::Context::Key::TOOL_NAME.
212 213 214 |
# File 'lib/toys/context.rb', line 212 def tool_name @__data[Key::TOOL_NAME] end |
#tool_source ⇒ Toys::SourceInfo
The source of the tool being executed.
This is a convenience getter for Toys::Context::Key::TOOL_SOURCE.
223 224 225 |
# File 'lib/toys/context.rb', line 223 def tool_source @__data[Key::TOOL_SOURCE] end |
#usage_errors ⇒ Array<Toys::ArgParser::UsageError>
The (possibly empty) array of errors detected during argument parsing.
This is a convenience getter for Toys::Context::Key::USAGE_ERRORS.
234 235 236 |
# File 'lib/toys/context.rb', line 234 def usage_errors @__data[Key::USAGE_ERRORS] end |
#verbosity ⇒ Integer
The current verbosity setting as an integer.
This is a convenience getter for Toys::Context::Key::VERBOSITY.
245 246 247 |
# File 'lib/toys/context.rb', line 245 def verbosity @__data[Key::VERBOSITY] end |