Class: ROM::Mapper::AttributeDSL Private

Inherits:
Object
  • Object
show all
Includes:
ModelDSL
Defined in:
lib/rom/mapper/attribute_dsl.rb

Overview

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

Mapper attribute DSL exposed by mapper subclasses

This class is private even though its methods are exposed by mappers. Typically it's not meant to be used directly.

TODO: break this madness down into smaller pieces

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes, options) ⇒ AttributeDSL

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.

Returns a new instance of AttributeDSL.

Parameters:

  • attributes (Array)

    accumulator array

  • options (Hash)

25
26
27
28
29
30
31
32
33
34
# File 'lib/rom/mapper/attribute_dsl.rb', line 25

def initialize(attributes, options)
  @attributes = attributes
  @options = options
  @copy_keys = options.fetch(:copy_keys)
  @symbolize_keys = options.fetch(:symbolize_keys)
  @prefix = options.fetch(:prefix)
  @prefix_separator = options.fetch(:prefix_separator)
  @reject_keys = options.fetch(:reject_keys)
  @steps = []
end

Instance Attribute Details

#attributesObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def attributes
  @attributes
end

#attributesObject (readonly) Originally defined in module ModelDSL

Returns the value of attribute attributes

#builderObject (readonly) Originally defined in module ModelDSL

Returns the value of attribute builder

#copy_keysObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def copy_keys
  @copy_keys
end

#klassObject (readonly) Originally defined in module ModelDSL

Returns the value of attribute klass

#optionsObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def options
  @options
end

#reject_keysObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def reject_keys
  @reject_keys
end

#stepsObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def steps
  @steps
end

#symbolize_keysObject (readonly)

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.


19
20
21
# File 'lib/rom/mapper/attribute_dsl.rb', line 19

def symbolize_keys
  @symbolize_keys
end

Instance Method Details

#attribute(name, options = EMPTY_HASH, &block) ⇒ Object

Define a mapping attribute with its options and/or block

Examples:

dsl = AttributeDSL.new([])

dsl.attribute(:name)
dsl.attribute(:email, from: 'user_email')
dsl.attribute(:name) { 'John' }
dsl.attribute(:name) { |t| t.upcase }

79
80
81
82
83
84
85
86
87
88
# File 'lib/rom/mapper/attribute_dsl.rb', line 79

def attribute(name, options = EMPTY_HASH, &block)
  with_attr_options(name, options) do |attr_options|
    if options[:type] && block
      raise ArgumentError,
            "can't specify type and block at the same time"
    end
    attr_options[:coercer] = block if block
    add_attribute(name, attr_options)
  end
end

#combine(name, options, &block) ⇒ Object

Define an embedded combined attribute that requires "combine" transformation

Typically this can be used to process results of eager-loading

Examples:

dsl = AttributeDSL.new([])

dsl.combine(:tags, user_id: :id) do
  model Tag

  attribute :name
end

Parameters:

  • name (Symbol)
  • options (Hash)

    @option options [Hash] :on The "join keys" @option options [Symbol] :type The type, either :array (default) or :hash


333
334
335
336
337
338
339
340
341
342
343
344
# File 'lib/rom/mapper/attribute_dsl.rb', line 333

def combine(name, options, &block)
  dsl = new(options, &block)

  attr_opts = {
    type: options.fetch(:type, :array),
    keys: options.fetch(:on),
    combine: true,
    header: dsl.header
  }

  add_attribute(name, attr_opts)
end

#embedded(name, options, &block) ⇒ Object

Define an embedded attribute

Block exposes the attribute dsl too

Examples:

dsl = AttributeDSL.new([])

dsl.embedded :tags, type: :array do
  attribute :name
end

dsl.embedded :address, type: :hash do
  model Address
  attribute :name
end

Parameters:

  • name (Symbol)

    attribute

  • options (Hash)

Options Hash (options):

  • :type (Symbol)

    Embedded type can be :hash or :array

  • :prefix (Symbol)

    Prefix that should be used for its attributes


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
# File 'lib/rom/mapper/attribute_dsl.rb', line 132

def embedded(name, options, &block)
  with_attr_options(name) do |attr_options|
    mapper = options[:mapper]

    if mapper
      embedded_options = {type: :array}.update(options)
      attributes_from_mapper(
        mapper, name, embedded_options.update(attr_options)
      )
    else
      dsl = new(options, &block)
      attr_options.update(options)
      add_attribute(
        name, {header: dsl.header, type: :array}.update(attr_options)
      )
    end
  end
end

#exclude(name) ⇒ 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.


90
91
92
# File 'lib/rom/mapper/attribute_dsl.rb', line 90

def exclude(name)
  attributes << [name, {exclude: true}]
end

#fold(*args, &block) ⇒ Object

Define an embedded hash attribute that requires "fold" transformation

Typically this is used in sql context to fold single joined field to the array of values.

Examples:

dsl = AttributeDSL.new([])

dsl.fold(tags: [:name])

See Also:


277
278
279
280
281
282
# File 'lib/rom/mapper/attribute_dsl.rb', line 277

def fold(*args, &block)
  with_name_or_options(*args) do |name, *|
    fold_options = {type: :array, fold: true}
    dsl(name, fold_options, &block)
  end
end

#group(*args, &block) ⇒ Object

Define an embedded hash attribute that requires "grouping" transformation

Typically this is used in sql context when relation is a join.

Examples:

dsl = AttributeDSL.new([])

dsl.group(tags: [:name])

dsl.group(:tags) do
  model Tag
  attribute :name
end

See Also:


