# mipl
Minimal Imperative Parsing Library, `mipl`—a Rust crate for building simple, minimal parsers.
Find `mipl`:
- [crates.io](https://crates.io/crates/mipl) for installation instructions and additional metadata.
- [docs.rs](https://docs.rs/mipl) for documentation.
- [Codeberg](https://codeberg.org/ecsolticia/mipl).
- [Tangled (mirror)](https://tangled.org/@did:plc:h5uflu6cfdbvjsggusevvy6i/mipl).
## Overview
### Token Streams
`mipl` fundamentally works on token streams, with peeking and **conditional** advancing of tokens being the central operations. [`Parser`](https://docs.rs/mipl/latest/mipl/parser/struct.Parser.html) is the core token stream, which is also an iterator, is peekable, and offers more specialized conditional token advancing through what are called "concrete parsers".
### Concrete Parsers
Concrete parsers are structs that implement the [`ConcreteParser`](https://docs.rs/mipl/latest/mipl/parser/concrete_parser/trait.ConcreteParser.html) trait. This trait, along with [`Peeker`](https://docs.rs/mipl/latest/mipl/parser/concrete_parser/trait.Peeker.html) and [`ContainerCp`](https://docs.rs/mipl/latest/mipl/parser/concrete_parser/trait.ContainerCp.html), provides an interface for defining how to advance tokens. The given peeker returns the peeked token only if it satisfied the directly defined criteria in its implementation. `ConcreteParser` only advances if said peeking criteria is satisfied for the coming token.
### Subparsers
Along with concrete parsers, `mipl` has "subparsers". These take `Parser`s (glorified token streams) and consume the coming tokens in some pattern or with some condition. Once they hit a wall, they return the new `Parser`. Importantly, they respect the law of conservation of tokens: what is consumed into the new subparser is consumed away from the parent parser.
### Flexible Character Delimiters
That `mipl` fundamentally works on tokens requires that it have a relatively "good" way of tokenization. `mipl` does it this way: there are two types of delimiters. Those that are to be discarded, and those that are kept in the token stream in spite of taking part in delimiting. This allows one to split based on tokens and do away with them, and then have further splits according to tokens that can also be matched individually later.
## Documentation
`mipl` currently has a non-zero amount of documentation on at least every public item through comments. Importantly, while it is not yet fully comprehensive, it can provide additional context for **each accessible item** compared to what is available on this file.
Said documentation is available here: [docs.rs/mipl](https://docs.rs/mipl).
For offline viewing, the documentation pages can be built using `cargo doc`. Note that this requires an appropriate development environment.
## Development Environment
The development environment for this project is specified in the root [`flake.nix`](./flake.nix) file. Importantly, it currently features `rustc` and `cargo` versions `1.89`, and `bash`.
## Licensing
`mipl` is distributed under the [MIT License](./LICENSE).