class AMEE::DataAbstraction::Term

Base class for representing quantities which are inputs to, outputs of, or metadata associated with, calculations. Typically several instances of the Term class (or subclasses) will be associated with instances of the Calculation class or its subclasses (PrototypeCalculation, OngoingCalculation).

Instances of Term are represented by several primary attributes:

label::       Symbol representing the unique, machine-readable name for the
              term (<b>required</b>)

value::       In principle, any object which represent the desired value
              which the term represents

name::        String representing a human-readable name for the term

path::        String representing the AMEE platform path to the AMEE item
              value definition which is associated with <tt>self</tt>.
              This attribute is required only if the term represents an
              item value definition in the AMEE platform

Other available attribute-like methods include type, interface, note, unit, per_unit, default_unit, default_per_unit and parent.

Subclasses of the Term correspond to:

Constants

Interfaces

Valid choices for suggested interfaces for a term. Dynamic boolean methods (such as text_box?) are generated for checking which value is set.

my_term.drop_down?                #=> true
UnitFields

Symbols representing the attributes of self which are concerned with quantity units.

Each symbol also represents <b>dynamically defined method<b> name for setting and retrieving the default and current units and per units. Units are initialized as instances of <i>Quantify::Unit::Base</tt> is required.

Set a unit attribute by passing an argument. Retrieve a value by calling without an argument. Unit attributes can be defined by any form which is accepted by the Quantify::Unit#for method (either an instance of Quantify::Unit::Base (or subclass) or a symbolized or string representation of the a unit symbol, name or label). E.g.,

my_term.unit :mi
my_term.unit                   #=> <Quantify::Unit::NonSI:0xb71cac48 @label="mi" ... >

my_term.default_unit 'feet'
my_term.default_unit           #=> <Quantify::Unit::NonSI:0xb71cac48 @label="ft" ... >

my_time_unit = Unit.hour       #=> <Quantify::Unit::NonSI:0xb71cac48 @label="h" ... >
my_term.default_per_unit my_time_unit
my_term.default_per_unit       #=> <Quantify::Unit::NonSI:0xb71cac48 @label="h" ... >

Dynamically defined methods are also available for setting and retrieving alternative units for the unit and per_unit attributes. If no alternative units are explicitly defined, they are instantiated by default to represent all dimensionally equivalent units available in the system of units defined by Quantify. E.g.

my_term.unit :kg
my_term.alternative_units     #=> [ <Quantify::Unit::NonSI:0xb71cac48 @label="mi" ... >,
                                    <Quantify::Unit::SI:0xb71cac48 @label="km" ... >,
                                    <Quantify::Unit::NonSI:0xb71cac48 @label="ft" ... >,
                                    ... ]

my_term.unit 'litre'
my_term.alternative_units :bbl, :gal
my_term.alternative_units     #=> [ <Quantify::Unit::NonSI:0xb71cac48 @label="bbl" ... >,
                                    <Quantify::Unit::NonSI:0xb71cac48 @label="gal" ... > ]

Attributes

parent[RW]

Symbol representing the owning parent calculation of self. Set the owning calculation object by passing as an argument. Retrieve it by calling without an argument, e.g.,

my_calculation = <AMEE::DataAbstraction::OngoingCalculation ... >

my_term.parent my_calculation

my_term.parent            #=> <AMEE::DataAbstraction::OngoingCalculation ... >
value_before_cast[RW]

Stores pre-cast value

Public Class Methods

convert_value_to_type(value, type) click to toggle source
# File lib/amee-data-abstraction/term.rb, line 512
def self.convert_value_to_type(value, type)
  return nil if value.blank?
  type = type.downcase.to_sym if type.is_a?(String)
  
  case type
    when :string    then value.to_s
    when :text      then value.to_s
    when :integer   then value.to_i rescue 0
    when :fixnum    then value.to_i rescue 0
    when :float     then value.to_f rescue 0
    when :decimal   then value.to_s.to_d rescue 0
    when :double    then value.to_s.to_d rescue 0
    when :datetime  then DateTime.parse(value.to_s) rescue nil
    when :time      then Time.parse(value.to_s) rescue nil
    when :date      then Date.parse(value.to_s) rescue nil
    else value
  end
end
new(options={},&block) click to toggle source

Initialize a new instance of Term.

The term can be configured in place by passing a block (evaluated in the context of the new instance) which defines the term properties using the macro-style instance helper methods.

my_term = Term.new {

  label :size
  path "vehicleSize"
  hide!
  ...
}

The parent calculation object associated with self can be assigned using the :parent hash key passed as an argument.

Unless otherwise configured within the passed block, several attributes attempt to take default configurations if possible using rules of thumb:

  • value => nil

  • enabled => true

  • visible => true

  • label => underscored, symbolized version of path

  • path => stringified version of label

  • name => stringified and humanised version of label

  • unit => default_unit

  • per_unit => default_per_unit

