Search documentation of Localize

# Localize.Unit.Parser (Localize v0.39.0)

Copy Markdown View Source

Parses CLDR Unit of Measure identifier strings into structured ASTs.

Implements the unit identifier syntax defined in Unicode TR35.

## Summary

### Functions

parse(input)

Parses a CLDR unit identifier string.

parse!(input)

Parses a CLDR unit identifier string, raising on error.

unit_identifier(binary, opts \\ [])

Parses the given `binary` as unit_identifier.

## Functions

# parse(input)

    @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!(input)

    @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(binary, opts \\ [])

    @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 unit_identifier.

Returns `{:ok, [token], rest, context, position, byte_offset}` or `{:error, reason, rest, context, line, byte_offset}` where `position` describes the location of the unit_identifier (start position) as `{line, offset_to_start_of_line}`.

To column where the error occurred can be inferred from `byte_offset - offset_to_start_of_line`.

## Options

- `:byte_offset` - the byte offset for the whole binary, defaults to 0
- `:line` - the line and the byte offset into that line, defaults to `{1, byte_offset}`
- `:context` - the initial context value. It will be converted to a map