Class: Toys::Context

Inherits:
Object
  • Object
show all
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

Tool

Defined Under Namespace

Modules: Key

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.exit(code = 0) ⇒ void

This method returns an undefined value.

Exit immediately with the given status code

Parameters:

  • code (Integer) (defaults to: 0) —

    The status code, which should be 0 for no error, or nonzero for an error condition. Default is 0.



339
340
341
 
# File 'toys-core/lib/toys/context.rb', line 339

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.

Parameters:

  • key (Symbol)

Returns:

  • (Object) 


252
253
254
 
# File 'toys-core/lib/toys/context.rb', line 252

def [](key)
  @__data[key]
end

#[]=(key, value) ⇒ Object

Set an option or other piece of context data by key.

Parameters:

  • key (Symbol)
  • value (Object) 


264
265
266
 
# File 'toys-core/lib/toys/context.rb', line 264

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.

Returns:

  • (Array<String>) 


161
162
163
 
# File 'toys-core/lib/toys/context.rb', line 161

def args
  @__data[Key::ARGS]
end

#cli ⇒ Toys::CLI

The currently running CLI.

This is a convenience getter for Toys::Context::Key::CLI.

Returns:



172
173
174
 
# File 'toys-core/lib/toys/context.rb', line 172

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.

Returns:

  • (String) —

    Context directory path

  • (nil) —

    if there is no context.



187
188
189
 
# File 'toys-core/lib/toys/context.rb', line 187

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

Parameters:

  • code (Integer) (defaults to: 0) —

    The status code, which should be 0 for no error, or nonzero for an error condition. Default is 0.



328
329
330
 
# File 'toys-core/lib/toys/context.rb', line 328

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.

Parameters:

  • path (String) —

    The path to find

  • type (nil, :file, :directory) (defaults to: nil) —

    Type of file system object to find, or nil to return any type.

Returns:

  • (String) —

    Absolute path of the result

  • (nil) —

    if the data was not found.



317
318
319
 
# File 'toys-core/lib/toys/context.rb', line 317

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.

Returns:

  • (Logger) 


198
199
200
 
# File 'toys-core/lib/toys/context.rb', line 198

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.

Returns:

  • (Hash) 


301
302
303
304
305
 
# File 'toys-core/lib/toys/context.rb', line 301

def options
  @__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.

Overloads:

  • #set(key, value) ⇒ self

    Set an option or other piece of context data by key.

    Parameters:

    • key (Symbol)
    • value (Object)

    Returns:

    • (self)
  • #set(hash) ⇒ self

    Set multiple content data keys and values

    Parameters:

    • hash (Hash) —

      The keys and values to set

    Returns:

    • (self)

Returns:

  • (self) 


284
285
286
287
288
289
290
291
 
# File 'toys-core/lib/toys/context.rb', line 284

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.

Returns:

  • (Array<String>) 


209
210
211
 
# File 'toys-core/lib/toys/context.rb', line 209

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.

Returns:



220
221
222
 
# File 'toys-core/lib/toys/context.rb', line 220

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.

Returns:



231
232
233
 
# File 'toys-core/lib/toys/context.rb', line 231

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.

Returns:

  • (Integer) 


242
243
244
 
# File 'toys-core/lib/toys/context.rb', line 242

def verbosity
  @__data[Key::VERBOSITY]
end