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
335 336 337 |
# File 'lib/toys/context.rb', line 335 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.
248 249 250 |
# File 'lib/toys/context.rb', line 248 def [](key) @__data[key] end |
#[]=(key, value) ⇒ Object
Set an option or other piece of context data by key.
260 261 262 |
# File 'lib/toys/context.rb', line 260 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.
157 158 159 |
# File 'lib/toys/context.rb', line 157 def args @__data[Key::ARGS] end |
#cli ⇒ Toys::CLI
The currently running CLI.
This is a convenience getter for Toys::Context::Key::CLI.
168 169 170 |
# File 'lib/toys/context.rb', line 168 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.
183 184 185 |
# File 'lib/toys/context.rb', line 183 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
324 325 326 |
# File 'lib/toys/context.rb', line 324 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.
313 314 315 |
# File 'lib/toys/context.rb', line 313 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.
194 195 196 |
# File 'lib/toys/context.rb', line 194 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.
297 298 299 300 301 |
# File 'lib/toys/context.rb', line 297 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.
280 281 282 283 284 285 286 287 |
# File 'lib/toys/context.rb', line 280 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.
205 206 207 |
# File 'lib/toys/context.rb', line 205 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.
216 217 218 |
# File 'lib/toys/context.rb', line 216 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.
227 228 229 |
# File 'lib/toys/context.rb', line 227 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.
238 239 240 |
# File 'lib/toys/context.rb', line 238 def verbosity @__data[Key::VERBOSITY] end |