Chumsky

https://docs.rs/chumsky/latest/chumsky/
Admin
Chumsky is a parser combinator library for Rust that lets you write high-performance, expressive...
Tokens:439,303
Snippets:3,346
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### iter example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Shows how to iterate over a slice using the iter method, yielding all items from start to end. The example asserts each yielded value and the final None.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### as_mut example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Example for `as_mut`, showing how to get a mutable reference to the inner value and modify it in place.

```rust
let mut x = Some(2);
match x.as_mut() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));
```

--------------------------------

### Example input for let expression

Source: https://docs.rs/chumsky/latest/chumsky/guide/_07_tutorial/index.html

Example input that the interpreter should now accept after adding the `decl` parser.

```text
let five = 5;
five * 3
```

--------------------------------

### zip_with example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Shows how to combine two Options using a function, with a custom struct example. Requires the nightly-only feature option_zip.

```rust
#![feature(option_zip)]

#[derive(Debug, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
    fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }
}

let x = Some(17.5);
let y = Some(42.7);
```

--------------------------------

### as_ref example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Example for `as_ref`, showing how to convert `Option<String>` to `Option<&String>` to avoid moving the original value when using `map`.

```rust
let text: Option<String> = Some("Hello, world!".to_string());
// First, cast `Option<String>` to `Option<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {text:?}");
```

--------------------------------

### array_windows example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the array_windows method on a slice. It returns overlapping windows of N elements, starting at the beginning. Panics if N is zero, and returns no windows if N is greater than the slice length.

```rust
let slice = [0, 1, 2, 3];
let mut iter = slice.array_windows();
assert_eq!(iter.next().unwrap(), &[0, 1]);
assert_eq!(iter.next().unwrap(), &[1, 2]);
assert_eq!(iter.next().unwrap(), &[2, 3]);
assert!(iter.next().is_none());
```

--------------------------------

### is_none example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Example for `is_none`, showing it returns `true` for `None` and `false` for `Some`.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none(), false);

let x: Option<u32> = None;
assert_eq!(x.is_none(), true);
```

--------------------------------

### is_some example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Example for `is_some`, showing it returns `true` for `Some` and `false` for `None`.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some(), true);

let x: Option<u32> = None;
assert_eq!(x.is_some(), false);
```

--------------------------------

### Example program for testing the interpreter

Source: https://docs.rs/chumsky/latest/chumsky/guide/_07_tutorial/index.html

Example program to test the interpreter with variable declarations, a function definition, and a function call.

```text
let five = 5;
let eight = 3 + five;
fn add x y = x + y;
add(five, eight)
```

--------------------------------

### as_slice example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Example for `as_slice`, showing that `Some` yields a slice with the value and `None` yields an empty slice.

```rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);
```

--------------------------------

### unwrap examples

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Shows unwrap returning the contained value for Some and panicking for None. The failing example is marked with ⓘ to indicate it will panic.

```rust
let x = Some("air");
assert_eq!(x.unwrap(), "air");
```

```rust
let x: Option<&str> = None;
assert_eq!(x.unwrap(), "air"); // fails
```

--------------------------------

### Slice get() example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Shows `get` returning a reference to an element or subslice, or `None` when out of bounds.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### take example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Shows how to take the value out of an Option, leaving None in its place, for both Some and None cases.

```rust
let mut x = Some(2);
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, Some(2));

let mut x: Option<u32> = None;
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, None);
```

--------------------------------

### Sample code written in Foo

Source: https://docs.rs/chumsky/latest/chumsky/guide/_07_tutorial/index.html

An example of the Foo language syntax that the tutorial will teach you to parse and interpret.

```text
let seven = 7;
fn add x y = x + y;
add(2, 3) * -seven
```

--------------------------------

### Example: configuring a parser with context

Source: https://docs.rs/chumsky/latest/chumsky/trait.ConfigParser.html

Shows how to use configure with ignore_with_ctx to parse a length-prefixed array. The parser accepts a number followed by that many items. Demonstrates successful and failing parses.

```rust
let int = text::int::<_, extra::Err<Rich<char>>>(10)
    .from_str()
    .unwrapped();

// By default, accepts any number of items
let item = text::ascii::ident()
    .padded()
    .repeated();

// With configuration, we can declare an exact number of items based on a prefix length
let len_prefixed_arr = int
    .ignore_with_ctx(item.configure(|repeat, ctx| repeat.exactly(*ctx)).collect::<Vec<_>>());

assert_eq!(
    len_prefixed_arr.parse("2 foo bar").into_result(),
    Ok(vec!["foo", "bar"]),
);

