1 // pest. The Elegant Parser 2 // Copyright (c) 2018 Dragoș Tiselice 3 // 4 // Licensed under the Apache License, Version 2.0 5 // <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0> or the MIT 6 // license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your 7 // option. All files in the project carrying such notice may not be copied, 8 // modified, or distributed except according to those terms. 9 10 //! # pest. The Elegant Parser 11 //! 12 //! pest is a general purpose parser written in Rust with a focus on accessibility, correctness, 13 //! and performance. It uses parsing expression grammars (or [PEG]) as input, which are similar in 14 //! spirit to regular expressions, but which offer the enhanced expressivity needed to parse 15 //! complex languages. 16 //! 17 //! [PEG]: https://en.wikipedia.org/wiki/Parsing_expression_grammar 18 //! 19 //! ## Getting started 20 //! 21 //! The recommended way to start parsing with pest is to read the official [book]. 22 //! 23 //! Other helpful resources: 24 //! 25 //! * API reference on [docs.rs] 26 //! * play with grammars and share them on our [fiddle] 27 //! * leave feedback, ask questions, or greet us on [Gitter] 28 //! 29 //! [book]: https://pest-parser.github.io/book 30 //! [docs.rs]: https://docs.rs/pest 31 //! [fiddle]: https://pest-parser.github.io/#editor 32 //! [Gitter]: https://gitter.im/dragostis/pest 33 //! 34 //! ## Usage 35 //! 36 //! The core of pest is the trait [`Parser`], which provides an interface to the parsing 37 //! functionality. 38 //! 39 //! The accompanying crate `pest_derive` can automatically generate a [`Parser`] from a PEG 40 //! grammar. Using `pest_derive` is highly encouraged, but it is also possible to implement 41 //! [`Parser`] manually if required. 42 //! 43 //! ## `.pest` files 44 //! 45 //! Grammar definitions reside in custom `.pest` files located in the crate `src` directory. 46 //! Parsers are automatically generated from these files using `#[derive(Parser)]` and a special 47 //! `#[grammar = "..."]` attribute on a dummy struct. 48 //! 49 //! ```ignore 50 //! #[derive(Parser)] 51 //! #[grammar = "path/to/my_grammar.pest"] // relative to src 52 //! struct MyParser; 53 //! ``` 54 //! 55 //! The syntax of `.pest` files is documented in the [`pest_derive` crate]. 56 //! 57 //! ## Inline grammars 58 //! 59 //! Grammars can also be inlined by using the `#[grammar_inline = "..."]` attribute. 60 //! 61 //! [`Parser`]: trait.Parser.html 62 //! [`pest_derive` crate]: https://docs.rs/pest_derive/ 63 64 #![doc(html_root_url = "https://docs.rs/pest")] 65 66 extern crate ucd_trie; 67 68 #[cfg(feature = "pretty-print")] 69 extern crate serde; 70 #[cfg(feature = "pretty-print")] 71 extern crate serde_json; 72 73 pub use parser::Parser; 74 pub use parser_state::{state, Atomicity, Lookahead, MatchDir, ParseResult, ParserState}; 75 pub use position::Position; 76 pub use span::{Lines, Span}; 77 use std::fmt::Debug; 78 use std::hash::Hash; 79 pub use token::Token; 80 81 pub mod error; 82 pub mod iterators; 83 mod macros; 84 mod parser; 85 mod parser_state; 86 mod position; 87 pub mod prec_climber; 88 mod span; 89 mod stack; 90 mod token; 91 #[doc(hidden)] 92 pub mod unicode; 93 94 /// A trait which parser rules must implement. 95 /// 96 /// This trait is set up so that any struct that implements all of its required traits will 97 /// automatically implement this trait as well. 98 /// 99 /// This is essentially a [trait alias](https://github.com/rust-lang/rfcs/pull/1733). When trait 100 /// aliases are implemented, this may be replaced by one. 101 pub trait RuleType: Copy + Debug + Eq + Hash + Ord {} 102 103 impl<T: Copy + Debug + Eq + Hash + Ord> RuleType for T {} 104