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:

Since:

  • 1.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ UnitGroupBuilder

Initializes a new UnitGroupBuilder instance.

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.

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.

See Also:

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.

See Also:

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_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.

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"

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.

Raises:

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"

Raises:

See Also:

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"]

See Also:

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

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"]

See Also:

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