@spec duration_units() :: [binary()]

The duration units a scalar/0 duration may use.

Read from Predicator.Vocabulary, which is the grammar's single enumerated source (px-15q), so a unit added to the lexer reaches this subset without a second list to update by hand.

Examples

iex> "d" in Predicator.Simple.duration_units()
true

@spec from_ast(Predicator.Parser.ast()) :: {:ok, t()} | :outside

Reads a t/0 out of an AST, or answers :outside.

Total: every Predicator.Parser.ast/0 gets an answer, and an AST outside the subset gets :outside rather than an exception. Source positions are ignored, so a hand-built node carrying nil reads the same as a parsed one.

Examples

iex> {:ok, ast} = Predicator.parse("amount >= 500")
iex> Predicator.Simple.from_ast(ast)
{:ok, %Predicator.Simple{connective: nil, clauses: [{[root: "amount"], :gte, {:integer, 500}}]}}

iex> {:ok, ast} = Predicator.parse("NOT plan == 'pro'")
iex> Predicator.Simple.from_ast(ast)
:outside

@spec from_source(binary()) ::
  {:ok, t()} | :outside | {:error, Predicator.Errors.ParseError.t()}

Parses source and reads a t/0 out of it.

Adds one arm to from_ast/1's two: {:error, error} for source that does not parse, carrying a Predicator.Errors.ParseError.t/0 with the position and span of the failure (ADR-0015). The three arms answer three different questions - in the subset, a valid expression outside it, and not an expression - and a caller that collapses any two of them loses information an editor needs.

Examples

iex> Predicator.Simple.from_source("step in ['payment', 'review']")
{:ok,
 %Predicator.Simple{
   connective: nil,
   clauses: [{[root: "step"], :in, {:list, [{:string, "payment", :single}, {:string, "review", :single}]}}]
 }}

iex> Predicator.Simple.from_source("len(step) > 0")
:outside

iex> {:error, %Predicator.Errors.ParseError{}} = Predicator.Simple.from_source("step in [")
iex> :ok
:ok

@spec operators(Predicator.Vocabulary.value_kind()) :: [
  %{op: op(), lexeme: binary(), label: binary(), arity: 2}
]

The operators an editor should offer for a value of kind.

One entry per operator, in the order Predicator.Vocabulary enumerates them, carrying everything a picklist row needs: :op is the atom to put in a clause/0, :lexeme is the spelling to_source/2 renders, :label is the phrase to show, and :arity is how many operands the operator takes - always 2 here, since every operator in the subset is a comparison or a membership test.

Nothing is enumerated locally. The admissions are the :value_kinds on the vocabulary's operator entries and the atoms are its :ast_ops, so an operator this subset does not admit, or one the grammar does not admit for this kind of value, is never offered - and neither is one the lexer would reject. test/predicator/simple_test.exs holds that as an invariant over every kind.

kind is guarded against Predicator.Vocabulary.value_kinds/0, so a misspelled kind raises FunctionClauseError rather than answering with the empty list that a kind with no operators would answer with.

Examples

iex> Predicator.Simple.operators(:boolean) |> Enum.map(& &1.op)
[:equal_equal, :strict_eq, :ne, :strict_ne, :contains]

iex> Predicator.Simple.operators(:number) |> Enum.find(&(&1.op == :gte))
%{op: :gte, lexeme: ">=", label: "is at least", arity: 2}

iex> Predicator.Simple.operators(:list) |> Enum.map(& &1.lexeme)
["IN"]

@spec to_ast(t()) :: Predicator.Parser.ast()

Builds the AST for a t/0.

Every node carries nil in its trailing position slot - the value records what the expression means, not where it was written. Clauses are joined left-associatively, which is the shape Predicator.Parser.parse/2 produces for the same source.

Expects a well-formed value; see well_formed?/1.

Examples

iex> {:ok, simple} = Predicator.Simple.from_source("plan == 'pro'")
iex> Predicator.Simple.to_ast(simple)
{:comparison, :equal_equal, {:identifier, "plan", nil}, {:string_literal, "pro", :single, nil}, nil}

@spec to_source(
  t(),
  keyword()
) :: binary()

Renders a t/0 back to source, through Predicator.decompile/2.

opts are that function's formatting options - :parentheses and :spacing - so a caller that renders the rest of its expressions one way renders these the same way.

Examples

iex> {:ok, simple} = Predicator.Simple.from_source("status == 'active' AND amount >= 500")
iex> Predicator.Simple.to_source(simple)
"status == 'active' AND amount >= 500"

iex> {:ok, simple} = Predicator.Simple.from_source("plan == 'pro'")
iex> Predicator.Simple.to_source(simple, spacing: :compact)
"plan=='pro'"

@spec well_formed?(term()) :: boolean()

Answers whether a value satisfies the invariants to_ast/1 expects.

Every value from_ast/1 returns is well-formed; this function is for values a caller assembled itself - an editor building one from form state. The invariants are that :clauses is a non-empty list of structurally valid clauses, and that :connective is nil exactly when there is one clause.

Examples

iex> {:ok, simple} = Predicator.Simple.from_source("amount >= 500")
iex> Predicator.Simple.well_formed?(simple)
true

iex> Predicator.Simple.well_formed?(%Predicator.Simple{connective: :and, clauses: [{[root: "amount"], :gte, {:integer, 500}}]})
false