Class: Toys::Context

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

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. This class method can be called if the instance method is or could be replaced by the tool.

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. (Note: if a non-integer is passed in, it is changed to -1.)



435
436
437
438
 
# File 'lib/toys/context.rb', line 435

def self.exit(code = 0)
  code = -1 unless code.is_a?(::Integer)
  throw :result, code
end

Instance Method Details

#[](key) ⇒ Object Also known as: get, __get

Fetch an option or other piece of data by key.

If the get method is overridden by the tool, you can still access it using the name __get or the [] operator.

Parameters:

  • key (Symbol)

Returns:

  • (Object) 


330
331
332
 
# File 'lib/toys/context.rb', line 330

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

#[]=(key, value) ⇒ Object

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

Parameters:

  • key (Symbol)
  • value (Object) 


342
343
344
 
# File 'lib/toys/context.rb', line 342

def []=(key, value)
  @__data[key] = value
end

#__exit ⇒ void

This method returns an undefined value.

Exit immediately with the given status code.

If the exit method is overridden by the tool, you can still access it using the name __exit or by calling exit.

Parameters:

  • code (Integer) —

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



424
425
426
 
# File 'lib/toys/context.rb', line 424

def exit(code = 0)
  Context.exit(code)
end

#args ⇒ Array<String> Also known as: __args

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.

If the args method is overridden by the tool, you can still access it using the name __args.

Returns:

  • (Array<String>) 


174
175
176
 
# File 'lib/toys/context.rb', line 174

def args
  @__data[Key::ARGS]
end

#cli ⇒ Toys::CLI? Also known as: __cli

The currently running CLI.

This is a convenience getter for Toys::Context::Key::CLI. Note the value could be nil if no CLI is present during the execution.

If the cli method is overridden by the tool, you can still access it using the name __cli.

Returns:



190
191
192
 
# File 'lib/toys/context.rb', line 190

def cli
  @__data[Key::CLI]
end

#context_directory ⇒ String Also known as: __context_directory

Return the effective context directory for this tool run. Generally, this is set to the directory containing the toys tool directory structure being read, or it may have been set by the tool definition itself. If a context directory has not been set explicitly, returns the current working directory. Will not return nil.

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

If the context_directory method is overridden by the tool, you can still access it using the name __context_directory.

Returns:

  • (String) —

    Effective context directory path



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

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.

If the exit method is overridden by the tool, you can still access it using the name __exit or by calling exit.

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.



421
422
423
 
# File 'lib/toys/context.rb', line 421

def exit(code = 0)
  Context.exit(code)
end

#find_data(path, type: nil) ⇒ String? Also known as: __find_data

Find the given data file or directory in this tool's search path.

If the find_data method is overridden by the tool, you can still access it using the name __find_data.

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.



406
407
408
 
# File 'lib/toys/context.rb', line 406

def find_data(path, type: nil)
  @__data[Key::TOOL_SOURCE]&.find_data(path, type: type)
end

#loader ⇒ Toys::Loader Also known as: __loader

The loader that loaded the tool being executed. It can be used to look up and load other tools.

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

If the loader method is overridden by the tool, you can still access it using the name __loader.

Returns:



225
226
227
 
# File 'lib/toys/context.rb', line 225

def loader
  @__data[Key::LOADER]
end

#logger ⇒ Logger Also known as: __logger

The logger for this execution.

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

If the logger method is overridden by the tool, you can still access it using the name __logger.

Returns:

  • (Logger) 


240
241
242
 
# File 'lib/toys/context.rb', line 240

def logger
  @__data[Key::LOGGER]
end

#options ⇒ Hash Also known as: __options

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.

If the options method is overridden by the tool, you can still access it using the name __options.

Returns:

  • (Hash) 


386
387
388
389
390
 
# File 'lib/toys/context.rb', line 386

def options
  @__data.select do |k, _v|
    k.is_a?(::Symbol) || k.is_a?(::String)
  end
end

#runner ⇒ Toys::Runner Also known as: __runner

The runner that is running the tool. It can be used to run other tools in the same process.

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

If the runner method is overridden by the tool, you can still access it using the name __runner.

Returns:



256
257
258
 
# File 'lib/toys/context.rb', line 256

def runner
  @__data[Key::RUNNER]
end

#set(key, value) ⇒ self #set(hash) ⇒ self Also known as: __set

Set one or more options or other context data by key.

If the set method is overridden by the tool, you can still access it using the name __set.

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) 


365
366
367
368
369
370
371
372
 
# File 'lib/toys/context.rb', line 365

def set(key, value = nil)
  if key.is_a?(::Hash)
    @__data.merge!(key)
  else
    @__data[key] = value
  end
  self
end

#tool_name ⇒ Array<String> Also known as: __tool_name

The full name of the tool being executed, as an array of strings.

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

If the tool_name method is overridden by the tool, you can still access it using the name __tool_name.

Returns:

  • (Array<String>) 


271
272
273
 
# File 'lib/toys/context.rb', line 271

def tool_name
  @__data[Key::TOOL_NAME]
end

#tool_source ⇒ Toys::SourceInfo Also known as: __tool_source

The source of the tool being executed.

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

If the tool_source method is overridden by the tool, you can still access it using the name __tool_source.

Returns:



286
287
288
 
# File 'lib/toys/context.rb', line 286

def tool_source
  @__data[Key::TOOL_SOURCE]
end

#usage_errors ⇒ Array<Toys::ArgParser::UsageError> Also known as: __usage_errors

The (possibly empty) array of errors detected during argument parsing.

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

If the usage_errors method is overridden by the tool, you can still access it using the name __usage_errors.

Returns:



301
302
303
 
# File 'lib/toys/context.rb', line 301

def usage_errors
  @__data[Key::USAGE_ERRORS]
end

#verbosity ⇒ Integer Also known as: __verbosity

The current verbosity setting as an integer.

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

If the verbosity method is overridden by the tool, you can still access it using the name __verbosity.

Returns:

  • (Integer) 


316
317
318
 
# File 'lib/toys/context.rb', line 316

def verbosity
  @__data[Key::VERBOSITY]
end