Crate manyhow

Expand description

Proc macro anyhow, a combination of ideas from anyhow and proc-macro-error to improve proc macro development, especially focused on the error handling.

§Motivation

Error handling in proc-macros is unideal, as the top level functions of proc-macros can only return TokenStreams both in success and failure case. This means that I often write code like this, moving the actual implementation in a separate function to be able to use the ergonomic rust error handling with e.g., ?.

use proc_macro2::TokenStream as TokenStream2;

#[proc_macro]
pub fn my_macro(input: TokenStream) -> TokenStream {
    match actual_implementation(input.into()) {
        Ok(output) => output,
        Err(error) => error.into_compile_error(),
    }
    .into()
}

fn actual_implementation(input: TokenStream2) -> syn::Result<TokenStream2> {
    // ..
}

§Using the `#[manyhow]` macro

To activate the error handling, just add #[manyhow] above any proc-macro implementation, reducing the above example to:

use manyhow::manyhow;
use proc_macro2::TokenStream as TokenStream2;

#[manyhow]
#[proc_macro]
// You can also merge the two attributes: #[manyhow(proc_macro)]
fn my_macro(input: TokenStream2) -> syn::Result<TokenStream2> {
    // ..
}

// On top of the TokenStreams any type that implements [`Parse`] is supported
#[manyhow(proc_macro_derive(MyMacro))]
#[proc_macro]
// The output can also be anything that implements `quote::ToTokens`
fn my_derive_macro(input: syn::DeriveInput) -> manyhow::Result<syn::ItemImpl> {
    // ..
}

See Without macros to see what this expands to under the hood.

You can also use the #[manyhow] attributes on a use statement, useful when moving your proc-macro implementations in separate modules.

use manyhow::manyhow;

mod module {
    use proc_macro2::TokenStream as TokenStream2;

    pub fn my_macro(input: TokenStream2) -> syn::Result<TokenStream2> {
        // ..
    }
}

#[manyhow]
#[proc_macro]
// You can also merge the two attributes: #[manyhow(proc_macro)]
pub use module::my_macro;

A proc macro function marked as #[manyhow] can take and return any TokenStream, and can also return Result<TokenStream, E> where E implements ToTokensError. As additional parameters a dummy and/or emitter can be specified.

The manyhow attribute takes optional flags to configure its behavior.

When used for proc_macro and proc_macro_attribute, #[manyhow(input_as_dummy, ...)] will take the input of a function like proc_macro to initialize the [dummy &mut TokenStream](# dummy-mut-tokenstream) while #[manyhow(item_as_dummy, ...)] on proc_macro_attribute will initialize the dummy with the annotated item.

You can merge the #[proc_macro*] attribute inside the manyhow flags e.g., #[manyhow(proc_macro)] or #[manyhow(proc_macro_derive(SomeTrait, ...))].

The #[manyhow(impl_fn, ...)] flag will put the actual macro implementation in a separate function. Making it available for e.g., unit testing with proc_macro_utils::assert_expansion!.

#[manyhow(impl_fn)]
#[proc_macro]
pub fn actual_macro(input: TokenStream2) -> TokenStream2 {
    // ...
}
// would roughly expand to
#[proc_macro]
pub fn actual_macro(input: TokenStream) -> TokenStream {
    actual_macro_impl(input.into()).into()
}
fn actual_macro_impl(input: TokenStream2) -> TokenStream2 {
    // ...
}

§Without macros

manyhow can be used without proc macros, and they can be disabled by adding manyhow with default-features=false.

The usage is more or less the same, though with some added boilerplate from needing to invoke one of function() (function!), attribute() (attribute!) or derive() (derive!) directly. For each version there exists a function and a macro_rules macro, while the function only supports proc_macro::TokenStream and proc_macro2::TokenStream, the macro versions also support any type that implements Parse and ToTokens respectively.

While the examples use closures, functions can be passed in as well. The above example would then change to:

use proc_macro2::TokenStream as TokenStream2;

#[proc_macro]
pub fn my_macro(input: TokenStream) -> TokenStream {
    manyhow::function(
        input,
        false,
        |input: TokenStream2| -> syn::Result<TokenStream2> {
            // ..
        },
    )
    // Or
    manyhow::function!(
        input,
        |input: syn::DeriveInput| -> manyhow::Result<syn::ItemImpl> {
            // ..
        },
    )
}

Emitter and dummy TokenStream can also be used. function() (function!) and attribute() (attribute!) take an additional boolean parameter controlling whether the input/item will be used as initial dummy.

§`emitter: &mut Emitter`

*MacroHandlers (the traits defining what closures/functions can be used with manyhow) can take a mutable reference to an Emitter. This allows collecting errors, but not fail immediately.

Emitter::into_result can be used to return if an Emitter contains any values.

use manyhow::{manyhow, Emitter, ErrorMessage};
use proc_macro2::TokenStream as TokenStream2;

#[manyhow]
#[proc_macro]
fn my_macro(input: TokenStream2, emitter: &mut Emitter) -> manyhow::Result<TokenStream2> {
    // ..
    emitter.emit(ErrorMessage::call_site("A fun error!"));
    emitter.into_result()?;
    // ..
}

§`dummy: &mut TokenStream`

*MacroHandlers can also take a mutable reference to a TokenStream, to enable emitting some dummy code to be used in case the macro errors.

This allows either appending tokens e.g., with ToTokens::to_tokens or directly setting the dummy code e.g., *dummy = quote!{some tokens}.

§Crate features

macros default Enables #[manyhow] attribute macro.
syn/syn2 default Enables errors for syn 2.x.
syn1 Enables errors for syn 1.x.
darling Enables errors for darling.

Macros§

attribute: Handles proc_macro_attribute implementation
bail: Exit by returning error, matching anyhow::bail!.
derive: Handles proc_macro_derive implementation.
emit: Push an error to an emitter.
ensure: Return early with an error, if a condition is not satisfied, matching anyhow::ensure!.
error_message: Creates an ErrorMessage, comparable to the anyhow! macro
function: Handles function like proc_macro implementation
span_range: Get a Range<Span> from a type that either implements SpanRanged or ToTokens (NOT both).

Structs§

Emitter: Allows emitting errors without returning.
Error: This crates Error type
ErrorMessage: A single error message
SilentError: Error that does not expand to any compile_error! and therefor does not cause compilation to fail.

Traits§

AnyTokenStream: Marker trait for proc_macro::TokenStream and proc_macro2::TokenStream
Attachment: Exposes ErrorMessage::attachment as a trait to allow ResultExt::attachment.
AttributeMacroHandler: Input of an attribute proc-macro
DeriveMacroHandler: Input of a derive proc-macro
FunctionMacroHandler: Input of a function proc-macro
JoinToTokensError: Allows to call .join(..) on any impl ToTokensError
MacroOutput: Output of a macro handler.
ResultExt: Some utilities on Result<T, impl ToTokensError>
SpanRanged: Returns the Range<Span> from the start to the end of multi-token structures.
ToTokensError: Error that can be converted to a TokenStream required to be used with MacroOutput

Functions§

attribute: Handles proc_macro_attribute implementation
derive: Handles proc_macro_derive implementation.
function: Handles function like proc_macro implementation
to_tokens_span_range: Implementation of SpanRangedfor T:ToTokens

Type Aliases§

Result: An alias for Result suited for use with this crate

Attribute Macros§

manyhowmacros: Attribute macro to remove boilerplate from proc macro entry points.

Crate manyhowCopy item path