pegasus v0.2.2

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

Functions

parse(binary, opts \\ [])

Parses the given binary as parse.

parser_from_ast(ast, opts)
parser_from_file(file, opts \\ [])
parser_from_string(string, opts \\ [])

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)