Crabtime

https://docs.rs/crabtime/latest/
Admin
Crabtime is a Rust macro system inspired by Zig's comptime that provides a novel way to write macros...
Tokens:15,806
Snippets:200
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Crabtime Macro Options Example

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Example of compilation stats generated by #[crabtime::function]. Shows cache status, output directory, and macro options used.

```text
# Compilation Stats
Start: 13:17:09 (825)
Duration: 0.35 s
Cached: true
Output Dir: /Users/crabtime_user/my_project/target/debug/build/crabtime/macro_path
Macro Options: MacroOptions {
    cache: true,
    content_base_name: false,
}

```

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

### sum_combinations Example

Source: https://docs.rs/crabtime/latest/crabtime/fn.sum_combinations.html

Demonstrates the output of sum_combinations(4), showing all ordered combinations of positive integers that sum to 4 with at least two summands.

```rust
pub fn sum_combinations(_n: usize) -> Vec<Vec<usize>>
```

```text
[1, 1, 1, 1]
[1, 1, 2]
[1, 2, 1]
[2, 1, 1]
[1, 3]
[3, 1]
[2, 2]
```

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

### Crabtime function Macro Expansion Example

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Shows how `#[crabtime::function]` expands to a standard Rust function that generates output. This example demonstrates dynamic string formatting within the macro.

```rust
#[crabtime::function]
fn my_macro_expansion2() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        __output_buffer__.push_str(
            &format!("enum Position{{dim}} {{ {cons} }}\n")
        );
    }
}
my_macro_expansion2!();
# fn main() {}
```

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

### Generate TokenStream Output with Crabtime

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Functions can return a `proc_macro2::TokenStream` for generating code. This example uses inline dependencies for brevity; use `Cargo.toml`'s `[build-dependencies]` in real projects.

```rust
#[crabtime::function]
fn gen_positions6() -> proc_macro2::TokenStream {
    // Inline dependencies used for brevity.
    // You should use [build-dependencies] section in your Cargo.toml instead.
    #![dependency(proc_macro2 = "1")]
    #![dependency(syn = "2")]
    #![dependency(quote = "1")]
    use proc_macro2::Span;
    use quote::quote;

    let components = ["X", "Y", "Z", "W"];
    let defs = (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].iter().map(|t|
            syn::Ident::new(t, Span::call_site())
        );
        let ident = syn::Ident::new(&format!("Position{{dim}}"), Span::call_site());
        quote! {
            enum #ident {
                #(#cons),*
            }
        }
    }).collect::<Vec<_>>();
    quote! {
        #(#defs)*
    }
}
gen_positions6!();
```

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

### Generate Output by Returning a TokenStream

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Return a `proc_macro2::TokenStream` from the function for advanced code generation. This example uses inline dependencies for brevity; use `build-dependencies` in `Cargo.toml` for real projects.

```rust
#[crabtime::function]
fn gen_positions6() -> proc_macro2::TokenStream {
    // Inline dependencies used for brevity.
    // You should use [build-dependencies] section in your Cargo.toml instead.
    #![dependency(proc-macro2 = "1")]
    #![dependency(syn = "2")]
    #![dependency(quote = "1")]
    use proc_macro2::Span;
    use quote::quote;

    let components = ["X", "Y", "Z", "W"];
    let defs = (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].iter().map(|t|
            syn::Ident::new(t, Span::call_site())
        );
        let ident = syn::Ident::new(&format!("Position{dim}"), Span::call_site());
        quote! {
            enum #ident {
                #(#cons),*
            }
        }
    }).collect::<Vec<_>>();
    quote! {
        #(#defs)*
    }
}
gen_positions6!();
# fn main() {}
```

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

### Crabtime Macro Performance Statistics Example

Source: https://docs.rs/crabtime/latest/crabtime

This snippet represents the kind of compilation stats you might see when expanding a `#[crabtime::function]` macro in your IDE. It highlights performance evaluation details.

```text
compilation stats like:

```

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

### Crabtime Inter-Module Macro Expansion

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Illustrates how macros defined in one module can be used in another. This example shows a function macro `inter_module_macro` being defined and then called from a different module.

