Class: PDK::Config::Namespace

Inherits:
Object
  • Object
show all
Defined in:
lib/pdk/config/namespace.rb

Direct Known Subclasses

JSON, JSONSchemaNamespace, YAML

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name = nil, file: nil, parent: nil, persistent_defaults: false, &block) ⇒ Namespace

Initialises the PDK::Config::Namespace object.

Parameters:

  • name (String) (defaults to: nil) —

    the name of the namespace (defaults to nil).

  • params (Hash{Symbol => Object}) —

    keyword parameters for the method.

  • block (Proc) —

    a block that is evaluated within the new instance.



27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/pdk/config/namespace.rb', line 27

def initialize(name = nil, file: nil, parent: nil, persistent_defaults: false, &block)
  @file = File.expand_path(file) unless file.nil?
  @settings = {}
  @name = name.to_s
  @parent = parent
  @persistent_defaults = persistent_defaults
  @mounts = {}
  @loaded_from_file = false

  instance_eval(&block) if block_given?
end

Instance Attribute Details

#file ⇒ String (readonly)

Returns the path to the file associated with the contents of this namespace.

Returns:

  • (String) —

    the path to the file associated with the contents of this namespace.



9
10
11
 
# File 'lib/pdk/config/namespace.rb', line 9

def file
  @file
end

#name ⇒ String

Determines the fully qualified name of the namespace.

If this is a child namespace, then fully qualified name for the namespace will be “<parent>.<child>”.

Returns:

  • (String) —

    the fully qualifed name of the namespace.



189
190
191
 
# File 'lib/pdk/config/namespace.rb', line 189

def name
  child_namespace? ? [parent.name, @name].join('.') : @name
end

#parent ⇒ self

Returns the parent namespace of this namespace.

Returns:

  • (self) —

    the parent namespace of this namespace.



12
13
14
 
# File 'lib/pdk/config/namespace.rb', line 12

def parent
  @parent
end

Instance Method Details

#[](key) ⇒ Object

Note:

Unlike a Ruby Hash, this will not return ‘nil` in the event that the key does not exist (see #fetch).

Get the value of the named key.

If there is a value for that key, return it. If not, follow the logic described in #default_config_value to determine the default value to return.

Parameters:

  • key (String, Symbol) —

    the name of the value to retrieve.

Returns:

  • (Object) —

    the requested value.



92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/pdk/config/namespace.rb', line 92

def [](key)
  # Check if it's a mount first...
  return @mounts[key.to_s] unless @mounts[key.to_s].nil?
  # Check if it's a setting, otherwise nil
  return nil if settings[key.to_s].nil?
  return settings[key.to_s].value unless settings[key.to_s].value.nil?
  default_value = settings[key.to_s].default
  return default_value if default_value.nil? || !@persistent_defaults
  # Persist the default value
  settings[key.to_s].value = default_value
  save_data
  default_value
end

#[]=(key, value) ⇒ nil

After the value has been set in memory, the value will then be persisted to disk.

Parameters:

  • key (String, Symbol) —

    the name of the configuration value.

  • value (Object) —

    the value of the configuration value.

Returns:

  • (nil)

Raises:

  • (ArgumentError) 


135
136
137
138
139
140
141
 
# File 'lib/pdk/config/namespace.rb', line 135

def []=(key, value)
  # You can't set the value of a mount
  raise ArgumentError, _('Namespace mounts can not be set a value') unless @mounts[key.to_s].nil?
  set_volatile_value(key, value)
  # Persist the change
  save_data
end

#child_namespace? ⇒ Boolean

Returns true if the namespace has a parent, otherwise false.

Returns:

  • (Boolean) —

    true if the namespace has a parent, otherwise false.



179
180
181
 
# File 'lib/pdk/config/namespace.rb', line 179

def child_namespace?
  !parent.nil?
end

#fetch(key, default_value) ⇒ Object

Get the value of the named key or the provided default value if not present. Note that this does not trigger persistent defaults

This differs from #[] in an important way in that it allows you to return a default value, which is not possible using ‘[] || default` as non-existent values when accessed normally via #[] will be defaulted to a new Hash.

Parameters:

  • key (String, Symbol) —

    the name of the value to fetch.

  • default_value (Object) —

    the value to return if the namespace does not contain the requested value.

Returns:

  • (Object) —

    the requested value.



119
120
121
122
123
124
125
126
 
