Module: Stannum::Entities::Properties

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

Overview

Abstract module for handling heterogenous entity properties.

This module provides a base for accessing and mutating entity properties such as attributes and associations.

Instance Method Summary collapse

Instance Method Details

#==(other) ⇒ Object

Compares the entity with the other object.

The other object must be an instance of the current class. In addition, the properties hashes of the two objects must be equal.

Returns:

  • true if the object is a matching entity.



25
26
27
28
29
 
# File 'lib/stannum/entities/properties.rb', line 25

def ==(other)
  return false unless other.class == self.class

  properties == other.properties
end

#[](property) ⇒ Object

Retrieves the property with the given key.

Parameters:

  • property (String, Symbol) —

    The property key.

Returns:

  • (Object) —

    the value of the property.

Raises:

  • ArgumentError if the key is not a valid property.



38
39
40
41
42
 
# File 'lib/stannum/entities/properties.rb', line 38

def [](property)
  tools.assertions.validate_name(property, as: 'property')

  get_property(property)
end

#[]=(property, value) ⇒ Object

Sets the given property to the given value.

Parameters:

  • property (String, Symbol) —

    The property key.

  • value (Object) —

    The value for the property.

Raises:

  • ArgumentError if the key is not a valid property.



50
51
52
53
54
 
# File 'lib/stannum/entities/properties.rb', line 50

def []=(property, value)
  tools.assertions.validate_name(property, as: 'property')

  set_property(property, value)
end

#assign_properties(properties) ⇒ Object Also known as: assign

Updates the struct’s properties with the given values.

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

Any properties that are not in the given hash are unchanged.

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

Parameters:

  • properties (Hash) —

    The initial properties for the struct.

Raises:

  • ArgumentError if the key is not a valid property.

See Also:



73
74
75
76
77
78
79
 
# File 'lib/stannum/entities/properties.rb', line 73

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

  set_properties(properties, force: false)
end

#initialize(**properties) ⇒ Object

Parameters:

  • properties (Hash) —

    the properties used to initialize the entity.



15
16
17
 
# File 'lib/stannum/entities/properties.rb', line 15

def initialize(**properties)
  set_properties(properties, force: true)
end

#inspect ⇒ String

Returns a string representation of the entity and its properties.

Returns:

  • (String) —

    a string representation of the entity and its properties.



83
84
85
 
# File 'lib/stannum/entities/properties.rb', line 83

def inspect
  inspect_with_options
end

#inspect_with_options(**options) ⇒ String

Returns a string representation of the entity and its properties.

Parameters:

  • options (Hash) —

    options for inspecting the entity.

Options Hash (**options):

  • memory_address (Boolean) —

    if true, displays the memory address of the object (as per Object#inspect). Defaults to false.

  • properties (Boolean) —

    if true, displays the entity properties. Defaults to true.

Returns:

  • (String) —

    a string representation of the entity and its properties.



95
96
97
98
99
100
 
# File 'lib/stannum/entities/properties.rb', line 95

def inspect_with_options(**options)
  address = options[:memory_address] ? ":#{memory_address}" : ''
  mapped  = inspect_properties(**options)

  "#<#{self.class.name}#{address}#{mapped}>"
end

#properties ⇒ Hash<String, Object>

Collects the entity properties.

Returns:

  • (Hash<String, Object>) —

    the entity properties.



105
106
107
 
# File 'lib/stannum/entities/properties.rb', line 105

def properties
  {}
end

#properties=(properties) ⇒ Object

Replaces the entity’s properties with the given values.

This method is used to update all of the properties of the entity. For each property, 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 property value to that property’s default value, if any.

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

Parameters:

  • properties (Hash) —

    the properties to assign to the entity.

Raises:

  • ArgumentError if any key is not a valid property.

See Also:



125
126
127
128
129
130
131
 
# File 'lib/stannum/entities/properties.rb', line 125

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

  set_properties(properties, force: true)
end

#to_h ⇒ Hash<String, Object>

Returns a Hash representation of the entity.

Returns:

  • (Hash<String, Object>) —

    the entity properties.

See Also:



138
139
140
 
# File 'lib/stannum/entities/properties.rb', line 138

def to_h
  properties
end