1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
//! # Minimal Parsing Language (MPL)
//!
//! [![Crate](https://img.shields.io/crates/v/mpl.svg)](https://crates.io/crates/mpl)
//! [![API](https://docs.rs/mpl/badge.svg)](https://docs.rs/mpl)
//!
//! This is minimal parser combinator of Minimal Parsing Language (MPL) like Top-Down Parsing Language (TDPL). It creates a abstract syntax tree (AST) for each input.
//!
//! ## Getting Started
//! 1. implement `Variable`
//! 2. insert each rule into `HashMap`
//! 3. `minimal_parse()`
//!
//! - Optional
//! - implement `Input`
//! - supports `[T]` and `str` by default
//! - implement `Position`
//! - supports `u*`, `i*`, and `f*` by default
//! - implement `Span`
//! - supports `StartAndLenSpan` by default
//! - implement `Terminal`
//! - supports `SliceTerminal`, `StrTerminal`, and `U8SliceTerminal` by default
//! - implement `Output`
//! - supports `()` by default
//! - implement `Rules`
//! - supports `HashMap` by default
//! - implement `Parse`
//! - supports `[T]`, `str`, and `[u8]` by default
//!
//! ### Example
//! ```rust
//! use crate::ParenthesesVariable::*;
//! use mpl::parser::Parser;
//! use mpl::rules::{RightRule, RightRuleKind::*, Rules};
//! use mpl::span::{StartAndLenSpan, Start, Len};
//! use mpl::output::Output;
//! use mpl::symbols::{StrTerminal, StrTerminal::*, Variable};
//! use mpl::trees::AST;
//! use std::collections::HashMap;
//!
//! #[derive(Clone, Debug, Hash, Eq, PartialEq)]
//! enum ParenthesesVariable {
//! Open,
//! Parentheses,
//! Close,
//! }
//!
//! impl Variable for ParenthesesVariable {}
//!
//! struct ParenthesesParser;
//!
//! impl<'i, V, P, L, R, O> Parser<'i, str, StrTerminal<'i>, V, StartAndLenSpan<P, L>, P, R, O>
//! for ParenthesesParser
//! where
//! V: Variable,
//! P: Start<str, L>,
//! L: Len<str, P>,
//! R: Rules<StrTerminal<'i>, V>,
//! O: Output<'i, str, V, StartAndLenSpan<P, L>>,
//! {
//! }
//!
//! /// ```
//! /// Open = '(' Parentheses / ()
//! /// Parentheses = Open Close / f
//! /// Close = ")" Open / f
//! /// ```
//! fn main() {
//! let parser = ParenthesesParser;
//! let mut rules = HashMap::new();
//!
//! rules.insert(
//! Open,
//! RightRule::from_right_rule_kind((T(Char('(')), V(Parentheses)), Empty),
//! );
//! rules.insert(
//! Parentheses,
//! RightRule::from_right_rule_kind((V(Open), V(Close)), Failure),
//! );
//! rules.insert(
//! Close,
//! RightRule::from_right_rule_kind((T(Str(")")), V(Open)), Failure),
//! );
//!
//! let input = "(()(()))";
//!
//! // all of the span
//! let all_of_the_span = StartAndLenSpan::<u32, u16>::from_start_len(0, input.len() as u16);
//!
//! let result: Result<
//! AST<ParenthesesVariable, StartAndLenSpan<u32, u16>, ()>,
//! AST<ParenthesesVariable, StartAndLenSpan<u32, u16>, ()>,
//! > = parser.parse(input, &rules, &Open, &all_of_the_span);
//!
//! if let Ok(ast) = result {
//! println!("{}", ast);
//! }
//! }
//! ```
//!
//! ### Test Examples
//! - [Number](tests/number.rs)
//! - [Parentheses](tests/parentheses.rs)
//! - [Wav Riff](tests/wav_riff.rs)
//!
//! ### Parsers written with MPL
//! - [WAV AST](https://github.com/kurotakazuki/wav_ast) : RIFF waveform Audio Format
//!
//! ## MPL
//! ### Definition of MPL grammar
//! A MPL grammar `G` is a tuple `G = (V, Σ, R, S)` in which:
//! - `V` is a finite set of variables.
//! - `Σ` is a finite set of original terminal symbols.
//! - `T` is an union of `Σ` or `M` (Σ ∪ M) (`M` (= {(), f}) is a finite set of metasymbols).
//! - `R` is a finite set of rules of the form
//! - `A = B C / D`
//! A in V (A ∈ V),
//! B, C, D in E (E = T ∪ V) (T ∩ V = ∅) (B, C, D ∈ E).
//! For any variable A there is exactly one rule with A to the left of `=`.
//! - S in V (S ∈ V) is the start variable.
//!
//! #### Empty
//! `()` is a metasymbol that always succeeds without consuming input.
//!
//! ```rust ignore
//! Empty = () () / ()
//! ```
//!
//! #### Failure
//! `f` is a metasymbol that always fails without consuming input.
//!
//! ```rust ignore
//! Failure = f f / f
//! ```
//!
//! ### Extended MPL
//! Since one of the goals of MPL is to create an AST, it also supports two features in terms of ease of use and speed.
//!
//! #### Any
//! `?` is a metasymbol representing any single input like wildcard character. This succeeds if there is any input left, and fails if there is no input left.
//!
//! ```rust ignore
//! Any = ? () / f
//! ```
//!
//! To extend the difinition of MPL grammar, let ? ∈ M.
//!
//! #### All
//! `*` is a metasymbol representing All remaining input like wildcard character. This will succeed even if the remaining inputs are zero.
//!
//! ```rust ignore
//! All = * () / f
//! ```
//!
//! Same as `All = ? All / ()`.
//!
//! To extend the difinition of MPL grammar, let * ∈ M.
pub mod choices;
pub mod input;
pub mod output;
pub mod parser;
pub mod position;
pub mod rules;
pub mod span;
pub mod symbols;
pub mod trees;