Class: PDK::Config::Namespace

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

Direct Known Subclasses

JSON, 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
 
# 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?
  @values = {}
  @name = name.to_s
  @parent = parent
  @persistent_defaults = persistent_defaults

  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.



177
178
179
 
# File 'lib/pdk/config/namespace.rb', line 177

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.



90
91
92
 
# File 'lib/pdk/config/namespace.rb', line 90

def [](key)
  data[key.to_s]
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) 


118
119
120
121
122
 
# File 'lib/pdk/config/namespace.rb', line 118

def []=(key, value)
  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.



167
168
169
 
# File 'lib/pdk/config/namespace.rb', line 167

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.

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.



107
108
109
 
# File 'lib/pdk/config/namespace.rb', line 107

def fetch(key, default_value)
  data.fetch(key.to_s, default_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.



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

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.



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

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?
  data[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) 


74
75
76
 
# File 'lib/pdk/config/namespace.rb', line 74

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’



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/pdk/config/namespace.rb', line 148

def resolve(filter = nil)
  # Explicitly force values to be loaded if they have not already
  # done so. This will not cause them to be persisted to disk
  (@values.keys - data.keys).each { |key_name| self[key_name] }
  resolved = {}
  data.each do |data_name, obj|
    case obj
    when PDK::Config::Namespace
      # Query the child namespace
      resolved.merge!(obj.resolve(filter))
    else
      setting_name = [name, data_name.to_s].join('.')
      resolved[setting_name] = self[data_name] if be_resolved?(setting_name, filter)
    end
  end
  resolved
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.



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

def to_h
  data.inject({}) do |new_hash, (key, value)|
    new_hash[key] = if value.is_a?(PDK::Config::Namespace)
                      value.include_in_parent? ? value.to_h : nil
                    else
                      value
                    end
    new_hash.delete_if { |_, v| v.nil? }
  end
end

#value(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) 


46
47
48
49
 
# File 'lib/pdk/config/namespace.rb', line 46

def value(key, &block)
  @values[key.to_s] ||= PDK::Config::Value.new(key.to_s)
  @values[key.to_s].instance_eval(&block) if block_given?
end