```rust
mod mod_a {
    #[crabtime::function]
    fn inter_module_macro() -> &str {
        "pub struct Generated;"
    }
    #[allow(clippy::single_component_path_imports)]
    pub(super) use inter_module_macro;
}

mod mod_b {
    super::mod_a::inter_module_macro!();
}

#[test]
fn inter_module_macro() {
    let _p = mod_b::Generated;
}
```

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

### Enabling Crabtime Macro Caching on Stable Rust

Source: https://docs.rs/crabtime/latest/index.html

This example shows how to enable caching for Crabtime macros on the stable Rust channel by using the `module` attribute. Caching improves performance by reusing previously generated projects.

```rust
#[crabtime::function(cache_key=my_key)]
#[module(my_crate::my_module)]
fn my_macro() {
    // ...
}
```

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

### Crabtime Output Macro with Interpolation

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Shows how the `crabtime::output!` macro handles string interpolation within its generated code. This example interpolates a variable containing branch definitions into an enum implementation.

```rust
#[crabtime::function]
fn interpolation_before_brace() {
    let is_a_branches = "A => true, B => false";
    crabtime::output! {
        enum E { A, B }
        impl E {
            fn is_a(&self) -> bool {
                match self {
                    {{is_a_branches}}
                }
            }
        }
    }
}
interpolation_before_brace!();
```

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

### Macro Cargo Configuration on Rust Stable Channel

Source: https://docs.rs/crabtime/latest/crabtime/index.html

When using the Rust stable channel, Crabtime requires manual specification of cargo configuration within macro blocks due to limitations in proc_macro_span stabilization. This example shows how to define edition, resolver, and dependencies.

```rust
#[crabtime::function]
fn my_macro() {
    // Do this only on Rust stable channel. On the unstable channel
    // use your Cargo.toml's [build-dependencies] section instead.
    #![edition(2024)]
    #![resolver(3)]
    #![dependency(anyhow = "1.0")]

    type Result<T> = anyhow::Result<T>;
    // ...
}
```

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

### Crabtime Macro Compilation Statistics Example

Source: https://docs.rs/crabtime/latest/index.html

This snippet represents the kind of compilation statistics that Crabtime can generate, which are visible when expanding a `#[crabtime::function]` usage in an IDE. It helps in understanding macro evaluation time.

```rust

```

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

### Direct String Formatting Equivalent

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Demonstrates how the `output!` macro's behavior can be replicated using direct string formatting and `push_str` to an output buffer. This clarifies the underlying mechanism.

```rust
#[crabtime::function]
fn my_macro_expansion3() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        __output_buffer__.push_str(
            &format!("enum Position{dim} {{ {cons} }}\n")
        );
    }
}
my_macro_expansion3!();

```

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

### println! Output Equivalent

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Shows the most basic equivalent of the `output!` macro's functionality using `println!` with a specific output prefix. This highlights the direct output generation.

```rust
#[crabtime::function]
fn my_macro_expansion4() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        println!("[OUTPUT] enum Position{dim} {{ ");
        println!("[OUTPUT]     {cons}");
        println!("[OUTPUT] }}");
    }
}
my_macro_expansion4!();

```

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

### Outputting via println! Macro

Source: https://docs.rs/crabtime/latest/crabtime

Shows the most basic form of output generation where each line of the generated code is printed using `println!` with an `[OUTPUT]` prefix, simulating direct console output.

```rust
#[crabtime::function]
fn my_macro_expansion4() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        println!("[OUTPUT] enum Position{{dim}} {{");
        println!("[OUTPUT]     {cons}");
        println!("[OUTPUT] }}");
    }
}
my_macro_expansion4!();

```

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

### Crabtime Output Macro Equivalent using println!

Source: https://docs.rs/crabtime/latest/index.html

Shows a further simplification of the Crabtime output mechanism, equivalent to using `println!` with a specific output prefix, illustrating the final output stage.

```Rust
#[crabtime::function]
fn my_macro_expansion4() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        println!("[OUTPUT] enum Position{dim} {{");
        println!("[OUTPUT]     {cons}");
        println!("[OUTPUT] }}");
    }
}
my_macro_expansion4!();

```

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

### Input by Using Supported Arguments

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Parametrize macros using supported argument types like `Vec<...>`,`&str`, `String`, and numbers. String arguments can be passed as literals or identifiers.

```rust
#[crabtime::function]
fn gen_positions7(name: String, components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions7!(Position, ["X", "Y", "Z", "W"]);
gen_positions7!(Color, ["R", "G", "B"]);
# fn main() {}
```

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

