Expand description
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&strsourceparse_from_bytes()creates a parser for a&[u8]sourceparse_from_path()creates a parser for aPathBufsourceparse_from_stdin()creates a parser for the standard input
Quick access to parsing or encoding a string and to parsing 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, and Numbers
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 |
|---|---|
legacy | Enable support for the old (deprecated) API (pre 2.0) |
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.
Modules
- Parse comments in various forms.
- Decode a byte stream into characters for subsequent processing.
- Define the parse errors that can be reported.
- Module for decoding numbers.
- Provide the legacy (pre 2.0) parsing API.
- Module for string encoding and decoding.
Structs
- Provide methods to implement a recursive descent parser.
- The parser core.
- Provide quick access to some simple utilities without having to create a parser, etc.
Enums
- Capture a location in a parse.
Constants
- 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.
- Maximum lookahead allowed.
- 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
- Create a parser from a byte slice. The source name is set to
<bytes>. - 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.
- Create a parser for the standard input. The source is set to the console and the name is the empty string to indicate this.
- Create a parser from a string. The source name is set to
<string>.