Class: Versionomy::Schema::Field

Inherits:
Object
  • Object
show all
Defined in:
lib/versionomy/schema/field.rb

Overview

Objects of this class represent fields in a schema.

Instance Method Summary collapse

Constructor Details

#initialize(name_, opts_ = {}, &block_) ⇒ Field

Create a field with the given name.

Recognized options include:

:type

Type of field. This should be :integer, :string, or :symbol. Default is :integer.

:default_value

Default value for the field if no value is explicitly set. Default is 0 for an integer field, the empty string for a string field, or the first symbol added for a symbol field.

You may provide an optional block. Within the block, you may call methods of Versionomy::Schema::FieldBuilder to further customize the field, or add child fields.

Raises Versionomy::Errors::IllegalValueError if the given default value is not legal.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/versionomy/schema/field.rb', line 69

def initialize(name_, opts_={}, &block_)
  @name = name_.to_sym
  @type = opts_[:type] || :integer
  if @type == :symbol
    @symbol_info = ::Hash.new
    @symbol_order = ::Array.new
  else
    @symbol_info = nil
    @symbol_order = nil
  end
  @default_value = opts_[:default_value]
  @bump_proc = nil
  @compare_proc = nil
  @canonicalize_proc = nil
  master_builder_ = opts_[:master_builder]
  if master_builder_
    @bump_proc = master_builder_._get_default_setting(@type, :bump)
    @compare_proc = master_builder_._get_default_setting(@type, :compare)
    @canonicalize_proc = master_builder_._get_default_setting(@type, :canonicalize)
    @default_value ||= master_builder_._get_default_setting(@type, :value)
  end
  @ranges = nil
  @default_child = nil
  @children = []
  ::Blockenspiel.invoke(block_, Schema::FieldBuilder.new(self, master_builder_)) if block_
  @default_value = canonicalize_value(@default_value)
end

Instance Method Details

#_add_symbol(symbol_, opts_ = {}) ⇒ Object

:nodoc:



102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/versionomy/schema/field.rb', line 102

def _add_symbol(symbol_, opts_={})  # :nodoc:
  if @type != :symbol
    raise Errors::TypeMismatchError
  end
  if @symbol_info.has_key?(symbol_)
    raise Errors::SymbolRedefinedError
  end
  @symbol_info[symbol_] = [@symbol_order.size, opts_[:bump]]
  @symbol_order << symbol_
  if @default_value.nil?
    @default_value = symbol_
  end
end

#_descendant_fields(set_ = nil) ⇒ Object

Return a set of all descendant fields, including this field.



364
365
366
367
368
369
 
# File 'lib/versionomy/schema/field.rb', line 364

def _descendant_fields(set_=nil)  # :nodoc:
  set_ ||= Set.new
  set_ << self
  @children.each{ |child_| child_._descendant_fields(set_) }
  set_
end

#_descendants_by_name ⇒ Object

Compute descendants as a hash of names to fields, including this field.



355
356
357
358
359
 
# File 'lib/versionomy/schema/field.rb', line 355

def _descendants_by_name  # :nodoc:
  hash_ = {@name => self}
  @children.each{ |child_| hash_.merge!(child_._descendants_by_name) }
  hash_
end

#_set_bump_proc(block_) ⇒ Object

:nodoc:



116
117
118
 
# File 'lib/versionomy/schema/field.rb', line 116

def _set_bump_proc(block_)  # :nodoc:
  @bump_proc = block_
end

#_set_canonicalize_proc(block_) ⇒ Object

:nodoc:



120
121
122
 
# File 'lib/versionomy/schema/field.rb', line 120

def _set_canonicalize_proc(block_)  # :nodoc:
  @canonicalize_proc = block_
end

#_set_compare_proc(block_) ⇒ Object

:nodoc:



124
125
126
 
# File 'lib/versionomy/schema/field.rb', line 124

def _set_compare_proc(block_)  # :nodoc:
  @compare_proc = block_
end

#_set_default_value(value_) ⇒ Object

:nodoc:



98
99
100
 
# File 'lib/versionomy/schema/field.rb', line 98

def _set_default_value(value_)  # :nodoc:
  @default_value = value_
end

#add_child(child_, ranges_ = nil) ⇒ Object

Adds the given child field for the given range.

If you provide a range of nil, adds the given child field as the default child for values that do not fall into any other explicitly specified range.

Otherwise, the ranges parameter must be an array of “range” objects. Each of these range objects must be either a single String, Symbol, or Integer to specify a single value; or a two-element array or a Range object (only inclusive ends are supported) to specify a range of values.

Raises Versionomy::Errors::RangeOverlapError if the specified range overlaps another previously specified range, or if more than one default child has been set.

Raises Versionomy::Errors::RangeSpecificationError if the range is incorrectly specified.

Raises Versionomy::Errors::CircularDescendantError if adding this child will result in a circular reference.



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/versionomy/schema/field.rb', line 275

