Module: Calibrate::Configurable

Extended by:
ClassMethods
Included in:
DirectoryStructure::StructurePath, Struct
Defined in:
lib/calibrate/configurable.rb,
lib/calibrate/configurable/proxy-value.rb,
lib/calibrate/configurable/class-methods.rb,
lib/calibrate/configurable/field-metadata.rb,
lib/calibrate/configurable/field-processor.rb,
lib/calibrate/configurable/instance-methods.rb,
lib/calibrate/configurable/directory-structure.rb

Overview

Handles setting options on objects it’s mixed into

Settings can have default values or be required (as opposed to defaulting to nil). Settings and their defaults are inherited (and can be overridden) by subclasses.

Calibrate also includes a yard-extension that will document settings of a Configurable

Examples:

class ConfExample
  include Configurable

  setting :foo
  settings :bar => 1, :baz => 3
  nil_fields :hoo, :ha, :harum
  required_fields :must

  def initialize
    setup_defaults
  end
end

ce = ConfExample.new
ce.bar #=> 1
ce.hoo #=> nil
ce.hoo = "hallo"
ce.check_required #=> raises error because :must and :foo aren't set

Defined Under Namespace

Modules: ClassMethods, DirectoryStructure Classes: Exception, FieldMetadata, FieldProcessor, MissingRelativePaths, NoDefaultValue, ProxyDecorator, ProxyValue, SettingsCopier, SettingsProxier, Struct

Constant Summary collapse

RequiredField = 
Object.new.freeze

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ClassMethods

default_value_for, default_values, field_metadata, field_names, included, inspect_instance, missing_required_fields_on, nested, nil_fields, required_fields, runtime_required_fields, runtime_setting, set_defaults_on, setting, settings

Class Method Details

.unset_defaults_guard ⇒ Object 



44
45
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 44

def self.unset_defaults_guard
end

Instance Method Details

#check_required ⇒ Object

Checks that all required fields have be set, otherwise raises an error

Raises:

  • RuntimeError if any required fields are unset



53
54
55
56
57
58
59
60
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 53

def check_required
  unset_defaults_guard
  missing = self.class.missing_required_fields_on(self)
  unless missing.empty?
    raise RequiredFieldUnset, "Required field#{missing.length > 1 ? "s" : ""} #{missing.map{|field| field.to_s.inspect}.join(", ")} unset on #{self.inspect}"
  end
  self
end

#copy_settings ⇒ Object 



12
13
14
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 12

def copy_settings
  SettingsCopier.new(self)
end

#copy_settings_to(other) ⇒ Object 



16
17
18
19
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 16

def copy_settings_to(other)
  copy_settings.to(other)
  self
end

#fail_unless_set(name) ⇒ Object Also known as: fail_if_unset

Requires that a named field be set



77
78
79
80
81
82
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 77

def fail_unless_set(name)
  if field_unset?(name)
    raise "Assertion failed: Field #{name} unset"
  end
  true
end

#field_unset?(name) ⇒ Boolean

Returns:

  • (Boolean) 


72
73
74
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 72

def field_unset?(name)
  self.class.field_metadata(name).unset_on?(self)
end

#from_hash(hash) ⇒ Object 



33
34
35
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 33

def from_hash(hash)
  self.class.from_hash(self, hash)
end

#initialize_copy(original) ⇒ Object 



8
9
10
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 8

def initialize_copy(original)
  original.copy_settings_to(self)
end

#proxy_settings ⇒ Object 



21
22
23
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 21

def proxy_settings
  SettingsProxier.new(self)
end

#proxy_settings_to(other) ⇒ Object 



25
26
27
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 25

def proxy_settings_to(other)
  proxy_settings.to(other)
end

#proxy_value ⇒ Object 



62
63
64
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 62

def proxy_value
  ProxyDecorator.new(self)
end

#setup_defaults ⇒ Object

Call during initialize to set default values on settings - if you’re using Configurable outside of Calibrate, be sure this gets called.



43
44
45
46
47
48
49
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 43

def setup_defaults
  def self.unset_defaults_guard
  end

  self.class.set_defaults_on(self)
  self
end

#to_hash ⇒ Object 



29
30
31
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 29

def to_hash
  self.class.to_hash(self)
end

#unset?(value) ⇒ Boolean

XXX deprecate

Returns:

  • (Boolean) 


67
68
69
70
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 67

def unset?(value)
  warn "#unset? is deprecated - use field_unset? instead"
  value.nil?
end

#unset_defaults_guard ⇒ Object 



37
38
39
 
# File 'lib/calibrate/configurable/instance-methods.rb', line 37

def unset_defaults_guard
  raise "Tried to check required settings before running setup_defaults"
end