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