257 lines
32 KiB
HTML
257 lines
32 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="pest. The Elegant Parser"><meta name="keywords" content="rust, rustlang, rust-lang, pest"><title>pest - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" type="text/css" href="../normalize.css"><link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../dark.css" disabled><link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script defer src="../crates.js"></script><script defer src="../main.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" href="https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../pest/index.html"><div class="logo-container"><img src="https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg" alt="logo"></div></a><h2 class="location"></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../pest/index.html"><div class="logo-container">
|
||
<img src="https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">Crate pest</a></h2><div class="sidebar-elems"><div class="block"><ul><li class="version">Version 2.5.2</li><li><a id="all-types" href="all.html">All Items</a></li></ul></div><section><div class="block"><ul><li><a href="#modules">Modules</a></li><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li><li><a href="#types">Type Definitions</a></li></ul></div></section></div></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../pest/index.html">
|
||
<img src="https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg" alt="logo"></a><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><button type="button">?</button></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></div></form></nav></div><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn"><span class="in-band">Crate <a class="mod" href="#">pest</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span></h1><span class="out-of-band"><a class="srclink" href="../src/pest/lib.rs.html#9-375">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="pest-the-elegant-parser"><a href="#pest-the-elegant-parser">pest. The Elegant Parser</a></h2>
|
||
<p>pest is a general purpose parser written in Rust with a focus on accessibility, correctness,
|
||
and performance. It uses parsing expression grammars (or <a href="https://en.wikipedia.org/wiki/Parsing_expression_grammar">PEG</a>) as input, which are similar in
|
||
spirit to regular expressions, but which offer the enhanced expressivity needed to parse
|
||
complex languages.</p>
|
||
<h3 id="getting-started"><a href="#getting-started">Getting started</a></h3>
|
||
<p>The recommended way to start parsing with pest is to read the official <a href="https://pest.rs/book">book</a>.</p>
|
||
<p>Other helpful resources:</p>
|
||
<ul>
|
||
<li>API reference on <a href="https://docs.rs/pest">docs.rs</a></li>
|
||
<li>play with grammars and share them on our <a href="https://pest.rs/#editor">fiddle</a></li>
|
||
<li>find previous common questions answered or ask questions on <a href="https://github.com/pest-parser/pest/discussions">GitHub Discussions</a></li>
|
||
<li>leave feedback, ask questions, or greet us on <a href="https://gitter.im/pest-parser/pest">Gitter</a> or <a href="https://discord.gg/XEGACtWpT2">Discord</a></li>
|
||
</ul>
|
||
<h3 id="usage"><a href="#usage">Usage</a></h3>
|
||
<p>The core of pest is the trait <a href="trait.Parser.html"><code>Parser</code></a>, which provides an interface to the parsing
|
||
functionality.</p>
|
||
<p>The accompanying crate <code>pest_derive</code> can automatically generate a <a href="trait.Parser.html"><code>Parser</code></a> from a PEG
|
||
grammar. Using <code>pest_derive</code> is highly encouraged, but it is also possible to implement
|
||
<a href="trait.Parser.html"><code>Parser</code></a> manually if required.</p>
|
||
<h3 id="pest-files"><a href="#pest-files"><code>.pest</code> files</a></h3>
|
||
<p>Grammar definitions reside in custom <code>.pest</code> files located in the crate <code>src</code> directory.
|
||
Parsers are automatically generated from these files using <code>#[derive(Parser)]</code> and a special
|
||
<code>#[grammar = "..."]</code> attribute on a dummy struct.</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Parser</span>)]</span>
|
||
<span class="attribute">#[<span class="ident">grammar</span> <span class="op">=</span> <span class="string">"path/to/my_grammar.pest"</span>]</span> <span class="comment">// relative to src</span>
|
||
<span class="kw">struct</span> <span class="ident">MyParser</span>;</code></pre></div>
|
||
<p>The syntax of <code>.pest</code> files is documented in the <a href="https://docs.rs/pest_derive/"><code>pest_derive</code> crate</a>.</p>
|
||
<h3 id="inline-grammars"><a href="#inline-grammars">Inline grammars</a></h3>
|
||
<p>Grammars can also be inlined by using the <code>#[grammar_inline = "..."]</code> attribute.</p>
|
||
<h3 id="grammar"><a href="#grammar">Grammar</a></h3>
|
||
<p>A grammar is a series of rules separated by whitespace, possibly containing comments.</p>
|
||
<h4 id="comments"><a href="#comments">Comments</a></h4>
|
||
<p>Comments start with <code>//</code> and end at the end of the line.</p>
|
||
<div class="example-wrap"><pre class="language-text"><code>// a comment</code></pre></div><h4 id="rules"><a href="#rules">Rules</a></h4>
|
||
<p>Rules have the following form:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">name</span> <span class="op">=</span> <span class="ident">optional_modifier</span> { <span class="ident">expression</span> }</code></pre></div>
|
||
<p>The name of the rule is formed from alphanumeric characters or <code>_</code> with the condition that the
|
||
first character is not a digit and is used to create token pairs. When the rule starts being
|
||
parsed, the starting part of the token is being produced, with the ending part being produced
|
||
when the rule finishes parsing.</p>
|
||
<p>The following token pair notation <code>a(b(), c())</code> denotes the tokens: start <code>a</code>, start <code>b</code>, end
|
||
<code>b</code>, start <code>c</code>, end <code>c</code>, end <code>a</code>.</p>
|
||
<h5 id="modifiers"><a href="#modifiers">Modifiers</a></h5>
|
||
<p>Modifiers are optional and can be one of <code>_</code>, <code>@</code>, <code>$</code>, or <code>!</code>. These modifiers change the
|
||
behavior of the rules.</p>
|
||
<ol>
|
||
<li>
|
||
<p>Silent (<code>_</code>)</p>
|
||
<p>Silent rules do not create token pairs during parsing, nor are they error-reported.</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> <span class="kw">_</span>{ <span class="string">"a"</span> }
|
||
<span class="ident">b</span> <span class="op">=</span> { <span class="ident">a</span> ~ <span class="string">"b"</span> }</code></pre></div>
|
||
<p>Parsing <code>"ab"</code> produces the token pair <code>b()</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Atomic (<code>@</code>)</p>
|
||
<p>Atomic rules do not accept whitespace or comments within their expressions and have a
|
||
cascading effect on any rule they call. I.e. rules that are not atomic but are called by atomic
|
||
rules behave atomically.</p>
|
||
<p>Any rules called by atomic rules do not generate token pairs.</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="string">"a"</span> }
|
||
<span class="ident">b</span> <span class="op">=</span> @{ <span class="ident">a</span> ~ <span class="string">"b"</span> }
|
||
|
||
<span class="ident">WHITESPACE</span> <span class="op">=</span> <span class="kw">_</span>{ <span class="string">" "</span> }</code></pre></div>
|
||
<p>Parsing <code>"ab"</code> produces the token pair <code>b()</code>, while <code>"a b"</code> produces an error.</p>
|
||
</li>
|
||
<li>
|
||
<p>Compound-atomic (<code>$</code>)</p>
|
||
<p>Compound-atomic are identical to atomic rules with the exception that rules called by them are
|
||
not forbidden from generating token pairs.</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="string">"a"</span> }
|
||
<span class="ident">b</span> <span class="op">=</span> ${ <span class="ident">a</span> ~ <span class="string">"b"</span> }
|
||
|
||
<span class="ident">WHITESPACE</span> <span class="op">=</span> <span class="kw">_</span>{ <span class="string">" "</span> }</code></pre></div>
|
||
<p>Parsing <code>"ab"</code> produces the token pairs <code>b(a())</code>, while <code>"a b"</code> produces an error.</p>
|
||
</li>
|
||
<li>
|
||
<p>Non-atomic (<code>!</code>)</p>
|
||
<p>Non-atomic are identical to normal rules with the exception that they stop the cascading effect
|
||
of atomic and compound-atomic rules.</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="string">"a"</span> }
|
||
<span class="ident">b</span> <span class="op">=</span> <span class="op">!</span>{ <span class="ident">a</span> ~ <span class="string">"b"</span> }
|
||
<span class="ident">c</span> <span class="op">=</span> @{ <span class="ident">b</span> }
|
||
|
||
<span class="ident">WHITESPACE</span> <span class="op">=</span> <span class="kw">_</span>{ <span class="string">" "</span> }</code></pre></div>
|
||
<p>Parsing both <code>"ab"</code> and <code>"a b"</code> produce the token pairs <code>c(a())</code>.</p>
|
||
</li>
|
||
</ol>
|
||
<h5 id="expressions"><a href="#expressions">Expressions</a></h5>
|
||
<p>Expressions can be either terminals or non-terminals.</p>
|
||
<ol>
|
||
<li>Terminals</li>
|
||
</ol>
|
||
<div><table><thead><tr><th>Terminal</th><th>Usage</th></tr></thead><tbody>
|
||
<tr><td><code>"a"</code></td><td>matches the exact string <code>"a"</code></td></tr>
|
||
<tr><td><code>^"a"</code></td><td>matches the exact string <code>"a"</code> case insensitively (ASCII only)</td></tr>
|
||
<tr><td><code>'a'..'z'</code></td><td>matches one character between <code>'a'</code> and <code>'z'</code></td></tr>
|
||
<tr><td><code>a</code></td><td>matches rule <code>a</code></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<p>Strings and characters follow
|
||
<a href="https://doc.rust-lang.org/reference/tokens.html#byte-escapes">Rust’s escape mechanisms</a>, while
|
||
identifiers can contain alphanumeric characters and underscores (<code>_</code>), as long as they do not
|
||
start with a digit.</p>
|
||
<ol start="2">
|
||
<li>Non-terminals</li>
|
||
</ol>
|
||
<div><table><thead><tr><th>Non-terminal</th><th>Usage</th></tr></thead><tbody>
|
||
<tr><td><code>(e)</code></td><td>matches <code>e</code></td></tr>
|
||
<tr><td><code>e1 ~ e2</code></td><td>matches the sequence <code>e1</code> <code>e2</code></td></tr>
|
||
<tr><td><code>e1 | e2</code></td><td>matches either <code>e1</code> or <code>e2</code></td></tr>
|
||
<tr><td><code>e*</code></td><td>matches <code>e</code> zero or more times</td></tr>
|
||
<tr><td><code>e+</code></td><td>matches <code>e</code> one or more times</td></tr>
|
||
<tr><td><code>e{n}</code></td><td>matches <code>e</code> exactly <code>n</code> times</td></tr>
|
||
<tr><td><code>e{, n}</code></td><td>matches <code>e</code> at most <code>n</code> times</td></tr>
|
||
<tr><td><code>e{n,}</code></td><td>matches <code>e</code> at least <code>n</code> times</td></tr>
|
||
<tr><td><code>e{m, n}</code></td><td>matches <code>e</code> between <code>m</code> and <code>n</code> times inclusively</td></tr>
|
||
<tr><td><code>e?</code></td><td>optionally matches <code>e</code></td></tr>
|
||
<tr><td><code>&e</code></td><td>matches <code>e</code> without making progress</td></tr>
|
||
<tr><td><code>!e</code></td><td>matches if <code>e</code> doesn’t match without making progress</td></tr>
|
||
<tr><td><code>PUSH(e)</code></td><td>matches <code>e</code> and pushes it’s captured string down the stack</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<p>where <code>e</code>, <code>e1</code>, and <code>e2</code> are expressions.</p>
|
||
<p>Matching is greedy, without backtracking. Note the difference in behavior for
|
||
these two rules in matching identifiers that don’t end in an underscore:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="comment">// input: ab_bb_b</span>
|
||
|
||
<span class="ident">identifier</span> <span class="op">=</span> @{ <span class="string">"a"</span> ~ (<span class="string">"b"</span><span class="op">|</span><span class="string">"_"</span>)<span class="op">*</span> ~ <span class="string">"b"</span> }
|
||
<span class="comment">// matches: a b_bb_b nothing -> error! </span>
|
||
|
||
<span class="ident">identifier</span> <span class="op">=</span> @{ <span class="string">"a"</span> ~ (<span class="string">"_"</span><span class="op">*</span> ~ <span class="string">"b"</span>)<span class="op">*</span> }
|
||
<span class="comment">// matches: a b, _bb, _b in three repetitions</span></code></pre></div>
|
||
<p>Expressions can modify the stack only if they match the input. For example,
|
||
if <code>e1</code> in the compound expression <code>e1 | e2</code> does not match the input, then
|
||
it does not modify the stack, so <code>e2</code> sees the stack in the same state as
|
||
<code>e1</code> did. Repetitions and optionals (<code>e*</code>, <code>e+</code>, <code>e{, n}</code>, <code>e{n,}</code>,
|
||
<code>e{m,n}</code>, <code>e?</code>) can modify the stack each time <code>e</code> matches. The <code>!e</code> and <code>&e</code>
|
||
expressions are a special case; they never modify the stack.
|
||
Many languages have “keyword” tokens (e.g. if, for, while) as well as general
|
||
tokens (e.g. identifier) that matches any word. In order to match a keyword,
|
||
generally, you may need to restrict that is not immediately followed by another
|
||
letter or digit (otherwise it would be matched as an identifier).</p>
|
||
<h3 id="special-rules"><a href="#special-rules">Special rules</a></h3>
|
||
<p>Special rules can be called within the grammar. They are:</p>
|
||
<ul>
|
||
<li><code>WHITESPACE</code> - runs between rules and sub-rules</li>
|
||
<li><code>COMMENT</code> - runs between rules and sub-rules</li>
|
||
<li><code>ANY</code> - matches exactly one <code>char</code></li>
|
||
<li><code>SOI</code> - (start-of-input) matches only when a <code>Parser</code> is still at the starting position</li>
|
||
<li><code>EOI</code> - (end-of-input) matches only when a <code>Parser</code> has reached its end</li>
|
||
<li><code>POP</code> - pops a string from the stack and matches it</li>
|
||
<li><code>POP_ALL</code> - pops the entire state of the stack and matches it</li>
|
||
<li><code>PEEK</code> - peeks a string from the stack and matches it</li>
|
||
<li><code>PEEK[a..b]</code> - peeks part of the stack and matches it</li>
|
||
<li><code>PEEK_ALL</code> - peeks the entire state of the stack and matches it</li>
|
||
<li><code>DROP</code> - drops the top of the stack (fails to match if the stack is empty)</li>
|
||
</ul>
|
||
<p><code>WHITESPACE</code> and <code>COMMENT</code> should be defined manually if needed. All other rules cannot be
|
||
overridden.</p>
|
||
<h3 id="whitespace-and-comment"><a href="#whitespace-and-comment"><code>WHITESPACE</code> and <code>COMMENT</code></a></h3>
|
||
<p>When defined, these rules get matched automatically in sequences (<code>~</code>) and repetitions
|
||
(<code>*</code>, <code>+</code>) between expressions. Atomic rules and those rules called by atomic rules are exempt
|
||
from this behavior.</p>
|
||
<p>These rules should be defined so as to match one whitespace character and one comment only since
|
||
they are run in repetitions.</p>
|
||
<p>If both <code>WHITESPACE</code> and <code>COMMENT</code> are defined, this grammar:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="ident">b</span> ~ <span class="ident">c</span> }</code></pre></div>
|
||
<p>is effectively transformed into this one behind the scenes:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="ident">b</span> ~ <span class="ident">WHITESPACE</span><span class="op">*</span> ~ (<span class="ident">COMMENT</span> ~ <span class="ident">WHITESPACE</span><span class="kw-2">*</span>)<span class="op">*</span> ~ <span class="ident">c</span> }</code></pre></div>
|
||
<h3 id="push-pop-drop-and-peek"><a href="#push-pop-drop-and-peek"><code>PUSH</code>, <code>POP</code>, <code>DROP</code>, and <code>PEEK</code></a></h3>
|
||
<p><code>PUSH(e)</code> simply pushes the captured string of the expression <code>e</code> down a stack. This stack can
|
||
then later be used to match grammar based on its content with <code>POP</code> and <code>PEEK</code>.</p>
|
||
<p><code>PEEK</code> always matches the string at the top of stack. So, if the stack contains <code>["b", "a"]</code>
|
||
(<code>"a"</code> being on top), this grammar:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="ident">PEEK</span> }</code></pre></div>
|
||
<p>is effectively transformed into at parse time:</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">a</span> <span class="op">=</span> { <span class="string">"a"</span> }</code></pre></div>
|
||
<p><code>POP</code> works the same way with the exception that it pops the string off of the stack if the
|
||
match worked. With the stack from above, if <code>POP</code> matches <code>"a"</code>, the stack will be mutated
|
||
to <code>["b"]</code>.</p>
|
||
<p><code>DROP</code> makes it possible to remove the string at the top of the stack
|
||
without matching it. If the stack is nonempty, <code>DROP</code> drops the top of the
|
||
stack. If the stack is empty, then <code>DROP</code> fails to match.</p>
|
||
<h4 id="advanced-peeking"><a href="#advanced-peeking">Advanced peeking</a></h4>
|
||
<p><code>PEEK[start..end]</code> and <code>PEEK_ALL</code> allow to peek deeper into the stack. The syntax works exactly
|
||
like Rust’s exclusive slice syntax. Additionally, negative indices can be used to indicate an
|
||
offset from the top. If the end lies before or at the start, the expression matches (as does
|
||
a <code>PEEK_ALL</code> on an empty stack). With the stack <code>["c", "b", "a"]</code> (<code>"a"</code> on top):</p>
|
||
|
||
<div class='information'><div class='tooltip ignore'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore"><code><span class="ident">fill</span> <span class="op">=</span> <span class="ident">PUSH</span>(<span class="string">"c"</span>) ~ <span class="ident">PUSH</span>(<span class="string">"b"</span>) ~ <span class="ident">PUSH</span>(<span class="string">"a"</span>)
|
||
<span class="ident">v</span> <span class="op">=</span> { <span class="ident">PEEK_ALL</span> } <span class="op">=</span> { <span class="string">"a"</span> ~ <span class="string">"b"</span> ~ <span class="string">"c"</span> } <span class="comment">// top to bottom</span>
|
||
<span class="ident">w</span> <span class="op">=</span> { <span class="ident">PEEK</span>[..] } <span class="op">=</span> { <span class="string">"c"</span> ~ <span class="string">"b"</span> ~ <span class="string">"a"</span> } <span class="comment">// bottom to top</span>
|
||
<span class="ident">x</span> <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">1</span>..<span class="number">2</span>] } <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">1</span>..<span class="op">-</span><span class="number">1</span>] } <span class="op">=</span> { <span class="string">"b"</span> }
|
||
<span class="ident">y</span> <span class="op">=</span> { <span class="ident">PEEK</span>[..<span class="op">-</span><span class="number">2</span>] } <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">0</span>..<span class="number">1</span>] } <span class="op">=</span> { <span class="string">"a"</span> }
|
||
<span class="ident">z</span> <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">1</span>..] } <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="op">-</span><span class="number">2</span>..<span class="number">3</span>] } <span class="op">=</span> { <span class="string">"c"</span> ~ <span class="string">"b"</span> }
|
||
<span class="ident">n</span> <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">2</span>..<span class="op">-</span><span class="number">2</span>] } <span class="op">=</span> { <span class="ident">PEEK</span>[<span class="number">2</span>..<span class="number">1</span>] } <span class="op">=</span> { <span class="string">""</span> }</code></pre></div>
|
||
<p>For historical reasons, <code>PEEK_ALL</code> matches from top to bottom, while <code>PEEK[start..end]</code> matches
|
||
from bottom to top. There is currently no syntax to match a slice of the stack top to bottom.</p>
|
||
<h3 id="rule"><a href="#rule"><code>Rule</code></a></h3>
|
||
<p>All rules defined or used in the grammar populate a generated <code>enum</code> called <code>Rule</code>. This
|
||
implements <code>pest</code>’s <code>RuleType</code> and can be used throughout the API.</p>
|
||
<h3 id="built-in-rules"><a href="#built-in-rules"><code>Built-in rules</code></a></h3>
|
||
<p>Pest also comes with a number of built-in rules for convenience. They are:</p>
|
||
<ul>
|
||
<li><code>ASCII_DIGIT</code> - matches a numeric character from 0..9</li>
|
||
<li><code>ASCII_NONZERO_DIGIT</code> - matches a numeric character from 1..9</li>
|
||
<li><code>ASCII_BIN_DIGIT</code> - matches a numeric character from 0..1</li>
|
||
<li><code>ASCII_OCT_DIGIT</code> - matches a numeric character from 0..7</li>
|
||
<li><code>ASCII_HEX_DIGIT</code> - matches a numeric character from 0..9 or a..f or A..F</li>
|
||
<li><code>ASCII_ALPHA_LOWER</code> - matches a character from a..z</li>
|
||
<li><code>ASCII_ALPHA_UPPER</code> - matches a character from A..Z</li>
|
||
<li><code>ASCII_ALPHA</code> - matches a character from a..z or A..Z</li>
|
||
<li><code>ASCII_ALPHANUMERIC</code> - matches a character from a..z or A..Z or 0..9</li>
|
||
<li><code>ASCII</code> - matches a character from \x00..\x7f</li>
|
||
<li><code>NEWLINE</code> - matches either “\n” or “\r\n” or “\r”</li>
|
||
</ul>
|
||
</div></details><h2 id="modules" class="small-section-header"><a href="#modules">Modules</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="mod" href="error/index.html" title="pest::error mod">error</a></div><div class="item-right docblock-short"><p>Types for different kinds of parsing failures.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="iterators/index.html" title="pest::iterators mod">iterators</a></div><div class="item-right docblock-short"><p>Types and iterators for parser output.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="pratt_parser/index.html" title="pest::pratt_parser mod">pratt_parser</a></div><div class="item-right docblock-short"><p>Constructs useful in prefix, postfix, and infix operator parsing with the
|
||
Pratt parsing method.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="prec_climber/index.html" title="pest::prec_climber mod">prec_climber</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short"><p>Constructs useful in infix operator parsing with the precedence climbing method.</p>
|
||
</div></div></div><h2 id="macros" class="small-section-header"><a href="#macros">Macros</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.fails_with.html" title="pest::fails_with macro">fails_with</a></div><div class="item-right docblock-short"><p>Testing tool that compares produced errors.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.parses_to.html" title="pest::parses_to macro">parses_to</a></div><div class="item-right docblock-short"><p>Testing tool that compares produced tokens.</p>
|
||
</div></div></div><h2 id="structs" class="small-section-header"><a href="#structs">Structs</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Lines.html" title="pest::Lines struct">Lines</a></div><div class="item-right docblock-short"><p>Line iterator for Spans, created by <a href="struct.Span.html#method.lines"><code>Span::lines()</code></a>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.LinesSpan.html" title="pest::LinesSpan struct">LinesSpan</a></div><div class="item-right docblock-short"><p>Line iterator for Spans, created by <a href="struct.Span.html#method.lines_span"><code>Span::lines_span()</code></a>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.ParserState.html" title="pest::ParserState struct">ParserState</a></div><div class="item-right docblock-short"><p>The complete state of a <a href="trait.Parser.html"><code>Parser</code></a>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Position.html" title="pest::Position struct">Position</a></div><div class="item-right docblock-short"><p>A cursor position in a <code>&str</code> which provides useful methods to manually parse that string.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Span.html" title="pest::Span struct">Span</a></div><div class="item-right docblock-short"><p>A span over a <code>&str</code>. It is created from either <a href="struct.Position.html#method.span">two <code>Position</code>s</a> or from a <a href="../iterators/struct.Pair.html#method.span"><code>Pair</code></a>.</p>
|
||
</div></div></div><h2 id="enums" class="small-section-header"><a href="#enums">Enums</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.Atomicity.html" title="pest::Atomicity enum">Atomicity</a></div><div class="item-right docblock-short"><p>The current atomicity of a <a href="struct.ParserState.html"><code>ParserState</code></a>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.Lookahead.html" title="pest::Lookahead enum">Lookahead</a></div><div class="item-right docblock-short"><p>The current lookahead status of a <a href="struct.ParserState.html"><code>ParserState</code></a>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.MatchDir.html" title="pest::MatchDir enum">MatchDir</a></div><div class="item-right docblock-short"><p>Match direction for the stack. Used in <code>PEEK[a..b]</code>/<code>stack_match_peek_slice</code>.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.Token.html" title="pest::Token enum">Token</a></div><div class="item-right docblock-short"><p>A token generated by a <code>Parser</code>.</p>
|
||
</div></div></div><h2 id="traits" class="small-section-header"><a href="#traits">Traits</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="trait" href="trait.Parser.html" title="pest::Parser trait">Parser</a></div><div class="item-right docblock-short"><p>A trait with a single method that parses strings.</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="trait" href="trait.RuleType.html" title="pest::RuleType trait">RuleType</a></div><div class="item-right docblock-short"><p>A trait which parser rules must implement.</p>
|
||
</div></div></div><h2 id="functions" class="small-section-header"><a href="#functions">Functions</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.set_call_limit.html" title="pest::set_call_limit fn">set_call_limit</a></div><div class="item-right docblock-short"><p>Sets the maximum call limit for the parser state
|
||
to prevent stack overflows or excessive execution times
|
||
in some grammars.
|
||
If set, the calls are tracked as a running total
|
||
over all non-terminal rules that can nest closures
|
||
(which are passed to transform the parser state).</p>
|
||
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.state.html" title="pest::state fn">state</a></div><div class="item-right docblock-short"><p>Creates a <code>ParserState</code> from a <code>&str</code>, supplying it to a closure <code>f</code>.</p>
|
||
</div></div></div><h2 id="types" class="small-section-header"><a href="#types">Type Definitions</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="type" href="type.ParseResult.html" title="pest::ParseResult type">ParseResult</a></div><div class="item-right docblock-short"><p>Type alias to simplify specifying the return value of chained closures.</p>
|
||
</div></div></div></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="pest" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.64.0 (a55dd71d5 2022-09-19)" ></div></body></html> |