1 // Copyright 2016 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! A support library for macro authors when defining new macros.
13 //! This library, provided by the standard distribution, provides the types
14 //! consumed in the interfaces of procedurally defined macro definitions such as
15 //! function-like macros `#[proc_macro]`, macro attributes `#[proc_macro_attribute]` and
16 //! custom derive attributes`#[proc_macro_derive]`.
18 //! Note that this crate is intentionally bare-bones currently.
19 //! This functionality is intended to be expanded over time as more surface
20 //! area for macro authors is stabilized.
22 //! See [the book](../book/first-edition/procedural-macros.html) for more.
24 #![stable(feature = "proc_macro_lib", since = "1.15.0")]
25 #![deny(missing_docs)]
26 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
27 html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
28 html_root_url = "https://doc.rust-lang.org/nightly/",
29 html_playground_url = "https://play.rust-lang.org/",
30 issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
31 test(no_crate_inject, attr(deny(warnings))),
32 test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))]
34 #![cfg_attr(not(stage0), feature(nll))]
35 #![cfg_attr(not(stage0), feature(infer_outlives_requirements))]
36 #![feature(rustc_private)]
37 #![feature(staged_api)]
38 #![feature(lang_items)]
39 #![feature(optin_builtin_traits)]
40 #![feature(non_exhaustive)]
42 #![recursion_limit="256"]
45 extern crate syntax_pos;
46 extern crate rustc_errors;
47 extern crate rustc_data_structures;
49 #[unstable(feature = "proc_macro_internals", issue = "27812")]
55 #[unstable(feature = "proc_macro_diagnostic", issue = "38356")]
56 pub use diagnostic::{Diagnostic, Level};
58 use std::{ascii, fmt, iter};
59 use std::path::PathBuf;
60 use rustc_data_structures::sync::Lrc;
61 use std::str::FromStr;
63 use syntax::errors::DiagnosticBuilder;
64 use syntax::parse::{self, token};
65 use syntax::symbol::Symbol;
66 use syntax::tokenstream;
67 use syntax_pos::{Pos, FileName};
69 /// The main type provided by this crate, representing an abstract stream of
70 /// tokens, or, more specifically, a sequence of token trees.
71 /// The type provide interfaces for iterating over those token trees and, conversely,
72 /// collecting a number of token trees into one stream.
74 /// This is both the input and output of `#[proc_macro]`, `#[proc_macro_attribute]`
75 /// and `#[proc_macro_derive]` definitions.
77 /// The API of this type is intentionally bare-bones, but it'll be expanded over
79 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
81 pub struct TokenStream(tokenstream::TokenStream);
83 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
84 impl !Send for TokenStream {}
85 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
86 impl !Sync for TokenStream {}
88 /// Error returned from `TokenStream::from_str`.
89 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
95 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
96 impl !Send for LexError {}
97 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
98 impl !Sync for LexError {}
101 /// Returns an empty `TokenStream` containing no token trees.
102 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
103 pub fn new() -> TokenStream {
104 TokenStream(tokenstream::TokenStream::empty())
107 /// Checks if this `TokenStream` is empty.
108 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
109 pub fn is_empty(&self) -> bool {
114 /// Attempts to break the string into tokens and parse those tokens into a token stream.
115 /// May fail for a number of reasons, for example, if the string contains unbalanced delimiters
116 /// or characters not existing in the language.
117 /// All tokens in the parsed stream get `Span::call_site()` spans.
119 /// NOTE: Some errors may cause panics instead of returning `LexError`. We reserve the right to
120 /// change these errors into `LexError`s later.
121 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
122 impl FromStr for TokenStream {
125 fn from_str(src: &str) -> Result<TokenStream, LexError> {
126 __internal::with_sess(|sess, data| {
127 Ok(__internal::token_stream_wrap(parse::parse_stream_from_source_str(
128 FileName::ProcMacroSourceCode, src.to_string(), sess, Some(data.call_site.0)
134 /// Prints the token stream as a string that is supposed to be losslessly convertible back
135 /// into the same token stream (modulo spans), except for possibly `TokenTree::Group`s
136 /// with `Delimiter::None` delimiters and negative numeric literals.
137 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
138 impl fmt::Display for TokenStream {
139 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
144 /// Prints token in a form convenient for debugging.
145 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
146 impl fmt::Debug for TokenStream {
147 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
148 f.write_str("TokenStream ")?;
149 f.debug_list().entries(self.clone()).finish()
153 #[unstable(feature = "proc_macro_quote", issue = "38356")]
154 pub use quote::{quote, quote_span};
156 /// Creates a token stream containing a single token tree.
157 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
158 impl From<TokenTree> for TokenStream {
159 fn from(tree: TokenTree) -> TokenStream {
160 TokenStream(tree.to_internal())
164 /// Collects a number of token trees into a single stream.
165 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
166 impl iter::FromIterator<TokenTree> for TokenStream {
167 fn from_iter<I: IntoIterator<Item = TokenTree>>(trees: I) -> Self {
168 trees.into_iter().map(TokenStream::from).collect()
172 /// A "flattening" operation on token streams, collects token trees
173 /// from multiple token streams into a single stream.
174 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
175 impl iter::FromIterator<TokenStream> for TokenStream {
176 fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self {
177 let mut builder = tokenstream::TokenStreamBuilder::new();
178 for stream in streams {
179 builder.push(stream.0);
181 TokenStream(builder.build())
185 #[stable(feature = "token_stream_extend", since = "1.30.0")]
186 impl Extend<TokenTree> for TokenStream {
187 fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, trees: I) {
188 self.extend(trees.into_iter().map(TokenStream::from));
192 #[stable(feature = "token_stream_extend", since = "1.30.0")]
193 impl Extend<TokenStream> for TokenStream {
194 fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) {
195 self.0.extend(streams.into_iter().map(|stream| stream.0));
199 /// Public implementation details for the `TokenStream` type, such as iterators.
200 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
201 pub mod token_stream {
202 use syntax::tokenstream;
203 use {TokenTree, TokenStream, Delimiter};
205 /// An iterator over `TokenStream`'s `TokenTree`s.
206 /// The iteration is "shallow", e.g. the iterator doesn't recurse into delimited groups,
207 /// and returns whole groups as token trees.
209 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
210 pub struct IntoIter {
211 cursor: tokenstream::Cursor,
212 stack: Vec<TokenTree>,
215 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
216 impl Iterator for IntoIter {
217 type Item = TokenTree;
219 fn next(&mut self) -> Option<TokenTree> {
221 let tree = self.stack.pop().or_else(|| {
222 let next = self.cursor.next_as_stream()?;
223 Some(TokenTree::from_internal(next, &mut self.stack))
225 // HACK: The condition "dummy span + group with empty delimiter" represents an AST
226 // fragment approximately converted into a token stream. This may happen, for
227 // example, with inputs to proc macro attributes, including derives. Such "groups"
228 // need to flattened during iteration over stream's token trees.
229 // Eventually this needs to be removed in favor of keeping original token trees
230 // and not doing the roundtrip through AST.
231 if tree.span().0.is_dummy() {
232 if let TokenTree::Group(ref group) = tree {
233 if group.delimiter() == Delimiter::None {
234 self.cursor.insert(group.stream.clone().0);
244 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
245 impl IntoIterator for TokenStream {
246 type Item = TokenTree;
247 type IntoIter = IntoIter;
249 fn into_iter(self) -> IntoIter {
250 IntoIter { cursor: self.0.trees(), stack: Vec::new() }
255 /// `quote!(..)` accepts arbitrary tokens and expands into a `TokenStream` describing the input.
256 /// For example, `quote!(a + b)` will produce a expression, that, when evaluated, constructs
257 /// the `TokenStream` `[Ident("a"), Punct('+', Alone), Ident("b")]`.
259 /// Unquoting is done with `$`, and works by taking the single next ident as the unquoted term.
260 /// To quote `$` itself, use `$$`.
262 /// This is a dummy macro, the actual implementation is in `quote::quote`.`
263 #[unstable(feature = "proc_macro_quote", issue = "38356")]
265 macro_rules! quote { () => {} }
267 #[unstable(feature = "proc_macro_internals", issue = "27812")]
271 /// A region of source code, along with macro expansion information.
272 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
273 #[derive(Copy, Clone)]
274 pub struct Span(syntax_pos::Span);
276 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
277 impl !Send for Span {}
278 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
279 impl !Sync for Span {}
281 macro_rules! diagnostic_method {
282 ($name:ident, $level:expr) => (
283 /// Create a new `Diagnostic` with the given `message` at the span
285 #[unstable(feature = "proc_macro_diagnostic", issue = "38356")]
286 pub fn $name<T: Into<String>>(self, message: T) -> Diagnostic {
287 Diagnostic::spanned(self, $level, message)
293 /// A span that resolves at the macro definition site.
294 #[unstable(feature = "proc_macro_span", issue = "38356")]
295 pub fn def_site() -> Span {
296 ::__internal::with_sess(|_, data| data.def_site)
299 /// The span of the invocation of the current procedural macro.
300 /// Identifiers created with this span will be resolved as if they were written
301 /// directly at the macro call location (call-site hygiene) and other code
302 /// at the macro call site will be able to refer to them as well.
303 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
304 pub fn call_site() -> Span {
305 ::__internal::with_sess(|_, data| data.call_site)
308 /// The original source file into which this span points.
309 #[unstable(feature = "proc_macro_span", issue = "38356")]
310 pub fn source_file(&self) -> SourceFile {
312 source_file: __internal::lookup_char_pos(self.0.lo()).file,
316 /// The `Span` for the tokens in the previous macro expansion from which
317 /// `self` was generated from, if any.
318 #[unstable(feature = "proc_macro_span", issue = "38356")]
319 pub fn parent(&self) -> Option<Span> {
320 self.0.parent().map(Span)
323 /// The span for the origin source code that `self` was generated from. If
324 /// this `Span` wasn't generated from other macro expansions then the return
325 /// value is the same as `*self`.
326 #[unstable(feature = "proc_macro_span", issue = "38356")]
327 pub fn source(&self) -> Span {
328 Span(self.0.source_callsite())
331 /// Get the starting line/column in the source file for this span.
332 #[unstable(feature = "proc_macro_span", issue = "38356")]
333 pub fn start(&self) -> LineColumn {
334 let loc = __internal::lookup_char_pos(self.0.lo());
337 column: loc.col.to_usize()
341 /// Get the ending line/column in the source file for this span.
342 #[unstable(feature = "proc_macro_span", issue = "38356")]
343 pub fn end(&self) -> LineColumn {
344 let loc = __internal::lookup_char_pos(self.0.hi());
347 column: loc.col.to_usize()
351 /// Create a new span encompassing `self` and `other`.
353 /// Returns `None` if `self` and `other` are from different files.
354 #[unstable(feature = "proc_macro_span", issue = "38356")]
355 pub fn join(&self, other: Span) -> Option<Span> {
356 let self_loc = __internal::lookup_char_pos(self.0.lo());
357 let other_loc = __internal::lookup_char_pos(other.0.lo());
359 if self_loc.file.name != other_loc.file.name { return None }
361 Some(Span(self.0.to(other.0)))
364 /// Creates a new span with the same line/column information as `self` but
365 /// that resolves symbols as though it were at `other`.
366 #[unstable(feature = "proc_macro_span", issue = "38356")]
367 pub fn resolved_at(&self, other: Span) -> Span {
368 Span(self.0.with_ctxt(other.0.ctxt()))
371 /// Creates a new span with the same name resolution behavior as `self` but
372 /// with the line/column information of `other`.
373 #[unstable(feature = "proc_macro_span", issue = "38356")]
374 pub fn located_at(&self, other: Span) -> Span {
375 other.resolved_at(*self)
378 /// Compares to spans to see if they're equal.
379 #[unstable(feature = "proc_macro_span", issue = "38356")]
380 pub fn eq(&self, other: &Span) -> bool {
384 diagnostic_method!(error, Level::Error);
385 diagnostic_method!(warning, Level::Warning);
386 diagnostic_method!(note, Level::Note);
387 diagnostic_method!(help, Level::Help);
390 /// Prints a span in a form convenient for debugging.
391 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
392 impl fmt::Debug for Span {
393 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
394 write!(f, "{:?} bytes({}..{})",
401 /// A line-column pair representing the start or end of a `Span`.
402 #[unstable(feature = "proc_macro_span", issue = "38356")]
403 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
404 pub struct LineColumn {
405 /// The 1-indexed line in the source file on which the span starts or ends (inclusive).
406 #[unstable(feature = "proc_macro_span", issue = "38356")]
408 /// The 0-indexed column (in UTF-8 characters) in the source file on which
409 /// the span starts or ends (inclusive).
410 #[unstable(feature = "proc_macro_span", issue = "38356")]
414 #[unstable(feature = "proc_macro_span", issue = "38356")]
415 impl !Send for LineColumn {}
416 #[unstable(feature = "proc_macro_span", issue = "38356")]
417 impl !Sync for LineColumn {}
419 /// The source file of a given `Span`.
420 #[unstable(feature = "proc_macro_span", issue = "38356")]
422 pub struct SourceFile {
423 source_file: Lrc<syntax_pos::SourceFile>,
426 #[unstable(feature = "proc_macro_span", issue = "38356")]
427 impl !Send for SourceFile {}
428 #[unstable(feature = "proc_macro_span", issue = "38356")]
429 impl !Sync for SourceFile {}
432 /// Get the path to this source file.
435 /// If the code span associated with this `SourceFile` was generated by an external macro, this
436 /// macro, this may not be an actual path on the filesystem. Use [`is_real`] to check.
438 /// Also note that even if `is_real` returns `true`, if `--remap-path-prefix` was passed on
439 /// the command line, the path as given may not actually be valid.
441 /// [`is_real`]: #method.is_real
442 #[unstable(feature = "proc_macro_span", issue = "38356")]
443 pub fn path(&self) -> PathBuf {
444 match self.source_file.name {
445 FileName::Real(ref path) => path.clone(),
446 _ => PathBuf::from(self.source_file.name.to_string())
450 /// Returns `true` if this source file is a real source file, and not generated by an external
451 /// macro's expansion.
452 #[unstable(feature = "proc_macro_span", issue = "38356")]
453 pub fn is_real(&self) -> bool {
454 // This is a hack until intercrate spans are implemented and we can have real source files
455 // for spans generated in external macros.
456 // https://github.com/rust-lang/rust/pull/43604#issuecomment-333334368
457 self.source_file.is_real_file()
462 #[unstable(feature = "proc_macro_span", issue = "38356")]
463 impl fmt::Debug for SourceFile {
464 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
465 f.debug_struct("SourceFile")
466 .field("path", &self.path())
467 .field("is_real", &self.is_real())
472 #[unstable(feature = "proc_macro_span", issue = "38356")]
473 impl PartialEq for SourceFile {
474 fn eq(&self, other: &Self) -> bool {
475 Lrc::ptr_eq(&self.source_file, &other.source_file)
479 #[unstable(feature = "proc_macro_span", issue = "38356")]
480 impl Eq for SourceFile {}
482 /// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`).
483 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
486 /// A token stream surrounded by bracket delimiters.
487 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
489 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
493 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
495 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
498 /// A single punctuation character (`+`, `,`, `$`, etc.).
499 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
501 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
504 /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc.
505 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
507 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
512 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
513 impl !Send for TokenTree {}
514 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
515 impl !Sync for TokenTree {}
518 /// Returns the span of this tree, delegating to the `span` method of
519 /// the contained token or a delimited stream.
520 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
521 pub fn span(&self) -> Span {
523 TokenTree::Group(ref t) => t.span(),
524 TokenTree::Ident(ref t) => t.span(),
525 TokenTree::Punct(ref t) => t.span(),
526 TokenTree::Literal(ref t) => t.span(),
530 /// Configures the span for *only this token*.
532 /// Note that if this token is a `Group` then this method will not configure
533 /// the span of each of the internal tokens, this will simply delegate to
534 /// the `set_span` method of each variant.
535 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
536 pub fn set_span(&mut self, span: Span) {
538 TokenTree::Group(ref mut t) => t.set_span(span),
539 TokenTree::Ident(ref mut t) => t.set_span(span),
540 TokenTree::Punct(ref mut t) => t.set_span(span),
541 TokenTree::Literal(ref mut t) => t.set_span(span),
546 /// Prints token treee in a form convenient for debugging.
547 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
548 impl fmt::Debug for TokenTree {
549 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
550 // Each of these has the name in the struct type in the derived debug,
551 // so don't bother with an extra layer of indirection
553 TokenTree::Group(ref tt) => tt.fmt(f),
554 TokenTree::Ident(ref tt) => tt.fmt(f),
555 TokenTree::Punct(ref tt) => tt.fmt(f),
556 TokenTree::Literal(ref tt) => tt.fmt(f),
561 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
562 impl From<Group> for TokenTree {
563 fn from(g: Group) -> TokenTree {
568 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
569 impl From<Ident> for TokenTree {
570 fn from(g: Ident) -> TokenTree {
575 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
576 impl From<Punct> for TokenTree {
577 fn from(g: Punct) -> TokenTree {
582 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
583 impl From<Literal> for TokenTree {
584 fn from(g: Literal) -> TokenTree {
585 TokenTree::Literal(g)
589 /// Prints the token tree as a string that is supposed to be losslessly convertible back
590 /// into the same token tree (modulo spans), except for possibly `TokenTree::Group`s
591 /// with `Delimiter::None` delimiters and negative numeric literals.
592 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
593 impl fmt::Display for TokenTree {
594 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
596 TokenTree::Group(ref t) => t.fmt(f),
597 TokenTree::Ident(ref t) => t.fmt(f),
598 TokenTree::Punct(ref t) => t.fmt(f),
599 TokenTree::Literal(ref t) => t.fmt(f),
604 /// A delimited token stream.
606 /// A `Group` internally contains a `TokenStream` which is surrounded by `Delimiter`s.
608 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
610 delimiter: Delimiter,
615 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
616 impl !Send for Group {}
617 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
618 impl !Sync for Group {}
620 /// Describes how a sequence of token trees is delimited.
621 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
622 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
625 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
628 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
631 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
634 /// An implicit delimiter, that may, for example, appear around tokens coming from a
635 /// "macro variable" `$var`. It is important to preserve operator priorities in cases like
636 /// `$var * 3` where `$var` is `1 + 2`.
637 /// Implicit delimiters may not survive roundtrip of a token stream through a string.
638 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
643 /// Creates a new `Group` with the given delimiter and token stream.
645 /// This constructor will set the span for this group to
646 /// `Span::call_site()`. To change the span you can use the `set_span`
648 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
649 pub fn new(delimiter: Delimiter, stream: TokenStream) -> Group {
651 delimiter: delimiter,
653 span: Span::call_site(),
657 /// Returns the delimiter of this `Group`
658 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
659 pub fn delimiter(&self) -> Delimiter {
663 /// Returns the `TokenStream` of tokens that are delimited in this `Group`.
665 /// Note that the returned token stream does not include the delimiter
667 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
668 pub fn stream(&self) -> TokenStream {
672 /// Returns the span for the delimiters of this token stream, spanning the
674 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
675 pub fn span(&self) -> Span {
679 /// Configures the span for this `Group`'s delimiters, but not its internal
682 /// This method will **not** set the span of all the internal tokens spanned
683 /// by this group, but rather it will only set the span of the delimiter
684 /// tokens at the level of the `Group`.
685 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
686 pub fn set_span(&mut self, span: Span) {
691 /// Prints the group as a string that should be losslessly convertible back
692 /// into the same group (modulo spans), except for possibly `TokenTree::Group`s
693 /// with `Delimiter::None` delimiters.
694 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
695 impl fmt::Display for Group {
696 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
697 TokenStream::from(TokenTree::from(self.clone())).fmt(f)
701 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
702 impl fmt::Debug for Group {
703 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
704 f.debug_struct("Group")
705 .field("delimiter", &self.delimiter())
706 .field("stream", &self.stream())
707 .field("span", &self.span())
712 /// An `Punct` is an single punctuation character like `+`, `-` or `#`.
714 /// Multicharacter operators like `+=` are represented as two instances of `Punct` with different
715 /// forms of `Spacing` returned.
716 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
724 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
725 impl !Send for Punct {}
726 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
727 impl !Sync for Punct {}
729 /// Whether an `Punct` is followed immediately by another `Punct` or
730 /// followed by another token or whitespace.
731 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
732 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
734 /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`.
735 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
737 /// E.g. `+` is `Joint` in `+=` or `'#`.
738 /// Additionally, single quote `'` can join with identifiers to form lifetimes `'ident`.
739 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
744 /// Creates a new `Punct` from the given character and spacing.
745 /// The `ch` argument must be a valid punctuation character permitted by the language,
746 /// otherwise the function will panic.
748 /// The returned `Punct` will have the default span of `Span::call_site()`
749 /// which can be further configured with the `set_span` method below.
750 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
751 pub fn new(ch: char, spacing: Spacing) -> Punct {
752 const LEGAL_CHARS: &[char] = &['=', '<', '>', '!', '~', '+', '-', '*', '/', '%', '^',
753 '&', '|', '@', '.', ',', ';', ':', '#', '$', '?', '\''];
754 if !LEGAL_CHARS.contains(&ch) {
755 panic!("unsupported character `{:?}`", ch)
760 span: Span::call_site(),
764 /// Returns the value of this punctuation character as `char`.
765 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
766 pub fn as_char(&self) -> char {
770 /// Returns the spacing of this punctuation character, indicating whether it's immediately
771 /// followed by another `Punct` in the token stream, so they can potentially be combined into
772 /// a multicharacter operator (`Joint`), or it's followed by some other token or whitespace
773 /// (`Alone`) so the operator has certainly ended.
774 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
775 pub fn spacing(&self) -> Spacing {
779 /// Returns the span for this punctuation character.
780 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
781 pub fn span(&self) -> Span {
785 /// Configure the span for this punctuation character.
786 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
787 pub fn set_span(&mut self, span: Span) {
792 /// Prints the punctuation character as a string that should be losslessly convertible
793 /// back into the same character.
794 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
795 impl fmt::Display for Punct {
796 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
797 TokenStream::from(TokenTree::from(self.clone())).fmt(f)
801 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
802 impl fmt::Debug for Punct {
803 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
804 f.debug_struct("Punct")
805 .field("ch", &self.as_char())
806 .field("spacing", &self.spacing())
807 .field("span", &self.span())
812 /// An identifier (`ident`).
814 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
821 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
822 impl !Send for Ident {}
823 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
824 impl !Sync for Ident {}
827 fn is_valid(string: &str) -> bool {
828 let mut chars = string.chars();
829 if let Some(start) = chars.next() {
830 (start == '_' || start.is_xid_start())
831 && chars.all(|cont| cont == '_' || cont.is_xid_continue())
837 /// Creates a new `Ident` with the given `string` as well as the specified
839 /// The `string` argument must be a valid identifier permitted by the
840 /// language, otherwise the function will panic.
842 /// Note that `span`, currently in rustc, configures the hygiene information
843 /// for this identifier.
845 /// As of this time `Span::call_site()` explicitly opts-in to "call-site" hygiene
846 /// meaning that identifiers created with this span will be resolved as if they were written
847 /// directly at the location of the macro call, and other code at the macro call site will be
848 /// able to refer to them as well.
850 /// Later spans like `Span::def_site()` will allow to opt-in to "definition-site" hygiene
851 /// meaning that identifiers created with this span will be resolved at the location of the
852 /// macro definition and other code at the macro call site will not be able to refer to them.
854 /// Due to the current importance of hygiene this constructor, unlike other
855 /// tokens, requires a `Span` to be specified at construction.
856 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
857 pub fn new(string: &str, span: Span) -> Ident {
858 if !Ident::is_valid(string) {
859 panic!("`{:?}` is not a valid identifier", string)
861 Ident::new_maybe_raw(string, span, false)
864 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`).
865 #[unstable(feature = "proc_macro_raw_ident", issue = "38356")]
866 pub fn new_raw(string: &str, span: Span) -> Ident {
867 if !Ident::is_valid(string) {
868 panic!("`{:?}` is not a valid identifier", string)
870 Ident::new_maybe_raw(string, span, true)
873 /// Returns the span of this `Ident`, encompassing the entire string returned
875 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
876 pub fn span(&self) -> Span {
880 /// Configures the span of this `Ident`, possibly changing its hygiene context.
881 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
882 pub fn set_span(&mut self, span: Span) {
887 /// Prints the identifier as a string that should be losslessly convertible
888 /// back into the same identifier.
889 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
890 impl fmt::Display for Ident {
891 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
892 TokenStream::from(TokenTree::from(self.clone())).fmt(f)
896 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
897 impl fmt::Debug for Ident {
898 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
899 f.debug_struct("Ident")
900 .field("ident", &self.to_string())
901 .field("span", &self.span())
906 /// A literal string (`"hello"`), byte string (`b"hello"`),
907 /// character (`'a'`), byte character (`b'a'`), an integer or floating point number
908 /// with or without a suffix (`1`, `1u8`, `2.3`, `2.3f32`).
909 /// Boolean literals like `true` and `false` do not belong here, they are `Ident`s.
910 // FIXME(eddyb) `Literal` should not expose internal `Debug` impls.
911 #[derive(Clone, Debug)]
912 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
915 suffix: Option<Symbol>,
919 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
920 impl !Send for Literal {}
921 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
922 impl !Sync for Literal {}
924 macro_rules! suffixed_int_literals {
925 ($($name:ident => $kind:ident,)*) => ($(
926 /// Creates a new suffixed integer literal with the specified value.
928 /// This function will create an integer like `1u32` where the integer
929 /// value specified is the first part of the token and the integral is
930 /// also suffixed at the end.
931 /// Literals created from negative numbers may not survive rountrips through
932 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
934 /// Literals created through this method have the `Span::call_site()`
935 /// span by default, which can be configured with the `set_span` method
937 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
938 pub fn $name(n: $kind) -> Literal {
940 lit: token::Lit::Integer(Symbol::intern(&n.to_string())),
941 suffix: Some(Symbol::intern(stringify!($kind))),
942 span: Span::call_site(),
948 macro_rules! unsuffixed_int_literals {
949 ($($name:ident => $kind:ident,)*) => ($(
950 /// Creates a new unsuffixed integer literal with the specified value.
952 /// This function will create an integer like `1` where the integer
953 /// value specified is the first part of the token. No suffix is
954 /// specified on this token, meaning that invocations like
955 /// `Literal::i8_unsuffixed(1)` are equivalent to
956 /// `Literal::u32_unsuffixed(1)`.
957 /// Literals created from negative numbers may not survive rountrips through
958 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
960 /// Literals created through this method have the `Span::call_site()`
961 /// span by default, which can be configured with the `set_span` method
963 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
964 pub fn $name(n: $kind) -> Literal {
966 lit: token::Lit::Integer(Symbol::intern(&n.to_string())),
968 span: Span::call_site(),
975 suffixed_int_literals! {
980 u128_suffixed => u128,
981 usize_suffixed => usize,
986 i128_suffixed => i128,
987 isize_suffixed => isize,
990 unsuffixed_int_literals! {
992 u16_unsuffixed => u16,
993 u32_unsuffixed => u32,
994 u64_unsuffixed => u64,
995 u128_unsuffixed => u128,
996 usize_unsuffixed => usize,
998 i16_unsuffixed => i16,
999 i32_unsuffixed => i32,
1000 i64_unsuffixed => i64,
1001 i128_unsuffixed => i128,
1002 isize_unsuffixed => isize,
1005 /// Creates a new unsuffixed floating-point literal.
1007 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1008 /// the float's value is emitted directly into the token but no suffix is
1009 /// used, so it may be inferred to be a `f64` later in the compiler.
1010 /// Literals created from negative numbers may not survive rountrips through
1011 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
1015 /// This function requires that the specified float is finite, for
1016 /// example if it is infinity or NaN this function will panic.
1017 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1018 pub fn f32_unsuffixed(n: f32) -> Literal {
1020 panic!("Invalid float literal {}", n);
1023 lit: token::Lit::Float(Symbol::intern(&n.to_string())),
1025 span: Span::call_site(),
1029 /// Creates a new suffixed floating-point literal.
1031 /// This consturctor will create a literal like `1.0f32` where the value
1032 /// specified is the preceding part of the token and `f32` is the suffix of
1033 /// the token. This token will always be inferred to be an `f32` in the
1035 /// Literals created from negative numbers may not survive rountrips through
1036 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
1040 /// This function requires that the specified float is finite, for
1041 /// example if it is infinity or NaN this function will panic.
1042 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1043 pub fn f32_suffixed(n: f32) -> Literal {
1045 panic!("Invalid float literal {}", n);
1048 lit: token::Lit::Float(Symbol::intern(&n.to_string())),
1049 suffix: Some(Symbol::intern("f32")),
1050 span: Span::call_site(),
1054 /// Creates a new unsuffixed floating-point literal.
1056 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1057 /// the float's value is emitted directly into the token but no suffix is
1058 /// used, so it may be inferred to be a `f64` later in the compiler.
1059 /// Literals created from negative numbers may not survive rountrips through
1060 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
1064 /// This function requires that the specified float is finite, for
1065 /// example if it is infinity or NaN this function will panic.
1066 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1067 pub fn f64_unsuffixed(n: f64) -> Literal {
1069 panic!("Invalid float literal {}", n);
1072 lit: token::Lit::Float(Symbol::intern(&n.to_string())),
1074 span: Span::call_site(),
1078 /// Creates a new suffixed floating-point literal.
1080 /// This consturctor will create a literal like `1.0f64` where the value
1081 /// specified is the preceding part of the token and `f64` is the suffix of
1082 /// the token. This token will always be inferred to be an `f64` in the
1084 /// Literals created from negative numbers may not survive rountrips through
1085 /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).
1089 /// This function requires that the specified float is finite, for
1090 /// example if it is infinity or NaN this function will panic.
1091 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1092 pub fn f64_suffixed(n: f64) -> Literal {
1094 panic!("Invalid float literal {}", n);
1097 lit: token::Lit::Float(Symbol::intern(&n.to_string())),
1098 suffix: Some(Symbol::intern("f64")),
1099 span: Span::call_site(),
1104 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1105 pub fn string(string: &str) -> Literal {
1106 let mut escaped = String::new();
1107 for ch in string.chars() {
1108 escaped.extend(ch.escape_debug());
1111 lit: token::Lit::Str_(Symbol::intern(&escaped)),
1113 span: Span::call_site(),
1117 /// Character literal.
1118 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1119 pub fn character(ch: char) -> Literal {
1120 let mut escaped = String::new();
1121 escaped.extend(ch.escape_unicode());
1123 lit: token::Lit::Char(Symbol::intern(&escaped)),
1125 span: Span::call_site(),
1129 /// Byte string literal.
1130 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1131 pub fn byte_string(bytes: &[u8]) -> Literal {
1132 let string = bytes.iter().cloned().flat_map(ascii::escape_default)
1133 .map(Into::<char>::into).collect::<String>();
1135 lit: token::Lit::ByteStr(Symbol::intern(&string)),
1137 span: Span::call_site(),
1141 /// Returns the span encompassing this literal.
1142 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1143 pub fn span(&self) -> Span {
1147 /// Configures the span associated for this literal.
1148 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1149 pub fn set_span(&mut self, span: Span) {
1154 /// Prints the literal as a string that should be losslessly convertible
1155 /// back into the same literal (except for possible rounding for floating point literals).
1156 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
1157 impl fmt::Display for Literal {
1158 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1159 TokenStream::from(TokenTree::from(self.clone())).fmt(f)
1163 /// Permanently unstable internal implementation details of this crate. This
1164 /// should not be used.
1166 /// These methods are used by the rest of the compiler to generate instances of
1167 /// `TokenStream` to hand to macro definitions, as well as consume the output.
1169 /// Note that this module is also intentionally separate from the rest of the
1170 /// crate. This allows the `#[unstable]` directive below to naturally apply to
1171 /// all of the contents.
1172 #[unstable(feature = "proc_macro_internals", issue = "27812")]
1174 pub mod __internal {
1175 use std::cell::Cell;
1179 use syntax::ext::base::ExtCtxt;
1181 use syntax::parse::{self, ParseSess};
1182 use syntax::parse::token::{self, Token};
1183 use syntax::tokenstream;
1184 use syntax_pos::{BytePos, Loc, DUMMY_SP};
1185 use syntax_pos::hygiene::{SyntaxContext, Transparency};
1187 use super::{TokenStream, LexError, Span};
1189 pub fn lookup_char_pos(pos: BytePos) -> Loc {
1190 with_sess(|sess, _| sess.source_map().lookup_char_pos(pos))
1193 pub fn new_token_stream(item: P<ast::Item>) -> TokenStream {
1194 let token = Token::interpolated(token::NtItem(item));
1195 TokenStream(tokenstream::TokenTree::Token(DUMMY_SP, token).into())
1198 pub fn token_stream_wrap(inner: tokenstream::TokenStream) -> TokenStream {
1202 pub fn token_stream_parse_items(stream: TokenStream) -> Result<Vec<P<ast::Item>>, LexError> {
1203 with_sess(move |sess, _| {
1204 let mut parser = parse::stream_to_parser(sess, stream.0);
1205 let mut items = Vec::new();
1207 while let Some(item) = try!(parser.parse_item().map_err(super::parse_to_lex_err)) {
1215 pub fn token_stream_inner(stream: TokenStream) -> tokenstream::TokenStream {
1219 pub trait Registry {
1220 fn register_custom_derive(&mut self,
1222 expand: fn(TokenStream) -> TokenStream,
1223 attributes: &[&'static str]);
1225 fn register_attr_proc_macro(&mut self,
1227 expand: fn(TokenStream, TokenStream) -> TokenStream);
1229 fn register_bang_proc_macro(&mut self,
1231 expand: fn(TokenStream) -> TokenStream);
1234 #[derive(Clone, Copy)]
1235 pub struct ProcMacroData {
1237 pub call_site: Span,
1240 #[derive(Clone, Copy)]
1241 struct ProcMacroSess {
1242 parse_sess: *const ParseSess,
1243 data: ProcMacroData,
1246 // Emulate scoped_thread_local!() here essentially
1248 static CURRENT_SESS: Cell<ProcMacroSess> = Cell::new(ProcMacroSess {
1249 parse_sess: ptr::null(),
1250 data: ProcMacroData { def_site: Span(DUMMY_SP), call_site: Span(DUMMY_SP) },
1254 pub fn set_sess<F, R>(cx: &ExtCtxt, f: F) -> R
1255 where F: FnOnce() -> R
1257 struct Reset { prev: ProcMacroSess }
1259 impl Drop for Reset {
1260 fn drop(&mut self) {
1261 CURRENT_SESS.with(|p| p.set(self.prev));
1265 CURRENT_SESS.with(|p| {
1266 let _reset = Reset { prev: p.get() };
1268 // No way to determine def location for a proc macro right now, so use call location.
1269 let location = cx.current_expansion.mark.expn_info().unwrap().call_site;
1270 let to_span = |transparency| Span(location.with_ctxt(
1271 SyntaxContext::empty().apply_mark_with_transparency(cx.current_expansion.mark,
1274 p.set(ProcMacroSess {
1275 parse_sess: cx.parse_sess,
1276 data: ProcMacroData {
1277 def_site: to_span(Transparency::Opaque),
1278 call_site: to_span(Transparency::Transparent),
1285 pub fn in_sess() -> bool
1287 !CURRENT_SESS.with(|sess| sess.get()).parse_sess.is_null()
1290 pub fn with_sess<F, R>(f: F) -> R
1291 where F: FnOnce(&ParseSess, &ProcMacroData) -> R
1293 let sess = CURRENT_SESS.with(|sess| sess.get());
1294 if sess.parse_sess.is_null() {
1295 panic!("procedural macro API is used outside of a procedural macro");
1297 f(unsafe { &*sess.parse_sess }, &sess.data)
1301 fn parse_to_lex_err(mut err: DiagnosticBuilder) -> LexError {
1303 LexError { _inner: () }