Lib.rs

This crate provides high-level macros for parsing various Rust constructs.

Specifically, these macros are concerned with taking Rust source constructs and rewriting them into a format which is more easily consumable by macro_rules! macros.

Table of Contents

• parse_enum!
• parse_item!
• parse_struct!
• Using parse-macros

parse_enum!

macro_rules! parse_enum {
(
then $cb:ident!( $($cb_arg:tt)* ),
$($body:tt)*
) => { ... };
}

Parses $body as an enum, invoking the macro $cb with the result. The general form of the expansion is:

$cb! {
$($cb_arg)*
enum {
attrs: $attrs:tt,
vis: $vis:tt,
name: $name:ident,
generics: $generics:tt,
where: $where_:tt,
variants: $variants:tt,
num_variants: $num_variants:tt,
}
}

Callback

$cb_name and $cb_arg specify the macro to invoke with the result of parsing. Note that $cb_arg may be contained in any of ( .. ), [ .. ], or { .. }.

Fields

The expansion contains the following fields:

• $attrs: a [ .. ]-delimited list of attributes. e.g.: [ #[doc="Does a thing"] #[repr(u8)] ].

• $vis: a ( .. )-delimited visibility annotation. e.g.: (), (pub).

• $name: the enum's name as an identifier. e.g.: Option.

• $generics: the { .. }-delimited output of parse_generics_shim! for the enum, containing the constr, params, ltimes, and tnames fields:

generics: {
constr: $constr:tt,
params: $params:tt,
ltimes: $ltimes:tt,
tnames: $tnames:tt,
}

• $constr: a [ .. ]-delimited, comma-terminated list of generic constraints. e.g. ['a, 'b: 'a, T, U: 'a + Copy,].

• $params: a [ .. ]-delimited, comma-terminated list of generic parameter names. e.g. ['a, 'b, T, U,].

• $ltimes: a [ .. ]-delimited, comma-terminated list of generic lifetime parameters. e.g. ['a, 'b,].

• $tnames: a [ .. ]-delimited, comma-terminated list of generic type parameters. e.g. [T, U,].

• $where_: the { .. }-delimited output of parse_where_shim! for the enum, containing the clause, and preds fields:

where: {
clause: $clause:tt,
preds: $preds:tt,
}

• $clause: a [ .. ]-delimited, comma-terminated clause, including the where keyword. If the clause is empty, the where keyword is omitted, and the brackets are empty. e.g. [], [ where for<'a> T: Fn(&'a i32), ].

• $preds: a [ .. ]-delimited, comma-terminated list of clause predicates. e.g. [], [ for<'a> T: Fn(&'a i32), ].

• $variants: a [ .. ]-delimited, comma-terminated list of variants (described below).

• $num_variants: the number of variants in the enum. e.g. 2.

Each variant has the following form:

{
ord: ($vord_index:tt, $vord_ident:ident),
attrs: $vattrs:tt,
kind: $vkind:ident,
name: $vname:ident,
fields: $vfields:tt,
num_fields: $vnum_fields:tt,
}

• $vord_index: the 0-based ordinal for this variant. e.g. 1.

• $vord_ident: an identifier guaranteed to be unique relative to other variants for the same enum. Identifiers are not guaranteed to be unique between different parse_enum! invocations. e.g. _ord_01.

• $vattrs: a [ .. ]-delimited list of attributes attached to the variant. e.g. [ #[doc="A variant unlike the rest."] ].

• $vkind: one of unitary, tuple, or record.

• $vname: the variant's name as an identifier. e.g. None.

• $vfields: a [ .. ]-delimited, comma-terminated list of fields (described below).

• $vnum_fields: the number of fields in the variant. e.g. 1.

Variant fields have the following form:

{
ord: ($ford_index:tt, $ford_ident:ident),
attrs: $fattrs:tt,
vis: $fvis:tt,
ty: $fty:ty,

// **NOTE**: only exists for *record* variant fields:
name: $fname:ident,
}

• $ford_index: the 0-based ordinal for this variant field. e.g. 1.

• $ford_ident: an identifier guaranteed to be unique relative to other fields for the same variant. Identifiers are not guaranteed to be unique between different parse_enum! invocations, or between variants in the same invocation. e.g. _ord_01.

• $fattrs: a [ .. ]-delimited list of attributes attached to the variant field. e.g. [ #[doc="A part of the whole."] ].

• $fvis: a ( .. )-delimited visibility annotation. e.g.: (), (pub).

• $fty: the type of the variant field.

• $fname: the variant field's name as an identifier. e.g. part.

Example

parse_enum! {
then stringify!(output:),
/// The `Option` type.
pub enum Option<T> {
/// No value.
None,
/// Some value `T`.
Some(T),
/// File could not be found.
FileNotFound { path: PathBuf },
}
}

// Expands to:
stringify!(