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.
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
: theenum
's name as an identifier. e.g.:Option
.$generics
: the{ .. }
-delimited output ofparse_generics_shim!
for theenum
, containing theconstr
,params
,ltimes
, andtnames
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 ofparse_where_shim!
for theenum
, containing theclause
, andpreds
fields:where: { clause: $clause:tt, preds: $preds:tt, }
$clause
: a[ .. ]
-delimited, comma-terminated clause, including thewhere
keyword. If the clause is empty, thewhere
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 theenum
. 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 sameenum
. Identifiers are not guaranteed to be unique between differentparse_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 ofunitary
,tuple
, orrecord
.$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 differentparse_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
: thestruct
's name as an identifier. e.g.:Option
.$generics
: the{ .. }
-delimited output ofparse_generics_shim!
for thestruct
, containing theconstr
,params
,ltimes
, andtnames
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 ofparse_where_shim!
for thestruct
, containing thepreds
field:where: { preds: $preds, }
$preds
: a[ .. ]
-delimited, comma-separated list of clause predicates. e.g.[ for<'a> T: Fn(&'a i32), ]
.
$kind
: one ofunitary
,tuple
, orrecord
. These correspond to the three kinds ofstruct
definitions:struct Unitary;
,struct Tuple(..);
andstruct Record { .. }
.$fields
: a[ .. ]
-delimited, comma-terminated list of fields (described below).$num_fields
: the number of fields in thestruct
. 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 thisstruct
field. e.g.1
.$ford_ident
: an identifier guaranteed to be unique relative to other fields for the samestruct
. Identifiers are not guaranteed to be unique between differentparse_struct!
invocations. e.g._ord_01
.$fattrs
: a[ .. ]
-delimited list of attributes attached to thestruct
field. e.g.[ #[doc="The amount of green-ness."] ]
.$fvis
: a( .. )
-delimited visibility annotation. e.g.:()
,(pub)
.$fty
: the type of thestruct
field.$fname
: thestruct
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