class Versionomy::Schema::Field

Objects of this class represent fields in a schema.

Public Class Methods

new(name_, opts_={}, &block_) click to toggle source

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.

# 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

Public Instance Methods

add_child(child_, ranges_=nil) click to toggle source

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.

# 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_) click to toggle source

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

# 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_) click to toggle source

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.

# 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

compare_values(val1_, val2_) click to toggle source

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.

# 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() click to toggle source

The default value of the field

# File lib/versionomy/schema/field.rb, line 156
def default_value
  @default_value
end

name() click to toggle source

The name of the field.

# File lib/versionomy/schema/field.rb, line 140
def name
  @name
end

possible_values() click to toggle source

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

# File lib/versionomy/schema/field.rb, line 164
def possible_values
  @symbol_order ? @symbol_order.dup : nil
end

type() click to toggle source

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

# File lib/versionomy/schema/field.rb, line 149
def type
  @type
end