# File 'lib/pdk/config/namespace.rb', line 119

def fetch(key, default_value)
  # Check if it's a mount first...
  return @mounts[key.to_s] unless @mounts[key.to_s].nil?
  # Check if it's a setting, otherwise default_value
  return default_value if settings[key.to_s].nil?
  # Check if has a value, otherwise default_value
  settings[key.to_s].value.nil? ? default_value : settings[key.to_s].value
end

#include_in_parent? ⇒ Boolean

Determines if the contents of the namespace should be included in the parent namespace when persisting to disk.

If the namespace has been mounted into a parent namespace and is not associated with its own file on disk, then the values in the namespace should be included in the parent namespace when persisting to disk.

Returns:

  • (Boolean) —

    true if the values should be included in the parent namespace.



202
203
204
 
# File 'lib/pdk/config/namespace.rb', line 202

def include_in_parent?
  child_namespace? && file.nil?
end

#mount(key, obj, &block) ⇒ self

Mount a provided [self] (or subclass) into the namespace.

Parameters:

  • key (String, Symbol) —

    the name of the namespace to be mounted.

  • obj (self) —

    the namespace to be mounted.

  • block (Proc) —

    a block to be evaluated within the instance of the newly mounted namespace.

Returns:

  • (self) —

    the mounted namespace.

Raises:

  • (ArgumentError) —

    if the object to be mounted is not a self or subclass thereof.



64
65
66
67
68
69
70
 
# File 'lib/pdk/config/namespace.rb', line 64

def mount(key, obj, &block)
  raise ArgumentError, _('Only PDK::Config::Namespace objects can be mounted into a namespace') unless obj.is_a?(PDK::Config::Namespace)
  obj.parent = self
  obj.name = key.to_s
  obj.instance_eval(&block) if block_given?
  @mounts[key.to_s] = obj
end

#namespace(name, &block) ⇒ Object

Create and mount a new child namespace.

Parameters:

  • name (String, Symbol) —

    the name of the new namespace.

  • block (Proc) 


76
77
78
 
# File 'lib/pdk/config/namespace.rb', line 76

def namespace(name, &block)
  mount(name, PDK::Config::Namespace.new, &block)
end

#resolve(filter = nil) ⇒ Hash{String => Object}

Resolves all filtered settings, including child namespaces, fully namespaced and filling in default values.

Parameters:

  • filter (String) (defaults to: nil) —

    Only resolve setting names which match the filter. See #be_resolved? for matching rules

Returns:

  • (Hash{String => Object}) —

    All resolved settings for example => ‘johndoe’



164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/pdk/config/namespace.rb', line 164

def resolve(filter = nil)
  resolved = {}
  # Resolve the settings
  settings.values.each do |setting|
    setting_name = setting.qualified_name
    if be_resolved?(setting_name, filter)
      resolved[setting_name] = setting.value.nil? ? setting.default : setting.value
    end
  end
  # Resolve the mounts
  @mounts.values.each { |mount| resolved.merge!(mount.resolve(filter)) }
  resolved
end

#setting(key, &block) ⇒ nil

Pre-configure a value in the namespace.

Allows you to specify validators and a default value for value in the namespace (see PDK::Config::Value#initialize).

Parameters:

  • key (String, Symbol) —

    the name of the value.

  • block (Proc) —

    a block that is evaluated within the new [self].

Returns:

  • (nil) 


48
49
50
51
 
# File 'lib/pdk/config/namespace.rb', line 48

def setting(key, &block)
  @settings[key.to_s] ||= PDK::Config::Setting.new(key.to_s, self)
  @settings[key.to_s].instance_eval(&block) if block_given?
end

#to_h ⇒ Hash{String => Object}

Convert the namespace into a Hash of values, suitable for serialising and persisting to disk.

Child namespaces that are associated with their own files are excluded from the Hash (as their values will be persisted to their own files) and nil values are removed from the Hash.

Returns:

  • (Hash{String => Object}) —

    the values from the namespace that should be persisted to disk.



152
153
154
155
156
157
158
 
# File 'lib/pdk/config/namespace.rb', line 152

def to_h
  new_hash = {}
  settings.each_pair { |k, v| new_hash[k] = v.value }
  @mounts.each_pair { |k, mount_point| new_hash[k] = mount_point.to_h if mount_point.include_in_parent? }
  new_hash.delete_if { |_, v| v.nil? }
  new_hash
end