|
8 | 8 | // option. This file may not be copied, modified, or distributed |
9 | 9 | // except according to those terms. |
10 | 10 |
|
11 | | -//! # Proc_Macro |
| 11 | +//! A support library for macro authors when defining new macros. |
12 | 12 | //! |
13 | | -//! A library for procedural macro writers. |
| 13 | +//! This library, provided by the standard distribution, provides the types |
| 14 | +//! consumed in the interfaces of procedurally defined macro definitions. |
| 15 | +//! Currently the primary use of this crate is to provide the ability to define |
| 16 | +//! new custom derive modes through `#[proc_macro_derive]`. |
14 | 17 | //! |
15 | | -//! ## Usage |
16 | | -//! This package provides the `qquote!` macro for syntax creation, and the prelude |
17 | | -//! (at libproc_macro::prelude) provides a number of operations: |
18 | | -//! - `concat`, for concatenating two TokenStreams. |
19 | | -//! - `ident_eq`, for checking if two identifiers are equal regardless of syntax context. |
20 | | -//! - `str_to_token_ident`, for converting an `&str` into a Token. |
21 | | -//! - `keyword_to_token_delim`, for converting a `parse::token::keywords::Keyword` into a |
22 | | -//! Token. |
23 | | -//! - `build_delimited`, for creating a new TokenStream from an existing one and a delimiter |
24 | | -//! by wrapping the TokenStream in the delimiter. |
25 | | -//! - `build_bracket_delimited`, `build_brace_delimited`, and `build_paren_delimited`, for |
26 | | -//! easing the above. |
27 | | -//! - `build_empty_args`, which returns a TokenStream containing `()`. |
28 | | -//! - `lex`, which takes an `&str` and returns the TokenStream it represents. |
| 18 | +//! Added recently as part of [RFC 1681] this crate is currently *unstable* and |
| 19 | +//! requires the `#![feature(proc_macro_lib)]` directive to use. |
29 | 20 | //! |
30 | | -//! The `qquote!` macro also imports `syntax::ext::proc_macro_shim::prelude::*`, so you |
31 | | -//! will need to `extern crate syntax` for usage. (This is a temporary solution until more |
32 | | -//! of the external API in libproc_macro is stabilized to support the token construction |
33 | | -//! operations that the qausiquoter relies on.) The shim file also provides additional |
34 | | -//! operations, such as `build_block_emitter` (as used in the `cond` example below). |
35 | | -//! |
36 | | -//! ## TokenStreams |
37 | | -//! |
38 | | -//! TokenStreams serve as the basis of the macro system. They are, in essence, vectors of |
39 | | -//! TokenTrees, where indexing treats delimited values as a single term. That is, the term |
40 | | -//! `even(a+c) && even(b)` will be indexibly encoded as `even | (a+c) | even | (b)` where, |
41 | | -//! in reality, `(a+c)` is actually a decorated pointer to `a | + | c`. |
42 | | -//! |
43 | | -//! If a user has a TokenStream that is a single, delimited value, they can use |
44 | | -//! `maybe_delimited` to destruct it and receive the internal vector as a new TokenStream |
45 | | -//! as: |
46 | | -//! ``` |
47 | | -//! `(a+c)`.maybe_delimited() ~> Some(a | + | c)` |
48 | | -//! ``` |
49 | | -//! |
50 | | -//! Check the TokenStream documentation for more information; the structure also provides |
51 | | -//! cheap concatenation and slicing. |
52 | | -//! |
53 | | -//! ## Quasiquotation |
54 | | -//! |
55 | | -//! The quasiquoter creates output that, when run, constructs the tokenstream specified as |
56 | | -//! input. For example, `qquote!(5 + 5)` will produce a program, that, when run, will |
57 | | -//! construct the TokenStream `5 | + | 5`. |
58 | | -//! |
59 | | -//! ### Unquoting |
60 | | -//! |
61 | | -//! Unquoting is currently done as `unquote`, and works by taking the single next |
62 | | -//! TokenTree in the TokenStream as the unquoted term. Ergonomically, `unquote(foo)` works |
63 | | -//! fine, but `unquote foo` is also supported. |
64 | | -//! |
65 | | -//! A simple example might be: |
66 | | -//! |
67 | | -//!``` |
68 | | -//!fn double(tmp: TokenStream) -> TokenStream { |
69 | | -//! qquote!(unquote(tmp) * 2) |
70 | | -//!} |
71 | | -//!``` |
72 | | -//! |
73 | | -//! ### Large Example: Implementing Scheme's `cond` |
74 | | -//! |
75 | | -//! Below is the full implementation of Scheme's `cond` operator. |
76 | | -//! |
77 | | -//! ``` |
78 | | -//! fn cond_rec(input: TokenStream) -> TokenStream { |
79 | | -//! if input.is_empty() { return quote!(); } |
80 | | -//! |
81 | | -//! let next = input.slice(0..1); |
82 | | -//! let rest = input.slice_from(1..); |
83 | | -//! |
84 | | -//! let clause : TokenStream = match next.maybe_delimited() { |
85 | | -//! Some(ts) => ts, |
86 | | -//! _ => panic!("Invalid input"), |
87 | | -//! }; |
88 | | -//! |
89 | | -//! // clause is ([test]) [rhs] |
90 | | -//! if clause.len() < 2 { panic!("Invalid macro usage in cond: {:?}", clause) } |
91 | | -//! |
92 | | -//! let test: TokenStream = clause.slice(0..1); |
93 | | -//! let rhs: TokenStream = clause.slice_from(1..); |
94 | | -//! |
95 | | -//! if ident_eq(&test[0], str_to_ident("else")) || rest.is_empty() { |
96 | | -//! quote!({unquote(rhs)}) |
97 | | -//! } else { |
98 | | -//! quote!({if unquote(test) { unquote(rhs) } else { cond!(unquote(rest)) } }) |
99 | | -//! } |
100 | | -//! } |
101 | | -//! ``` |
| 21 | +//! [RFC 1681]: https://github.com/rust-lang/rfcs/blob/master/text/1681-macros-1.1.md |
102 | 22 | //! |
| 23 | +//! Note that this crate is intentionally very bare-bones currently. The main |
| 24 | +//! type, `TokenStream`, only supports `fmt::Display` and `FromStr` |
| 25 | +//! implementations, indicating that it can only go to and come from a string. |
| 26 | +//! This functionality is intended to be expanded over time as more surface |
| 27 | +//! area for macro authors is stabilized. |
103 | 28 |
|
104 | 29 | #![crate_name = "proc_macro"] |
105 | | -#![unstable(feature = "rustc_private", issue = "27812")] |
106 | | -#![feature(plugin_registrar)] |
107 | | -#![crate_type = "dylib"] |
| 30 | +#![unstable(feature = "proc_macro_lib", issue = "27812")] |
108 | 31 | #![crate_type = "rlib"] |
109 | | -#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", |
110 | | - html_favicon_url = "https://doc.rust-lang.org/favicon.ico", |
111 | | - html_root_url = "https://doc.rust-lang.org/nightly/")] |
| 32 | +#![crate_type = "dylib"] |
112 | 33 | #![cfg_attr(not(stage0), deny(warnings))] |
| 34 | +#![deny(missing_docs)] |
113 | 35 |
|
114 | | -#![feature(staged_api)] |
115 | | -#![feature(rustc_diagnostic_macros)] |
116 | 36 | #![feature(rustc_private)] |
| 37 | +#![feature(staged_api)] |
| 38 | +#![feature(lang_items)] |
117 | 39 |
|
118 | | -extern crate rustc_plugin; |
119 | 40 | extern crate syntax; |
120 | | -extern crate syntax_pos; |
121 | | -#[macro_use] extern crate log; |
122 | 41 |
|
123 | | -mod qquote; |
124 | | -pub mod build; |
125 | | -pub mod parse; |
126 | | -pub mod prelude; |
127 | | -use qquote::qquote; |
| 42 | +use std::fmt; |
| 43 | +use std::str::FromStr; |
| 44 | + |
| 45 | +use syntax::ast; |
| 46 | +use syntax::parse; |
| 47 | +use syntax::ptr::P; |
| 48 | + |
| 49 | +/// The main type provided by this crate, representing an abstract stream of |
| 50 | +/// tokens. |
| 51 | +/// |
| 52 | +/// This is both the input and output of `#[proc_macro_derive]` definitions. |
| 53 | +/// Currently it's required to be a list of valid Rust items, but this |
| 54 | +/// restriction may be lifted in the future. |
| 55 | +/// |
| 56 | +/// The API of this type is intentionally bare-bones, but it'll be expanded over |
| 57 | +/// time! |
| 58 | +pub struct TokenStream { |
| 59 | + inner: Vec<P<ast::Item>>, |
| 60 | +} |
| 61 | + |
| 62 | +/// Error returned from `TokenStream::from_str`. |
| 63 | +#[derive(Debug)] |
| 64 | +pub struct LexError { |
| 65 | + _inner: (), |
| 66 | +} |
| 67 | + |
| 68 | +/// Permanently unstable internal implementation details of this crate. This |
| 69 | +/// should not be used. |
| 70 | +/// |
| 71 | +/// These methods are used by the rest of the compiler to generate instances of |
| 72 | +/// `TokenStream` to hand to macro definitions, as well as consume the output. |
| 73 | +/// |
| 74 | +/// Note that this module is also intentionally separate from the rest of the |
| 75 | +/// crate. This allows the `#[unstable]` directive below to naturally apply to |
| 76 | +/// all of the contents. |
| 77 | +#[unstable(feature = "proc_macro_internals", issue = "27812")] |
| 78 | +#[doc(hidden)] |
| 79 | +pub mod __internal { |
| 80 | + use std::cell::Cell; |
| 81 | + |
| 82 | + use syntax::ast; |
| 83 | + use syntax::ptr::P; |
| 84 | + use syntax::parse::ParseSess; |
| 85 | + use super::TokenStream; |
| 86 | + |
| 87 | + pub fn new_token_stream(item: P<ast::Item>) -> TokenStream { |
| 88 | + TokenStream { inner: vec![item] } |
| 89 | + } |
128 | 90 |
|
129 | | -use rustc_plugin::Registry; |
| 91 | + pub fn token_stream_items(stream: TokenStream) -> Vec<P<ast::Item>> { |
| 92 | + stream.inner |
| 93 | + } |
130 | 94 |
|
131 | | -// ____________________________________________________________________________________________ |
132 | | -// Main macro definition |
| 95 | + pub trait Registry { |
| 96 | + fn register_custom_derive(&mut self, |
| 97 | + trait_name: &str, |
| 98 | + expand: fn(TokenStream) -> TokenStream); |
| 99 | + } |
| 100 | + |
| 101 | + // Emulate scoped_thread_local!() here essentially |
| 102 | + thread_local! { |
| 103 | + static CURRENT_SESS: Cell<*const ParseSess> = Cell::new(0 as *const _); |
| 104 | + } |
| 105 | + |
| 106 | + pub fn set_parse_sess<F, R>(sess: &ParseSess, f: F) -> R |
| 107 | + where F: FnOnce() -> R |
| 108 | + { |
| 109 | + struct Reset { prev: *const ParseSess } |
| 110 | + |
| 111 | + impl Drop for Reset { |
| 112 | + fn drop(&mut self) { |
| 113 | + CURRENT_SESS.with(|p| p.set(self.prev)); |
| 114 | + } |
| 115 | + } |
| 116 | + |
| 117 | + CURRENT_SESS.with(|p| { |
| 118 | + let _reset = Reset { prev: p.get() }; |
| 119 | + p.set(sess); |
| 120 | + f() |
| 121 | + }) |
| 122 | + } |
| 123 | + |
| 124 | + pub fn with_parse_sess<F, R>(f: F) -> R |
| 125 | + where F: FnOnce(&ParseSess) -> R |
| 126 | + { |
| 127 | + let p = CURRENT_SESS.with(|p| p.get()); |
| 128 | + assert!(!p.is_null()); |
| 129 | + f(unsafe { &*p }) |
| 130 | + } |
| 131 | +} |
| 132 | + |
| 133 | +impl FromStr for TokenStream { |
| 134 | + type Err = LexError; |
| 135 | + |
| 136 | + fn from_str(src: &str) -> Result<TokenStream, LexError> { |
| 137 | + __internal::with_parse_sess(|sess| { |
| 138 | + let src = src.to_string(); |
| 139 | + let cfg = Vec::new(); |
| 140 | + let name = "<proc-macro source code>".to_string(); |
| 141 | + let mut parser = parse::new_parser_from_source_str(sess, cfg, name, |
| 142 | + src); |
| 143 | + let mut ret = TokenStream { inner: Vec::new() }; |
| 144 | + loop { |
| 145 | + match parser.parse_item() { |
| 146 | + Ok(Some(item)) => ret.inner.push(item), |
| 147 | + Ok(None) => return Ok(ret), |
| 148 | + Err(mut err) => { |
| 149 | + err.cancel(); |
| 150 | + return Err(LexError { _inner: () }) |
| 151 | + } |
| 152 | + } |
| 153 | + } |
| 154 | + }) |
| 155 | + } |
| 156 | +} |
133 | 157 |
|
134 | | -#[plugin_registrar] |
135 | | -pub fn plugin_registrar(reg: &mut Registry) { |
136 | | - reg.register_macro("qquote", qquote); |
| 158 | +impl fmt::Display for TokenStream { |
| 159 | + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
| 160 | + for item in self.inner.iter() { |
| 161 | + let item = syntax::print::pprust::item_to_string(item); |
| 162 | + try!(f.write_str(&item)); |
| 163 | + try!(f.write_str("\n")); |
| 164 | + } |
| 165 | + Ok(()) |
| 166 | + } |
137 | 167 | } |
0 commit comments