232
233
234
235
236
237
238
239
240
241
242
243
244
# File 'lib/rom/mapper/attribute_dsl.rb', line 232

def group(*args, &block)
  ensure_mapper_configuration("group", args, block_given?)

  with_name_or_options(*args) do |name, options, mapper|
    group_options = {type: :array, group: true}.update(options)

    if mapper
      attributes_from_mapper(mapper, name, group_options)
    else
      dsl(name, group_options, &block)
    end
  end
end

#headerHeader

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.

Generate a header from attribute definitions

Returns:


351
352
353
# File 'lib/rom/mapper/attribute_dsl.rb', line 351

def header
  Header.coerce(attributes, copy_keys: copy_keys, model: model, reject_keys: reject_keys)
end

#model(options = nil) ⇒ Object Originally defined in module ModelDSL

Set or generate a model

Examples:

class MyDefinition
  include ROM::Mapper::ModelDSL

  def initialize
    @attributes = [[:name], [:title]]
  end
end

definition = MyDefinition.new

# just set a model constant
definition.model(User)

# generate model class for the attributes
definition.model(name: 'User')

#prefix(value = Undefined) ⇒ Object

Redefine the prefix for the following attributes

Examples:


dsl = AttributeDSL.new([])
dsl.attribute(:prefix, 'user')

44
45
46
47
48
49
50
# File 'lib/rom/mapper/attribute_dsl.rb', line 44

def prefix(value = Undefined)
  if value.equal?(Undefined)
    @prefix
  else
    @prefix = value
  end
end

#prefix_separator(value = Undefined) ⇒ Object

Redefine the prefix separator for the following attributes

Examples:


dsl = AttributeDSL.new([])
dsl.attribute(:prefix_separator, '.')

60
61
62
63
64
65
66
# File 'lib/rom/mapper/attribute_dsl.rb', line 60

def prefix_separator(value = Undefined)
  if value.equal?(Undefined)
    @prefix_separator
  else
    @prefix_separator = value
  end
end

#step(options = EMPTY_HASH, &block) ⇒ Object

Perform transformations sequentially

Examples:

dsl = AttributeDSL.new()

dsl.step do
  attribute :name
end

104
105
106
# File 'lib/rom/mapper/attribute_dsl.rb', line 104

def step(options = EMPTY_HASH, &block)
  steps << new(options, &block)
end

#unfold(name, options = EMPTY_HASH) ⇒ Object

Define an embedded hash attribute that requires "unfold" transformation

Typically this is used in non-sql context to convert array of values (like in Cassandra 'SET' or 'LIST' types) to array of tuples.

Source values are assigned to the first key, the other keys being left blank.

Examples:

dsl = AttributeDSL.new([])

dsl.unfold(tags: [:name, :type], from: :tags_list)

dsl.unfold :tags, from: :tags_list do
  attribute :name, from: :tag_name
  attribute :type, from: :tag_type
end

See Also:


304
305
306
307
308
309
310
311
312
# File 'lib/rom/mapper/attribute_dsl.rb', line 304

def unfold(name, options = EMPTY_HASH)
  with_attr_options(name, options) do |attr_options|
    old_name = attr_options.fetch(:from, name)
    dsl(old_name, type: :array, unfold: true) do
      attribute name, attr_options
      yield if block_given?
    end
  end
end

#ungroup(*args, &block) ⇒ Object

Define an embedded array attribute that requires "ungrouping" transformation

Typically this is used in non-sql context being prepared for import to sql.

Examples:

dsl = AttributeDSL.new([])
dsl.ungroup(tags: [:name])

See Also:


257
258
259
260
261
262
# File 'lib/rom/mapper/attribute_dsl.rb', line 257

def ungroup(*args, &block)
  with_name_or_options(*args) do |name, options, *|
    ungroup_options = {type: :array, ungroup: true}.update(options)
    dsl(name, ungroup_options, &block)
  end
end

#unwrap(*args, &block) ⇒ Object

Define an embedded hash attribute that requires "unwrapping" transformation

Typically this is used in no-sql context to normalize data before inserting to sql gateway.

Examples:

dsl = AttributeDSL.new([])

dsl.unwrap(address: [:street, :zipcode, :city])

dsl.unwrap(:address) do
  attribute :street
  attribute :zipcode
  attribute :city
end

See Also:


203
204
205
206
207
208
209
210
211
212
213
# File 'lib/rom/mapper/attribute_dsl.rb', line 203

def unwrap(*args, &block)
  with_name_or_options(*args) do |name, options, mapper|
    unwrap_options = {type: :hash, unwrap: true}.update(options)

    if mapper
      attributes_from_mapper(mapper, name, unwrap_options)
    else
      dsl(name, unwrap_options, &block)
    end
  end
end

#wrap(*args, &block) ⇒ Object

Define an embedded hash attribute that requires "wrapping" transformation

Typically this is used in sql context when relation is a join.

Examples:

dsl = AttributeDSL.new([])

dsl.wrap(address: [:street, :zipcode, :city])

dsl.wrap(:address) do
  model Address
  attribute :street
  attribute :zipcode
  attribute :city
end

See Also:


170
171
172
173
174
175
176
177
178
179
180
181
182
# File 'lib/rom/mapper/attribute_dsl.rb', line 170

def wrap(*args, &block)
  ensure_mapper_configuration("wrap", args, block_given?)

  with_name_or_options(*args) do |name, options, mapper|
    wrap_options = {type: :hash, wrap: true}.update(options)

    if mapper
      attributes_from_mapper(mapper, name, wrap_options)
    else
      dsl(name, wrap_options, &block)
    end
  end
end