Unity (Unity v0.6.0)

Copy Markdown View Source

An Elixir unit conversion calculator inspired by the Unix units utility.

Uses Localize.Unit as the primary engine for unit creation, conversion, arithmetic, and localized output. Adds a NimbleParsec-based expression parser and an interpreter that evaluates unit expressions interactively or from the command line.

Quick start

iex> result = Unity.eval!("3 meters to feet")
iex> result.name
"foot"

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

Expression syntax

  • 3 meters to feet — unit conversion.

  • 60 mph + 10 km/h — arithmetic on compatible units.

  • 100 kg * 9.8 m/s^2 — unit multiplication.

  • sqrt(9 m^2) — built-in functions.

  • 1|3 cup — rational numbers.

  • let x = 42 km — variable binding.

Summary

Types

env()
result()

Functions

eval(input, environment \\ %{})

Parses and evaluates a unit expression string.

eval!(input, environment \\ %{})

Parses and evaluates a unit expression string, raising on failure.

format(result, options \\ [])

Formats a result value for display.

format!(result, options \\ [])

Formats a result value for display, raising on failure.

Types

env()

@type env() :: Unity.Interpreter.env()

result()

@type result() :: Localize.Unit.t() | number() | {:decomposed, [Localize.Unit.t()]}

Functions

eval(input, environment \\ %{})

@spec eval(String.t(), env()) :: {:ok, result(), env()} | {:error, String.t()}

Parses and evaluates a unit expression string.

Arguments

  • input - the expression string to evaluate.

  • environment - a map of variable bindings. Defaults to %{}.

Returns

  • {:ok, result, environment} on success.

  • {:error, message} on failure.

Examples

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

eval!(input, environment \\ %{})

@spec eval!(String.t(), env()) :: result()

Parses and evaluates a unit expression string, raising on failure.

Arguments

  • input - the expression string to evaluate.

  • environment - a map of variable bindings. Defaults to %{}.

Returns

The evaluation result (Localize.Unit.t() or a number).

Examples

iex> result = Unity.eval!("3 meters to feet")
iex> result.name
"foot"

format(result, options \\ [])

@spec format(
  result(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}

Formats a result value for display.

Delegates to Unity.Formatter.format/2.

Arguments

Returns

  • {:ok, formatted_string} on success.

  • {:error, reason} on failure.

Examples

iex> {:ok, unit} = Localize.Unit.new(9.84252, "foot")
iex> Unity.format(unit)
{:ok, "9.84252 feet"}

format!(result, options \\ [])

@spec format!(
  result(),
  keyword()
) :: String.t()

Formats a result value for display, raising on failure.

Arguments

Returns

The formatted string.

Examples

iex> {:ok, unit} = Localize.Unit.new(9.84252, "foot")
iex> Unity.format!(unit)
"9.84252 feet"