core_extensions/macros/macro_utils/tokens_method.rs
1/// Does slice and iterator operations on tokens, passing the result to a callback macro.
2///
3/// # Elements
4///
5/// The elements that this operates on are token trees, which can be any of:
6///
7/// - A macro parameter(eg: `$foo`)
8///
9/// - A literal
10///
11/// - A pair of matching `[]`/`()`/`{}` (no matter what's contained by the matched pair)
12///
13/// - An identifier
14///
15/// - Punctuation
16///
17/// # Methods
18///
19/// These are the methods that this provides:
20///
21/// - [`first`](#first): Gets the first token tree.
22///
23/// - [`last`](#last): Gets the last token tree.
24///
25/// - [`split_first`](#split_first): Gets the first token tree, and the remaining ones.
26///
27/// - [`split_last`](#split_last): Gets the last token tree, and the remaining ones.
28///
29/// - [`split_last_n`](#split_last_n): Gets the last n token trees, and the remaining ones.
30///
31/// - [`split_at`](#split_at): Gets the token trees before the nth one, and from it.
32///
33/// - [`get`](#get): Gets the token(s) at an index or range.
34///
35/// - [`split`](#split)/[`split_terminator`](#split_terminator)/
36/// [`split_starter`](#split_starter): Splits the tokens with some needle tokens.
37///
38/// - [`zip_shortest`](#zip_shortest)/[`zip_longest`](#zip_longest):
39/// Return the token trees of every list iterated over in lockstep.
40///
41/// - [`iterate`](#iterate):
42/// Nested iteration over multiple lists.
43///
44/// The methods that take integer arguments use
45/// [the `<number>` syntax](./macro.gen_ident_range.html#number-syntax) from [`gen_ident_range`]
46///
47/// # Iterators
48///
49/// This macro can iterate over both lists of token trees (eg: `(foo bar baz)`),
50/// and iteration functions (eg: `range(0..10)`).
51///
52/// ### Functions
53///
54/// Iteration functions can be used to generate tokens or transform a list of tokens.
55///
56/// These are the functions:
57///
58/// - [`range`](#range-fn): Iterates over all the integers in a range, can be unbounded.
59///
60/// - [`gen_ident_range`](#gen_ident_range-fn):
61/// Generates identifiers by using the [`gen_ident_range`] macro.
62///
63/// - [`chain`](#chain-fn): Concatenates multiple iterators.
64///
65/// - [`take`](#take-fn): Takes some amount of elements from a possibly unbounded iterator.
66///
67/// - [`skip`](#skip-fn): Skips elements from a possibly unbounded iterator.
68///
69/// - [`cycle`](#cycle-fn): Takes a bounded iterator and repeats it infinitely.
70///
71/// - [`repeat`](#repeat-fn): Repeats a bounded iterator some amount of times.
72///
73///
74/// When an iterator function generates an unbounded amount of tokens,
75/// they must be constrained by another iterator to be used,
76/// otherwise producing a compile-time error to prevent the proc macro from running forever.
77///
78/// # Version compatibility
79///
80/// This macro requires Rust 1.45.0 to be invoked inside of a function.
81///
82/// # Examples
83///
84/// Examples that demonstrate properties common to all methods
85///
86/// ### Macro parameters
87///
88/// This demonstrates how you can pass macro parameters to `tokens_method`.
89///
90/// Note that because this example uses this macro in an expression,
91/// it requires at least Rust 1.45.0.
92///
93#[cfg_attr(feature = "rust_1_46", doc = "```rust")]
94#[cfg_attr(not(feature = "rust_1_46"), doc = "```ignore")]
95///
96/// fn main() {
97/// {
98/// let arrays = split_array!(2 => 3, 5, 8, 5 + 8, 3 + 5 + 13, 34, 55);
99/// assert_eq!(arrays, ([3, 5], [8, 13, 21, 34, 55]));
100/// }
101/// {
102/// let arrays = split_array!(100 => 3, 5, 8, 5 + 8, 3 + 5 + 13, 34, 55);
103/// const EMPTY: [i32; 0] = [];
104/// assert_eq!(arrays, ([3, 5, 8, 13, 21, 34, 55], EMPTY));
105/// }
106/// }
107///
108///
109/// #[macro_export]
110/// macro_rules! split_array {
111/// ($split_at:literal => $($elem:expr),* $(,)?) => {
112/// // `tokens_method` calls `__priv_split_array` with `foo bar` as the first arguments,
113/// // passing the return value of `split_at` after them.
114/// $crate::__::tokens_method!{
115/// __priv_split_array!{foo bar}
116/// split_at($split_at):
117/// ($($elem)*) // Note the lack of `,`!
118/// }
119/// }
120/// }
121///
122/// #[doc(hidden)]
123/// #[macro_export]
124/// macro_rules! __priv_split_array {
125/// (foo bar ($($left:expr)*) ($($right:expr)*)) => {
126/// ([$($left,)*], [$($right,)*])
127/// }
128/// }
129///
130/// #[doc(hidden)]
131/// mod __ {
132/// pub use core_extensions::tokens_method;
133/// }
134/// ```
135///
136/// # `first`
137///
138/// Gets the first token tree.
139///
140/// If there are no elements, this produces a `()`.
141///
142/// This can take an unbounded iterator function, since it only gets the first element.
143///
144/// ```rust
145/// use core_extensions::tokens_method;
146///
147/// fn main() {
148/// assert_eq!(foo(), "bar");
149/// assert_eq!(foo2(), "bar2");
150/// assert_eq!(baz(), "qux");
151/// }
152///
153/// macro_rules! expects_fooooo {
154/// ($func:ident $lit:literal (1000) ) => {
155/// fn $func() -> &'static str {
156/// $lit
157/// }
158/// }
159/// }
160/// // `tokens_method` calls `expects_fooooo` here
161/// tokens_method!{
162/// expects_fooooo!{ foo "bar" }
163/// first:
164/// (1000 20 30 (40 50))
165/// }
166/// tokens_method!{
167/// expects_fooooo!{ foo2 "bar2" }
168/// first:
169/// range(1000..) // taking an unbounded iterator argument
170/// }
171///
172/// macro_rules! expects_baaaz {
173/// ($func:ident $lit:literal ((1 2 3)) ) => {
174/// fn $func() -> &'static str {
175/// $lit
176/// }
177/// }
178/// }
179/// // `tokens_method` calls `expects_baaaz` here
180/// tokens_method!{
181/// expects_baaaz!{ baz "qux" }
182/// first:
183/// ((1 2 3) 20 30 (40 50))
184/// }
185///
186/// ```
187///
188/// # `last`
189///
190/// Gets the last token tree.
191///
192/// If there are no elements, this produces a `()`.
193///
194/// ### Example
195///
196/// ```rust
197/// use core_extensions::tokens_method;
198///
199/// fn main() {
200/// assert_eq!(foo(), "bar");
201/// assert_eq!(baz(), "qux");
202/// }
203///
204/// macro_rules! expects_fooooo {
205/// ($func:ident $lit:literal (1000) ) => {
206/// fn $func() -> &'static str {
207/// $lit
208/// }
209/// }
210/// }
211/// // `tokens_method` calls `expects_fooooo` here
212/// tokens_method!{
213/// expects_fooooo!{ foo "bar" }
214/// last:
215/// (20 30 (40 50) 1000)
216/// }
217///
218///
219/// macro_rules! expects_baaaz {
220/// ($func:ident $lit:literal ((1 2 3)) ) => {
221/// fn $func() -> &'static str {
222/// $lit
223/// }
224/// }
225/// }
226/// // `tokens_method` calls `expects_baaaz` here
227/// tokens_method!{
228/// expects_baaaz!{ baz "qux" }
229/// last:
230/// (20 30 (40 50) (1 2 3))
231/// }
232///
233/// ```
234///
235/// # `split_first`
236///
237/// Gets the first token tree, and the remaining ones.
238///
239/// If there are no elements, this produces `() ()`.
240/// If there is only one element, this produces `($first_element) ()`.
241///
242/// ### Example
243///
244/// ```rust
245/// use core_extensions::tokens_method;
246///
247/// fn main() {
248/// assert_eq!(foo(), "bar");
249/// assert_eq!(baz(), "qux");
250/// }
251///
252/// macro_rules! expects_fooooo {
253/// ($func:ident $lit:literal (1000) (20 30 (40 50)) ) => {
254/// fn $func() -> &'static str {
255/// $lit
256/// }
257/// }
258/// }
259/// // `tokens_method` calls `expects_fooooo` here
260/// tokens_method!{
261/// expects_fooooo!{ foo "bar" }
262/// split_first:
263/// (1000 20 30 (40 50))
264/// }
265///
266/// macro_rules! expects_baaaz {
267/// ($func:ident $lit:literal ((1 2 3)) (20 30 (40 50)) ) => {
268/// fn $func() -> &'static str {
269/// $lit
270/// }
271/// }
272/// }
273/// // `tokens_method` calls `expects_baaaz` here
274/// tokens_method!{
275/// expects_baaaz!{ baz "qux" }
276/// split_first:
277/// ((1 2 3) 20 30 (40 50))
278/// }
279///
280/// ```
281///
282/// # `split_last`
283///
284/// Gets the last token tree, and the remaining ones.
285///
286/// If there are no elements, this produces `() ()`.
287/// If there is only one element, this produces `() ($last_elemnent)`.
288///
289/// ### Example
290///
291/// ```rust
292/// use core_extensions::tokens_method;
293///
294/// fn main() {
295/// assert_eq!(foo(), "bar");
296/// assert_eq!(baz(), "qux");
297/// }
298///
299/// macro_rules! expects_fooooo {
300/// ($func:ident $lit:literal (20 30 (40 50)) (1000) ) => {
301/// fn $func() -> &'static str {
302/// $lit
303/// }
304/// }
305/// }
306/// // `tokens_method` calls `expects_fooooo` here
307/// tokens_method!{
308/// expects_fooooo!{ foo "bar" }
309/// split_last:
310/// (20 30 (40 50) 1000)
311/// }
312///
313/// macro_rules! expects_baaaz {
314/// ($func:ident $lit:literal (20 30 (40 50)) ((1 2 3)) ) => {
315/// fn $func() -> &'static str {
316/// $lit
317/// }
318/// }
319/// }
320/// // `tokens_method` calls `expects_baaaz` here
321/// tokens_method!{
322/// expects_baaaz!{ baz "qux" }
323/// split_last:
324/// (20 30 (40 50) (1 2 3))
325/// }
326///
327/// ```
328///
329/// # `split_last_n`
330///
331/// Gets the last n token trees, and the remaining ones.
332///
333/// If there's fewer than n token trees in the list,
334/// this simply returns the list in `() (here)`.
335///
336/// ### Example
337///
338/// ```rust
339/// use core_extensions::tokens_method;
340///
341/// fn main() {
342/// assert_eq!(foo(), "bar");
343/// assert_eq!(baz(), "qux");
344/// }
345///
346/// macro_rules! expects_fooooo {
347/// ($func:ident $lit:literal (20 30) ((40 50) 1000) ) => {
348/// fn $func() -> &'static str {
349/// $lit
350/// }
351/// }
352/// }
353/// // `tokens_method` calls `expects_fooooo` here
354/// tokens_method!{
355/// expects_fooooo!{ foo "bar" }
356/// split_last_n(2):
357/// (20 30 (40 50) 1000)
358/// }
359///
360/// macro_rules! expects_baaaz {
361/// ($func:ident $lit:literal (10 20) (30 (40 50) (1 2 3)) ) => {
362/// fn $func() -> &'static str {
363/// $lit
364/// }
365/// }
366/// }
367/// // `tokens_method` calls `expects_baaaz` here
368/// tokens_method!{
369/// expects_baaaz!{ baz "qux" }
370/// // Equivalent to `split_last_n(3)`
371/// split_last_n(count(_ 1 (2 2 2))):
372/// (10 20 30 (40 50) (1 2 3))
373/// }
374///
375/// ```
376///
377/// # `split_at`
378///
379/// Gets the token trees before the nth one, and from it.
380///
381/// If there's fewer than n token trees in the list,
382/// this simply returns the list in `(here) ()`.
383///
384/// ### Example
385///
386/// ```rust
387/// use core_extensions::tokens_method;
388///
389/// fn main() {
390/// assert_eq!(foo(), "bar");
391/// assert_eq!(baz(), "qux");
392/// }
393///
394/// macro_rules! expects_fooooo {
395/// ($func:ident $lit:literal (20) (30 (40 50) 1000 2345) ) => {
396/// fn $func() -> &'static str {
397/// $lit
398/// }
399/// }
400/// }
401/// // `tokens_method` calls `expects_fooooo` here
402/// tokens_method!{
403/// expects_fooooo!{ foo "bar" }
404/// split_at(1):
405/// (20 30 (40 50) 1000 2345)
406/// }
407///
408/// macro_rules! expects_baaaz {
409/// ($func:ident $lit:literal (20 30 (40 50)) (1000 2345) ) => {
410/// fn $func() -> &'static str {
411/// $lit
412/// }
413/// }
414/// }
415/// // `tokens_method` calls `expects_baaaz` here
416/// tokens_method!{
417/// expects_baaaz!{ baz "qux" }
418/// // Equivalent to `split_at(3)`
419/// split_at(count(_ 1 (2 2 2))):
420/// (20 30 (40 50) 1000 2345)
421/// }
422///
423/// ```
424///
425/// # `get`
426///
427/// Gets the token(s) at an index (either an integer or a range).
428///
429/// IF the integer index is out of bounds, this outputs `()`.
430///
431/// IF the range is out of bounds,
432/// this outputs the elements at the in-bound indices (of the range).
433///
434/// If the input elements come from an unbounded iterator,
435/// the range must have an end bound.
436///
437/// ### Example
438///
439/// ```rust
440/// use core_extensions::tokens_method;
441///
442/// # fn main() {}
443///
444/// macro_rules! expects_one {
445/// (foo bar (6)) => {}
446/// }
447/// // `tokens_method` invokes `expects_one` here
448/// tokens_method!{expects_one!{ foo bar } get(3): (2 3 (4 5) 6 7)}
449///
450/// // taking an unbounded iterator
451/// tokens_method!{expects_one!{ foo bar } get(2): range(4..)}
452///
453/// // `count(_ 1 (2 2))` is equivalent to `3`
454/// tokens_method!{expects_one!{ foo bar } get(count(_ 1 (2 2))): (2 3 (4 5) 6 7)}
455///
456///
457/// macro_rules! expects_two {
458/// (baz qux (3 (4 5)) ) => {}
459/// }
460/// // `tokens_method` calls `expects_two` here
461/// tokens_method!{expects_two!{ baz qux } get(1..3): (2 3 (4 5) 6 7)}
462/// tokens_method!{expects_two!{ baz qux } get(1..=2): (2 3 (4 5) 6 7)}
463///
464///
465/// macro_rules! expects_three {
466/// (baz qux (2 3 (4 5)) ) => {}
467/// }
468/// // `tokens_method` calls `expects_three` here
469/// tokens_method!{expects_three!{ baz qux } get(0..3): (2 3 (4 5) 6 7)}
470/// tokens_method!{expects_three!{ baz qux } get( ..3): (2 3 (4 5) 6 7)}
471/// tokens_method!{expects_three!{ baz qux } get(0..=2): (2 3 (4 5) 6 7)}
472/// tokens_method!{expects_three!{ baz qux } get( ..=2): (2 3 (4 5) 6 7)}
473///
474///
475/// macro_rules! expects_four {
476/// (baz qux (3 (4 5) 6 7) ) => {}
477/// }
478/// // `tokens_method` calls `expects_four` here
479/// tokens_method!{expects_four!{ baz qux } get(1..): (2 3 (4 5) 6 7)}
480/// tokens_method!{expects_four!{ baz qux } get(1..): (2 3 (4 5) 6 7)}
481/// tokens_method!{
482/// expects_four!{ baz qux }
483/// get(1..=4):
484/// chain((2 3 (4 5)) range(6..))
485/// }
486///
487/// ```
488///
489/// # `split`
490///
491/// Splits the tokens with some needle tokens.
492///
493/// If the needle is at the end of the tokens, this outputs a final `()`.
494/// Eg: `X` splits `foo X bar X` into `(foo) (bar) ()`.
495///
496/// If the needle is not found, this outputs all the tokens.
497///
498/// ### Example
499///
500/// Note that because this example uses this macro in an expression,
501/// it requires at least Rust 1.45.0.
502///
503#[cfg_attr(feature = "rust_1_46", doc = "```rust")]
504#[cfg_attr(not(feature = "rust_1_46"), doc = "```ignore")]
505/// fn main() {
506/// assert_eq!(
507/// piped!(100 |> |x:u32| x + 1 |> |x:u32| x.to_string() ),
508/// "101",
509/// );
510/// assert_eq!(piped!("foo" |> String::from |> repeat), "foofoofoofoo");
511/// }
512///
513/// fn repeat<S: AsRef<str>>(s: S) -> String {
514/// s.as_ref().repeat(4)
515/// }
516///
517/// #[macro_export]
518/// macro_rules! piped {
519/// ( $($tt:tt)* ) => {
520/// $crate::__::tokens_method!(
521/// $crate::__priv_piped!(hello)
522/// split(|>):
523/// ($($tt)*)
524/// )
525/// }
526/// }
527///
528/// #[doc(hidden)]
529/// #[macro_export]
530/// macro_rules! __priv_piped {
531/// (hello ($value:expr) $(($f:expr))* ) => ({
532/// match $value {x => {
533/// $( let x = $f(x); )*
534/// x
535/// }}
536/// })
537/// }
538///
539/// #[doc(hidden)]
540/// pub mod __ {
541/// pub use core_extensions::tokens_method;
542/// }
543/// ```
544///
545/// # `split_terminator`
546///
547/// Splits the tokens with some needle tokens.
548///
549/// If the needle is at the end of the tokens, this does not output an additional `()`.
550/// Eg: `X` splits `foo X bar X` into `(foo) (bar)`.
551///
552/// If the needle is not found, this outputs all the tokens.
553///
554/// ### Example
555///
556/// Note that because this example uses this macro in an expression,
557/// it requires at least Rust 1.45.0.
558///
559#[cfg_attr(feature = "rust_1_46", doc = "```rust")]
560#[cfg_attr(not(feature = "rust_1_46"), doc = "```ignore")]
561/// fn main() {
562/// let expected = "hello99_99world";
563///
564/// // `++` can be used between strings
565/// assert_eq!(concaten!("hello" ++ format!("{0}_{0}", 99) ++ "world"), expected);
566///
567/// // `++` can also terminate the argument list
568/// assert_eq!(concaten!("hello" ++ format!("{0}_{0}", 99) ++ "world" ++), expected);
569/// }
570///
571/// #[macro_export]
572/// macro_rules! concaten {
573/// ( $($tt:tt)* ) => {
574/// $crate::__::tokens_method!(
575/// $crate::__priv_concaten!(hello)
576/// split_terminator(++):
577/// ($($tt)*)
578/// )
579/// }
580/// }
581///
582/// #[doc(hidden)]
583/// #[macro_export]
584/// macro_rules! __priv_concaten {
585/// (hello $(($f:expr))* ) => ({
586/// let mut buff = $crate::__::String::new();
587/// $(
588/// buff.push_str($f.as_ref());
589/// )*
590/// buff
591/// });
592/// ($($tt:tt)*) => { core_extensions::compile_error_stringify!{$($tt)*} }
593/// }
594///
595/// #[doc(hidden)]
596/// pub mod __ {
597/// pub use core_extensions::tokens_method;
598///
599/// pub use std::string::String;
600/// }
601/// ```
602///
603/// # `split_starter`
604///
605/// Splits the tokens with some needle tokens.
606///
607/// If the needle is at the start of the tokens, this does not output a `()` at the start.
608/// Eg: `X` splits `X foo X bar` into `(foo) (bar)`.
609///
610/// If the needle is not found, this outputs all the tokens.
611///
612/// ### Example
613///
614/// Note that because this example uses this macro in an expression,
615/// it requires at least Rust 1.45.0.
616///
617#[cfg_attr(feature = "rust_1_46", doc = "```rust")]
618#[cfg_attr(not(feature = "rust_1_46"), doc = "```ignore")]
619/// fn main() {
620/// let expected = Flags::Foo.or(Flags::Bar).or(Flags::Baz).or(Flags::Qux);
621///
622/// // `|` can be used between flags
623/// assert_eq!(combine!(Foo | Bar | Flags::Baz.or(Flags::Qux) ), expected);
624///
625/// // `|` can also start the argument list
626/// const PRE_FLAGS: Flags = combine!(| Foo | returns_flags() | Bar );
627/// assert_eq!(PRE_FLAGS, expected);
628/// }
629///
630/// const fn returns_flags()-> Flags {
631/// combine!(Baz | Qux)
632/// }
633///
634/// /// Allows using `Foo | Bar` syntax for Flags in a const context
635/// /// (as of Rust 1.51.0, custom types can't overload the `|` operator in const contexts).
636/// #[macro_export]
637/// macro_rules! combine {
638/// ( $($tt:tt)* ) => {
639/// $crate::__::tokens_method!(
640/// $crate::__priv_combine!(world)
641/// split_starter(|):
642/// ($($tt)*)
643/// )
644/// }
645/// }
646///
647/// #[doc(hidden)]
648/// #[macro_export]
649/// macro_rules! __priv_combine {
650/// (world $($param:tt)* ) => (
651/// $crate::Flags::Empty $( .or($crate::__priv_combine!(@flag $param)) )*
652/// );
653/// (@flag ($ident:ident)) => { $crate::Flags::$ident };
654/// (@flag ($expression:expr)) => { $expression };
655/// }
656///
657/// #[derive(Debug, Copy, Clone, PartialEq, Eq)]
658/// #[repr(transparent)]
659/// pub struct Flags(u32);
660///
661/// impl Flags {
662/// pub const Empty: Self = Self(0);
663/// pub const Foo: Self = Self(1);
664/// pub const Bar: Self = Self(2);
665/// pub const Baz: Self = Self(4);
666/// pub const Qux: Self = Self(8);
667///
668/// pub const fn or(mut self, other: Self) -> Self {
669/// self.0 |= other.0;
670/// self
671/// }
672/// }
673///
674/// #[doc(hidden)]
675/// pub mod __ {
676/// pub use core_extensions::tokens_method;
677/// }
678/// ```
679///
680///
681/// # `zip_shortest`
682///
683/// Returns the token trees of every list iterated over in lockstep.
684///
685/// This returns as many token trees as the shortest list.
686///
687/// This is similar to [lockstep iteration in macro_rules! macros](#lockstep_iteration),
688/// except that those require the lists to be the same length.
689///
690/// ### Example
691///
692/// ```rust
693/// use core_extensions::tokens_method;
694///
695/// fn main() {
696/// assert_eq!(foo(), "bar");
697/// assert_eq!(baz(), "qux");
698/// }
699///
700/// macro_rules! expected {
701/// (
702/// $func:ident $value:literal
703/// ((foo3) (bar3) (qux3))
704/// ((foo5) (bar5) (qux5))
705/// ((foo8) (bar8) (qux8))
706/// ((foo13) (bar13) (qux13))
707/// ((foo21) (bar21) (qux21))
708/// ) => {
709/// fn $func() -> &'static str {
710/// $value
711/// }
712/// }
713/// }
714///
715/// // `tokens_method` calls `expected` here
716/// tokens_method!{
717/// expected!{foo "bar"}
718/// zip_shortest:
719/// (foo3 foo5 foo8 foo13 foo21)
720/// (bar3 bar5 bar8 bar13 bar21)
721/// (qux3 qux5 qux8 qux13 qux21)
722/// }
723///
724/// // `tokens_method` calls `expected` here
725/// tokens_method!{
726/// expected!{baz "qux"}
727/// zip_shortest:
728/// (foo3 foo5 foo8 foo13 foo21)
729/// (bar3 bar5 bar8 bar13 bar21)
730/// // this list is truncated because it's longer than the others
731/// (qux3 qux5 qux8 qux13 qux21 qux34 qux55)
732/// }
733///
734/// ```
735///
736/// <span id="lockstep_iteration"></span>
737/// `macro_rules!` requires lockstep iteration to be over lists of the exact same length:
738/// ```
739/// macro_rules! iteration {
740/// ([$($a:tt)*] [$($b:tt)*]) => {
741/// bar!( $(($a $b))* )
742/// }
743/// }
744/// ```
745/// while `zip_shortest` truncates to the shortest list,
746/// and `zip_longest` fills in `()` for the shorter lists.
747///
748///
749/// # `zip_longest`
750///
751/// Returns the token trees of every list iterated over in lockstep.
752///
753/// This returns as many token trees as the longest list,
754/// filling in `()` for the shorter lists.
755///
756/// This is similar to [lockstep iteration in macro_rules! macros](#lockstep_iteration),
757/// except that those require the lists to be the same length.
758///
759/// ### Example
760///
761/// ```rust
762/// use core_extensions::tokens_method;
763///
764/// fn main() {
765/// assert_eq!(baz(), "qux");
766/// }
767///
768/// macro_rules! expected {
769/// (
770/// $func:ident $value:literal
771/// ((0) (bar3) (qux3))
772/// ((1) (bar5) (qux5))
773/// ((2) (bar8) (qux8))
774/// ((3) (bar13) (qux13))
775/// ((4) (bar21) (qux21))
776/// ((5) () (qux34))
777/// ((6) () (qux55))
778/// ) => {
779/// fn $func() -> &'static str {
780/// $value
781/// }
782/// }
783/// }
784///
785/// // `tokens_method` calls `expected` here
786/// tokens_method!{
787/// expected!{baz "qux"}
788/// zip_longest:
789///
790/// // Unbounded ranges only generate as many tokens as the longest finite iterator
791/// range(0..)
792/// (bar3 bar5 bar8 bar13 bar21)
793/// (qux3 qux5 qux8 qux13 qux21 qux34 qux55)
794/// }
795///
796/// ```
797///
798/// # `iterate`
799///
800/// Nested iteration over multiple lists.
801///
802/// This can iterate over any amount of lists.
803///
804///
805/// ### Basic example
806///
807/// ```rust
808/// use core_extensions::tokens_method;
809///
810///
811/// fn main() {
812/// assert_eq!(single(), "111");
813/// assert_eq!(double(), "222");
814/// assert_eq!(triple(), "333");
815/// }
816///
817/// macro_rules! assertion_single{
818/// (
819/// $func:ident $expr:literal
820/// (foo bar baz)
821/// ) => {
822/// fn $func() -> &'static str {
823/// $expr
824/// }
825/// }
826/// }
827/// tokens_method!{
828/// assertion_single!{single "111"}
829/// iterate:
830/// (foo bar baz)
831/// }
832///
833///
834/// macro_rules! assertion_double{
835/// (
836/// $func:ident $expr:literal
837/// (
838/// { a } (foo bar baz)
839/// { b } (foo bar baz)
840/// { c } (foo bar baz)
841/// )
842/// ) => {
843/// fn $func() -> &'static str {
844/// $expr
845/// }
846/// }
847/// }
848/// tokens_method!{
849/// assertion_double!{double "222"}
850/// iterate:
851/// (a b c)
852/// (foo bar baz)
853/// }
854///
855///
856/// macro_rules! assertion_triple{
857/// (
858/// $func:ident $expr:literal
859/// (
860/// { 3 } (
861/// { a } (foo bar baz)
862/// { b } (foo bar baz)
863/// { c } (foo bar baz)
864/// )
865/// { 5 } (
866/// { a } (foo bar baz)
867/// { b } (foo bar baz)
868/// { c } (foo bar baz)
869/// )
870/// { 8 } (
871/// { a } (foo bar baz)
872/// { b } (foo bar baz)
873/// { c } (foo bar baz)
874/// )
875/// )
876/// ) => {
877/// fn $func() -> &'static str {
878/// $expr
879/// }
880/// }
881/// }
882/// tokens_method!{
883/// assertion_triple!{triple "333"}
884/// iterate:
885/// (3 5 8)
886/// (a b c)
887/// (foo bar baz)
888/// }
889///
890/// ```
891///
892/// ### Enum Example
893///
894/// This demonstrates a macro to declare an enum in which all the variants have the same fields.
895///
896/// ```rust
897///
898/// homogeneous_enum!{
899/// pub enum Foo { Bar, Baz, Qux }
900/// fields = { a, b, c }
901/// field_type = u32,
902/// }
903///
904/// fn main() {
905/// Foo::Bar{a: 3, b: 5, c: 8};
906/// Foo::Baz{a: 13, b: 21, c: 34};
907/// Foo::Qux{a: 55, b: 89, c: 144};
908/// }
909///
910/// #[macro_export]
911/// macro_rules! homogeneous_enum{
912/// (
913/// $(#[$attr:meta])*
914/// $vis:vis enum $enum_name:ident {
915/// $($variant:ident),* $(,)?
916/// }
917/// fields = { $($field:ident),* $(,)? }
918/// field_type = $field_ty:ty $(,)?
919/// ) => {
920/// $crate::__::tokens_method!{
921/// $crate::__priv_homogeneous_enum!{
922/// $(#[$attr])*
923/// $vis,
924/// $enum_name,
925/// $field_ty,
926/// }
927/// iterate:
928/// ($($variant)*)
929/// ($($field)*)
930/// }
931/// }
932/// }
933///
934///
935/// #[doc(hidden)]
936/// #[macro_export]
937/// macro_rules! __priv_homogeneous_enum{
938/// (
939/// $(#[$attr:meta])*
940/// $vis:vis,
941/// $enum_name:ident,
942/// $field_ty:ty,
943/// ($(
944/// {$variant:ident} ($($field_ident:ident)*)
945/// )*)
946/// ) => {
947/// $(#[$attr])*
948/// $vis enum $enum_name {
949/// $(
950/// $variant {
951/// $( $field_ident: $field_ty, )*
952/// },
953/// )*
954/// }
955/// }
956/// }
957///
958/// mod __ {
959/// pub use core_extensions::tokens_method;
960/// }
961/// ```
962///
963/// <span id="range-fn"></span>
964/// # `range` iterator function
965///
966/// Iterates over a range, can be bounded or unbounded.
967///
968/// If the range is unbounded, it must be constrained by some other iterator,
969/// otherwise causing a compile-time error.
970///
971/// This uses
972/// [the `<number>` syntax](./macro.gen_ident_range.html#number-syntax) from [`gen_ident_range`]
973/// for the range bounds.
974///
975/// ### Example
976///
977/// ```
978/// use core_extensions::tokens_method;
979///
980/// macro_rules! assertion {
981/// ((0 1 2 3 4)) => {}
982/// }
983///
984/// // `tokens_method` calls `assertion` here
985/// tokens_method!{assertion!{} iterate: range(0..5)}
986/// tokens_method!{assertion!{} iterate: range(..5)}
987/// tokens_method!{assertion!{} iterate: range(0..=4)}
988/// tokens_method!{assertion!{} iterate: range(..=4)}
989/// // You can use `count(....)` to count token trees, using the count as a range bound.
990/// tokens_method!{assertion!{} iterate: range(..count(_ _ _ _ _))}
991///
992/// macro_rules! assert_zip {
993/// (((0) (a)) ((1) (b)) ((2) (c)) ((3) ((d f g))) ((4) ({h i j}))) => {}
994/// }
995///
996/// // Both of these call `assert_zip` with the same tokens
997/// tokens_method!{
998/// assert_zip!{}
999/// zip_shortest:
1000/// range(0..)
1001/// (a b c (d f g) {h i j})
1002/// }
1003/// tokens_method!{
1004/// assert_zip!{}
1005/// zip_longest:
1006/// range(0..)
1007/// (a b c (d f g) {h i j})
1008/// }
1009///
1010/// # fn main() {}
1011///
1012/// ```
1013///
1014/// <span id="gen_ident_range-fn"></span>
1015/// # `gen_ident_range` iterator function
1016///
1017/// Generates identifiers by using the [`gen_ident_range`] macro.
1018///
1019/// The range can be unbounded so long as it's constrained by some other iterator,
1020///
1021/// ### Example
1022///
1023/// ```
1024/// use core_extensions::tokens_method;
1025///
1026/// macro_rules! assertion {
1027/// ((pre_1 pre_2 pre_3 pre_4 pre_5)) => {}
1028/// }
1029///
1030/// // `tokens_method` calls `assertion` here
1031/// tokens_method!{
1032/// assertion!{}
1033/// iterate: gen_ident_range(for pre_* in 1..=5)
1034/// }
1035/// tokens_method!{
1036/// assertion!{}
1037/// iterate: gen_ident_range(for pre_* in 1..6)
1038/// }
1039/// tokens_method!{
1040/// assertion!{}
1041/// iterate: gen_ident_range(for pre_* in 1..=count(_ _ _ _ _))
1042/// }
1043///
1044///
1045/// // One way unbounded ranges can be used
1046/// macro_rules! assertion_zipped {
1047/// (((a) (foo0)) ((b) (foo1)) ((c) (foo2))) => {}
1048/// }
1049///
1050/// // `tokens_method` calls `assertion_zipped` here
1051/// tokens_method!{
1052/// assertion_zipped!{}
1053/// zip_shortest:
1054/// (a b c)
1055/// gen_ident_range(for foo* in 0..)
1056/// }
1057///
1058/// # fn main() {}
1059///
1060/// ```
1061///
1062/// <span id="chain-fn"></span>
1063/// # `chain` iterator function
1064///
1065/// Concatenates multiple iterators.
1066///
1067/// The iterators can be unbounded so long as `chain` is constrained by some other iterator,
1068///
1069/// ### Example
1070///
1071/// ```
1072/// use core_extensions::tokens_method;
1073///
1074/// macro_rules! assertion {
1075/// ((a b c 0 1 2)) => {}
1076/// }
1077///
1078/// // `tokens_method` calls `assertion` here
1079/// tokens_method!{
1080/// assertion!{}
1081/// iterate: chain((a b c) range(0..=2))
1082/// }
1083///
1084///
1085/// macro_rules! assertion_zipped {
1086/// (((0) (a)) ((1) (b)) ((2) (10)) ((3) (11))) => {};
1087/// }
1088///
1089/// // One way unbounded ranges can be used.
1090/// // `tokens_method` calls `assertion_zipped` here
1091/// tokens_method!{
1092/// assertion_zipped!{}
1093/// zip_shortest:
1094/// range(0..=3)
1095/// chain((a b) range(10..))
1096/// }
1097///
1098/// # fn main() {}
1099///
1100/// ```
1101///
1102/// <span id="take-fn"></span>
1103/// # `take` iterator function
1104///
1105/// Takes some amount of elements from a possibly unbounded iterator.
1106///
1107/// ### Example
1108///
1109/// ```
1110/// use core_extensions::tokens_method;
1111///
1112/// macro_rules! assertion {
1113/// ((a b 0 1 2)) => {}
1114/// }
1115///
1116/// // `tokens_method` calls `assertion` here
1117/// tokens_method!{
1118/// assertion!{}
1119/// iterate:
1120/// take(5, chain((a b) range(0..10)))
1121/// }
1122///
1123/// tokens_method!{
1124/// assertion!{}
1125/// iterate:
1126/// take(count(_ _ _ _ _), chain((a b) range(0..)))
1127/// }
1128///
1129/// # fn main() {}
1130///
1131/// ```
1132///
1133/// <span id="skip-fn"></span>
1134/// # `skip` iterator function
1135///
1136/// Skips elements from a possibly unbounded iterator.
1137///
1138/// ### Example
1139///
1140/// ```
1141/// use core_extensions::tokens_method;
1142///
1143/// macro_rules! assertion {
1144/// ((f g 0 1 2)) => {}
1145/// }
1146///
1147/// // `tokens_method` calls `assertion` here
1148/// tokens_method!{
1149/// assertion!{}
1150/// iterate:
1151/// skip(5, chain((a b c d e f g) range(0..3)))
1152/// }
1153/// tokens_method!{
1154/// assertion!{}
1155/// iterate:
1156/// skip(count(_ _ _ _ _), chain((a b c d e f g) range(0..3)))
1157/// }
1158///
1159/// // passing an unbounded iterator to skip
1160/// tokens_method!{
1161/// assertion!{}
1162/// iterate:
1163/// take(5, skip(4, chain((b c d e f g) range(0..))))
1164/// }
1165///
1166/// # fn main() {}
1167///
1168/// ```
1169///
1170/// <span id="cycle-fn"></span>
1171/// # `cycle` iterator function
1172///
1173/// Takes a bounded iterator and repeats it infinitely.
1174///
1175/// ### Example
1176///
1177/// ```
1178/// use core_extensions::tokens_method;
1179///
1180/// macro_rules! assertion {
1181/// (
1182/// ((0) (a)) ((1) (b)) ((2) (c))
1183/// ((0) (d)) ((1) (e)) ((2) (f))
1184/// ((0) (g)) ((1) (h))
1185/// ) => {}
1186/// }
1187/// tokens_method!{
1188/// assertion!{}
1189/// zip_shortest:
1190/// cycle(range(0..3))
1191/// (a b c d e f g h)
1192/// }
1193///
1194/// # fn main() {}
1195///
1196/// ```
1197///
1198/// <span id="repeat-fn"></span>
1199/// # `repeat` iterator function
1200///
1201/// Repeats a bounded iterator some amount of times.
1202///
1203/// ### Example
1204///
1205/// ```
1206/// use core_extensions::tokens_method;
1207///
1208/// macro_rules! assertion_four_times {
1209/// ((0 1 2 0 1 2 0 1 2 0 1 2)) => {}
1210/// }
1211/// // `tokens_method` calls `assertion_four_times` here
1212/// tokens_method!{
1213/// assertion_four_times!{}
1214/// iterate:
1215/// repeat(4, range(0..=2))
1216/// }
1217///
1218///
1219/// macro_rules! assertion_zero_times {
1220/// (()) => {}
1221/// }
1222/// // `tokens_method` calls `assertion_zero_times` here
1223/// tokens_method!{
1224/// assertion_zero_times!{}
1225/// iterate:
1226/// repeat(0, range(0..=2))
1227/// }
1228///
1229/// # fn main() {}
1230///
1231/// ```
1232///
1233/// [`gen_ident_range`]: ./macro.gen_ident_range.html
1234#[cfg_attr(feature = "docsrs", doc(cfg(feature = "macro_utils")))]
1235pub use core_extensions_proc_macros::tokens_method;