def add_child(child_, ranges_=nil)
  if child_._descendant_fields.include?(self)
    raise Errors::CircularDescendantError
  end
  @children << child_
  if ranges_.nil?
    if @default_child
      raise Errors::RangeOverlapError("Cannot have more than one default child")
    end
    @default_child = child_
    return
  end
  ranges_ = [ranges_] unless ranges_.is_a?(Array)
  ranges_.each do |range_|
    case range_
    when ::Range
      if range_.exclude_end?
        raise Errors::RangeSpecificationError("Ranges must be inclusive")
      end
      normalized_range_ = [range_.first, range_.last]
    when ::Array
      if range_.size != 2
        raise Errors::RangeSpecificationError("Range array should have two elements")
      end
      normalized_range_ = range_.dup
    when ::String, ::Symbol, ::Integer
      normalized_range_ = [range_, range_]
    else
      raise Errors::RangeSpecificationError("Unrecognized range type #{range_.class}")
    end
    normalized_range_.map! do |elem_|
      if elem_.nil?
        elem_
      else
        case @type
        when :integer
          elem_.to_i
        when :string
          elem_.to_s
        when :symbol
          begin
            elem_.to_sym
          rescue
            raise Errors::RangeSpecificationError("Bad symbol value: #{elem_.inspect}")
          end
        end
      end
    end
    normalized_range_ << child_
    @ranges ||= Array.new
    insert_index_ = @ranges.size
    @ranges.each_with_index do |r_, i_|
      if normalized_range_[0] && r_[1]
        cmp_ = compare_values(normalized_range_[0], r_[1])
        if cmp_.nil?
          raise Errors::RangeSpecificationError
        end
        if cmp_ > 0
          next
        end
      end
      if normalized_range_[1] && r_[0]
        cmp_ = compare_values(normalized_range_[1], r_[0])
        if cmp_.nil?
          raise Errors::RangeSpecificationError
        end
        if cmp_ < 0
          insert_index_ = i_
          break
        end
      end
      raise Errors::RangeOverlapError
    end
    @ranges.insert(insert_index_, normalized_range_)
  end
end

#bump_value(value_) ⇒ Object

Given a value, bump it to the “next” value. Utilizes a bump procedure if given; otherwise uses default behavior depending on the type.



173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/versionomy/schema/field.rb', line 173

def bump_value(value_)
  if @bump_proc
    nvalue_ = @bump_proc.call(value_)
    nvalue_ || value_
  elsif @type == :integer || @type == :string
    value_.next
  else
    info_ = @symbol_info[value_]
    info_ ? info_[1] || value_ : nil
  end
end

#canonicalize_value(value_) ⇒ Object

Given a value, return a “canonical” value for this field. Utilizes a canonicalization procedure if given; otherwise uses default behavior depending on the type.

Raises Versionomy::Errors::IllegalValueError if the given value is not legal.



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/versionomy/schema/field.rb', line 211

def canonicalize_value(value_)
  orig_value_ = value_
  if @canonicalize_proc
    value_ = @canonicalize_proc.call(value_)
  else
    case @type
    when :integer
      value_ = value_.to_i rescue nil
    when :string
      value_ = value_.to_s rescue nil
    when :symbol
      value_ = value_.to_sym rescue nil
    end
  end
  if value_.nil? || (@type == :symbol && !@symbol_info.has_key?(value_))
    raise Errors::IllegalValueError, "#{@name} does not allow the value #{orig_value_.inspect}"
  end
  value_
end

#child(value_) ⇒ Object

Returns the child field associated with the given value. Returns nil if this field has no child for the given value.



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/versionomy/schema/field.rb', line 235

def child(value_)  # :nodoc:
  if @ranges
    @ranges.each do |r_|
      if !r_[0].nil?
        cmp_ = compare_values(r_[0], value_)
        next if cmp_.nil? || cmp_ > 0
      end
      if !r_[1].nil?
        cmp_ = compare_values(r_[1], value_)
        next if cmp_.nil? || cmp_ < 0
      end
      return r_[2]
    end
  end
  @default_child
end

#compare_values(val1_, val2_) ⇒ Object

Perform a standard comparison on two values. Returns an integer that may be positive, negative, or 0. Utilizes a comparison procedure if given; otherwise uses default behavior depending on the type.



191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/versionomy/schema/field.rb', line 191

def compare_values(val1_, val2_)
  if @compare_proc
    @compare_proc.call(val1_, val2_)
  elsif @type == :integer || @type == :string
    val1_ <=> val2_
  else
    info1_ = @symbol_info[val1_]
    info2_ = @symbol_info[val2_]
    info1_ && info2_ ? info1_[0] <=> info2_[0] : nil
  end
end

#default_value ⇒ Object

The default value of the field



156
157
158
 
# File 'lib/versionomy/schema/field.rb', line 156

def default_value
  @default_value
end

#inspect ⇒ Object

:nodoc:



129
130
131
 
# File 'lib/versionomy/schema/field.rb', line 129

def inspect   # :nodoc:
  "#<#{self.class}:0x#{object_id.to_s(16)} name=#{@name}>"
end

#name ⇒ Object

The name of the field.



140
141
142
 
# File 'lib/versionomy/schema/field.rb', line 140

def name
  @name
end

#possible_values ⇒ Object

Returns a list of possible values for this field, if the type is :symbol. Returns nil for any other type



164
165
166
 
# File 'lib/versionomy/schema/field.rb', line 164

def possible_values
  @symbol_order ? @symbol_order.dup : nil
end

#to_s ⇒ Object

:nodoc:



133
134
135
 
# File 'lib/versionomy/schema/field.rb', line 133

def to_s   # :nodoc:
  inspect
end

#type ⇒ Object

The type of the field. Possible values are :integer, :string, or :symbol.



149
150
151
 
# File 'lib/versionomy/schema/field.rb', line 149

def type
  @type
end