Ergo.Context (Ergo v0.4.6)

Ergo.Context defines the Context struct that is used to maintain parser state as the various parsers work, and various functions for creating & manipulating contexts.

Fields

  • invoke_fn

The invoke_fn defines the parsing entry point used for calling parsers.

  • status

When a parser returns it either sets status to :ok to indicate that it was successful or to a tuple {:error, :error_atom} where error_atom is an atom indiciting the specific type of error. It may optionally set the message field to a human readable message.

  • message

A human readable version of any error raised.

  • input

The binary input being parsed.

  • index

Represents the position in the input which has been read so far. Initially 0 it increments for each character processed.

  • line

Represents the current line of the input. Initially 1 it increments whenever a is read from the input.

  • col

Represents the current column of the input. Initially 1 it is incremented every time a character is read from the input and automatically resets whenever a is read.

  • ast

Represents the current data structure being built from the input.

  • debug

When set to 'true' parsers will attempt to log their behaviours as they run using the Elixir Logger at the :info level.

  • tracks

Parsers for which track: true is specified (by default this is most of the combinator parsers but not the terminal parsers) will add themselves to the Context tracks in the form of {ref, index}. If the same parser attempts to add itself a second time at the same index an error is thrown because a cycle has been detected.

Link to this section Summary

Functions

Because we build ASTs using lists they end up in reverse order. This method reverses the AST back to in-parse-order

Where an AST has been built from individual characters and needs to be converted to a string

Called to perform an arbitrary transformation on the AST value of a Context.

The ignore parser matches but returns a nil for the AST. Parsers like sequence accumulate these nil values. Call this function to remove them

new returns a newly initialised Context

Reads the next character from the input of the passed in Context.

Returns truthy value if the parser referred to by ref has already been called for the index index.

Examples

iex> context = Context.new(&Ergo.Parser.call/2, "Hello")
iex> assert %Context{status: :ok, ast: ?H, input: "ello", index: 1, line: 1, col: 2} = Context.peek(context)

iex> context = Context.new(&Ergo.Parser.call/2, "")
iex> assert %Context{status: {:error, :unexpected_eoi}, message: "Unexpected end of input", index: 0, line: 1, col: 1} = Context.peek(context)

Clears the value of the status and ast fields to ensure that the wrong status information cannot be returned from a child parser.

Updates the Context to track that the parser referred to by ref has been called for the index index.

Link to this section Functions

Link to this function

ast_in_parsed_order(ctx)

Because we build ASTs using lists they end up in reverse order. This method reverses the AST back to in-parse-order

Examples

iex> context = Ergo.Context.new(&Ergo.Parser.call/2, "", ast: [4, 3, 2, 1])
iex> assert %Context{ast: [1, 2, 3, 4]} = Context.ast_in_parsed_order(context)
Link to this function

ast_to_string(ctx)

Where an AST has been built from individual characters and needs to be converted to a string

Examples

iex> context = Ergo.Context.new(&Ergo.Parser.call/2, "", ast: [?H, ?e, ?l, ?l, ?o])
iex> assert %Context{ast: "Hello"} = Context.ast_to_string(context)
Link to this function

ast_transform(ctx, fun)

Called to perform an arbitrary transformation on the AST value of a Context.

Examples

iex> alias Ergo.Context
iex> context = Context.new(&Ergo.Parser.call/2, "", ast: "Hello World")
iex> assert %Context{ast: "Hello World"} = Context.ast_transform(context, &Function.identity/1)

iex> alias Ergo.Context
iex> context = Context.new(&Ergo.Parser.call/2, "", ast: "Hello World")
iex> assert %Context{ast: 11} = Context.ast_transform(context, &String.length/1)

iex> alias Ergo.Context
iex> context = Context.new(&Ergo.Parser.call/2, "", ast: "Hello World")
iex> assert %Context{ast: "Hello World"} = Context.ast_transform(context, nil)
Link to this function

ast_without_ignored(ctx)

The ignore parser matches but returns a nil for the AST. Parsers like sequence accumulate these nil values. Call this function to remove them

Examples

iex> context = Ergo.Context.new(&Ergo.Parser.call/2, "", ast: ["Hello", nil, "World", nil])
iex> assert %Context{ast: ["Hello", "World"]} = Context.ast_without_ignored(context)
Link to this function

new(invoke_fn, input \\ "", options \\ [])

new returns a newly initialised Context

with input set to the string passed in.

Examples:

iex> Context.new(&Ergo.Parser.call/2, "Hello World") %Context{status: :ok, input: "Hello World", line: 1, col: 1, index: 0, debug: false, tracks: %MapSet{}, invoke_fn: &Ergo.Parser.call/2}

Link to this function

next_char(context)

Reads the next character from the input of the passed in Context.

If the input is empty returns status: {:error, :unexpected_eoi}.

Otherwise returns a new Context setting ast to the character read and incrementing positional variables such as index, line, and column appropriately.

Examples

iex> context = Context.next_char(Context.new(&Ergo.Parser.call/2, "")) iex> assert %Context{status: {:error, :unexpected_eoi}, message: "Unexpected end of input"} = context

iex> context = Context.next_char(Context.new(&Ergo.Parser.call/2, "Hello World")) iex> assert %Context{status: :ok, input: "ello World", ast: ?H, index: 1, line: 1, col: 2} = context

Link to this function

parser_tracked?(context, ref)

Returns truthy value if the parser referred to by ref has already been called for the index index.

Examples

iex> alias Ergo.Context iex> parser_ref = 123 iex> context = Context.new(&Ergo.Parser.call/2, "Hello World") |> Context.track_parser(parser_ref) iex> assert Context.parser_tracked?(context, parser_ref)

Examples

iex> context = Context.new(&Ergo.Parser.call/2, "Hello")
iex> assert %Context{status: :ok, ast: ?H, input: "ello", index: 1, line: 1, col: 2} = Context.peek(context)

iex> context = Context.new(&Ergo.Parser.call/2, "")
iex> assert %Context{status: {:error, :unexpected_eoi}, message: "Unexpected end of input", index: 0, line: 1, col: 1} = Context.peek(context)
Link to this function

reset_status(ctx)

Clears the value of the status and ast fields to ensure that the wrong status information cannot be returned from a child parser.

Examples

iex> context = Context.new(&Ergo.Parser.call/2, "Hello World")
iex> context = %{context | status: {:error, :inexplicable_error}, ast: true}
iex> context = Context.reset_status(context)
iex> assert %Context{status: :ok, ast: nil} = context
Link to this function

track_parser(ctx, ref)

Updates the Context to track that the parser referred to by ref has been called for the index index.

Examples:

iex> alias Ergo.Context
iex> import Ergo.Terminals
iex> context = Context.new(&Ergo.Parser.call/2, "Hello World")
iex> parser = literal("Hello")
iex> context2 = Context.track_parser(context, parser.ref)
iex> assert MapSet.member?(context2.tracks, {parser.ref, 0})