Unity.GnuUnitsImporter (Unity v0.6.0)

Copy Markdown View Source

Imports unit definitions from a GNU units definition file into the Localize custom unit registry.

Supports simple linear conversions, fractional definitions, compound expressions, and aliases. Function definitions (nonlinear conversions), conditional blocks, and directives are skipped.

Usage

# Import from the system default location
{:ok, stats} = Unity.GnuUnitsImporter.import()

# Import from a specific file
{:ok, stats} = Unity.GnuUnitsImporter.import("/path/to/definitions.units")

# Export to a .exs file for use with Localize.Unit.load_custom_units/1
{:ok, count} = Unity.GnuUnitsImporter.export("priv/gnu_units.exs")

# Parse without registering (for inspection)
{:ok, parsed} = Unity.GnuUnitsImporter.parse("/path/to/definitions.units")

Summary

Functions

export(output_path, input_path \\ nil)

Exports resolved GNU unit definitions to an .exs file compatible with Localize.Unit.load_custom_units/1.

import(path \\ nil)

Imports GNU unit definitions and registers them via Localize.Unit.define_unit/2.

parse(path \\ nil)

Parses a GNU units definition file without registering or exporting.

Functions

export(output_path, input_path \\ nil)

@spec export(String.t(), String.t() | nil) ::
  {:ok, non_neg_integer()} | {:error, String.t()}

Exports resolved GNU unit definitions to an .exs file compatible with Localize.Unit.load_custom_units/1.

This allows generating the definitions once, inspecting or editing the output, and loading it at application startup without re-parsing the GNU file.

Arguments

  • output_path — path for the output .exs file.

  • input_path — path to the GNU definitions file. If omitted, uses the bundled file shipped with this library.

Returns

  • {:ok, count} with the number of definitions exported.

  • {:error, reason} on failure.

import(path \\ nil)

@spec import(String.t() | nil) :: {:ok, map()} | {:error, String.t()}

Imports GNU unit definitions and registers them via Localize.Unit.define_unit/2.

Arguments

  • path — path to the definitions file. If omitted, uses the bundled file shipped with this library.

Returns

  • {:ok, stats} where stats is a map with :imported, :skipped, :errors, and :constants keys. The :constants map contains dimensionless values (e.g., "dozen" => 12.0) suitable for use as let bindings in a Unity evaluation environment.

  • {:error, reason} if the file cannot be found or parsed.

parse(path \\ nil)

@spec parse(String.t() | nil) :: {:ok, map()} | {:error, String.t()}

Parses a GNU units definition file without registering or exporting.

Useful for inspecting the parsed and resolved data.

Arguments

  • path — path to the definitions file. If omitted, uses the bundled file shipped with this library.

Returns

  • {:ok, %{parsed: parsed, resolved: resolved}} with the raw data.

  • {:error, reason} on failure.