Ergo.Parser (Ergo v0.6.0)
Ergo.Parser
contains the Parser record type. Ergo parsers are anonymous functions but we embed
them in a Parser
record that can hold arbitrary metadata. The primary use for the metadata is
the storage of debugging information.
Link to this section Summary
Functions
call/2
invokes the specified parser by calling its parsing function with the specified context having
first reset the context status.
Create a new combinator parser with the given label, parsing function, and optional metadata.
diagnose/2
invokes the specified parser by calling its parsing function with the specific context while
tracking the progress of the parser. The progress can be retrieved from the progress
key of the returned
context.
invoke/2
is the main entry point for the parsing process. It looks up the parser control function within
the Context
and uses it to run the given parser
.
The rewrite_error/2 call allows a higher-level parser to rewrite the error returned by a subordinate parser, translating it into something a user is more likely to be able to understand.
Create a new terminal parser with the given label, parsing function, and optional metadata.
track_parser
first checks if the parser has already been tracked for the current input index and, if it has,
raises a CycleError
to indicate the parser is in a loop. Otherwise it adds the parser at the current index.
Link to this section Functions
call(ctx, parser)
call/2
invokes the specified parser by calling its parsing function with the specified context having
first reset the context status.
combinator(label, parser_fn, meta \\ [])
Create a new combinator parser with the given label, parsing function, and optional metadata.
diagnose(ctx, parser)
diagnose/2
invokes the specified parser by calling its parsing function with the specific context while
tracking the progress of the parser. The progress can be retrieved from the progress
key of the returned
context.
Examples
iex> alias Ergo.{Context, Parser}
iex> import Ergo.{Combinators, Terminals}
iex> context = Context.new(&Ergo.Parser.diagnose/2, "Hello World")
iex> parser = many(wc())
iex> assert %{status: :ok} = Parser.invoke(parser, context)
invoke(parser, ctx)
invoke/2
is the main entry point for the parsing process. It looks up the parser control function within
the Context
and uses it to run the given parser
.
This indirection allows a different control function to be specified, e.g. by the diagnose entry point which can wrap the parser call, while still calling the same parsing function (i.e. we are not introducing debugging variants of the parsers that could be subject to different behaviours)
process(ctx, parser)
rewrite_error(ctx, parser)
The rewrite_error/2 call allows a higher-level parser to rewrite the error returned by a subordinate parser, translating it into something a user is more likely to be able to understand.
should_debug?(parser, context)
terminal(label, parser_fn, meta \\ [])
Create a new terminal parser with the given label, parsing function, and optional metadata.
trace_in(ctx, label, debug)
trace_out(ctx, label, debug)
track_parser(ctx, parser)
track_parser
first checks if the parser has already been tracked for the current input index and, if it has,
raises a CycleError
to indicate the parser is in a loop. Otherwise it adds the parser at the current index.
Examples
iex> alias Ergo.{Context, Parser} iex> import Ergo.{Terminals, Combinators} iex> context = Context.new(&Ergo.Parser.call/2, "Hello World") iex> parser = many(char(?H)) iex> context2 = Parser.track_parser(context, parser) iex> assert Context.parser_tracked?(context2, parser.ref)