assert_eq!(
    len_prefixed_arr.parse("0").into_result(),
    Ok(vec![]),
);

len_prefixed_arr.parse("3 foo bar baz bam").into_result().unwrap_err();
len_prefixed_arr.parse("3 foo bar").into_result().unwrap_err();
```

--------------------------------

### Slice len() example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Shows how to use the `len` method to get the number of elements in a slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### element_offset basic example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Basic usage of `element_offset` to get the index of an element reference. It uses pointer arithmetic and does not compare elements.

```rust
let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

--------------------------------

### Full parser example using select!

Source: https://docs.rs/chumsky/latest/chumsky/macro.select.html

Complete example of a parser that converts a token stream into an AST, using select! for literals and recursive parsing for lists.

```rust
// The type of our parser's input (tokens like this might be emitted by your compiler's lexer)
#[derive(Clone, Debug, PartialEq)]
enum Token {
    Num(u64),
    Bool(bool),
    LParen,
    RParen,
}

// The type of our parser's output, a syntax tree
#[derive(Debug, PartialEq)]
enum Ast {
    Num(u64),
    Bool(bool),
    List(Vec<Ast>),
}

// Our parser converts a stream of input tokens into an AST
// `select!` is used to deconstruct some of the tokens and turn them into AST nodes
let ast = recursive::<_, _, extra::Err<Simple<Token>>, _, _>(|ast| {
    let literal = select! {
        Token::Num(x) => Ast::Num(x),
        Token::Bool(x) => Ast::Bool(x),
    };

    literal.or(ast
        .repeated()
        .collect()
        .delimited_by(just(Token::LParen), just(Token::RParen))
        .map(Ast::List))
});

use Token::*;
assert_eq!(
    ast.parse(&[LParen, Num(5), LParen, Bool(false), Num(42), RParen, RParen]).into_result(),
    Ok(Ast::List(vec![
        Ast::Num(5),
        Ast::List(vec![
            Ast::Bool(false),
            Ast::Num(42),
        ]),
    ])),
);
```

--------------------------------

### ExactSizeInput::span_from

Source: https://docs.rs/chumsky/latest/chumsky/input/trait.ExactSizeInput.html

Gets a span from a start cursor to the end of the input. This method is unsafe and requires that the cursors provided are generated by this input.

```APIDOC
## ExactSizeInput::span_from

### Description
Gets a span from a start cursor to the end of the input. This method is unsafe and requires that the cursors provided are generated by this input.

### Method
unsafe fn span_from(cache: &mut Self::Cache, range: RangeFrom<&Self::Cursor>) -> Self::Span

### Parameters
- **cache** (&mut Self::Cache) - Required - The cache for the input.
- **range** (RangeFrom<&Self::Cursor>) - Required - A range starting from a cursor to the end of the input.

### Returns
- **Self::Span** - The span from the start cursor to the end of the input.

### Safety
As with functions on `Input`, the cursors provided must be generated by this input.
```

--------------------------------

### as_rchunks example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the as_rchunks method, which splits the slice into chunks starting from the end, with a remainder slice at the beginning. Panics if N is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
```

--------------------------------

### binary_search basic example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the basic usage of `binary_search` on a slice. Shows that `Ok` is returned with the index when found, and `Err` with the insertion index when not found. For multiple matches, any index in the range may be returned.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### windows examples

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Examples for the windows method: the first shows overlapping windows of size 3; the second shows that when the slice is shorter than the window size, the iterator yields no values; the third shows using Cell::as_slice_of_cells to mutate elements through windows, since there is no windows_mut. Panics if size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.windows(3);
assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
assert!(iter.next().is_none());
```

```rust
let slice = ['f', 'o', 'o'];
let mut iter = slice.windows(4);
assert!(iter.next().is_none());
```

```rust
use std::cell::Cell;

let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
let slice = &mut array[..];
let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
for w in slice_of_cells.windows(3) {
    Cell::swap(&w[0], &w[2]);
}
assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);
```

--------------------------------

### as_mut_slice examples

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Shows how to obtain a mutable slice from an Option using as_mut_slice, including modifying the value through the slice and using first_mut to get a mutable reference.

```rust
assert_eq!(
    [Some(1234).as_mut_slice(), None.as_mut_slice()],
    [&mut [1234][..], &mut [][..]],
);
```

```rust
let mut x = Some(1234);
x.as_mut_slice()[0] += 1;
assert_eq!(x, Some(1235));
```

```rust
assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123))
```

--------------------------------

### rchunks example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the rchunks method on a slice. It returns chunks of chunk_size elements starting from the end, with the last chunk possibly shorter. Panics if chunk_size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### expect examples

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Demonstrates the expect method: returns the contained value for Some, panics with the provided message for None, and shows the recommended message style using 'should'.

