Search documentation of bb

# BB.Unit.Option (bb v0.17.0)

Copy Markdown View Source

Functions for specifying and validating units in option schemas.

## Summary

### Types

schema_option()
schema_options()

### Functions

unit_type(options \\ [])

Create a Spark.Options schema type for a unit.

validate(value, options \\ [])

Validate a value against a category.

## Types

# schema_option()

    @type schema_option() ::
      {:compatible, atom() | String.t()}
      | {:min, Localize.Unit.t()}
      | {:max, Localize.Unit.t()}
      | {:eq, Localize.Unit.t()}

# schema_options()

    @type schema_options() :: [schema_option()]

## Functions

# unit_type(options \\ [])

    @spec unit_type(Keyword.t()) :: {:custom, BB.Unit.Option, :validate, [Keyword.t()]}

Create a Spark.Options schema type for a unit.

## Examples

Basic usage returns a custom schema type tuple:

    iex> BB.Unit.Option.unit_type()
    {:custom, BB.Unit.Option, :validate, [[]]}

With compatible option to restrict unit category:

    iex> BB.Unit.Option.unit_type(compatible: :meter)
    {:custom, BB.Unit.Option, :validate, [[compatible: :meter]]}

With min constraint:

    iex> BB.Unit.Option.unit_type(min: Localize.Unit.new!(0, "meter"))
    {:custom, BB.Unit.Option, :validate, [[min: Localize.Unit.new!(0, "meter")]]}

With max constraint:

    iex> BB.Unit.Option.unit_type(max: Localize.Unit.new!(100, "meter"))
    {:custom, BB.Unit.Option, :validate, [[max: Localize.Unit.new!(100, "meter")]]}

Combined constraints:

    iex> BB.Unit.Option.unit_type(compatible: :meter, min: Localize.Unit.new!(0, "meter"), max: Localize.Unit.new!(100, "meter"))
    {:custom, BB.Unit.Option, :validate, [[compatible: :meter, min: Localize.Unit.new!(0, "meter"), max: Localize.Unit.new!(100, "meter")]]}

# validate(value, options \\ [])

    @spec validate(any(), Keyword.t()) ::
      {:ok, Localize.Unit.t()} | {:ok, BB.Dsl.ParamRef.t()} | {:error, String.t()}

Validate a value against a category.

## Examples

Valid unit passes through:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(5, "meter"))
    {:ok, Localize.Unit.new!(5, "meter")}

Non-unit values are rejected:

    iex> BB.Unit.Option.validate("not a unit")
    {:error, "Value `\"not a unit\"` is not a `Localize.Unit` struct"}

Compatible unit check passes for same category:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(100, "centimeter"), compatible: :meter)
    {:ok, Localize.Unit.new!(100, "centimeter")}

Incompatible units are rejected:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(90, "degree"), compatible: :meter)
    {:error, "The unit `degree` is not compatible with `meter`"}

Min constraint - value must be >= min:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(5, "meter"), min: Localize.Unit.new!(1, "meter"))
    {:ok, Localize.Unit.new!(5, "meter")}

Max constraint - value must be <= max:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(5, "meter"), max: Localize.Unit.new!(10, "meter"))
    {:ok, Localize.Unit.new!(5, "meter")}

Eq constraint - value must equal exactly:

    iex> BB.Unit.Option.validate(Localize.Unit.new!(5, "meter"), eq: Localize.Unit.new!(5, "meter"))
    {:ok, Localize.Unit.new!(5, "meter")}

ParamRef values are accepted and annotated with expected unit type:

    iex> ref = BB.Dsl.ParamRef.param([:motion, :max_speed])
    iex> {:ok, validated} = BB.Unit.Option.validate(ref, compatible: :meter)
    iex> validated.expected_unit_type
    :meter