@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, and nothing about the vocabulary is re-derived here. The admissions are the :value_kinds on the vocabulary's operator entries, the atoms are its :ast_ops, and the choice between the two spellings of a word operator is its :canonical marker - 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 the lower-case spelling of one to_source/2 would render in upper case. 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. :number is the kind for an integer and for a float alike - there is no :float kind to ask for, by the decision recorded above.

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 value_kind(value()) :: Predicator.Vocabulary.value_kind()

The Predicator.Vocabulary.value_kind/0 that governs value.

operators/1 answers which operators belong beside a kind of value. This answers which kind a value is, so the two compose into the whole question an editor row asks - value |> value_kind() |> operators() - and no consumer has to keep its own translation from the subset's scalar tags to the vocabulary's kinds. Two consumers writing that translation separately could disagree about the same value; there is one answer here instead, and it is this package's.

The mapping is not one-to-one, and the two places it is not are decisions rather than omissions.

An integer and a float are two scalar/0 shapes and one kind, :number, for the reason recorded above: every operator worth offering beside 19.99 is one worth offering beside 500.

iex> Predicator.Simple.value_kind({:integer, 500})
:number

iex> Predicator.Simple.value_kind({:float, 19.99})
:number

A relative date is :datetime. There is no :relative_date kind and this is not a gap left for a consumer to judge: 30d ago is a point in time by the time anything compares it - Predicator.Evaluator resolves it against DateTime.utc_now/0 and pushes a DateTime.t/0 - so the operators that apply to it are the datetime operators, and a kind of its own would name the same list under a second name.

iex> Predicator.Simple.value_kind({:relative_date, [{30, "d"}], :ago})
:datetime

iex> Predicator.Simple.operators(:datetime) == Predicator.Simple.operators(:date)
true

A list is :list whatever its members are, which is what makes IN the operator offered for it.

iex> Predicator.Simple.value_kind({:list, [{:string, "payment", :single}]})
:list

@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