Crate trivet

Trivet is a library for building parsers. It is not a parser generator; it is a parser facilitator. It provides a collection of low-level routines with which you can build recursive descent parsers if you are careful.

This is the API documentation for Trivet. For a better guide to building parsers with this library, see the The Trivet Parsing Library.

Comments, bugs, feature requrests, and instructions on contributing to this project can be found on the web at the project repository.

The primary item of interest here is the Parser struct, which provides the parsing primitives with which you can build recursive descent parsers.

There are special methods to construct parsers around different sources.

• parse_from_string() creates a parser for a &str source
• parse_from_bytes() creates a parser for a &[u8] source
• parse_from_path() creates a parser for a PathBuf source
• parse_from_stdin() creates a parser for the standard input

Quick access to parsing or encoding common structures (times, dates, strings, numbers) is available via the Tools struct.

Library Functionality

Features of this parser library include line and column tracking, processing of both UTF-8 and UTF-16 input, including partial parsing of corrupt files (a Unicode failure does not break the entire parse).

Comments, Strings, Numbers, Keywords, Dates, and Times

Comments can be parsed automatically by the Parser, and multiple kinds of comments are directly supported. See the documentation for Parser for details.

Strings can be parsed by a configurable strings::StringParser. This supports many different string encoding standards. This approach provides a lot of flexibility, but if you have a specific string encoding in mind, a dedicated parser for that standard will likely be faster. The strings::StringEncoder provides for writing strings in different ways.

Numbers can be parsed by a configurable numbers::NumberParser. Again, this provides a lot of different encoding standards.\

Crate Features

Specific settings can be enabled or disabled using features in Cargo.toml. These features (except legacy) should be considered experimental and you should not depend on them.

Feature	Meaning
no_stall_detection	Disable stall detection for parsers
no_tracking	Disable line and column tracking
no_ucd	Do not build in the Unicode name database
uppercase_hex	Prefer uppercase hexadecimal numbers
strict	Unused at present

Features are discussed in The Rust Book.

Re-exports

pub use crate::errors::ParseResult;

Modules

decoder

Decode a byte stream into characters for subsequent processing.

errors

Define the parse errors that can be reported.

numbers

Module for decoding numbers.

parsers

Provide parsers for some file formats.

strings

Module for string encoding and decoding.

Structs

Parser

Provide methods to implement a recursive descent parser.

ParserCore

The parser core.

Tools

Provide quick access to some simple utilities without having to create a parser, etc.

Enums

Loc

Capture a location in a parse.

Constants

EOF_LIMIT

The limit on the number of times you can try to consume after reaching the end of the file. Excessive attempts to consume characters after reaching the end of file indicate a stalled parse and failure to check for the end of file condition.

MAX_LOOKAHEAD

Maximum lookahead allowed.

PEEK_LIMIT

The limit on the number of times you can peek without consuming. Excessive peeks without consuming any characters indicate bad parsing logic and a stalled parse.

Functions

parse_from_bytes

Create a parser from a byte slice. The source name is set to <bytes>.

parse_from_path

Create a parser for the given file. The source name is set to the given path. This method can fail if it is unable to open the given file, or is unable to read from it.

parse_from_stdin

Create a parser for the standard input. The source is set to the console and the name is the empty string to indicate this.

parse_from_string

Create a parser from a string. The source name is set to <string>.