# File lib/amee-data-abstraction/term.rb, line 131
def initialize(options={},&block)
  @parent=options[:parent]
  @value=nil
  @type=nil
  @enabled=true
  @visible=true
  instance_eval(&block) if block
  label path.to_s.underscore.to_sym unless path.blank?||label
  path label.to_s unless path
  name label.to_s.humanize unless name
  unit default_unit unless unit
  per_unit default_per_unit unless per_unit
end
validate_dimensional_equivalence?(*units) click to toggle source

Checks that the units included in units are dimensionally equivalent, that is, that they represent the same physucal quantity

# File lib/amee-data-abstraction/term.rb, line 505
def self.validate_dimensional_equivalence?(*units)
  unless [units].flatten.all? {|unit| unit.dimensions == units[0].dimensions }
    raise AMEE::DataAbstraction::Exceptions::InvalidUnits,
      "The specified term units are not of equivalent dimensions: #{units.map(&:label).join(",")}"
  end
end

Public Instance Methods

==(other_term) click to toggle source
# File lib/amee-data-abstraction/term.rb, line 361
def ==(other_term)
  !TermsList::TermProperties.inject(false) do |boolean,prop|
    boolean || self.send(prop) != other_term.send(prop)
  end
end
after?(lab) click to toggle source

Returns true if self occurs after the term with a label matching lab in the terms list of the parent calculation. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 400
def after?(lab)
  parent.terms.labels.index(lab)<parent.terms.labels.index(label)
end
before?(lab) click to toggle source

Returns true if self occurs before the term with a label matching lab in the terms list of the parent calculation. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 392
def before?(lab)
   parent.terms.labels.index(lab)>parent.terms.labels.index(label)
end
convert_unit(options={}) click to toggle source

Return a new instance of Term, based on self but with a change of units, according to the options hash provided, and the value attribute updated to reflect the new units.

To specify a new unit, pass the required unit via the :unit key. To specify a new per_unit, pass the required per unit via the :per_unit key. E.g.,

my_term.convert_unit(:unit => :kg)

my_term.convert_unit(:unit => :kg, :per_unit => :h)

my_term.convert_unit(:unit => 'kilogram')

my_term.convert_unit(:per_unit => Quantify::Unit.h)

my_term.convert_unit(:unit => <Quantify::Unit::SI ... >)

If self does not hold a numeric value or either a unit or per unit attribute, self is returned.

# File lib/amee-data-abstraction/term.rb, line 433
def convert_unit(options={})
  return self unless is_numeric? && (unit || per_unit)

  new = clone
  if has_numeric_value?
    if options[:unit] && unit
      new_unit = Unit.for(options[:unit])
      Term.validate_dimensional_equivalence?(unit,new_unit)
      new.value Quantity.new(new.value,new.unit).to(new_unit).value
    end
    if options[:per_unit] && per_unit
      new_per_unit = Unit.for(options[:per_unit])
      Term.validate_dimensional_equivalence?(per_unit,new_per_unit)
      new.value Quantity.new(new.value,(1/new.per_unit)).to(Unit.for(new_per_unit)).value
    end
  end
  new.unit options[:unit] if options[:unit]
  new.per_unit options[:per_unit] if options[:per_unit]
  return new
end
disable!() click to toggle source

Declare that the term’s UI element should be disabled

# File lib/amee-data-abstraction/term.rb, line 314
def disable!
  @disabled=true
end
disabled?() click to toggle source

Returns true if the UI element of self is disabled. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 326
def disabled?
  @disabled
end
enable!() click to toggle source

Declare that the term’s UI element should be enabled

# File lib/amee-data-abstraction/term.rb, line 319
def enable!
  @disabled=false
end
enabled?() click to toggle source

Returns true if the UI element of self is enabled. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 333
def enabled?
  !disabled?
end
has_numeric_value?() click to toggle source

Returns true if self has a numeric value. That is, can it have statistics applied? This method permits handling of term summing,

averaging, etc. Otherwise, returns <tt>false</tt>.
# File lib/amee-data-abstraction/term.rb, line 371
def has_numeric_value?
  is_numeric? && set? && Float(value) rescue false
end
hidden?() click to toggle source

Returns true if self is configured as hidden. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 347
def hidden?
  !visible?
end
hide!() click to toggle source

Declare that the term’s UI element should not be shown in generated UIs.

# File lib/amee-data-abstraction/term.rb, line 352
def hide!
  @visible=false
end
initialize_copy(source) click to toggle source
Calls superclass method
# File lib/amee-data-abstraction/term.rb, line 404
def initialize_copy(source)
  super
  UnitFields.each do |property|
    prop = send(property)
    self.send(property, prop.clone) unless prop.nil?
  end
