class Capistrano::Configuration::Variables

Holds the variables assigned at Capistrano runtime via `set` and retrieved with `fetch`. Does internal bookkeeping to help identify user mistakes like spelling errors or unused variables that may lead to unexpected behavior. Also allows validation rules to be registered with `validate`.

Constants

CAPISTRANO_LOCATION
IGNORED_LOCATIONS

Attributes

fetched_keys[R]
locations[R]
values[R]

Public Class Methods

new(values={}) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 18
def initialize(values={})
  @trusted_keys = []
  @fetched_keys = []
  @locations = {}
  @values = values
  @trusted = true
end

Public Instance Methods

delete(key) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 60
def delete(key)
  values.delete(key)
end
fetch(key, default=nil, &block) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 42
def fetch(key, default=nil, &block)
  fetched_keys << key
  peek(key, default, &block)
end
fetch_for(key, default, &block) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 56
def fetch_for(key, default, &block)
  block ? values.fetch(key, &block) : values.fetch(key, default)
end
keys() click to toggle source
# File lib/capistrano/configuration/variables.rb, line 78
def keys
  values.keys
end
peek(key, default=nil, &block) click to toggle source

Internal use only.

# File lib/capistrano/configuration/variables.rb, line 48
def peek(key, default=nil, &block)
  value = fetch_for(key, default, &block)
  while callable_without_parameters?(value)
    value = (values[key] = value.call)
  end
  value
end
set(key, value=nil, &block) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 33
def set(key, value=nil, &block)
  invoke_validations(key, value, &block)
  @trusted_keys << key if trusted?
  remember_location(key)
  values[key] = block || value
  trace_set(key)
  values[key]
end
source_locations(key) click to toggle source

Returns an array of source file location(s) where the given key was assigned (i.e. where `set` was called). If the key was never assigned, returns `nil`.

# File lib/capistrano/configuration/variables.rb, line 90
def source_locations(key)
  locations[key]
end
trusted_keys() click to toggle source
# File lib/capistrano/configuration/variables.rb, line 70
def trusted_keys
  @trusted_keys.dup
end
untrusted!() { || ... } click to toggle source
# File lib/capistrano/configuration/variables.rb, line 26
def untrusted!
  @trusted = false
  yield
ensure
  @trusted = true
end
untrusted_keys() click to toggle source
# File lib/capistrano/configuration/variables.rb, line 74
def untrusted_keys
  keys - @trusted_keys
end
unused_keys() click to toggle source

Keys that have been set, but which have never been fetched.

# File lib/capistrano/configuration/variables.rb, line 83
def unused_keys
  keys - fetched_keys
end
validate(key, &validator) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 64
def validate(key, &validator)
  vs = (validators[key] || [])
  vs << validator
  validators[key] = vs
end

Private Instance Methods

callable_without_parameters?(x) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 109
def callable_without_parameters?(x)
  x.respond_to?(:call) && (!x.respond_to?(:arity) || x.arity == 0)
end
invoke_validations(key, value, &block) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 117
def invoke_validations(key, value, &block)
  unless value.nil? || block.nil?
    raise Capistrano::ValidationError,
          "Value and block both passed to Configuration#set"
  end

  return unless validators.key? key

  validators[key].each do |validator|
    validator.call(key, block || value)
  end
end
remember_location(key) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 102
def remember_location(key)
  location = caller.find do |line|
    IGNORED_LOCATIONS.none? { |i| line.include?(i) }
  end
  (locations[key] ||= []) << location
end
trace_set(key) click to toggle source
# File lib/capistrano/configuration/variables.rb, line 130
def trace_set(key)
  return unless fetch(:print_config_variables, false)
  puts "Config variable set: #{key.inspect} => #{values[key].inspect}"
end
trusted?() click to toggle source
# File lib/capistrano/configuration/variables.rb, line 98
def trusted?
  @trusted
end
validators() click to toggle source
# File lib/capistrano/configuration/variables.rb, line 113
def validators
  @validators ||= {}
end