### Crabtime function Macro Expansion with println!

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Demonstrates an alternative expansion of `#[crabtime::function]` using `println!` for output. This highlights different methods for generating output within the macro.

```rust
#[crabtime::function]
fn my_macro_expansion4() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        println!("[OUTPUT] enum Position{{dim}} {{ ");
        println!("[OUTPUT]     {cons}");
        println!("[OUTPUT] }}");
    }
}
my_macro_expansion4!();
# fn main() {}
```

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

### Equivalent output_str! Syntax

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Presents an alternative syntax using `output_str!` which achieves the same result as the `output!` macro for generating Rust code. This is useful for IDE compatibility.

```rust
#[crabtime::function]
fn my_macro_expansion2(pattern!([$($components_arg:expr),*$(,)?]): _) {
    let components: Vec<String> = expand!(
        [$(crabtime::stringify_if_needed!($components_arg).to_string()),*]
    ).into_iter().collect();
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output_str! {
            enum Position{dim} {
                {cons}
            }
        }
    }
}
my_macro_expansion2!(["X", "Y", "Z", "W"]);

```

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

### Generate Output by Returning a String

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Return a string from the function, which will be used as the generated macro code. This is suitable for straightforward code generation.

```rust
#[crabtime::function]
fn gen_positions4(components: Vec<String>) -> String {
    (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].join(",");
        format!("enum Position{dim} {{ {cons} }}")
    }).collect::<Vec<_>>().join("\n")
}
gen_positions4!(["X", "Y", "Z", "W"]);
# fn main() {}
```

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

### Stdout Protocol Utilities for Prefixing Lines

Source: https://docs.rs/crabtime/latest/crabtime/index.html

These functions help in transforming multi-line strings by adding appropriate prefixes for Crabtime's stdout protocol. They are useful for ensuring correct formatting of debug logs, output code, warnings, and errors.

```rust
mod crabtime {
    fn prefix_lines_with(prefix: &str, input: &str) -> String {
        // Adds the given prefix to each line of the input string.
    }

    fn prefix_lines_with_output(input: &str) -> String {
        // Adds `[OUTPUT]` to each line of the input string.
    }

    fn prefix_lines_with_warning(input: &str) -> String {
        // Adds `[WARNING]` to each line of the input string.
    }

    fn prefix_lines_with_error(input: &str) -> String {
        // Adds `[ERROR]` to each line of the input string.
    }
}
```

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

### Crabtime output! Macro Mockup Definition

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Provides a mockup definition for the `output!` macro, intended to prevent IDE errors. The actual implementation is generated by Crabtime macros during compilation.

```rust
/// AVAILABLE ONLY WITHIN THE CRABTIME MACRO.
#[macro_export]
macro_rules! output {
    ($($ts:tt)*) => {};
}
```

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

### Crabtime Stdout Protocol Utilities

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Utility functions to prefix lines with specific protocols like [OUTPUT], [WARNING], or [ERROR]. Useful for manual control over macro output.

```rust
mod crabtime {
    fn prefix_lines_with(prefix: &str, input: &str) -> String {
        // Adds the given prefix to each line of the input string.
        # panic!()
    }

    fn prefix_lines_with_output(input: &str) -> String {
        // Adds `[OUTPUT]` to each line of the input string.
        # panic!()
    }

    fn prefix_lines_with_warning(input: &str) -> String {
        // Adds `[WARNING]` to each line of the input string.
        # panic!()
    }

    fn prefix_lines_with_error(input: &str) -> String {
        // Adds `[ERROR]` to each line of the input string.
        # panic!()
    }
}

```

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

### Equivalent using crabtime::output_str! Macro

Source: https://docs.rs/crabtime/latest/crabtime

Presents an alternative syntax using `crabtime::output_str!` which achieves the same result as `crabtime::output!` by directly writing a formatted string to the output buffer.

```rust
#[crabtime::function]
fn my_macro_expansion2(pattern!([$($components_arg:expr),*$(,)?]): _) {
    let components: Vec<String> = expand!(
        [$(crabtime::stringify_if_needed!($components_arg).to_string()),*]
    ).into_iter().collect();
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output_str! {
            "\n            enum Position{dim} {\n                {cons}\n            }\n        "}
    }
}
my_macro_expansion2!(["X", "Y", "Z", "W"]);

```

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