```rust
let x = Some("value");
assert_eq!(x.expect("fruits are healthy"), "value");
```

```rust
let x: Option<&str> = None;
x.expect("fruits are healthy"); // panics with `fruits are healthy`
```

```rust
let item = slice.get(0)
    .expect("slice should not be empty");
```

--------------------------------

### rchunks_exact example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the rchunks_exact method on a slice. It returns chunks of exactly chunk_size elements starting from the end, omitting the remainder which can be retrieved via the remainder function. Panics if chunk_size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks_exact(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['l']);
```

--------------------------------

### zip_with example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Combines two Option values using a function if both are Some. The first example shows a successful combination, the second shows a None result.

```rust
assert_eq!(x.zip_with(y, Point::new), Some(Point { x: 17.5, y: 42.7 }));
assert_eq!(x.zip_with(None, Point::new), None);
```

--------------------------------

### zip example

Source: https://docs.rs/chumsky/latest/chumsky/number/format/type.OptionU8.html

Shows how to combine two Options into a tuple Option, returning None if either is None.

```rust
let x = Some(1);
let y = Some("hi");
let z = None::<u8>;

assert_eq!(x.zip(y), Some((1, "hi")));
assert_eq!(x.zip(z), None);
```

--------------------------------

### strip_circumfix example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Shows how to use strip_circumfix on a slice. Returns Some with the subslice after the prefix and before the suffix if the slice starts with prefix, ends with suffix, and they don't overlap; otherwise returns None. Empty prefix or suffix is allowed.

```rust
let v = &[10, 50, 40, 30];
assert_eq!(v.strip_circumfix(&[10], &[30]), Some(&[50, 40][..]));
assert_eq!(v.strip_circumfix(&[10], &[40, 30]), Some(&[50][..]));
assert_eq!(v.strip_circumfix(&[10, 50], &[40, 30]), Some(&[][..]));
assert_eq!(v.strip_circumfix(&[50], &[30]), None);
assert_eq!(v.strip_circumfix(&[10], &[40]), None);
assert_eq!(v.strip_circumfix(&[], &[40, 30]), Some(&[10, 50][..]));
assert_eq!(v.strip_circumfix(&[10, 50], &[]), Some(&[40, 30][..]));
assert_eq!(v.strip_circumfix(&[10, 50, 40], &[50, 40, 30]), None);
```

--------------------------------

### binary_search_by_key example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates binary_search_by_key on a slice of pairs sorted by their second elements. Shows Ok with a unique index, Err with insertion indices, and a range match for multiple possible positions.

```rust
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
         (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
         (1, 21), (2, 34), (4, 55)];

assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b),  Ok(9));
assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b),   Err(7));
assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
let r = s.binary_search_by_key(&1, |&(a, b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### strip_prefix example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Shows how to use strip_prefix on a slice. Returns Some with the subslice after the prefix if the slice starts with the prefix, or None otherwise. Empty prefix returns the original slice; prefix equal to the slice returns an empty slice.

```rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```

--------------------------------

### try_shrink_to_fit example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Demonstrates the nightly-only try_shrink_to_fit, which attempts to shrink capacity and returns a Result. The example uses expect to assert success and checks capacity is at least 3.

```rust
#![feature(vec_fallible_shrink)]

let mut vec = Vec::with_capacity(10);
vec.extend([1, 2, 3]);
assert!(vec.capacity() >= 10);
vec.try_shrink_to_fit().expect("for this test, shrink shouldn't fail");
assert!(vec.capacity() >= 3);
```

--------------------------------

### extend_from_within example

Source: https://docs.rs/chumsky/latest/chumsky/inspector/struct.TruncateState.html

Clones a slice of elements in the given range and appends them to the end. Panics if the starting index is greater than the end index, if the index is greater than the vector length, or if the new capacity exceeds isize::MAX bytes.

```rust
let mut characters = vec!['a', 'b', 'c', 'd', 'e'];
characters.extend_from_within(2..);
assert_eq!(characters, ['a', 'b', 'c', 'd', 'e', 'c', 'd', 'e']);

let mut numbers = vec![0, 1, 2, 3, 4];
numbers.extend_from_within(..2);
assert_eq!(numbers, [0, 1, 2, 3, 4, 0, 1]);

let mut strings = vec![String::from("hello"), String::from("world"), String::from("!")];
strings.extend_from_within(1..=2);
assert_eq!(strings, ["hello", "world", "!", "world", "!"]);
```
Tokens:
Raw