Attribute Macro inline_proc::inline_proc

#[inline_proc]

Write an inline procedural macro.

This attribute must go on a module, and that module’s name must be unique in the entire crate.

Metadata

The module’s first item must be an invocation of a metadata::{format}! macro, where {format} is the chosen format to write the metadata in. Currently we support JSON and RON, feature-gated with the json and ron features respectively. In these examples we will use RON because it is shorter and clearer.

Unfortunately TOML can’t be used for this since it is whitespace-sensitive and Rust’s lexer strips out all whitespace. Additionally, the proc_macro_span feature is unstable so we can’t even reconstruct the whitespace.

Metadata Options

use inline_proc::inline_proc;

#[inline_proc]
mod metadata_options {
    metadata::ron!(
        // The path to your cargo executable. By default it uses the same one as the one used
        // to compile the proc macro (the $CARGO env variable).
        cargo: "cargo",

        // Whether to pass `--color=always` to Cargo; otherwise the lines printed by Cargo will
        // not appear in color. Default is true.
        color: true,

        // Whether to check the code with Clippy. Default is false.
        clippy: true,

        // The edition to use. Default is 2015 edition.
        edition: "2021",

        // The dependencies of the proc macro. This is in the same format as Cargo.toml's
        // `[dependencies]` section.
        dependencies: {
            "proc-macro2": "1",
            "syn": ( version: "1", features: ["full"] ),
        },

        // The path to use for the `inline_proc` crate inside non-exported macros. Defaults to
        // `::inline_proc`. Use this if you have renamed the crate.
        inline_proc_path: "::inline_proc",

        // The macros exported by this module.
        exports: (
            // The bang macros exported by this module.
            bang_macros: {
                // This is a map of the external macro names to paths to the macro functions.
                "my_nice_macro": "my_nice_macro",
                // You can use this form to export the macros. See the crate root for an
                // explanation of how this works.
                "my_public_macro": ( function: "my_nice_macro", export: true ),
            },
            // The derive macros exported by this module.
            derives: {
                "MyDeriveMacro": "my_derive_macro",
            },
            // The attribute macros exported by this module.
            attributes: {
                "my_attribute_macro": "my_attribute_macro",
            },
        )
    );

    use proc_macro::TokenStream;

    // These functions must have a visibility of pub(super) or higher.

    // Bang macros take one token stream and return one token stream.
    pub fn my_nice_macro(input: TokenStream) -> TokenStream {
        input
    }

    // Derive macros take one token stream and return one token stream. Unlike other macros
    // the original token stream is not destroyed.
    pub fn my_derive_macro(_item: TokenStream) -> TokenStream {
        TokenStream::new()
    }

    // Attribute macros take two token streams; the attribute parameters and the item. On a
    // regular attribute macro, it looks like this:
    //
    // #[my_attribute_macro(/* attribute parameters */)]
    // struct Whatever; // <-- item
    //
    // And on an inline attribute macro it looks like this:
    //
    // #[inline_attr[my_attribute_macro(/* attribute parameters */)]]
    // struct Whatever; // <-- item
    pub fn my_attribute_macro(_attr: TokenStream, item: TokenStream) -> TokenStream {
        item
    }
}

Output

This macro generates a macro_rules! macro for each macro listed in exports. This macro can be used like so:

// A bang macro
my_bang_macro!(input tokens);
// A derive macro
MyDeriveMacro!(item tokens);
// An attribute macro
my_attribute_macro!((attribute parameters) item tokens);

However for derive macros and attribute macros it is recommended to use the InlineDerive and #[inline_attr] macros instead.