### Generate Enum Variants with TokenStream Input

Source: https://docs.rs/crabtime/latest/index.html

This snippet illustrates consuming macro input directly as a `TokenStream`. This approach offers maximum flexibility for complex macro logic, requiring manual conversion of the `TokenStream` to usable data.

```rust
#[crabtime::function]
fn gen_positions9(name: TokenStream) {
    #![dependency(proc-macro2 = "1")]
    let components = ["X", "Y", "Z", "W"];
    let name_str = name.to_string();
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name_str}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions9!(Position);
```

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

### Using output! Macro for Enum Generation

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Shows how the `output!` macro can be used within a `crabtime::function` to generate Rust code, specifically an enum with varying dimensions and components.

```rust
#[crabtime::function]
fn my_macro_expansion1(components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum Position{dim} {
                {cons}
            }
        }
    }
}
my_macro_expansion1!(["X", "Y", "Z", "W"]);

```

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

### Direct String Buffer Manipulation for Output

Source: https://docs.rs/crabtime/latest/crabtime

Demonstrates the fundamental way Crabtime generates output by directly appending formatted strings to an output buffer, equivalent to the `output!` macro's behavior.

```rust
#[crabtime::function]
fn my_macro_expansion3() {
    let components = ["X", "Y", "Z", "W"];
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        __output_buffer__.push_str(
            &format!("enum Position{{dim}} {{ {cons} }}\n")
        );
    }
}
my_macro_expansion3!();

```

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

### Generate TokenStream with Crabtime

Source: https://docs.rs/crabtime/latest/crabtime

Return a `proc_macro2::TokenStream` from a function to generate code. This method offers the most flexibility for complex code generation scenarios. Note the use of inline dependencies for brevity; use `Cargo.toml` for real projects.

```rust
#[crabtime::function]
fn gen_positions6() -> proc_macro2::TokenStream {
    // Inline dependencies used for brevity.
    // You should use [build-dependencies] section in your Cargo.toml instead.
    #![dependency(proc-macro2 = "1")]
    #![dependency(syn = "2")]
    #![dependency(quote = "1")]
    use proc_macro2::Span;
    use quote::quote;

    let components = ["X", "Y", "Z", "W"];
    let defs = (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].iter().map(|t|
            syn::Ident::new(t, Span::call_site())
        );
        let ident = syn::Ident::new(&format!("Position{{dim}}"), Span::call_site());
        quote! {
            enum #ident {
                #(#cons),*
            }
        }
    }).collect::<Vec<_>>();
    quote! {
        #(#defs)*
    }
}
gen_positions6!();
```

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

### Generate Enum Positions by Returning a String

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Functions can directly return a formatted string, which will be used as the generated macro code.

```rust
#[crabtime::function]
fn gen_positions4(components: Vec<String>) -> String {
    (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].join(",");
        format!("enum Position{{dim}} {{ {cons} }}")
    }).collect::<Vec<_>>().join("\n")
}
gen_positions4!(["X", "Y", "Z", "W"]);
```

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

### Using the output! Macro in Crabtime

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

The `output!` macro in Crabtime is a shortcut for writing to the output buffer using `format!`. It simplifies generating code snippets within your macro expansions.

```rust
crabtime::output! {
            enum Position{{dim}} {
                {{cons}}
            }
        }

```

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

### Accessing Workspace Path

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Demonstrates how to access the WORKSPACE_PATH variable within a Crabtime macro function. This path points to the root of your project.

```rust
#[crabtime::function]
fn check_paths() {
    println!("Workspace path: {}", crabtime::WORKSPACE_PATH);
}
check_paths!();

```

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

### Generated Main Function Structure

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Illustrates the internal structure of a temporary Rust project generated by the `crabtime::function` macro. This shows how user code is embedded and executed.

```rust
const SOURCE_CODE: &str = "..."; // Your code as a string.

mod crabtime {
    // Various utils described in this documentation.
}

fn main() {
    let mut __output_buffer__ = String::new();
    let result = {
        // Your code.
    };
    crabtime::push_as_str(&mut __output_buffer__, &result);
    println!("{}", crabtime::prefix_lines_with_output(&__output_buffer__));
}

```

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

### Generate Enum Positions with crabtime::output_str!

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Use `crabtime::output_str!` to immediately write strings to the code output buffer.

