Class: Thor::Execution

Inherits:
Object
  • Object
show all
Includes:
NRSER::Log::Mixin
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`.



91
92
93
94
95
96
 
# File 'lib/thor/execution.rb', line 91

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


67
68
69
 
# File 'lib/thor/execution.rb', line 67

def given_args
  @given_args
end

#thor_class ⇒ Class<Thor> (readonly)

The Thor subclass that is being executed.

Returns:



60
61
62
 
# File 'lib/thor/execution.rb', line 60

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) 


76
77
78
 
# File 'lib/thor/execution.rb', line 76

def thor_config
  @thor_config
end

#thor_instance ⇒ Class<Thor>? (readonly)

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

Returns:



84
85
86
 
# File 'lib/thor/execution.rb', line 84

def thor_instance
  @thor_instance
end

Instance Method Details

#backtrace? ⇒ Boolean

Should we print backtraces with errors?

Returns:

  • (Boolean) 


230
231
232
 
# File 'lib/thor/execution.rb', line 230

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

#debug? ⇒ Boolean

Are we in debug mode?

Returns:

  • (Boolean) 


224
225
226
 
# File 'lib/thor/execution.rb', line 224

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.



124
125
126
 
# File 'lib/thor/execution.rb', line 124

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.



110
111
112
 
# File 'lib/thor/execution.rb', line 110

def env_prefixes
  BUILT_IN_ENV_PREFIXES
end

#exec! ⇒ Object

Let’s do this thang!



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
274
275
276
 
# File 'lib/thor/execution.rb', line 242

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.



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

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.



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

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) 


236
237
238
 
# File 'lib/thor/execution.rb', line 236

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