rust ÓL#rustc 1.81.0 (eeb90cda1 2024-09-04)ÁÝ ˆ4<‹YÄÊ_óì—-759718a9bb18a123ÁÆ4–ae'£¾7`ã/µÐ–-89ef43c30f9b928eÁŒ°“ÒxèvAÙ¡¥›—Q±-1426abde5263ac46Árustc_std_workspace_coreÁXP\ŒéVB*¿D‚°i-d08e4e7d05aff086ÁÃñÇPF}®iï‚J ÚdTâ-bcbe36736b9f0af2Á¥±ç,Oï\ä¾;&ŸTZ-93dda7487230aedaÁcfg_ifÁe7‰Cö?Åubõrj×-814df84e64e9c749Á hashbrownÁÊiäVÊE´£å‘KŠ-1128f34f910afc3aÁrustc_std_workspace_allocÁÝ-–õ+/u8Îèhü–-ec2cabfc22cdef7dÁ std_detectÁuºÓMCáhåþO‘.-67d9d7b318bd750dÁrustc_demangleÁ"½ˆQ¿Œb`8;kwì-13c5a35fb3626718Á« x@ýþ8^#‚¡ù,ø%ÊÍ-7da375a7ca1e9a5eÁ peg_macrosÁÃË '+È’ÃõP…‹#-5751bd063bbc34d0Ápeg_runtimeÁhð5p*ÅyÞÎø›¼41-d3962009be6b7746ÁÝ úruntimeÁÝ úTŒv ù<´vparserÁ4Òv ÅerrorÁ-‡å ¡>ParseÁ-½Y ParseElemÁMÙaParseLiteralÁeº e ParseSliceÁUËg RuleResultÁUÃ–üívK `rust-peg` is a simple yet flexible parser generator that makes it easy toÁüN7 write robust parsers. Based on the [Parsing ExpressionÁüO:J Grammar][wikipedia-peg] formalism, it provides a Rust macro that builds aÁüŠMC recursive descent parser from a concise definition of the grammar.ÁüØFŸJ [wikipedia-peg]: https://en.wikipedia.org/wiki/Parsing_expression_grammarÁü£Mñ ## FeaturesÁ|õ…H * Parse input from `&str`, `&[u8]`, `&[T]` or custom types implementingÁü‰K traitsÁdÕ) * Customizable reporting of parse errorsÁüâ,? * Rules can accept arguments to create reusable rule templatesÁüB; * Precedence climbing for prefix/postfix/infix expressionsÁüÒ>M * Helpful `rustc` error messages for errors in the grammar definition or theÁü‘P Rust code embedded within itÁüâ"' * Rule-level tracing to debug grammarsÁü…*° ## OverviewÁ|´ÄK The `peg::parser!{}` macro encloses a `grammar NAME() for INPUT_TYPE { ...ÁüÈNG }` definition containing a set of rules which match components of yourÁü—J language.ÁlâðJ Rules are defined with `rule NAME(PARAMETERS) -> RETURN_TYPE = PEG_EXPR`.ÁüôMM The body of the rule, following the `=`, is a PEG expression, definining howÁüÂP) the input is matched to produce a value.Áü“ ,À M PEG expressions are evaluated at a particular position of the input. When anÁüÄ PM expression matches, it advances the position and optionally returns a value.Áü• P2 The expression syntax and behavior is [documentedÁüæ 5 below](#expression-reference).Áüœ"¿M The macro expands to a Rust `mod` containing a function for each rule markedÁüÃPD `pub` in the grammar. To parse an input sequence, call one of theseÁü”GJ functions. The call returns a `Result` carrying either theÁüÜMM successfully parsed value returned by the rule, or a `ParseError` containingÁüª P; the failure position and the set of tokens expected there.Áüû >º ## ExampleÁt¾ÍR Parse a comma-separated list of numbers surrounded by brackets into a `Vec`:ÁüÑU§ ```rustÁ\« peg::parser!{ÁŒ·" grammar list_parser() for str {ÁüÉ% rule number() -> u32Áäï8 = n:$(['0'..='9']+) {? n.parse().or(Err("u32")) }ÁüŒ;È pub rule list() -> VecÁüÌ#* = "[" l:(number() ** ",") "]" { l }Áüð- }Á<ž }Á,¦¬ pub fn main() {Áœ°P assert_eq!(list_parser::list("[1,1,2,3,5,8]"), Ok(vec![1, 1, 2, 3, 5, 8]));ÁüÄSù,˜ ```Á<ž¦ ## Expression ReferenceÁÜªÆ ### AtomsÁlÊØ5 * `"keyword"` - _Literal:_ match a literal string.ÁüÜ8Y * `['0'..='9']` - _Pattern:_ match a single element that matches a Rust `match`-styleÁü•\/ pattern. [(details)](#pattern-expressions)Áüò2k * `[^ '0'..='9']` - _Inverted pattern:_ match a single element that does not match a Rust `match`-styleÁü¥nü”2Y * `some_rule()` - _Rule:_ match a rule defined elsewhere in the grammar and return itsÁüÇ\? result. Arguments in the parentheses are Rust expressions.Áü¤BN * `_` or `__` or `___` - _Rule (underscore):_ As a special case, rule namesÁüçQX consisting of underscores can be defined and invoked without parentheses. These areÁü¹[< conventionally used to match whitespace between tokens.Áü•?G * `(e)` - _Parentheses:_ wrap an expression into a group to overrideÁüÕJL normal precedence. Returns the same value as the inner expression. (UseÁü O? an _Action_ block to set the return value for a sequence).ÁüðB³ ### CombiningÁŒ·É^ * `e1 e2 e3` - _Sequence:_ match expressions in sequence (`e1` followed by `e2` followed byÁüÍa' `e3`), ignoring the return values.Áü¯*M * `a:e1 e2 b:e3 c:e4 { rust }` - _Action:_ match `e1`, `e2`, `e3`, `e4` inÁüÚPK sequence, like above. If they match successfully, run the Rust code inÁü«NI the block and return its return value. The variable names before theÁüúL; colons in the sequence are bound to the results of theÁüÇ>K corresponding expressions. It is important that the Rust code embeddedÁü†NK in the grammar is deterministic and free of side effects, as it may beÁüÕN called multiple times.Áô¤K * `a:e1 b:e2 c:e3 {? rust }` - _Conditional action:_ Like above, but theÁüÃNK Rust block returns a `Result` instead of a value directly. OnÁü’ NM `Ok(v)`, it matches successfully and returns `v`. On `Err(e)`, the matchÁüá PJ of the entire expression fails and it tries alternatives or reports aÁü²!M' parse failure with the `&str` `e`.Áü€"*\ * `e1 / e2 / e3` - _Ordered choice:_ try to match `e1`. If the match succeeds, return itsÁü«"_+ result, otherwise try `e2`, and so on.Áü‹#.º# ### RepetitionÁ”¾#Z * `expression?` - _Optional:_ match zero or one repetitions of `expression`. Returns anÁüÑ#] `Option`.ÁŒ¯$\ * `expression*` - _Repeat:_ match zero or more repetitions of `expression` and return theÁüÁ$_ results as a `Vec`.ÁÜ¡%` * `expression+` - _One-or-more:_ match one or more repetitions of `expression` and return theÁü½%cû1Ü¡&_ * `expression*` - _Range repeat:_ match between `n` and `m` repetitions of `expression`Áü½&b? return the results as a `Vec`. [(details)](#repeat-ranges)Áü 'B_ * `expression ** delim` - _Delimited repeat:_ match zero or more repetitions of `expression`Áüã'b> delimited with `delim` and return the results as a `Vec`.ÁüÆ(As * `expression ** delim` - _Delimited repeat (range):_ match between `n` and `m` repetitions of `expression`Áüˆ)vZ delimited with `delim` and return the results as a `Vec`. [(details)](#repeat-ranges)Áüÿ)]l * `expression ++ delim` - _Delimited repeat (one or more):_ match one or more repetitions of `expression`ÁüÝ*o°5üÍ+A, ### SpecialÁ„“,R * `$(e)` - _Slice:_ match the expression `e`, and return the slice of the inputÁü¤,U corresponding to the match.Áüú,#M * `&e` - _Positive lookahead:_ Match only if `e` matches at this position,Áüž-P& without consuming any characters.Áüï-)J * `!e` - _Negative lookahead:_ Match only if `e` does not match at thisÁü™.M0 position, without consuming any characters.Áüç.3J * `position!()` - return a `usize` representing the current offset intoÁü›/M* the input without consuming anything.Áüé/-c * `quiet!{ e }` - match the expression `e`, but don't report literals within it as "expected" inÁü—0f error messages.Á¼þ0Z * `expected!("something")` - fail to match, and report the specified string as expectedÁü–1] at the current location.Áüô1 _ * `precedence!{ ... }` - Parse infix, prefix, or postfix expressions by precedence climbing.Áü•2b& [(details)](#precedence-climbing)Áüø2)¢3 ## Expression detailsÁÌ¦3À3 ### Pattern expressionsÁÜÄ3à30 The `[pat]` syntax expands into a [Rust `match`Áüä33` pattern](https://doc.rust-lang.org/book/ch18-03-pattern-syntax.html) against the next characterÁü˜4c (or element) of the input.Áôü4 Á$›5E When the pattern begins with `^`, the matching behavior is inverted:Áü 5H> the expression succeeds only if the pattern does *not* match.Áüé5A3 `[^' ']` matches any character other than a space.Áü«66â6F To match sets of characters, use Rust's `..=` inclusive range patternÁüæ6I\ syntax and `|` to match multiple patterns. For example `['a'..='z' | 'A'..='Z']` matches anÁü°7_. upper or lower case ASCII alphabet character.Áü81Â8Z If your input type is a slice of an enum type, a pattern could match an enum variant likeÁüÆ8] `[Token::Operator('+')]`.Áì¤9Â9H Variables captured by the pattern are accessible in a subsequent actionÁüÆ9K$ block: `[Token::Integer(i)] { i }`.Áü’:'…C$º:K The pattern expression also evaluates to the matched element, which can beÁü¿:NO captured into a variable or used as the return value of a rule: `c:['+'|'-']`.ÁüŽ;R…C$á;B Like Rust `match`, pattern expressions support guard expressions:Áüæ;E `[c if c.is_ascii_digit()]`.Áü¬< Í<] `[_]` matches any single element. As this always matches except at end-of-file, combining itÁüÑ<`H with negative lookahead as `![_]` is the idiom for matching EOF in PEG.Áü²=K…C$þ= ### Repeat rangesÁ¬ƒ>™>\ The repeat operators `*` and `**` can be followed by an optional range specification of theÁü>_~ form `` (exact), `` (min-inclusive), `<,m>` (max-inclusive) or `` (range-inclusive), where `n` and `m` are eitherÁüý>9 integers, or a Rust `usize` expression enclosed in `{}`.Áüÿ?<¼@ ### Precedence climbingÁÜÀ@Ü@X `precedence!{ rules... }` provides a convenient way to parse infix, prefix, and postfixÁüà@[ operators using the [precedenceÁü¼A#^ climbing](http://eli.thegreenplace.net/2012/08/02/parsing-expressions-by-precedence-climbing)ÁüàAa algorithm.ÁtÂBÑB ```rust,no_runÁ”ÕB' # peg::parser!{grammar doc() for str {ÁüèB*) # pub rule number() -> i64 = "..." { 0 }Áü“C,, pub rule arithmetic() -> i64 = precedence!{ÁüÀC/ x:(@) "+" y:@ { x + y }ÁìðC x:(@) "-" y:@ { x - y }ÁìŽD --ÁD¬D x:(@) "*" y:@ { x * y }ÁìµD x:(@) "/" y:@ { x / y }ÁìÓD¦TDñD$ x:@ "^" y:(@) { x.pow(y as u32) }ÁüúD'¦TD¢E n:number() { n }Á´«E "(" e:arithmetic() ")" { e }ÁüÂE"ù,åE # }}ÁDëE # fn main() {}Á”ôE<‡FF] Each `--` introduces a new precedence level that binds more tightly than previous precedenceÁü“F`X levels. The levels consist of one or more operator rules each followed by a Rust actionÁüôF[ expression.Á|ÐGàG\ The `(@)` and `@` are the operands, and the parentheses indicate associativity. An operatorÁüäG_] rule beginning and ending with `@` is an infix expression. Prefix and postfix rules have oneÁüÄH`; `@` at the beginning or end, and atoms do not include `@`.Áü¥I>äI ## Input typesÁ”èIûIH The first line of the grammar declares an input type. This is normallyÁüÿIKL `str`, but `rust-peg` handles input types through a series of traits. TheÁüËJOM library comes with implementations for `str`, `[u8]`, and `[T]`. Define theÁü›KP@ traits below to use your own types as input to `peg` grammars:ÁüìKC°La * [`Parse`] is the base trait required for all inputs. The others are only required to use theÁü´Ld corresponding expressions.Áü™M"b * [`ParseElem`] implements the `[_]` pattern operator, with a method returning the next item ofÁü¼Me the input to match.ÁÜ¢NG * [`ParseLiteral`] implements matching against a `"string"` literal.Áü¾NJ\ * [`ParseSlice`] implements the `$()` operator, returning a slice from a span of indexes.Áü‰O_éOL As a more complex example, the body of the `peg::parser!{}` macro itself isÁüíOOL parsed with `peg`, using a [definition of these traits][gh-flat-token-tree]Áü½PO* for a type that wraps Rust's `TokenTree`.ÁüQ-»Q_ [gh-flat-token-tree]: https://github.com/kevinmehall/rust-peg/blob/master/peg-macros/tokens.rsÁü¿Qb¢R ## End-of-file handlingÁÜ¦RÂRa Normally, parsers report an error if the top-level rule matches without consuming all the input.ÁüÆRdZ To allow matching a prefix of the input, add the `#[no_eof]` attribute before `pub rule`.Áü«S]Z Take care to not miss a malformed `x` at the last position if the rule ends with a `x()*`Áü‰T] repeat expression.Á´çTþT ## Rule parametersÁ´‚U™UX Rules can be parameterized with types, lifetimes, and values, just like Rust functions.ÁüU[ùUa In addition to Rust values, rules can also accept PEG expression fragments as arguments by usingÁüýUda `rule` as a parameter type. When calling such a rule, use `<>` around a PEG expression in theÁüâVdA argument list to capture the expression and pass it to the rule.ÁüÇWDŒX For example:Á„X¡X¨R”¥XÁRü¸X*" rule num_radix(radix: u32) -> u32ÁüãX%K = n:$(['0'..='9']+) {? u32::from_str_radix(n, radix).or(Err("number")) }Áü‰YNØYE rule list(x: rule) -> Vec = "[" v:(x() ** ",") ","? "]" {v}ÁüÜYH¥Z9 pub rule octal_list() -> Vec = list()Áü©Z<‘VDæZ V”ïZ<‚[Š[ ## Failure reportingÁÄŽ[§[V When a match fails, position information is automatically recorded to report a set ofÁü«[YI "expected" tokens that would have allowed the parser to advance further.Áü…\LÒ\Z Some rules should never appear in error messages, and can be suppressed with `quiet!{e}`:ÁüÖ\]¨R”´]ÁRüÇ]*1 rule whitespace() = quiet!{[' ' | '\n' | '\t']+}Áüò]4‘VD§^ V”°^<Ã^Ë^_ If you want the "expected" set to contain a more helpful string instead of character sets, youÁüÏ^b/ can use `quiet!{}` and `expected!()` together:Áü²_2å_¨R”é_ÁRüü_* rule identifier()Á¬§`J = quiet!{[ 'a'..='z' | 'A'..='Z']['a'..='z' | 'A'..='Z' | '0'..='9' ]*}Áü½`M / expected!("identifier")Áü‹a‘VD«a V”´a<ÇaÏa ## ImportsÁtÓaâa¨R”æa mod ast {Álùa pub struct Expr;Á¼‡bù,Ÿb¥b% peg::parser!{grammar doc() for str {Áü©b( use self::ast::Expr;ÁäÒb }}Á4ïb V”öb<‰c‘cX The grammar may begin with a series of `use` declarations, just like in Rust, which areÁü•c[_ included in the generated module. Unlike normal `mod {}` blocks, `use super::*` is inserted byÁüñcb? default, so you don't have to deal with this most of the time.ÁüÔdB—e ## Rustdoc commentsÁ¼›e³e_ `rustdoc` comments with `///` before a `grammar` or `pub rule` are propagated to the resultingÁü·eb module or function:Á¼šf²f¨R”¶fÁRüÉf* /// Parse an array expression.Áüôf"2 pub rule array() -> Vec = "[...]" { vec![] }Áü—g5‘VDÍg V”Ög<égñg^ As with all procedural macros, non-doc comments are ignored by the lexer and can be used likeÁüõga in any other Rust code.ÁÜ×hóh ## Caching and left recursionÁü÷h!™iL A `rule` without parameters can be prefixed with `#[cache]` if it is likelyÁüiOM to be checked repeatedly in the same position. This memoizes the rule resultÁüíiP< as a function of input position, in the style of a [packratÁü¾j? parser][wp-peg-packrat].Áäþj›k [wp-peg-packrat]: https://en.wikipedia.org/wiki/Parsing_expression_grammar#Implementing_parsers_from_parsing_expression_grammarsÁüŸk„¤lD However, idiomatic code avoids structures that parse the same inputÁü¨lGL repeatedly, so the use of `#[cache]` is often not a performance win. SimpleÁüðlOJ rules may also be faster to re-match than the additional cost of the hashÁüÀmM table lookup and insert.ÁäŽn«nM For example, a complex rule called `expr` might benefit from caching if usedÁü¯nPL like `expr() "x" / expr() "y" / expr() "z"`, but this could be rewritten toÁü€oO7 `expr() ("x" / "y" / "z")` which would be even faster.ÁüÐo:‹pQ `#[cache_left_rec]` extends the `#[cache]` mechanism with the ability to resolveÁüpT4 left-recursive rules, which are otherwise an error.Áüäp7œqO The `precedence!{}` syntax is another way to handle nested operators and avoidÁü qR( repeatedly matching an expression rule.Áüóq+Ÿr ## TracingÁt£r²rK If you pass the `peg/trace` feature to Cargo when building your project, aÁü¶rNH trace of the rules attempted and matched will be printed to stdout whenÁü…sK parsing. For example,ÁÌÑs ```shÁLës! $ cargo run --features peg/traceÁüõs$ ...Á<št% [PEG_TRACE] Matched rule type at 8:5Áü¢t(3 [PEG_TRACE] Attempting to match rule ident at 8:12ÁüËt64 [PEG_TRACE] Attempting to match rule letter at 8:12Áü‚u70 [PEG_TRACE] Failed to match rule letter at 8:12Áüºu3ƒ‰<îu<öuÝ ú ù0ÀH ÅØ_å p>ÿ†Y• a¯½eÌØgçó–¼ÿuü˜v#0”ÆvH<âv!0Rust matchpatternÁ (details)ÁÿÿHhttps://github.com/kevinmehall/rust-peg/blob/master/peg-macros/tokens.rsÁ:https://doc.rust-lang.org/book/ch18-03-pattern-syntax.htmlÁ•–8https://en.wikipedia.org/wiki/Parsing_expression_grammarÁ packratparserÁParsing ExpressionGrammarÁprecedenceclimbingÁ¯edefinition of these traitsÁþŒ–ã•aŽRhttp://eli.thegreenplace.net/2012/08/02/parsing-expressions-by-precedence-climbingÁþÌÌšš¯documentedbelowÁ¯ºêŽèŒÿYþŒã•ŽþÌgüŽüŽêŽööºèŒÆäµC>áPð7]âÌL$ÉÐ\íâ=q#ørÈE4A…äJ…Á£Éïá4XS`ÐS@Ä1¦›ŽEXŽEEáPð7]âÌÉïá4XSqÿÿMQfÿÿÿÿÿÿÿqÿÿMQfÿÿÿÿÿÿÿXC:\Users\olexa\.cargo\registry\src\index.crates.io-6f17d22bba15001f\peg-0.8.4\src\lib.rsÁ ¿DâV6ò²p{«‘²Õn*Iæ·¶)c‚h£ÎâîvÞO;NGNL -C?Q#+OKNQ-QQ6#QHNQ?V&<$.T9]3o3]CR\@KPCb+QOM?OOOOQN+`/^`dcCcBw^pBV$Q*N4N.g^!c*4dIB7J`2^L(OSF!aL`‚=\$b+-0 ( # a\`a?LPQDe#fK`PP.ce^^\eeE+&OI= ZM^+5 c3+N )\cCc+#6 b"PQ@…HPNQP;U8S,OL %)784%ÞtËeö¬¤—Ó¯ á`áFÝJx86_64-pc-windows-msvcÁ3|™¤³d)“l =7Ï˜pegÁ-7fe48a6c661aa89dÁ¦‡gM'S¨èž™È‘8Yörust-end-file