Unity

An Elixir unit conversion calculator inspired by the Unix units utility. Uses Localize as the primary engine for unit creation, conversion, arithmetic, and localized output.

Features

• Parse and evaluate unit expressions: 3 meters to feet, 60 mph to km/h.
• Arithmetic on units: 12 ft + 3 in, 100 kg * 9.8 m/s^2.
• Built-in functions: sqrt, cbrt, abs, round, ceil, floor, trig, logarithms.
• Juxtaposition multiplication: kg m / s^2 = (kg * m) / s^2, matching GNU units precedence.
• Rational numbers: 1|3 cup to mL.
• Concatenated exponents: cm3 = cm^3.
• Measurement system conversion: 100 meter to us, 100 fahrenheit to metric, to preferred, to imperial, to SI.
• Variables: let distance = 42.195 km, then reuse distance / time.
• Mixed-unit display: 3.756 hours to h;min;s → 3 hours, 45 minutes, 21.6 seconds.
• Locale-aware output: number and unit formatting via Localize.
• Interactive REPL with _ (previous result), help, list, info, conformable, and locale commands.
• CLI for single-expression evaluation, piping, and scripting.

Installation

Add unity to your list of dependencies in mix.exs:

def deps do
  [
    {:unity, "~> 0.1.0"}
  ]
end

Library usage

iex> {:ok, result, _env} = Unity.eval("3 meters to feet")
iex> result.value
9.84251968503937

iex> Unity.format!(Unity.eval!("60 mph to km/h"))
"96.56064 kilometers per hour"

iex> Unity.format!(Unity.eval!("100 celsius to fahrenheit"))
"212 degrees Fahrenheit"

iex> {:ok, result, _env} = Unity.eval("3.756 hours to h;min;s")
iex> Unity.format!(result)
"3 hours, 45 minutes, 21.6 seconds"

Variables

iex> {:ok, _, env} = Unity.eval("let distance = 42.195 km")
iex> {:ok, _, env} = Unity.eval("let time = 2 hours", env)
iex> {:ok, result, _} = Unity.eval("distance / time", env)
iex> result.name
"kilometer-per-hour"

Measurement system conversion

iex> Unity.format!(Unity.eval!("100 meter to us"))
"0.062137 miles"

iex> Unity.format!(Unity.eval!("100 fahrenheit to metric"))
"37.777778 degrees Celsius"

iex> Unity.format!(Unity.eval!("100 meter to imperial"))
"0.062137 miles"

# "preferred" uses the current locale's measurement system
iex> Localize.put_locale(:de)
iex> Unity.format!(Unity.eval!("100 fahrenheit to preferred"))
"37,777778 Grad Celsius"

Locale-aware output

iex> result = Unity.eval!("1234.5 meter to kilometer")
iex> Unity.format!(result, locale: :de)
"1,2345 Kilometer"
iex> Unity.format!(result, locale: :ja)
"1.2345 キロメートル"

Interactive REPL

$ mix run -e "Unity.Repl.start()"
Unity v0.1.0 — type "help" for commands, "quit" to exit

> 3 meters to feet
9.84252 feet

> 60 mph to km/h
96.56064 kilometers per hour

> 100 kg * 9.8 m/s^2
980 kilogram-meter-per-square-second

> 1 gallon to liters
3.785412 liters

> 12 ft + 3 in to ft
12.25 feet

> sqrt(9 m^2)
3 meters

> _ to cm
300 centimeters

> 1|3 cup to mL
78.862746 milliliters

> 3.756 hours to h;min;s
3 hours, 45 minutes, 21.6 seconds

> let distance = 42.195 km
42.195 kilometers

> let time = 2 hours
2 hours

> distance / time
21.0975 kilometers per hour

> locale de
Locale set to :de

> 1234.5 meter to kilometer
1,2345 Kilometer

CLI (escript)

Build and install the escript:

mix escript.build

Usage:

# Interactive mode
./unity

# Single conversion
./unity "3 meters to feet"

# Two-argument conversion (GNU units style)
./unity "3 meters" "feet"

# Verbose mode
./unity -v "1 gallon" "liters"

# Terse mode (for scripts)
./unity -t "100 celsius" "fahrenheit"

# Locale-aware output
./unity --locale de "1234.5 meter to kilometer"

# Read from stdin
echo "3 meters" | ./unity - feet

# Pipe-friendly
echo "3 meters to feet" | ./unity

# List unit categories
./unity --list

# List units in a category
./unity --list length

# List conformable units
./unity --conformable meter

Expression syntax

Operator precedence (highest to lowest)

Supported unit aliases

Over 150 common abbreviations are supported, including:

• Length: m, km, cm, mm, ft, in, yd, mi, nmi, ly

• Mass: g, kg, mg, lb, oz, t, st

• Time: s, ms, min, h, d, wk, yr

• Temperature: °C, °F, K, celsius, fahrenheit, kelvin

• Speed: mph, kph, mps, kn

• Volume: L, mL, gal, qt, pt, cup, tbsp, tsp, floz

• Energy: J, kJ, cal, kcal, kWh, eV, BTU

• Power: W, kW, MW, hp

• Pressure: Pa, kPa, atm, psi

• Frequency: Hz, kHz, MHz, GHz

• Force: N, kN, lbf

• And more: area, angle, digital, electric, light, radiation units

All CLDR unit names (meter, kilogram, second, etc.) and SI-prefixed forms (kilometer, milligram, gigahertz, etc.) are accepted directly.

Importing Gnu Units unit definitions

Its possible to directly import many - but not all - of the unit definitions from Gnu Units. A copy of the data is included in the library package but you can specify other locations at import time. Importing Gnu Unit definitions converts the data into Localize.Unit custom units. Only linear units can be imoprts (those of the form ax + b

See Unity.GnuUnitsImporter for more information.

A fun example from history

See https://www.ibiblio.org/harris/500milemail.html. Here's our implementation:

$ iex -S mix
iex(1)> Unity.GnuUnitsImporter.import()
iex(2)> Unity.Repl.start()
Unity v0.2.0 — type "help" for commands, "quit" to exit

> 3 millilightsecond to mile
558.847191 miles

References

• units, the inspiration for Unity.

• Numbat s a statically typed programming language for scientific computations with first class support for physical dimensions and units.

License

Apache 2.0 (See LICENSE.md)