Bug: 152069661

Clone this repo:
  1. 73c886f Update TEST_MAPPING am: d31c5122b4 am: 4484502971 am: b273e2b9db by David LeGare · 2 years ago android13-d2-release android13-d3-s1-release android13-d4-release android13-d4-s1-release android13-d4-s2-release android13-dev android13-frc-odp-release android13-mainline-go-adservices-release android13-qpr1-release android13-qpr1-s1-release android13-qpr1-s2-release android13-qpr1-s3-release android13-qpr1-s4-release android13-qpr1-s5-release android13-qpr1-s6-release android13-qpr1-s7-release android13-qpr1-s8-release android13-qpr2-b-s1-release android13-qpr2-release android13-qpr2-s1-release android13-qpr2-s10-release android13-qpr2-s11-release android13-qpr2-s12-release android13-qpr2-s2-release android13-qpr2-s3-release android13-qpr2-s5-release android13-qpr2-s6-release android13-qpr2-s7-release android13-qpr2-s8-release android13-qpr2-s9-release android13-qpr3-c-s1-release android13-qpr3-c-s10-release android13-qpr3-c-s11-release android13-qpr3-c-s12-release android13-qpr3-c-s2-release android13-qpr3-c-s3-release android13-qpr3-c-s4-release android13-qpr3-c-s5-release android13-qpr3-c-s6-release android13-qpr3-c-s7-release android13-qpr3-c-s8-release android13-qpr3-release android13-qpr3-s1-release android13-qpr3-s10-release android13-qpr3-s11-release android13-qpr3-s12-release android13-qpr3-s13-release android13-qpr3-s14-release android13-qpr3-s2-release android13-qpr3-s3-release android13-qpr3-s4-release android13-qpr3-s5-release android13-qpr3-s6-release android13-qpr3-s7-release android13-qpr3-s8-release android13-qpr3-s9-release main main-16k main-16k-with-phones master aml_go_ads_330913000 aml_go_ads_330915000 aml_go_ads_330915100 aml_go_odp_330912000 android-13.0.0_r16 android-13.0.0_r17 android-13.0.0_r18 android-13.0.0_r19 android-13.0.0_r20 android-13.0.0_r21 android-13.0.0_r22 android-13.0.0_r23 android-13.0.0_r24 android-13.0.0_r27 android-13.0.0_r28 android-13.0.0_r29 android-13.0.0_r30 android-13.0.0_r32 android-13.0.0_r33 android-13.0.0_r34 android-13.0.0_r35 android-13.0.0_r36 android-13.0.0_r37 android-13.0.0_r38 android-13.0.0_r39 android-13.0.0_r40 android-13.0.0_r41 android-13.0.0_r42 android-13.0.0_r43 android-13.0.0_r44 android-13.0.0_r45 android-13.0.0_r46 android-13.0.0_r47 android-13.0.0_r48 android-13.0.0_r49 android-13.0.0_r50 android-13.0.0_r51 android-13.0.0_r52 android-13.0.0_r53 android-13.0.0_r54 android-13.0.0_r55 android-13.0.0_r56 android-13.0.0_r57 android-13.0.0_r58 android-13.0.0_r59 android-13.0.0_r60 android-13.0.0_r61 android-13.0.0_r62 android-13.0.0_r63 android-13.0.0_r64 android-13.0.0_r65 android-13.0.0_r66 android-13.0.0_r67 android-13.0.0_r68 android-13.0.0_r69 android-13.0.0_r70 android-13.0.0_r71 android-13.0.0_r72 android-13.0.0_r73 android-13.0.0_r74 android-13.0.0_r75 android-13.0.0_r76 android-13.0.0_r77 android-13.0.0_r78 android-13.0.0_r79 android-13.0.0_r80 android-13.0.0_r81 android-13.0.0_r82 android-13.0.0_r83 t_frc_ase_330444010 t_frc_odp_330442000 t_frc_odp_330442040
  2. b273e2b Update TEST_MAPPING am: d31c5122b4 am: 4484502971 by David LeGare · 2 years ago
  3. 4484502 Update TEST_MAPPING am: d31c5122b4 by David LeGare · 2 years ago
  4. d31c512 Update TEST_MAPPING by David LeGare · 2 years ago
  5. ae7efce Merge "Refresh Android.bp, cargo2android.json, TEST_MAPPING." am: 697f23a697 am: bc0555c8b7 am: 133ad4c384 am: 32e7fda721 by Joel Galenson · 2 years, 3 months ago

Procedural macros in expression position

Since Rust 1.30, the language supports user-defined function-like procedural macros. However these can only be invoked in item position, not in statements or expressions.

This crate implements an alternative type of procedural macro that can be invoked in statement or expression position.

This approach works with any Rust version 1.31+.

Defining procedural macros

Two crates are required to define a procedural macro.

The implementation crate

This crate must contain nothing but procedural macros. Private helper functions and private modules are fine but nothing can be public.

» example of an implementation crate

Just like you would use a #[proc_macro] attribute to define a natively supported procedural macro, use proc-macro-hack's #[proc_macro_hack] attribute to define a procedural macro that works in expression position. The function signature is the same as for ordinary function-like procedural macros.

use proc_macro::TokenStream;
use proc_macro_hack::proc_macro_hack;
use quote::quote;
use syn::{parse_macro_input, Expr};

#[proc_macro_hack]
pub fn add_one(input: TokenStream) -> TokenStream {
    let expr = parse_macro_input!(input as Expr);
    TokenStream::from(quote! {
        1 + (#expr)
    })
}

The declaration crate

This crate is allowed to contain other public things if you need, for example traits or functions or ordinary macros.

» example of a declaration crate

Within the declaration crate there needs to be a re-export of your procedural macro from the implementation crate. The re-export also carries a #[proc_macro_hack] attribute.

use proc_macro_hack::proc_macro_hack;

/// Add one to an expression.
///
/// (Documentation goes here on the re-export, not in the other crate.)
#[proc_macro_hack]
pub use demo_hack_impl::add_one;

Both crates depend on proc-macro-hack:

[dependencies]
proc-macro-hack = "0.5"

Additionally, your implementation crate (but not your declaration crate) is a proc macro crate:

[lib]
proc-macro = true

Using procedural macros

Users of your crate depend on your declaration crate (not your implementation crate), then use your procedural macros as usual.

» example of a downstream crate

use demo_hack::add_one;

fn main() {
    let two = 2;
    let nine = add_one!(two) + add_one!(2 + 3);
    println!("nine = {}", nine);
}

Limitations

  • Only proc macros in expression position are supported. Proc macros in pattern position (#20) are not supported.

  • By default, nested invocations are not supported i.e. the code emitted by a proc-macro-hack macro invocation cannot contain recursive calls to the same proc-macro-hack macro nor calls to any other proc-macro-hack macros. Use proc-macro-nested if you require support for nested invocations.

  • By default, hygiene is structured such that the expanded code can‘t refer to local variables other than those passed by name somewhere in the macro input. If your macro must refer to local variables that don’t get named in the macro input, use #[proc_macro_hack(fake_call_site)] on the re-export in your declaration crate. Most macros won't need this.

  • On compilers that are new enough to natively support proc macros in expression position, proc-macro-hack does not automatically use that support, since the hygiene can be subtly different between the two implementations. To opt in to compiling your macro to native #[proc_macro] on sufficiently new compilers, use #[proc_macro_hack(only_hack_old_rustc)] on the re-export in your declaration crate.

License