View Source Dequel.Parser (Dequel v0.4.1)

Parser for the Dequel query language using NimbleParsec.

Parses query strings into AST tuples like {:==, [], [:field, "value"]}.

Atom Safety

Field names and relation names in queries are converted to atoms using String.to_existing_atom/1. This means:

Schemas must be loaded before parsing - The atoms for field names must already exist in the atom table. When using Ecto schemas, this happens automatically when the schema module is compiled/loaded.
Unknown fields will raise - If a query references a field that doesn't exist as an atom, an ArgumentError will be raised. This is intentional to catch typos early rather than silently returning no results.
No atom table exhaustion - Since we only convert to existing atoms, malicious queries cannot exhaust the atom table.

For runtime field validation with better error messages, use the semantic analyzer with a schema resolver which can provide context-aware errors.

Summary

Functions

expression(binary, opts \\ [])

Parses the given binary as expression.

factor(binary, opts \\ [])

Parses the given binary as factor.

field_match!(input)

object_block(binary, opts \\ [])

Parses the given binary as object_block.

parse!(input)

term(binary, opts \\ [])

Parses the given binary as term.

wrap_block(list)

Functions

expression(binary, opts \\ [])

@spec expression(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: pos_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as expression.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the expression (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

:byte_offset - the byte offset for the whole binary, defaults to 0
:line - the line and the byte offset into that line, defaults to {1, byte_offset}
:context - the initial context value. It will be converted to a map

factor(binary, opts \\ [])

@spec factor(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: pos_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as factor.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the factor (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

:byte_offset - the byte offset for the whole binary, defaults to 0
:line - the line and the byte offset into that line, defaults to {1, byte_offset}
:context - the initial context value. It will be converted to a map

field_match!(input)

object_block(binary, opts \\ [])

@spec object_block(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: pos_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as object_block.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the object_block (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

:byte_offset - the byte offset for the whole binary, defaults to 0
:line - the line and the byte offset into that line, defaults to {1, byte_offset}
:context - the initial context value. It will be converted to a map

parse!(input)

term(binary, opts \\ [])

@spec term(binary(), keyword()) ::
  {:ok, [term()], rest, context, line, byte_offset}
  | {:error, reason, rest, context, line, byte_offset}
when line: {pos_integer(), byte_offset},
     byte_offset: pos_integer(),
     rest: binary(),
     reason: String.t(),
     context: map()

Parses the given binary as term.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the term (start position) as {line, offset_to_start_of_line}.

To column where the error occurred can be inferred from byte_offset - offset_to_start_of_line.

Options

:byte_offset - the byte offset for the whole binary, defaults to 0
:line - the line and the byte offset into that line, defaults to {1, byte_offset}
:context - the initial context value. It will be converted to a map