Crate macro_magic

Macro Magic 🪄

Overview

This crate provides an #[export_tokens] attribute macro, and a number of companion macros, most prominently #[import_tokens_proc] and #[import_tokens_attr], which, when used in tandem with #[export_tokens], allow you to create regular and attribute proc macros in which you can import and make use of the tokens of external/foreign items marked with #[export_tokens] in other modules, files, and even in other crates merely by referring to them by name/path.

Among other things, the patterns introduced by macro_magic can be used to implement safe and efficient exportation and importation of item tokens within the same file, and even across file and crate boundaries.

Stability

macro_magic is designed to work with stable Rust, and is fully no_std compatible (in fact, there is a unit test to ensure everything is no_std safe).

Limitations

One thing that macro_magic doesn’t provide is the ability to build up state information across multiple macro invocations, however this problem can be tackled effectively using the outer macro pattern. There is also my (deprecated but functional) macro_state crate, which relies on some incidental features of the rust compiler that could be removed in the future.

Note that the transition from 0.1.7 to 0.2.0 of macro_magic removed and/or re-wrote a number of features that relied on a non-future-proof behavior of writing/reading files from the OUT_DIR. Versions of macro_magic >= 0.2.0 are completely future-proof and safe, however features that provided the ability to enumerate all the #[export_tokens] calls in a namespace have been removed. The proper way to do this is with the outer macro pattern, mentioned above.

Modules

• core
  Contains the internal code behind the macro_magic macros in a re-usable form, in case you need to design new macros that utilize some of the internal functionality of macro_magic.

Macros

• export_tokens_alias
  Creates an attribute proc macro that is an alias for #[export_tokens].
• forward_tokens
  “Forwards” the tokens of the specified exported item (specified by path as the first arg) to the specified proc or macro_rules! macro (specified by path as the second arg).
• import_tokens
  Allows you to import the tokens of an external item marked with #[export_tokens] whose path is already known at compile-time without having to do any additional parsing.

Attribute Macros

• export_tokens
  Can be applied to any [syn::Item]-compatible item. Doing so will make the tokens for this item available for import by the other macros in this crate.
• import_tokens_attr
  Can be attached to an attribute proc macro function, causing it to receive the tokens for the external item referred to by the path provided as the attr / first argument to the attribute macro.
• import_tokens_proc
  An attribute macro that can be attached to a proc macro function definition that will cause it to receive the tokens of the external item referred to by its argument as input to your proc macro.
• use_attr
  Can be used to properly import and re-export attribute macros that were created using import_tokens_attr.
• use_proc
  Can be used to properly import and re-export proc macros that were created using import_tokens_proc.