# `Localize.Unit.Parser`
[🔗](https://github.com/elixir-localize/localize/blob/v1.2.0/lib/localize/unit/parser.ex#L1)

Parses CLDR Unit of Measure identifier strings into structured ASTs.

Implements the unit identifier syntax defined in
[Unicode TR35](https://www.unicode.org/reports/tr35/tr35-general.html#unit-syntax).

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, tuple()} | {:error, Exception.t()}
```

Parses a CLDR unit identifier string.

### Arguments

* `input` is a unit identifier string such as `"meter-per-second"` or
  `"length-kilometer"`.

### Returns

* `{:ok, ast}` where `ast` is the parsed unit structure, or

* `{:error, reason}` if the input cannot be parsed.

### Examples

    iex> Localize.Unit.Parser.parse("meter")
    {:ok, {:unit, type: nil, numerator: [{:single_unit, prefix: nil, power: nil, base: "meter"}], denominator: []}}

    iex> Localize.Unit.Parser.parse("meter-per-second")
    {:ok, {:unit, type: nil, numerator: [{:single_unit, prefix: nil, power: nil, base: "meter"}], denominator: [{:single_unit, prefix: nil, power: nil, base: "second"}]}}

# `parse!`

```elixir
@spec parse!(String.t()) :: {atom(), keyword()} | no_return()
```

Parses a CLDR unit identifier string, raising on error.

Same as `parse/1` but returns the AST directly or raises
`ArgumentError`.

### Arguments

* `input` is a unit identifier string.

### Returns

* The parsed unit AST.

### Examples

    iex> Localize.Unit.Parser.parse!("meter")
    {:unit, type: nil, numerator: [{:single_unit, prefix: nil, power: nil, base: "meter"}], denominator: []}

# `unit_identifier`

```elixir
@spec unit_identifier(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: non_neg_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()
```

Parses the given `binary` as a CLDR unit identifier, returning the
raw NimbleParsec result tuple.

This is the low-level parsec entry point. Most callers should use
`parse/1`, which unwraps the result and returns tagged
`{:ok, ast}` / `{:error, exception}` tuples.

### Arguments

* `binary` is a unit identifier string such as `"meter"`.

* `opts` is a keyword list of NimbleParsec options (`:byte_offset`,
  `:line`, and `:context`).

### Returns

* `{:ok, [token], rest, context, position, byte_offset}` on success.

* `{:error, reason, rest, context, line, byte_offset}` on failure.

### Examples

    iex> Localize.Unit.Parser.unit_identifier("meter")
    {:ok, [unit: [type: nil, numerator: [single_unit: [prefix: nil, power: nil, base: "meter"]], denominator: []]], "", %{}, {1, 0}, 5}

---

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