```rust
#[crabtime::function]
fn gen_positions5(components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output_str!("enum Position{dim} {{ {cons} }}")
    }
}
gen_positions5!(["X", "Y", "Z", "W"]);
```

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

### Output Macro Definition

Source: https://docs.rs/crabtime/latest/crabtime/macro.output.html

The `output!` macro is defined using `macro_rules!`. It is intended for internal use within the Crabtime macro system and accepts a variable number of tokens.

```rust
macro_rules! output {
    ($($ts:tt)*) => { ... };
}
```

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

### Define Macro with TokenStream Input

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Define a macro that accepts a TokenStream and generates enum variants. This approach is suitable when the macro needs to process raw tokens directly.

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

#[macro_use] extern crate crabtime;

#[crabtime::function]
fn gen_positions9(name: proc_macro2::TokenStream) {
    #![dependency(proc-macro2 = "1")]
    let components = ["X", "Y", "Z", "W"];
    let name_str = name.to_string();
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name_str}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions9!(Position);
# fn main() {}
```

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

### Generate Enum Variants with Patterns

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Utilize `pattern!` for more control over input structure, similar to `macro_rules!`. Use `expand!` to process the pattern input.

```Rust
// Please note that we need to type the pattern argument as `_` to make the
// code a valid Rust code.
#[crabtime::function]
fn gen_positions8(pattern!($name:ident, $components:tt): _) {
    let components = expand!($components);
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        // We don't need to use `expand!` here.
        let name = stringify!($name);
        crabtime::output! {
            enum {{name}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions8!(Position, ["X", "Y", "Z", "W"]);
gen_positions8!(Color, ["R", "G", "B"]);

```

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

### Crabtime Macros for Stdout Communication

Source: https://docs.rs/crabtime/latest/crabtime/index.html

These macros simplify printing prefixed lines to stdout, adhering to Crabtime's communication protocol. They are used for outputting code, warnings, and errors.

```rust
mod crabtime {
    macro_rules! output_str {
        // Outputs code by printing a line prefixed with `[OUTPUT]`.
    }

    macro_rules! warning {
        // On the nightly channel prints a compilation warning.
        // On the stable channel prints a log prefixed with `[WARNING]`.
    }

    macro_rules! error {
        // On the nightly channel prints a compilation error.
        // On the stable channel prints a log prefixed with `[ERROR]`.
    }
}
```

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

### Crabtime Macro for Function in Implementation Block

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Demonstrates the compilation of a function macro used within an `impl` block. The `fn_in_impl!` macro generates a method for the `Test` struct.

```rust
#[crabtime::function]
fn fn_in_impl() -> &str {
    "pub fn test(&self) {}"
}
struct Test;
impl Test {
    fn_in_impl!();
}
```

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

### Generate URLs with crabtime::output! and String Literals

Source: https://docs.rs/crabtime/latest/crabtime/index.html

When interpolating string literals, manually wrap or escape them within the `format!` macro to ensure correct inclusion of quotes in the generated code.

```rust
#[crabtime::function]
fn gen_urls(components: Vec<String>) {
    for (idx, path) in components.iter().enumerate() {
        let full_url = format!("\"{}\"", ["http://localhost:3000", path].join("/"));
        crabtime::output! {
            println!("{}", {{full_url}});
        }
    }
}

fn main() {
    gen_urls!(["home", "about", "contact"]);
}
```

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

### Generate Enum Variants with Supported Arguments

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Use `Vec`, `&str`, `String`, and numbers as direct arguments. String arguments can be literals or identifiers.

```Rust
#[crabtime::function]
fn gen_positions7(name: String, components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions7!(Position, ["X", "Y", "Z", "W"]);
gen_positions7!(Color, ["R", "G", "B"]);

```

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

### Using crabtime::output! Macro for Enum Generation

Source: https://docs.rs/crabtime/latest/crabtime

Shows how the `crabtime::output!` macro can be used within a macro expansion to generate Rust code, specifically an enum with dynamically determined dimensions and variants.

```rust
#[crabtime::function]
fn my_macro_expansion1(components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum Position{{dim}} {
                {{cons}}
            }
        }
    }
}
my_macro_expansion1!(["X", "Y", "Z", "W"]);

```

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

### Accessing Project Paths in Crabtime Macros

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Crabtime macros expose path variables for navigating your project structure. Use these within your macro definitions to access workspace, crate configuration, and call site file paths.

```rust
println!("Workspace path: {}", crabtime::WORKSPACE_PATH);

```

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

### Using `crabtime::expression` for Expression Contexts

Source: https://docs.rs/crabtime/latest/crabtime/index.html

When a macro's output needs to be used in an expression context, use `#[crabtime::expression]` to automatically handle the necessary wrapping. This avoids limitations with `macro_rules!`.

```rust
#[crabtime::expression]
fn gen_expr() {
    let output_num = 3;
    crabtime::output! {
        {{output_num}}
    }
}

fn test() {
    let x = gen_expr!();
}
```

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

### write_ln Macro Definition

Source: https://docs.rs/crabtime/latest/crabtime/macro.write_ln.html

This is the definition of the write_ln macro. It is designed to accept any number of tokens and has an empty implementation body, indicating its functionality is handled internally by the crabtime macro system.

```rust
macro_rules! write_ln {
    ($($ts:tt)*) => { ... };
}
```

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

### Crabtime Function Macro Usage

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Demonstrates the basic compilation check for the `crabtime::function` macro. This macro is used to define functions that can be expanded by Crabtime.

```rust
#[crabtime::function]
fn empty_def_compilation() {}
empty_def_compilation!();
```

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

### Generate Enum Variants with TokenStream Input

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Consume input directly as a `TokenStream` for advanced manipulation within the macro.

```Rust
#[crabtime::function]
fn gen_positions9(name: TokenStream) {
    #![dependency(proc-macro2 = "1")]
    let components = ["X", "Y", "Z", "W"];
    let name_str = name.to_string();
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name_str}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions9!(Position);

```

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

### CRATE_CONFIG_PATH Constant Definition

Source: https://docs.rs/crabtime/latest/crabtime/constant.CRATE_CONFIG_PATH.html

The CRATE_CONFIG_PATH constant is defined as a string literal. It is only available within the Crabtime macro context.

```rust
pub const CRATE_CONFIG_PATH: &str = "AVAILABLE ONLY WITHIN THE CRABTIME MACRO.";
```

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

### CALL_SITE_FILE_PATH Constant Definition

Source: https://docs.rs/crabtime/latest/crabtime/constant.CALL_SITE_FILE_PATH.html

The CALL_SITE_FILE_PATH constant indicates that it is only available within the crabtime macro.

```rust
pub const CALL_SITE_FILE_PATH: &str = "AVAILABLE ONLY WITHIN THE CRABTIME MACRO.";
```

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

### Enable Crabtime Caching with Module Attribute

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Configure Crabtime caching on the stable Rust channel by providing a `module` attribute to specify the cache location.

```Rust
#[crabtime::function(cache_key=my_key)]
#[module(my_crate::my_module)]
fn my_macro() {
    // ...
}

```

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

### Using Function-like Macros in Expression Contexts with Braces

Source: https://docs.rs/crabtime/latest/crabtime

When using a function-like macro defined with `#[crabtime::function]` in an expression context, wrap the macro call in extra braces `{}`. This is a workaround due to `macro_rules!` limitations.

```Rust
#[crabtime::function]
fn gen_expr() {
    let output_num = 3;
    crabtime::output! {
        {{output_num}}
    }
}

fn test() {
    // `let x = gen_expr!{};` would not work here!
    let x = { gen_expr!{} };
}

```

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

### Generate Enum Positions with crabtime::output_str!

Source: https://docs.rs/crabtime/latest/crabtime

Use `crabtime::output_str!` to immediately write strings to the code output buffer. This macro is suitable for direct, uninterpolated string output.

```rust
#[crabtime::function]
fn gen_positions5(components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output_str!("enum Position{{dim}} {{ {cons} }}")
    }
}
gen_positions5!(["X", "Y", "Z", "W"]);
```

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

### Generating Enum Structures with crabtime::quote!

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Generates enum definitions and returns them as strings. This allows for storing and reusing the generated code across multiple calls.

```rust
#[crabtime::function]
fn gen_positions3(components: Vec<String>) -> String {
    let structs = (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].join(",");
        crabtime::quote! {
            enum Position{{dim}} {
                {{cons}}
            }
        }
    }).collect::<Vec<String>>();
    structs.join("\n\n")
}
```

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

### Defining Function-Like Macros with `crabtime::function`

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Define function-like macros by annotating a function with `#[crabtime::function]`. Crabtime replaces the function with a macro definition. The macro can be called to execute the function at build time, using its output as generated Rust code. Use `#[macro_export]` to export the macro.

```rust
// Replaces the function definition with a `gen_positions1!` macro.
#[crabtime::function]
#[macro_export] // <- This is how you export it!
fn gen_positions1() -> &str {
    "
    enum Position1 { X }
    enum Position2 { X, Y }
    enum Position3 { X, Y, Z }
    enum Position4 { X, Y, Z, W }
    "
}

// Compiles and evaluates the gen_positions1 function at build-time and
// uses its output as the new code source.
gen_positions1!();
```

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

### Generate Enum Positions with crabtime::output!

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Use `crabtime::output!` for direct code generation with space-aware variable interpolation. It preserves single braces and uses double braces for interpolation.

```rust
#[crabtime::function]
fn gen_positions2(components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum Position{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions2!(["X", "Y", "Z", "W"]);
```

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

### Generate Enum Positions with crabtime::quote!

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Use `crabtime::quote!` to return generated code as a `String`. This allows storing and reusing the code in subsequent macro calls.

```rust
#[crabtime::function]
fn gen_positions3(components: Vec<String>) -> String {
    let structs = (1 ..= components.len()).map(|dim| {
        let cons = components[0..dim].join(",");
        crabtime::quote! {
            enum Position{{dim}} {
                {{cons}}
            }
        }
    }).collect::<Vec<String>>();
    structs.join("\n")
}
gen_positions3!(["X", "Y", "Z", "W"]);
```

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

### Defining a Function-like Macro with #[crabtime::function]

Source: https://docs.rs/crabtime/latest/crabtime

Define a function-like macro using the `#[crabtime::function]` attribute. The annotated function is replaced by a macro definition that can be called to execute the function at build time and use its output as generated Rust code. Use `#[macro_export]` to export the macro.

```Rust
// Replaces the function definition with a `gen_positions1!` macro.
#[crabtime::function]
#[macro_export] // <- This is how you export it!
fn gen_positions1() -> &str {
    "\n    enum Position1 { X }
    enum Position2 { X, Y }
    enum Position3 { X, Y, Z }
    enum Position4 { X, Y, Z, W }
    "
}

// Compiles and evaluates the gen_positions1 function at build-time and
// uses its output as the new code source.
gen_positions1!();

```

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

### WORKSPACE_PATH Constant Definition

Source: https://docs.rs/crabtime/latest/crabtime/constant.WORKSPACE_PATH.html

Defines the WORKSPACE_PATH constant. This constant is only accessible within Crabtime macros.

```rust
pub const WORKSPACE_PATH: &str = "AVAILABLE ONLY WITHIN THE CRABTIME MACRO.";
```

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

### Crabtime Macro Execution Flow

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

The content of a `crabtime::function` is pasted into a temporary Rust project's main function for compilation and execution. Its stdout becomes the generated Rust code.

```rust
const SOURCE_CODE: &str = "..."; // Your code as a string.

# mod phantom_for_crabtime_name_crash_resolution {
mod crabtime {
    // Various utils described in this documentation.
    # pub fn push_as_str(str: &mut String, result: &()) {}
    # pub fn prefix_lines_with_output(input: &str) -> String { String::new() }
}

fn main() {
    let mut __output_buffer__ = String::new();
    let result = {
        // Your code.
    };
    crabtime::push_as_str(&mut __output_buffer__, &result);
    println!("{}", crabtime::prefix_lines_with_output(&__output_buffer__));
}
# }
# fn main() {}

```

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

### One-shot Compile-Time Evaluation

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Use `crabtime::eval!` for straightforward compile-time evaluation of an expression, pasting its output as new code. This is the simplest use case for Crabtime.

```rust
const MY_NUM: usize = crabtime::eval! {
    (std::f32::consts::PI.sqrt() * 10.0).round() as usize
};
```

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

### Generate Enum Variants with Supported Arguments

Source: https://docs.rs/crabtime/latest/index.html

This snippet demonstrates using common Rust types like String and Vec<String> as direct arguments to a Crabtime macro. The macro automatically translates these into patterns for generating enum variants.

```rust
#[crabtime::function]
fn gen_positions7(name: String, components: Vec<String>) {
    for dim in 1 ..= components.len() {
        let cons = components[0..dim].join(",");
        crabtime::output! {
            enum {{name}}{{dim}} {
                {{cons}}
            }
        }
    }
}
gen_positions7!(Position, ["X", "Y", "Z", "W"]);
gen_positions7!(Color, ["R", "G", "B"]);
```

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

### One-shot Evaluation with crabtime::eval!

Source: https://docs.rs/crabtime/latest/crabtime

Use `crabtime::eval!` to evaluate an expression at compile time and paste its result as new code. This is the simplest use case for Crabtime.

```Rust
const MY_NUM: usize = crabtime::eval! {
    (std::f32::consts::PI.sqrt() * 10.0).round() as usize
};

```

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

### Function Attribute Macro

Source: https://docs.rs/crabtime/latest/crabtime/attr.function.html

This is the basic syntax for applying the #[function] attribute macro. It is used to mark a function for special processing by the crabtime framework.

```Rust
#[function]
```

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

### crabtime quote Macro Definition

Source: https://docs.rs/crabtime/latest/crabtime/macro.quote.html

This snippet shows the definition of the `quote` macro. It is available only within the crabtime macro environment and is used for token manipulation.

```rust
macro_rules! quote {
    ($($ts:tt)*) => { ... };
}
```

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

### Manual Braced Wrapping for Expression Contexts

Source: https://docs.rs/crabtime/latest/crabtime/index.html

Alternatively, manually wrap macro calls in extra braces `{}` when using `#[crabtime::function]` in expression contexts. This allows the macro to be used in both expression and statement contexts.

```rust
#[crabtime::function]
fn gen_expr() {
    let output_num = 3;
    crabtime::output! {
        {{output_num}}
    }
}

fn test() {
    // `let x = gen_expr!{};` would not work here!
    let x = { gen_expr!{} };
}
```

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

### Define Macro with Pattern Argument

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Define a macro that accepts a pattern argument and generates enum variants based on component count. This is useful for creating enumerated types with varying dimensions.

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

#[macro_use] extern crate crabtime;

//! // Please note that we need to type the pattern argument as `_` to make the
//! // code a valid Rust code.
//! #[crabtime::function]
//! fn gen_positions8(pattern!($name:ident, $components:tt): _) {
//!     let components = expand!($components);
//!     for dim in 1 ..= components.len() {
//!         let cons = components[0..dim].join(",");
//!         // We don't need to use `expand!` here.
//!         let name = stringify!($name);
//!         crabtime::output! {
//!             enum {{name}}{{dim}} {
//!                 {{cons}}
//!             }
//!         }
//!     }
//! }
//! gen_positions8!(Position, ["X", "Y", "Z", "W"]);
//! gen_positions8!(Color, ["R", "G", "B"]);
//! # fn main() {}
```

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

### crabtime eval macro definition

Source: https://docs.rs/crabtime/latest/crabtime/macro.eval.html

Defines the `eval` macro. It accepts any number of tokens and expands to an ellipsis, indicating a placeholder for actual implementation logic.

```rust
macro_rules! eval {
    ($($ts:tt)*) => { ... };
}
```

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

### eval_function Attribute Macro Usage

Source: https://docs.rs/crabtime/latest/crabtime/attr.eval_function.html

This is the basic syntax for applying the eval_function attribute macro. It is used to mark functions for evaluation.

```rust
#[eval_function]
```

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

### Generating Expressions with #[crabtime::expression]

Source: https://docs.rs/crabtime/latest/crabtime

Use `#[crabtime::expression]` to define macros that generate Rust code suitable for expression contexts. This attribute handles the necessary wrapping for using the macro's output in expressions.

```Rust
#[crabtime::expression]
fn gen_expr() {
    let output_num = 3;
    crabtime::output! {
        {{output_num}}
    }
}

fn test() {
    let x = gen_expr!();
}

```

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

### Crabtime Quote Macro Definition

Source: https://docs.rs/crabtime/latest/src/crabtime/lib.rs.html

Defines the `quote!` macro, which is available only within the Crabtime macro environment. It is used for string literal generation.

```rust
#[macro_export]
macro_rules! quote {
    ($($ts:tt)*) => { String::new() };
}
```
Tokens:
Raw