Pegasus (pegasus v0.2.2)

converts peg files into NimbleParsec parsers.

For documentation on this peg format: https://www.piumarta.com/software/peg/peg.1.html

To use, drop this in your model:

defmodule MyModule
  require Pegasus

  Pegasus.parser_from_string("""
  foo <- "foo" "bar"
  """)
end

See NimbleParsec for the description of the output.

MyModule.foo("foobar") # ==> {:ok, ["foo", "bar"], ...}

Capitalized Identifiers

for capitalized identifiers, you will have to use apply/3 to call the function, or you may wrap it in another combinator like so:

defmodule Capitalized do
  require Pegasus
  import NimbleParsec

  Pegasus.parser_from_string("Foo <- 'foo'")

  defparsec :parse, parsec(:Foo)
end

You may also load a parser from a file using parser_from_file/2.

parser-options

Parser Options

Parser options are passed as a keyword list after the parser defintion string (or file). The keys for the options are the names of the combinators, followed by a keyword list of supplied options, which are applied in the specified order:

start_position

:start_position

When true, drops a map %{line: <line>, column: <column>, offset: <offset>} into the arguments for this keyword at the front of its list.

collect

:collect

You may collect the contents of a combinator using the collect: true option. If this combinator calls other combinators, they must leave only iodata (no tags, no tokens) in the arguments list.

token

:token

You may substitute the contents of any combinator with a token (usually an atom). The following conditions apply:

  • token: false - no token (default)
  • token: true - token is set to the atom name of the combinator
  • token: <value> - token is set to the value of setting

tag

:tag

You may tag the contents of your combinator using the :tag option. The following conditions apply:

  • tag: false - No tag (default)
  • tag: true - Use the combinator name as the tag.
  • tag: <atom> - Use the supplied atom as the tag.

post_traverse

:post_traverse

You may supply a post_traversal for any parser. See NimbleParsec for how to implement post-traversal functions. These are defined by passing a keyword list to the parser_from_file/2 or parser_from_string/2 function.

ignore

:ignore

If true, clears the arguments from the list.

Example

Pegasus.parser_from_string("""
  foo <- "foo" "bar"
  """,
  foo: [post_traverse: {:some_function, []}]
)

defp foo(rest, ["bar", "foo"], context, {_line, _col}, _bytes) do
  {rest, [:parsed], context}
end

parser

:parser

You may sepecify to export a combinator as a parser by specifying parser: true. By default, only a combinator will be generated. See NimbleParsec.defparsec/3 to understand the difference.

Example

Pegasus.parser_from_string("""
  foo <- "foo" "bar"
  """, foo: [parser: true]
)

export

:export

You may sepecify to export a combinator as a public function by specifying export: true. By default, the combinators are private functions.

Example

Pegasus.parser_from_string("""
  foo <- "foo" "bar"
  """, foo: [export: true]
)

not-implemented-features

Not implemented features

Actions, which imply the use of C code, are not implemented. These currently fail to parse but in the future they may silently do nothing.

Link to this section Summary

Link to this section Functions

Link to this function

parse(binary, opts \\ [])

@spec parse(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 parse.

Returns {:ok, [token], rest, context, position, byte_offset} or {:error, reason, rest, context, line, byte_offset} where position describes the location of the parse (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

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
Link to this macro

parser_from_ast(ast, opts)

(macro)
Link to this macro

parser_from_file(file, opts \\ [])

(macro)
Link to this macro

parser_from_string(string, opts \\ [])

(macro)