Class: Stannum::Association

Inherits:
Object
  • Object
show all
Defined in:
lib/stannum/association.rb

Overview

Data object representing an association on an entity.

Defined Under Namespace

Classes: AbstractAssociationError, Builder, InverseAssociationError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, options:, type:) ⇒ Association

Returns a new instance of Association.

Parameters:

  • name (String, Symbol) —

    The name of the association. Converted to a String.

  • options (Hash, nil) —

    Options for the association. Converted to a Hash with Symbol keys. Defaults to an empty Hash.

  • type (Class, Module, String) —

    The type of the association. Can be a Class, a Module, or the name of a class or module.



57
58
59
60
61
62
63
64
65
66
 
# File 'lib/stannum/association.rb', line 57

def initialize(name:, options:, type:)
  validate_name(name)
  validate_options(options)
  validate_type(type)

  @name    = name.to_s
  @options = tools.hash_tools.convert_keys_to_symbols(options || {})

  @type, @resolved_type = resolve_type(type)
end

Instance Attribute Details

#name ⇒ String (readonly)

Returns the name of the association.

Returns:

  • (String) —

    the name of the association.



69
70
71
 
# File 'lib/stannum/association.rb', line 69

def name
  @name
end

#options ⇒ Hash (readonly)

Returns the association options.

Returns:

  • (Hash) —

    the association options.



72
73
74
 
# File 'lib/stannum/association.rb', line 72

def options
  @options
end

#type ⇒ String (readonly)

Returns the name of the association type Class or Module.

Returns:

  • (String) —

    the name of the association type Class or Module.



75
76
77
 
# File 'lib/stannum/association.rb', line 75

def type
  @type
end

Instance Method Details

#add_value(entity, value, update_inverse: true) ⇒ void

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.

This method returns an undefined value.

Adds the given value to the association for the entity.

Parameters:

  • entity (Stannum::Entity) —

    the entity to update.

  • value (Object) —

    the new value for the association.

  • update_inverse (Boolean) (defaults to: true) —

    if true, updates the inverse association (if any). Defaults to false.

Raises:



87
88
89
90
 
# File 'lib/stannum/association.rb', line 87

def add_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
  raise AbstractAssociationError,
    "#{self.class} is an abstract class - use an association subclass"
end

#clear_value(entity, update_inverse: true) ⇒ void

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.

This method returns an undefined value.

Removes the value of the association for the entity.

Parameters:

Raises:



99
100
101
102
 
# File 'lib/stannum/association.rb', line 99

def clear_value(entity, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
  raise AbstractAssociationError,
    "#{self.class} is an abstract class - use an association subclass"
end

#entity_class_name ⇒ String?

Returns the name of the original entity class.

Returns:

  • (String, nil) —

    the name of the original entity class.



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

def entity_class_name
  @options[:entity_class_name]
end

#foreign_key? ⇒ true, false

Returns true if the association has defines a foreign key; otherwise false.

Returns:

  • (true, false) —

    true if the association has defines a foreign key; otherwise false.



111
112
113
 
# File 'lib/stannum/association.rb', line 111

def foreign_key?
  false
end

#foreign_key_name ⇒ String?

Returns the name of the foreign key, if any.

Returns:

  • (String?) —

    the name of the foreign key, if any.



116
117
118
 
# File 'lib/stannum/association.rb', line 116

def foreign_key_name
  nil
end

#foreign_key_type ⇒ Class, ...

Returns the type of the foreign key, if any.

Returns:



122
123
124
 
# File 'lib/stannum/association.rb', line 122

def foreign_key_type
  nil
end

#get_value(entity) ⇒ 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 value of the association for the entity.

Parameters:

Returns:

  • (Object) —

    the value of the association.

Raises:



133
134
135
136
 
# File 'lib/stannum/association.rb', line 133

def get_value(entity) # rubocop:disable Lint/UnusedMethodArgument
  raise AbstractAssociationError,
    "#{self.class} is an abstract class - use an association subclass"
end

#inverse? ⇒ Boolean

Returns true if the association has an inverse association; otherwise false.

Returns:

  • (Boolean) —

    true if the association has an inverse association; otherwise false.



140
141
142
 
# File 'lib/stannum/association.rb', line 140

def inverse?
  !!@options[:inverse]
end

#inverse_name ⇒ String

Returns the name of the inverse association, if any.

Returns:

  • (String) —

    the name of the inverse association, if any.



145
146
147
 
# File 'lib/stannum/association.rb', line 145

def inverse_name
  @inverse_name ||= resolve_inverse_name
end

#many? ⇒ false

Returns true if the association is a plural association; otherwise false.

Returns:

  • (false) —

    true if the association is a plural association; otherwise false.



151
152
153
 
# File 'lib/stannum/association.rb', line 151

def many?
  false
end

#one? ⇒ false

Returns true if the association is a singular association; otherwise false.

Returns:

  • (false) —

    true if the association is a singular association; otherwise false.



157
158
159
 
# File 'lib/stannum/association.rb', line 157

def one?
  false
end

#reader_name ⇒ Symbol

Returns the name of the reader method for the association.

Returns:

  • (Symbol) —

    the name of the reader method for the association.



162
163
164
 
# File 'lib/stannum/association.rb', line 162

def reader_name
  @reader_name ||= name.intern
end

#remove_value(entity, value, update_inverse: true) ⇒ void

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.

This method returns an undefined value.

Removes the given value from the association for the entity.

Parameters:

  • entity (Stannum::Entity) —

    the entity to update.

  • value (Stannum::Entity) —

    the association value to remove.

  • update_inverse (Boolean) (defaults to: true) —

    if true, updates the inverse association (if any). Defaults to false.

Raises:



176
177
178
179
 
# File 'lib/stannum/association.rb', line 176

def remove_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
  raise AbstractAssociationError,
    "#{self.class} is an abstract class - use an association subclass"
end

#resolved_inverse ⇒ Stannum::Association

Returns the inverse association, if any.

Returns:



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/stannum/association.rb', line 182

def resolved_inverse
  return @resolved_inverse if @resolved_inverse

  return unless inverse?

  @resolved_inverse = resolved_type.associations[inverse_name]
rescue KeyError => exception
  raise InverseAssociationError,
    "unable to resolve inverse association #{exception.key.inspect}"
end

#resolved_type ⇒ Module

Returns the type of the association.

Returns:

  • (Module) —

    the type of the association.



194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/stannum/association.rb', line 194

def resolved_type
  return @resolved_type if @resolved_type

  @resolved_type = Object.const_get(type)

  unless @resolved_type.is_a?(Module)
    raise NameError, "constant #{type} is not a Class or Module"
  end

  @resolved_type
end

#set_value(entity, value, update_inverse: true) ⇒ void

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.

This method returns an undefined value.

Replaces the association for the entity with the given value.

Parameters:

  • entity (Stannum::Entity) —

    the entity to update.

  • value (Object) —

    the new value for the association.

  • update_inverse (Boolean) (defaults to: true) —

    if true, updates the inverse association (if any). Defaults to false.

Raises:



216
217
218
219
 
# File 'lib/stannum/association.rb', line 216

def set_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
  raise AbstractAssociationError,
    "#{self.class} is an abstract class - use an association subclass"
end

#writer_name ⇒ Symbol

Returns the name of the writer method for the association.

Returns:

  • (Symbol) —

    the name of the writer method for the association.



222
223
224
 
# File 'lib/stannum/association.rb', line 222

def writer_name
  @writer_name ||= :"#{name}="
end