Crate parse_macros [−] [src]

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.

Links

Table of Contents

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!(
    output:
    enum {
        attrs: [ #[doc=r"The `Option` type."] ],
        vis: (pub),
        name: Option,
        generics: {
            constr: [T,],
            params: [T,],
            ltimes: [],
            tnames: [T,],
        },
        where: {
            clause: [],
            preds: [],
        },
        variants: [
            {
                ord: (0, _ord_00),
                attrs: [ #[doc=r"No value."] ],
                kind: unitary,
                name: None,
                fields: [],
                num_fields: 0,
            },
            {
                ord: (1, _ord_01),
                attrs: [ #[doc=r"Some value `T`."] ],
                kind: tuple,
                name: Some,
                fields: [
                    {
                        ord: (0, _ord_00),
                        attrs: [],
                        vis: (),
                        ty: T,
                    },
                ],
                num_fields: 1,
            },
            {
                ord: (2, _ord_02),
                attrs: [ #[doc=r"File could not be found."] ],
                kind: record,
                name: FileNotFound,
                fields: [
                    {
                        ord: (0, _ord_00),
                        attrs: [],
                        vis: (),
                        ty: PathBuf,
                        name: path,
                    },
                ],
                num_fields: 1,
            },
        ],
        num_variants: 3,
    }
)

parse_item!

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

Parses $body as an item, invoking the macro $cb with the result. This forwards to the appropriate parse_*! macro, depending on what kind of item is in $body.

See parse_enum!, and parse_struct! for more details.

parse_struct!

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

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

$cb! {
    $($cb_arg)*
    struct {
        attrs: $attrs:tt,
        vis: $vis:tt,
        name: $name:ident,
        generics: $generics:tt,
        where: $where_:tt,
        kind: $kind:ident,
        fields: $fields:tt,
        num_fields: $num_fields: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(C)] ].

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

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

  • $generics: the { .. }-delimited output of parse_generics_shim! for the struct, 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 struct, containing the preds field:

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

  • $kind: one of unitary, tuple, or record. These correspond to the three kinds of struct definitions: struct Unitary;, struct Tuple(..); and struct Record { .. }.

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

  • $num_fields: the number of fields in the struct. e.g. 2.

struct 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* `struct` fields:
    name: $fname:ident,
}

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

  • $ford_ident: an identifier guaranteed to be unique relative to other fields for the same struct. Identifiers are not guaranteed to be unique between different parse_struct! invocations. e.g. _ord_01.

  • $fattrs: a [ .. ]-delimited list of attributes attached to the struct field. e.g. [ #[doc="The amount of green-ness."] ].

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

  • $fty: the type of the struct field.

  • $fname: the struct field's name as an identifier. e.g. green.

Example

parse_struct! {
    then stringify!(output:),
    /// Represents a colour.
    pub struct Rgb<Ch> {
        /// The degree of red-ness.
        r: Ch,
        /// How eco-friendly is this colour?
        g: Ch,
        /// Maybe it's blue, maybe it's not?
        b: Option<Ch>,
    }
}

// Expands to:
stringify!(
    output:
    struct {
        attrs: [ #[doc=r"Represents a colour."] ],
        vis: (pub),
        name: Rgb,
        generics: {
            constr: [Ch,],
            params: [Ch,],
            ltimes: [],
            tnames: [Ch,],
        },
        where: {
            clause: [],
            preds: [],
        },
        kind: record,
        fields: [
            {
                ord: (0, _ord_00),
                attrs: [ #[doc=r"The degree of red-ness."] ],
                vis: (),
                ty: Ch,
                name: r,
            },
            {
                ord: (1, _ord_01),
                attrs: [ #[doc=r"How eco-friendly is this colour?"] ],
                vis: (),
                ty: Ch,
                name: g,
            },
            {
                ord: (2, _ord_02),
                attrs: [ #[doc=r"Maybe it's blue, maybe it's not?"] ],
                vis: (),
                ty: Option<Ch>,
                name: b,
            },
        ],
        num_fields: 3,
    }
)

Using parse-macros

For Crate Authors

Add the following to your Cargo.toml manifest:

[features]
use-parse-generics-poc = [
    "parse-generics-poc",
    "parse-macros/use-parse-generics-poc",
]

[dependencies]
parse-generics-poc = { version = "0.1.0", optional = true }
parse-macros = "0.1.0"

This allows your users to enable the proof-of-concept compiler plugin through your crate. You should also copy and modify the following section (replacing whizzo with your crate's name).

For Crate Users

Add the following to your Cargo.toml manifest:

[features]
use-parse-generics-poc = [
    "whizzo/use-parse-generics-poc",
    "parse-generics-poc",
    "parse-macros/use-parse-generics-poc",
]

[dependencies]
whizzo = "0.1.0"
parse-generics-poc = { version = "0.1.0", optional = true }
parse-generics-shim = "0.1.0"
parse-macros = "0.1.0"

Then, add the following to your crate's root module:

#![cfg_attr(feature="parse-generics-poc", feature(plugin))]
#![cfg_attr(feature="parse-generics-poc", plugin(parse_generics_poc))]
#[macro_use] extern crate parse_generics_shim;
#[macro_use] extern crate parse_macros;
#[macro_use] extern crate whizzo;

By default, this will use stable-but-inferior implementations of the generics-parsing macros. In particular, you cannot use lifetimes other than 'a through 'z, and macros may fail to expand for sufficiently complex inputs.

If a macro fails to expand due to the "recursion limit", place the following attribute at the top of your crate's root module, and raise the number until the macro works:

#![recursion_limit="32"]

If you are using a compatible nightly compiler, you can enable the fully-featured versions of the generics-parsing macros (see the proposed RFC #1583 for context). If you have followed the instructions above, this can be done by adding --features=use-parse-generic-poc to your cargo build command.

The documentation for parse-generics-poc will specify which nightly it is known to be compatible with. If you are using rustup, you can configure your crate to use the appropriate compiler using the following (replacing the date shown with the one listed in the parse-generics-poc documentation):

rustup override add nightly-2016-04-06