Class: Toys::Tool

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/tool.rb

Overview

This class manages the object context in effect during the execution of a tool. The context is a hash of key-value pairs.

Flags and arguments defined by your tool normally report their values in the context, using keys that are strings or symbols.

Keys that are neither strings nor symbols are by convention used for other context information, including:

  • Common information such as the Definition::Tool object being executed, the arguments originally passed to it, or the usage error string. These well-known keys can be accessed via constants in the Keys module.
  • Common settings such as the verbosity level, and whether to exit immediately if a subprocess exits with a nonzero result. These keys are also present as Context constants.
  • Private information used internally by middleware and mixins.

This class provides convenience accessors for common keys and settings, and you can retrieve argument-set keys using the #options hash.

Defined Under Namespace

Modules: Keys

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.exit(code = 0) ⇒ Object

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.



278
279
280
 
# File 'lib/toys/tool.rb', line 278

def self.exit(code = 0)
  throw :result, code
end

Instance Method Details

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

Return an option or other piece of data by key.

Parameters:

  • key (Symbol)

Returns:

  • (Object) 


218
219
220
 
# File 'lib/toys/tool.rb', line 218

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

#[]=(key, value) ⇒ Object

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

Parameters:

  • key (Symbol)
  • value (Object) 


229
230
231
 
# File 'lib/toys/tool.rb', line 229

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

#args ⇒ Array[String]

Return the raw arguments passed to the tool, as an array of strings. This does not include the tool name itself.

Returns:

  • (Array[String]) 


175
176
177
 
# File 'lib/toys/tool.rb', line 175

def args
  @__data[Keys::ARGS]
end

#binary_name ⇒ String

Return the name of the binary that was executed.

Returns:

  • (String) 


208
209
210
 
# File 'lib/toys/tool.rb', line 208

def binary_name
  @__data[Keys::BINARY_NAME]
end

#cli ⇒ Toys::CLI

Return the currently running CLI.

Returns:



142
143
144
 
# File 'lib/toys/tool.rb', line 142

def cli
  @__data[Keys::CLI]
end

#exit(code = 0) ⇒ Object

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.



268
269
270
 
# File 'lib/toys/tool.rb', line 268

def exit(code = 0)
  throw :result, code
end

#loader ⇒ Toys::Loader

Return the active loader that can be used to get other tools.

Returns:



200
201
202
 
# File 'lib/toys/tool.rb', line 200

def loader
  @__data[Keys::LOADER]
end

#logger ⇒ Logger

Return the logger for this execution.

Returns:

  • (Logger) 


192
193
194
 
# File 'lib/toys/tool.rb', line 192

def logger
  @__data[Keys::LOGGER]
end

#options ⇒ Hash

Returns 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) 


256
257
258
259
260
 
# File 'lib/toys/tool.rb', line 256

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

#set(key, value = nil) ⇒ Object

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

Parameters:

  • key (Symbol)
  • value (Object) (defaults to: nil) 


239
240
241
242
243
244
245
246
 
# File 'lib/toys/tool.rb', line 239

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

#tool_definition ⇒ Toys::Definition::Tool

Return the tool being executed.

Returns:



158
159
160
 
# File 'lib/toys/tool.rb', line 158

def tool_definition
  @__data[Keys::TOOL_DEFINITION]
end

#tool_name ⇒ Array[String]

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

Returns:

  • (Array[String]) 


166
167
168
 
# File 'lib/toys/tool.rb', line 166

def tool_name
  @__data[Keys::TOOL_NAME]
end

#usage_error ⇒ String?

Return any usage error detected during argument parsing, or nil if no error was detected.

Returns:

  • (String, nil) 


184
185
186
 
# File 'lib/toys/tool.rb', line 184

def usage_error
  @__data[Keys::USAGE_ERROR]
end

#verbosity ⇒ Integer

Return the current verbosity setting as an integer.

Returns:

  • (Integer) 


150
151
152
 
# File 'lib/toys/tool.rb', line 150

def verbosity
  @__data[Keys::VERBOSITY]
end