# `Unity.GnuUnitsImporter`
[🔗](https://github.com/elixir-localize/unity/blob/v0.6.0/lib/unity/gnu_units_importer.ex#L1)

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

# `export`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*