Class: Toys::Context
- Inherits:
-
Object
- Object
- Toys::Context
- Defined in:
- toys-core/lib/toys/context.rb
Overview
Defined in the toys-core gem
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
346 347 348 |
# File 'toys-core/lib/toys/context.rb', line 346 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.
259 260 261 |
# File 'toys-core/lib/toys/context.rb', line 259 def [](key) @__data[key] end |
#[]=(key, value) ⇒ Object
Set an option or other piece of context data by key.
271 272 273 |
# File 'toys-core/lib/toys/context.rb', line 271 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.
168 169 170 |
# File 'toys-core/lib/toys/context.rb', line 168 def args @__data[Key::ARGS] end |
#cli ⇒ Toys::CLI
The currently running CLI.
This is a convenience getter for Toys::Context::Key::CLI.
179 180 181 |
# File 'toys-core/lib/toys/context.rb', line 179 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.
194 195 196 |
# File 'toys-core/lib/toys/context.rb', line 194 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
335 336 337 |
# File 'toys-core/lib/toys/context.rb', line 335 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.
324 325 326 |
# File 'toys-core/lib/toys/context.rb', line 324 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.
205 206 207 |
# File 'toys-core/lib/toys/context.rb', line 205 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.
308 309 310 311 312 |
# File 'toys-core/lib/toys/context.rb', line 308 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.
291 292 293 294 295 296 297 298 |
# File 'toys-core/lib/toys/context.rb', line 291 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.
216 217 218 |
# File 'toys-core/lib/toys/context.rb', line 216 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.
227 228 229 |
# File 'toys-core/lib/toys/context.rb', line 227 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.
238 239 240 |
# File 'toys-core/lib/toys/context.rb', line 238 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.
249 250 251 |
# File 'toys-core/lib/toys/context.rb', line 249 def verbosity @__data[Key::VERBOSITY] end |