Module: Stannum::Entities::Attributes

Included in:
Stannum::Entity, Struct
Defined in:
lib/stannum/entities/attributes.rb

Overview

Methods for defining and accessing entity attributes.

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.apply(other) ⇒ Object

Generates Attributes schema for the class.

Creates a new Stannum::Schema and sets it as the class’s :Attributes constant. If the superclass is an entity class (and already defines its own Attributes, includes the superclass Attributes in the class Attributes). Finally, includes the class Attributes in the class.



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/stannum/entities/attributes.rb', line 73

def apply(other)
  return unless other.is_a?(Class)

  return if entity_class?(other)

  other.const_set(:Attributes, build_schema)

  if entity_class?(other.superclass)
    other::Attributes.include(other.superclass::Attributes)
  end

  other.include(other::Attributes)
end

Instance Method Details

#assign_attributes(attributes) ⇒ Object

Updates the struct’s attributes with the given values.

This method is used to update some (but not all) of the attributes of the struct. For each key in the hash, it calls the corresponding writer method with the value for that attribute. If the value is nil, this will set the attribute value to the default for that attribute.

Any attributes that are not in the given hash are unchanged, as are any properties that are not attributes.

If the attributes hash includes any keys that do not correspond to an attribute, the struct will raise an error.

Raises:

  • ArgumentError if any key is not a valid attribute.

See Also:



136
137
138
139
140
141
142
 
# File 'lib/stannum/entities/attributes.rb', line 136

def assign_attributes(attributes)
  unless attributes.is_a?(Hash)
    raise ArgumentError, 'attributes must be a Hash'
  end

  set_attributes(attributes, force: false)
end

#attributes ⇒ Hash<String, Object>

Collects the entity attributes.



147
148
149
 
# File 'lib/stannum/entities/attributes.rb', line 147

def attributes
  @attributes.dup
end

#attributes=(attributes) ⇒ Object

Replaces the entity’s attributes with the given values.

This method is used to update all of the attributes of the entity. For each attribute, the writer method is called with the value from the hash, or nil if the corresponding key is not present in the hash. Any nil or missing values set the attribute value to that attribute’s default value, if any. Non-attribute properties are unchanged.

If the attributes hash includes any keys that do not correspond to a valid attribute, the entity will raise an error.

Raises:

  • ArgumentError if any key is not a valid attribute.

See Also:



167
168
169
170
171
172
173
 
# File 'lib/stannum/entities/attributes.rb', line 167

def attributes=(attributes)
  unless attributes.is_a?(Hash)
    raise ArgumentError, 'attributes must be a Hash'
  end

  set_attributes(attributes, force: true)
end

#initialize(**properties) ⇒ Object 



110
111
112
113
114
115
116
 
# File 'lib/stannum/entities/attributes.rb', line 110

def initialize(**properties)
  @attributes = {}

  self.class.attributes.each_key { |key| @attributes[key] = nil }

  super
end

#properties ⇒ Hash<String, Object>

Collects the entity properties.



176
177
178
 
# File 'lib/stannum/entities/attributes.rb', line 176

def properties
  super.merge(attributes)
end

#read_attribute(key, safe: true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Retrieves the attribute value for the requested key.

If the :safe flag is set, will verify that the attribute name is valid (a non-empty String or Symbol) and that there is a defined attribute by that name. By default, :safe is set to true.



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/stannum/entities/attributes.rb', line 192

def read_attribute(key, safe: true)
  if safe
    tools.assertions.validate_name(key, as: 'attribute')

    unless self.class.attributes.key?(key.to_s)
      raise ArgumentError, "unknown attribute #{key.inspect}"
    end
  end

  @attributes[key.to_s]
end

#write_attribute(key, value, safe: true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Assigns the attribute value for the requested key.

If the :safe flag is set, will verify that the attribute name is valid (a non-empty String or Symbol) and that there is a defined attribute by that name. By default, :safe is set to true.



217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/stannum/entities/attributes.rb', line 217

def write_attribute(key, value, safe: true)
  if safe
    tools.assertions.validate_name(key, as: 'attribute')

    unless self.class.attributes.key?(key.to_s)
      raise ArgumentError, "unknown attribute #{key.inspect}"
    end
  end

  @attributes[key.to_s] = value
end