1 //! # Custom [`Stream`] 2 //! 3 //! `winnow` is batteries included with support for 4 //! - Basic inputs like `&str`, newtypes with 5 //! - Improved debug output like [`Bytes`] 6 //! - [`Stateful`] for passing state through your parser, like tracking recursion 7 //! depth 8 //! - [`LocatingSlice`] for looking up the absolute position of a token 9 //! 10 //! But that won't always cut it for your parser. For example, you might lex `&str` into 11 //! a series of tokens and then want to parse a `TokenStream`. 12 //! 13 //! ## Implementing a custom stream 14 //! 15 //! Let's assume we have an input type we'll call `MyStream`. 16 //! `MyStream` is a sequence of `MyItem` type. 17 //! 18 //! The goal is to define parsers with this signature: `&mut MyStream -> PResult<Output>`. 19 //! ```rust 20 //! # use winnow::prelude::*; 21 //! # type MyStream<'i> = &'i str; 22 //! # type Output<'i> = &'i str; 23 //! fn parser<'s>(i: &mut MyStream<'s>) -> PResult<Output<'s>> { 24 //! "test".parse_next(i) 25 //! } 26 //! ``` 27 //! 28 //! Here are the traits you may have to implement for `MyStream`: 29 //! 30 //! | trait | usage | 31 //! |---|---| 32 //! | [`Stream`] |Core trait for driving parsing| 33 //! | [`StreamIsPartial`] | Marks the input as being the complete buffer or a partial buffer for streaming input | 34 //! | [`AsBytes`] |Casts the input type to a byte slice| 35 //! | [`AsBStr`] |Casts the input type to a slice of ASCII / UTF-8-like bytes| 36 //! | [`Compare`] |Character comparison operations| 37 //! | [`FindSlice`] |Look for a substring in self| 38 //! | [`Location`] |Calculate location within initial input| 39 //! | [`Offset`] |Calculate the offset between slices| 40 //! 41 //! And for `MyItem`: 42 //! 43 //! | trait | usage | 44 //! |---|---| 45 //! | [`AsChar`] |Transforms common types to a char for basic token parsing| 46 //! | [`ContainsToken`] |Look for the token in the given set| 47 //! 48 //! And traits for `&[MyItem]`: 49 //! 50 //! | trait | usage | 51 //! |---|---| 52 //! | [`SliceLen`] |Calculate the input length| 53 //! | [`ParseSlice`] |Used to integrate `&str`'s `parse()` method| 54 //! 55 //! ## Implementing a custom token 56 //! 57 //! If you are parsing `&[Myitem]`, leaving just the `MyItem` traits. 58 //! 59 //! For example: 60 //! ```rust 61 #![doc = include_str!("../../examples/arithmetic/parser_lexer.rs")] 62 //! ``` 63 64 #[allow(unused_imports)] // Here for intra-dock links 65 use crate::stream::*; 66