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, &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.



24
25
26
27
28
29
30
31
 
# File 'lib/pdk/config/namespace.rb', line 24

def initialize(name = nil, file: nil, parent: nil, &block)
  @file = File.expand_path(file) unless file.nil?
  @values = {}
  @name = name.to_s
  @parent = parent

  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.



157
158
159
 
# File 'lib/pdk/config/namespace.rb', line 157

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.



86
87
88
 
# File 'lib/pdk/config/namespace.rb', line 86

def [](key)
  data[key.to_s]
end

#[]=(key, value) ⇒ nil

Set the value of the named key.

If the key has been pre-configured with #value, then the value of the key will be validated against any validators that have been configured.

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) 


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

def []=(key, value)
  @values[key.to_s].validate!([name, key.to_s].join('.'), value) if @values.key?(key.to_s)

  data[key.to_s] = value
  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.



147
148
149
 
# File 'lib/pdk/config/namespace.rb', line 147

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.



103
104
105
 
# File 'lib/pdk/config/namespace.rb', line 103

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.



170
171
172
 
# File 'lib/pdk/config/namespace.rb', line 170

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.



58
59
60
61
62
63
64
 
# File 'lib/pdk/config/namespace.rb', line 58

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) 


70
71
72
 
# File 'lib/pdk/config/namespace.rb', line 70

def namespace(name, &block)
  mount(name, PDK::Config::Namespace.new, &block)
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.



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

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) 


42
43
44
45
 
# File 'lib/pdk/config/namespace.rb', line 42

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