laika.parse

A block source represents the source for a block level element where each individual line might have a different x-offset to the root source.

This type of source is essential to preserve position tracking in recursive block parsing. For block level markup the first passes have to identify the type of block and remove their markup decoration. The remaining inline markup is then passed to inline parsers, but the input to those parsers is no longer a consecutive substring of the root input, making it hard to provide exact positions in error messages.

This type of source cursor solves this issue by providing a view to parsers that looks like a consecutive string of inline markup without the stripped decoration, while maintaining the x- and y-offsets of each line in relation to the root source.

Such a source will be used in multi-pass parsers, where the root parser might strip some markup decoration from each line and then pass the result down to the next recursion. In such a case each line might have a different x-offset from the root input. The use of this instance ensures that the correct position can still be tracked.

Companion for creating BlockSource instances.

The failure case of Parsed containing an error message and the remaining input.

Implementation note: The message property is of type Message, to allow for lazy message creation. The former SDK parser combinators which this API is partially inspired by contained a lot of unnecessary string concatenations for messages which were then never read. This implementation avoids this extra cost and the result is measurable (about 15% performance gain for a typical Markdown document for example).

Represents a generated source, where an AST node has been created programmatically and cannot be traced back to the corresponding input source.

A line source represents all or part of a single line from the root input source.

Such a source will be used in multi-pass parsers, particularly block-level parsers, where the root parser might strip some markup decoration from each line and then pass the result down to the next recursion. In such a case each line might have a different x-offset from the root input. The use of this instance ensures that the correct position can still be tracked.

A LineSource is usually used as part of a BlockSource and less frequently on its own.

Companion for creating LineSource instances.

Represents a lazy failure message. Implementations can use the specified SourceCursor to construct the actual message, e.g. for adding parts of the input to the message.

Message companion providing several pre-built messages and factory methods.

Represents the result of a Parser, a value of type T in case of success, a message in case of failure as well as the SourceCursor for the remaining input.

The abstract base for all parser implementations.

Contains the main parse function as well as various combinator function to create a new parser based on this one.

Companion factory for creating new parser instances.

Represents an offset into a source string. Its main purpose is error reporting, e.g. printing a visual representation of the line containing the error.

A root source represents the full input string of a parsing operation.

In a single-pass parser like those for HOCON or CSS, only RootCursor instances will be used for the entire parsing operation.

In a multi-pass parser like those for text markup, a RootCursor is only used for the first pass, whereas the subsequent passes on parts of the input are performed with the other SourceCursor implementations.

For this reason this type of cursor is only meant to be used for creating a root cursor for the input holding the whole document (e.g. the entire markup document or the full template).

For creating a cursor for a fragment of the input, either BlockSource or LineSource must be used to preserve position tracking in relation to the root input.

Represents the state and context of a parsing operation, containing the input string as well as positional information.

Companion for creating new SourceCursor instances. This type of constructor is only meant to be used for creating a root cursor for the input holding the whole document (e.g. the entire markup document or the full template).

For creating a cursor for a fragment of the input, either BlockSource or LineSource must be used to preserve position tracking in relation to the root input.

Represents any source cursor other than the root cursor and it is mandated by some APIs that solely deal with recursive parsing where the root input will never be used as the source for the parser.

The success case of Parsed containing the result and the remaining input.

Grouping of all parser builders that allows to construct most common parsers with a single import.

These include the base parsers like opt and not, the text parsers like literal and anyOf(Char*), as well as the more specialized parsers for text markup like spans and blocks.

Alternatively these groups can be brought into scope individually.

Collection of extension methods that helps keeping parser definitions concise.

It includes extension methods on string that allows to use string literals in parser definitions like "{" ~ anyNot('}') ~ "}" and extensions for parsers for particular target types, e.g. concat for a Parser[Seq[A], Seq[A]] and mapN for any parser Parser[A ~ B ~ C] (up to 5 concatenated elements).