Trivet

A trivet is a flat, heat resistant object that serves as a barrier between a hot serving dish and a dining table to protect the table from heat damage.

Trivet is a Rust library of tools for writing recursive descent parsers. These are low level tools. Trivet is not an easy to use library for writing a parser for a complex language, and is not a good choice for languages that need unbounded lookahead... but then what is?

Why Trivet

Trivet is probably not the parsing library you want. You don't write a nice description of your language and then generate a parser from that description. No. Trivet gives you tools to peek at the stream and consume characters from it... and that's pretty much it.

Trivet has no dependencies other than the Rust standard libraries, and the entire code base is tiny. It even deals with the odd encoding on Windows.

If all that sounds good, then Welcome!

Trivet uses Semantic Versioning.

Bugs?

Have you found a bug? Submit it through the Trivet Issues tracker, and be sure to include (1) what happens, (2) what you expect to happen, (3) how to reproduce the bug, and (4) what version of Trivet you are using.

Online Documentation

For the master branch only:

• The Trivet Book
• Trivet Rust API

Local Documentation

If you have built the documentation locally, then this link will take you to it.

• Local Trivet Book
• Local Trivet Rust API

Building

You need to have Rust 2021 edition installed to compile. Compilation should be relatively simple.

$ cargo build
   Compiling trivet v2.0.0 (/home/Projects/trivet)
    Finished dev [unoptimized + debuginfo] target(s) in 0.14s

This should build the Trivet library.

You might have a look at etc/build.sh and etc\build.ps1. These are little scripts (in bash and powershell) that run the "pre-commit" pipeline.

Trivet Book

Trivet has a book describing its use. To build the book you need mdBook and mdbook-linkcheck. You can install these as follows.

$ cargo install mdbook mdbook-linkcheck
    Updating crates.io index
  Downloaded mdbook v0.4.34
  Downloaded 1 crate (1.5 MB) in 0.95s
  ...
     Summary Successfully installed mdbook-linkcheck, mdbook!

Once these are installed you can build the book with the following command.

$ mdbook build doc
2023-08-08 07:11:00 [INFO] (mdbook::book): Book building has started
2023-08-08 07:11:00 [INFO] (mdbook::book): Running the html backend
2023-08-08 07:11:00 [INFO] (mdbook::book): Running the linkcheck backend
2023-08-08 07:11:00 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer

You can also automatically rebuild the book on any changes with the following.

$ mdbook serve doc
2023-08-08 07:11:23 [INFO] (mdbook::book): Book building has started
2023-08-08 07:11:23 [INFO] (mdbook::book): Running the html backend
...
2023-08-08 07:11:23 [INFO] (warp::server): listening on http://127.0.0.1:3000

API Documentation

If you want documentation run cargo doc --no-deps.

After generation the API documentation should be available locally starting at target/doc/trivet/index.html.

Security

Please submit sensitive security issues using the "This issue is confidential..." button below the issue description field in the issue tracker.

The code should be checked, periodically, against the known Rust security advisories. This can be done with cargo audit. You can install that with cargo install cargo-audit.

Consider installing Trivy. This is a vulnerability scanner.

Contribute

See Contributing for information about contributing to this project.

If you are interested in contributing, see the Roadmap, the TechDebt, and any TODO or BUG comments in the code for some things that still need to be done. Others may be working on them, so be sure to check in with the project.

Copyright

Trivet is Copyright (c) 2023 by Stacy Prowell mailto:sprowell+trivet@gmail.com. All rights reserved. See the Copyright and License files for more information.