Class: Thor::Execution

Inherits:
Object
  • Object
show all
Includes:
SemanticLogger::Loggable
Defined in:
lib/thor/execution.rb

Overview

An execution is an object created by Base::ClassMethods#exec! that holds references to all relevant objects for running a Thor instance as an executable and manages that execution.

Constant Summary collapse

BUILT_IN_ENV_PREFIXES =

Constants

Hamster::Vector['ATLI', 'THOR']

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(thor_class:, given_args:, thor_config:) ⇒ Execution

Instantiate a new ‘Thor::Execution`.



88
89
90
91
92
93
 
# File 'lib/thor/execution.rb', line 88

def initialize thor_class:, given_args:, thor_config:
  @thor_class = thor_class
  @given_args = given_args.dup
  @thor_config = thor_config
  @thor_instance = nil
end

Instance Attribute Details

#given_args ⇒ Array<String> (readonly)

The command line arguments given for execution.

Returns:

  • (Array<String>) 


64
65
66
 
# File 'lib/thor/execution.rb', line 64

def given_args
  @given_args
end

#thor_class ⇒ Class<Thor> (readonly)

The Thor subclass that is being executed.

Returns:



57
58
59
 
# File 'lib/thor/execution.rb', line 57

def thor_class
  @thor_class
end

#thor_config ⇒ Hash (readonly)

The configuration hash, which includes any config values passed to Base::ClassMethods#exec!, and is mutated in Base#initialize to include things like the current command.

Returns:

  • (Hash) 


73
74
75
 
# File 'lib/thor/execution.rb', line 73

def thor_config
  @thor_config
end

#thor_instance ⇒ Class<Thor>? (readonly)

The instance or Thor being executed, if it has been successfully constructed.

Returns:



81
82
83
 
# File 'lib/thor/execution.rb', line 81

def thor_instance
  @thor_instance
end

Instance Method Details

#backtrace? ⇒ Boolean

Should we print backtraces with errors?

Returns:

  • (Boolean) 


227
228
229
 
# File 'lib/thor/execution.rb', line 227

def backtrace?
  debug? || get_context_value( :backtrace ).truthy?
end

#debug? ⇒ Boolean

Are we in debug mode?

Returns:

  • (Boolean) 


221
222
223
 
# File 'lib/thor/execution.rb', line 221

def debug?
  get_context_value( :debug ).truthy?
end

#env_key_for(prefix:, key:) ⇒ return_type

TODO:

Document env_key method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



121
122
123
 
# File 'lib/thor/execution.rb', line 121

def env_key_for prefix:, key:
  "#{ prefix }_#{ key.upcase }"
end

#env_prefixes ⇒ return_type

TODO:

Document env_prefixes method.

Returns @todo Document return value.

Parameters:

  • arg_name (type) —

    @todo Add name param description.

Returns:

  • (return_type) —

    @todo Document return value.



107
108
109
 
# File 'lib/thor/execution.rb', line 107

def env_prefixes
  BUILT_IN_ENV_PREFIXES
end

#exec! ⇒ Object

Let’s do this thang!



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/thor/execution.rb', line 239

def exec!
  thor_config[:shell] ||= Thor::Base.shell.new
  
  thor_class.send(
    :dispatch,
    nil,
    given_args,
    nil,
    thor_config
  ) { |thor_instance|
    @thor_instance = thor_instance
    
    logger.debug "Got Thor instance",
      options: thor_instance.options
  }
rescue SystemExit
  # `exit` was called; we want to just let this keep going
  raise
rescue Errno::EPIPE
  # This happens if a thor command is piped to something like `head`,
  # which closes the pipe when it's done reading. This will also
  # mean that if the pipe is closed, further unnecessary
  # computation will not occur.
  exit true
rescue Exception => error
  raise if raise_errors?
  
  if backtrace?
    logger.error error
  else
    logger.error error.message
  end
  
  exit false
end

#get_context_value(key, with_source: false) ⇒ Object, Array<(Object, Symbol?, (String | Symbol)?>)

Get the value for a key from the “context”, which is the hierarchy of Thor instance class options, Thor config values and ENV variables.

Parameters:

  • key (Symbol) —

    The key to get the value for.

  • with_source: (Boolean) (defaults to: false) —

    When true, returns where the value was found as well (see below).

Returns:

  • (Object) —

    When with_source: is false, just returns the value that was found, or nil if none was.

  • (Array<(Object, Symbol?, (String | Symbol)?>)) —

    When with_source: is true returns an Array triple:

    1. The value that was found, or ‘nil` if none was.

    2. A symbol indicating where the value was found:

      1. :thor_instance_options The ‘#options` hash of the #thor_instance. You will only see this result if the Thor instance successfully constructed and became available to the execution.

      2. :thor_config The #thor_config hash.

      3. :env The ENV.

      If the value isn’t found, this will be nil.

    3. The key used to get the value from the source hash-like. This is only really important when it came from the ENV.

      If the value is not found, this will be nil.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/thor/execution.rb', line 196

def get_context_value key, with_source: false
  # 1.  First stop is the Thor instance's options (if we have a Thor instance)
  if thor_instance && thor_instance.options.key?( key )
    if with_source
      return [thor_instance.options[key], :thor_instance_options, key]
    else
      return thor_instance.options[key]
    end
  end
  
  # 2.  Next, check the config that was handed to `.exec!`
  if thor_config.key? key
    if with_source
      return [thor_config[key], :thor_config, key]
    else
      return thor_config[key]
    end
  end
  
  # 3. Last, check the ENV (returns `nil` if nothing found)
  get_from_env key, with_source: with_source
end

#get_from_env(key, with_source: false) ⇒ String?, ...

TODO:

Document get_from_env method.

Parameters:

  • key (Symbol) —

    The key to get the value for.

  • with_source: (Boolean) (defaults to: false) —

    When true, returns where the value was found as well (see below).

Returns:

  • (String?) —

    When with_source: is false, just returns the value that was found, or nil if none was.

  • (Array<(nil, nil, nil)>) —

    When with_source: is true and no value was found.

  • (Array<(String, :env, String)>) —

    When with_source: is true and the value was found.

    The first entry is the value, the last is the ENV key it was at.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/thor/execution.rb', line 143

def get_from_env key, with_source: false
  env_prefixes.each do |prefix|
    env_key = env_key_for prefix: prefix, key: key
    if ENV.key? env_key
      if with_source
        return [ENV[env_key], :env, env_key]
      else
        return ENV[env_key]
      end
    end
  end
  
  if with_source
    [nil, nil, nil]
  else
    nil
  end
end

#raise_errors? ⇒ Boolean

Should we raise errors (versus print them and exit)?

Returns:

  • (Boolean) 


233
234
235
 
# File 'lib/thor/execution.rb', line 233

def raise_errors?
  debug? || get_context_value( :raise_errors ).truthy?
end