@spec expected_type_name(atom()) :: String.t()

Formats an expected type name for error messages with proper articles.

Examples

iex> Predicator.Errors.expected_type_name(:integer)
"an integer"

iex> Predicator.Errors.expected_type_name(:boolean)
"a boolean"

iex> Predicator.Errors.expected_type_name(:custom_type)
"a custom_type"

@spec operation_display_name(atom()) :: String.t()

Formats an operation name for user-friendly error messages.

Examples

iex> Predicator.Errors.operation_display_name(:add)
"Arithmetic add"

iex> Predicator.Errors.operation_display_name(:logical_and)
"Logical AND"

iex> Predicator.Errors.operation_display_name(:unary_bang)
"Logical NOT"

@spec put_position(
  term(),
  Predicator.Types.position() | Predicator.Types.span() | nil
) :: term()

Attaches a source position or span to an error struct.

Given a Predicator.Types.position/0, sets :position. Given a Predicator.Types.span/0, sets :span to the span and :position to its start, so a caller reading only :position keeps getting a usable caret when the program was compiled with spans.

Returns the error unchanged when the location is nil or when the value has no :position field, so it is safe to call on any error value - including the bare-string errors some evaluator paths return internally.

Examples

iex> error = Predicator.Errors.EvaluationError.new("boom", "boom")
iex> Predicator.Errors.put_position(error, {1, 3}).position
{1, 3}

iex> error = Predicator.Errors.EvaluationError.new("boom", "boom")
iex> decorated = Predicator.Errors.put_position(error, {{1, 1}, {1, 9}})
iex> {decorated.position, decorated.span}
{{1, 1}, {{1, 1}, {1, 9}}}

iex> error = Predicator.Errors.EvaluationError.new("boom", "boom")
iex> Predicator.Errors.put_position(error, nil).position
nil

iex> Predicator.Errors.put_position("boom", {1, 3})
"boom"

@spec type_name_with_value(atom(), any()) :: String.t()

Formats a type name with its value for error messages.

Examples

iex> Predicator.Errors.type_name_with_value(:string, "hello")
"\"hello\" (string)"

iex> Predicator.Errors.type_name_with_value(:integer, 42)
"42 (integer)"

iex> Predicator.Errors.type_name_with_value(:undefined, :undefined)
":undefined (undefined)"