Crate shrimple_parser

Zero-dependency library with no-std support for writing parsers in a concise functional style & with rich error-reporting.

Every parser is a function that maps an Input. Parsers can match on Patterns.

The basic form of the function is

use shrimple_parser::{Input, ParsingResult};

fn parse_foo<In: Input>(input: In) -> ParsingResult<In, Foo, FooParseError> { ... }

If the parser is infallible, i.e. never returns an unrecoverable error, it’s customary to make it generic over the reason type, to make combining it easier.

fn parse_foo<In: Input, Reason>(input: In) -> ParsingResult<In, Foo, Reason> { ... }

Kinds of errors are distinguished via a user-defined Reason type, which signals what did a parser expect. A ParsingError can also have no reason, which will mean that the error is recoverable.

Some built-in parsers can have core::convert::Infallible as their error reason, which means that any error the parser may ever return is recoverable.

The distinction between recoverable & fatal errors is important for parsers that need to try multiple options.

Error reporting with precise location in the source is facilitated by constructing a FullParsingError with methods such as Parser::with_full_error, ParsingError::with_src_loc

Re-exports

pub use pattern::Pattern;

Modules

pattern

Abstractions for working with patterns.

tuple

This module contains utilities for working with generic tuples, such as:

utils

This module provides utility functions for locating pointers into text.

Macros

any

Make a parser/pattern that tries any of the provided paths.

call

Generates a closure that calls a function with a tuple’s contents as it arguments. The input can be anything as long as the last token contains all the arguments parenthesized.

from_tuple

Generates a closure that constructs a struct from a tuple. The struct fields must be exactly in the order in which they’re expected to be in the tuple.

match_out

Make a mapping parser that chooses the path based on the current output of the parser. The usage

nonzero

Create a non-zero integer from a literal.

Structs

FullLocation

Like Location, but also stores the path to the file.

FullParsingError

A final error with information about where in the source did the error occur.

Iter

Iterator returned by Parser::iter

Location

Location of the error. Useful for error reporting, and used by crate::FullParsingError

ParsingError

Error returned by a parser.

Enums

LineColumnToLocationErrorproc-macro2

The error returned when converting a proc_macro2::LineColumn to Location.

Traits

Input

This trait represents input that can be parsed by a Parser and/or matched by a Pattern

MappingParser

A trait alias for a function that maps from the input & intermediate output to the rest of the input & a different output.

Parser

A trait representing a function that takes some string-like input and returns either a tuple of (the rest of the input, the output) or a ParsingError.

Functions

parse_ascii_whitespace

Parses a sequence of ASCII whitespace. See char::is_ascii_whitespace for the definition of that.

parse_char

Parses any 1 character from the input.

parse_whitespace

Parses a sequence of Unicode whitespace. See char::is_whitespace for the definition of that.

ready

Returns a parser that always returns the provided value.

Type Aliases

ParsingResult

The result of a parser.