end
inspect() click to toggle source

Returns a pretty print string representation of self

# File lib/amee-data-abstraction/term.rb, line 380
def inspect
  elements = {:label => label, :value => value, :unit => unit,
              :per_unit => per_unit, :type => type,
              :disabled => disabled?, :visible => visible?}
  attr_list = elements.map {|k,v| "#{k}: #{v.inspect}" } * ', '
  "<#{self.class.name} #{attr_list}>"
end
interface(inf=nil) click to toggle source

Symbolized attribute representing the expected interface type for self. Set a value by passing an argument. Retrieve a value by calling without an argument, e.g.,

my_term.interface :drop_down

my_term.interface                  #=> :drop_down

Must represent one of the valid choices defined in the Term::Interfaces constant

If the provided interface is not valid (as defined in Term::Interfaces)

an <i>InvalidInterface</i> exception is raised
# File lib/amee-data-abstraction/term.rb, line 173
def interface(inf=nil)
  if inf
    raise Exceptions::InvalidInterface unless Interfaces.include? inf
    @interface=inf
  end
  return @interface
end
is_numeric?() click to toggle source
# File lib/amee-data-abstraction/term.rb, line 375
def is_numeric?
  ![:string, :text, :datetime, :time, :date ].include?(type)
end
note(string=nil) click to toggle source

String representing an annotation for self. Set a value by passing an argument. Retrieve a value by calling without an argument, e.g.,

my_term.note 'Enter the mass of cement produced in the reporting period'

my_term.note                       #=> 'Enter the mass of cement ...'
# File lib/amee-data-abstraction/term.rb, line 213
def note(string=nil)
  instance_variable_set("@note",string.gsub('"',"'")) unless string.nil?
  instance_variable_get("@note")
end
set?() click to toggle source

Returns true if self has a populated value attribute. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 302
def set?
  !value_before_cast.nil?
end
show!() click to toggle source

Declare that the term’s UI element should be shown in generated UIs.

# File lib/amee-data-abstraction/term.rb, line 357
def show!
  @visible=true
end
to_q()
Alias for: to_quantity
to_quantity() click to toggle source

Return an instance of Quantify::Quantity describing the quantity represented by self.

If self does not contain a numeric value, nil is returned.

If self contains a numeric value, but no unit or per unit, just the numeric value is returned

# File lib/amee-data-abstraction/term.rb, line 462
def to_quantity
  return nil unless has_numeric_value?
  if (unit.is_a? Quantify::Unit::Base) && (per_unit.is_a? Quantify::Unit::Base)
    quantity_unit = unit/per_unit
  elsif unit.is_a? Quantify::Unit::Base
    quantity_unit = unit
  elsif per_unit.is_a? Quantify::Unit::Base
    quantity_unit = 1/per_unit
  else
    return value
  end
  Quantity.new(value,quantity_unit)
end
Also aliased as: to_q
to_s(format=:symbol) click to toggle source

Returns a string representation of term based on the term value and any units which are defined. The format of the unit representation follows that defined by format, which should represent any of the formats supported by the <i>Quantify::Unit::Base</tt> class (i.e. :name, :pluralized_name, :symbol and :label). Default behaviour uses the unit symbol atribute, i.e. if no format explcitly specified:

my_term.to_s                      #=> "12345 ton"

my_term.to_s :symbol              #=> "12345 ton"

my_term.to_s :name                #=> "12345 short ton"

my_term.to_s :pluralized_name     #=> "12345 tons"

my_term.to_s :label               #=> "12345 ton_us"
# File lib/amee-data-abstraction/term.rb, line 494
def to_s(format=:symbol)
  if has_numeric_value? && (unit || per_unit)
    self.to_quantity.to_s(format)
  else
    "#{value}"
  end
end
unset?() click to toggle source

Returns true if self does not have a populated value attribute. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 309
def unset?
  value_before_cast.nil?
end
value(*args) click to toggle source

Object representing the value which self is considered to represent (e.g. the quantity or name of something). Set a value by passing an argument. Retrieve a value by calling without an argument, e.g.,

my_term.value 12
my_term.value                      #=> 12

my_term.value 'Ford Escort'
my_term.value                      #=> 'Ford Escort'

my_term.value DateTime.civil(2010,12,31)
my_term.value                      #=> <Date: 4911123/2,0,2299161>
# File lib/amee-data-abstraction/term.rb, line 197
def value(*args)
  unless args.empty?
    @value_before_cast = args.first
    @value = @type ? self.class.convert_value_to_type(args.first, @type) : args.first
  end
  @value
end
visible?() click to toggle source

Returns true if self is configured as visible. Otherwise, returns false.

# File lib/amee-data-abstraction/term.rb, line 340
def visible?
  @visible
end