Class: UnitMeasurements::UnitGroupBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/unit_measurements/unit_group_builder.rb

Overview

The UnitMeasurements::UnitGroupBuilder class provides a flexible and configurable way to define units and create unit groups with specific systems and primitive unit.

It provides methods like primitive, system, unit, and si_unit to define units and their conversions within the unit group.

See Also:

Author:

Since:

  • 1.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ UnitGroupBuilder

Initializes a new UnitGroupBuilder instance.

Author:

Since:

  • 1.0.0



31
32
33
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 31

def initialize
  @units = []
end

Instance Attribute Details

#units ⇒ Array<Unit> (readonly)

An array to store the units defined using the builder.

Returns:

  • (Array<Unit>) —

    An array of Unit instances.

Author:

Since:

  • 1.0.0



25
26
27
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 25

def units
  @units
end

Instance Method Details

#build ⇒ UnitGroup

Constructs and returns a UnitGroup instance based on the units defined using the builder.

Returns:

  • (UnitGroup) —

    An instance of UnitGroup containing units and their conversions.

See Also:

Author:

Since:

  • 1.0.0



84
85
86
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 84

def build
  UnitGroup.new(@primitive, @units, @cache_file)
end

#build_si_units(name, value:, add_binary_prefixes:, aliases:) ⇒ Array<Unit> (private)

Builds an array of Unit instances with one instance of Unit with name name along with all SI prefixed Unit instances for it.

Parameters:

  • name (String|Symbol) —

    The name of the unit.

  • value (Numeric|String) —

    The conversion value of the unit.

  • add_binary_prefixes (TrueClass|FalseClass) —

    Whether the unit supports binary SI prefixes along with decimal SI prefixes.

  • aliases (Array<String|Symbol>, optional) —

    An array of alternative names for the unit.

Returns:

  • (Array<Unit>) —

    An array of Unit instances.

See Also:

Author:

Since:

  • 1.0.0



165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 165

def build_si_units(name, value:, add_binary_prefixes:, aliases:)
  si_units = [build_unit(name, value: value, aliases: aliases)]

  si_prefixes = add_binary_prefixes ? (Unit::SI_DECIMAL_PREFIXES + Unit::SI_BINARY_PREFIXES) : Unit::SI_DECIMAL_PREFIXES

  si_prefixes.each do |short_prefix, long_prefix, multiplier|
    si_aliases = long_prefix.product(aliases.to_a).flat_map do |prefix, unit|
      aliases.map { |alias_unit| prefix + alias_unit.to_s }
    end
    si_units << build_unit("#{short_prefix}#{name}", value: "#{multiplier} #{name}", aliases: si_aliases)
  end

  si_units
end

#build_unit(name, value:, aliases:) ⇒ Unit (private)

Builds an instance of Unit with name name, and specified conversion value, and alternate names.

Parameters:

  • name (String|Symbol) —

    The name of the unit.

  • value (Numeric|String) —

    The conversion value of the unit.

  • aliases (Array<String|Symbol>, optional) —

    An array of alternative names for the unit.

Returns:

  • (Unit) —

    An instance of Unit.

Author:

Since:

  • 1.0.0



193
194
195
196
197
198
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 193

def build_unit(name, value:, aliases:)
  unit = Unit.new(name, value: value, aliases: aliases, system: @system)
  check_for_duplicate_unit_names!(unit)

  unit
end

#cache(cache_file) ⇒ Object

Sets the name of the cache file for the unit group.

Examples:

cache "conversion_cache.json"

Parameters:

  • cache_file (String) —

    The name of the cache file.

Author:

Since:

  • 5.2.0



142
143
144
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 142

def cache(cache_file)
  @cache_file = cache_file
end

#check_for_duplicate_unit_names!(unit) ⇒ Object (private)

Checks for duplicate unit names within the list of units.

This method ensures that there are no duplicate unit names within the list of units. If a duplicate name is found, it raises a UnitAlreadyDefinedError.

This method is used internally by the UnitGroupBuilder class to build units and handle unit definitions.

Parameters:

  • unit (Unit) —

    The unit to be checked.

Raises:

Author:

Since:

  • 1.0.0



216
217
218
219
220
221
222
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 216

def check_for_duplicate_unit_names!(unit)
  names = @units.flat_map(&:names)

  if names.any? { |name| unit.names.include?(name) }
    raise UnitAlreadyDefinedError, unit.name
  end
end

#primitive(primitive) ⇒ Object

Sets the primitive unit for the unit group. It raises PrimitiveUnitAlreadySetError if the primitive unit has already been set for the unit group.

Examples:

primitive "m"

Parameters:

  • primitive (String|Symbol) —

    The name of the primitive unit.

Raises:

See Also:

Author:

Since:

  • 4.0.0



127
128
129
130
131
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 127

def primitive(primitive)
  raise PrimitiveUnitAlreadySetError if @primitive

  @primitive = primitive
end

#si_unit(name, value: 1.0, add_binary_prefixes: false, aliases: []) ⇒ Array<Unit>

Builds a set of SI units and adds them to the list of units. This method defines unit defined using name along with all the SI prefixes.

Examples:

si_unit "m", aliases: ["meter", "metre", "meters", "metres"]

Parameters:

  • name (String|Symbol) —

    The name of the unit.

  • value (Numeric|String) (defaults to: 1.0) —

    The conversion value of the unit.

  • add_binary_prefixes (TrueClass|FalseClass) (defaults to: false) —

    Whether the unit supports binary SI prefixes along with decimal SI prefixes.

  • aliases (Array<String|Symbol>, optional) (defaults to: []) —

    An array of alternative names for the unit.

Returns:

  • (Array<Unit>) —

    An array of Unit instances.

See Also:

Author:

Since:

  • 1.0.0



71
72
73
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 71

def si_unit(name, value: 1.0, add_binary_prefixes: false, aliases: [])
  @units += build_si_units(name, value: value, add_binary_prefixes: add_binary_prefixes, aliases: aliases)
end

#system(system_name, &block) ⇒ Object

Defines the unit system within the unit group and evaluates the provided block in the context of the builder.

This method is used to group multiple units within the certain unit system, viz., metric, imperial, etc.

Examples:

Defining an imperial system with inches and feet:

system :imperial do
  unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]
  unit "ft", value: "12 in", aliases: ["'", "foot", "feet"]
end

Parameters:

  • system_name (String|Symbol) —

    The name of the unit system in which the units are to be grouped.

  • block —

    A block of code to be executed in the context of the builder.

Author:

Since:

  • 4.0.0



106
107
108
109
110
111
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 106

def system(system_name, &block)
  @system = system_name
  instance_eval(&block) if block_given?
ensure
  @system = nil
end

#unit(name, value: 1.0, aliases: []) ⇒ Unit

Defines a unit and adds it to the list of units.

Examples:

unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]

Parameters:

  • name (String|Symbol) —

    The name of the unit.

  • value (Numeric|String) (defaults to: 1.0) —

    The conversion value of the unit.

  • aliases (Array<String|Symbol>, optional) (defaults to: []) —

    An array of alternative names for the unit.

Returns:

  • (Unit) —

    An instance of Unit.

See Also:

Author:

Since:

  • 1.0.0



49
50
51
 
# File 'lib/unit_measurements/unit_group_builder.rb', line 49

def unit(name, value: 1.0, aliases: [])
  @units << build_unit(name, value: value, aliases: aliases)
end