tokel_std/
lib.rs

1#![forbid(
2    clippy::all,
3    clippy::perf,
4    clippy::nursery,
5    clippy::unwrap_used,
6    clippy::panic,
7    clippy::pedantic,
8    rustdoc::all,
9    unsafe_code
10)]
11//! # `tokel-std`
12//!
13//! A standard library of minimal, composable [`Transformer`] implementations for the Tokel engine.
14//!
15//! ## Available Transformers
16//!
17//! | Transformer       | Description | Example |
18//! |-------------------|-------------|---------|
19//! | [`Reverse`]       | Reverses the sequence of token trees. | `[< a b c >]:reverse` -> `c b a` |
20//! | [`Intersperse`]   | Inserts a token tree between each input token tree. | `[< a b c >]:intersperse[[,]]` -> `a , b , c` |
21//! | [`PushLeft`]      | Prepends a `TokenStream` to the input. | `[< b c >]:push_left[[a]]` -> `a b c` |
22//! | [`PushRight`]     | Appends a `TokenStream` to the input. | `[< a b >]:push_right[[c]]` -> `a b c` |
23//! | [`PopLeft`]       | Removes the first token tree from the input. | `[< a b c >]:pop_left` -> `b c` |
24//! | [`PopRight`]      | Removes the last token tree from the input. | `[< a b c >]:pop_right` -> `a b` |
25//! | [`Take`]          | Keeps the first N token trees. (Argument: `syn::LitInt`). | `[< a b c d >]:take[[2]]` -> `a b` |
26//! | [`Skip`]          | Discards the first N token trees. (Argument: `syn::LitInt`). | `[< a b c d >]:skip[[2]]` -> `c d` |
27//! | [`Repeat`]        | Repeats the input N times. (Argument: `syn::LitInt`). | `[< a b >]:repeat[[3]]` -> `a b a b a b` |
28//! | [`Count`]         | Returns the number of input token trees as an integer literal. | `[< a b c >]:count` -> `3` |
29//! | [`Sequence`]      | Yields an integer sequence. (Argument: `[[ start..end ]]`). | `[< >]:sequence[[1..=3]]` -> `1 2 3` |
30//! | [`Enumerate`]     | Stateful generator yielding an incrementing `u32` literal. | `[< >]:enumerate` -> `0` |
31//! | [`Concatenate`]   | Concatenates text representations of tokens into a single `Ident` or string literal. | `[< hello _ world >]:concatenate` -> `hello_world` |
32//! | [`ToString`]      | Stringifies arbitrary tokens into string literals. | `[< hello _ world >]:to_string` -> `"hello" "_" "world"` |
33//! | [`Case`]          | Converts identifiers and strings to a target [`CaseStyle`]. | `[< hello_world >]:case[[pascal]]` -> `HelloWorld` |
34//!
35//! ## Notes
36//!
37//! * **Arguments:** Transformers can accept other transformer expressions as arguments. Inner expressions are evaluated first.
38//! * **State:** Stateful transformers (like [`Enumerate`]) keep their state for the lifetime of the registered instance.
39//! * **Details:** See the module-level documentation ([`iter`], [`string`], [`structure`], [`state`]) for specific argument types and behaviors.
40//!
41//! [`Transformer`]: tokel_engine::prelude::Transformer
42//! [`Reverse`]: iter::Reverse
43//! [`Intersperse`]: iter::Intersperse
44//! [`PushLeft`]: iter::PushLeft
45//! [`PushRight`]: iter::PushRight
46//! [`PopLeft`]: iter::PopLeft
47//! [`PopRight`]: iter::PopRight
48//! [`Take`]: iter::Take
49//! [`Skip`]: iter::Skip
50//! [`Repeat`]: iter::Repeat
51//! [`Count`]: iter::Count
52//! [`Sequence`]: iter::Sequence
53//! [`Enumerate`]: state::Enumerate
54//! [`Concatenate`]: string::Concatenate
55//! [`Case`]: string::Case
56//! [`CaseStyle`]: string::CaseStyle
57//! [`iter`]: crate::iter
58//! [`string`]: crate::string
59//! [`structure`]: crate::structure
60//! [`state`]: crate::state
61//!
62//! ---
63//!
64//! *The following is the main `tokel` workspace documentation:*
65#![doc = include_str!("../README.md")]
66
67use tokel_engine::prelude::{Registry, Transformer};
68
69pub mod string;
70
71pub mod iter;
72
73pub mod structure;
74
75pub mod state;
76
77/// Registers all standard `Transformer`s into the provided `Registry`.
78///
79/// This inserts the default transformers from the `string`, `iter`, `structure`,
80/// and `state` modules.
81///
82/// # Errors
83///
84/// Returns an error if a transformer with the same name is already in the `Registry`.
85/// If this happens, any transformers that were successfully registered before the error
86/// will remain in the registry.
87#[inline]
88pub fn register(registry: &mut Registry) -> Result<(), Box<dyn Transformer>> {
89    string::register(registry)?;
90
91    iter::register(registry)?;
92
93    structure::register(registry)?;
94
95    state::register(registry)?;
96
97    Ok(())
98}
tokel_std/lib.rs

tokel_std/
lib.rs
