Lines Matching +full:proc +full:- +full:macro +full:- +full:api
1 …thub]](https://github.com/dtolnay/proc-macro2) [![crates-io]](https://crates.io/crates/proc-m…
3 //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo…
4 //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=55555…
5 //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&lo…
9 //! A wrapper around the procedural macro API of the compiler's [`proc_macro`]
12 //! [`proc_macro`]: https://doc.rust-lang.org/proc_macro/
14 //! - **Bring proc-macro-like functionality to other contexts like build.rs and
16 //! macros and cannot ever exist in code outside of a procedural macro.
17 //! Meanwhile `proc_macro2` types may exist anywhere including non-macro code.
19 //! `proc_macro2` rather than `proc_macro`, the procedural macro ecosystem
21 //! reimplementing non-macro equivalents of those libraries.
23 //! - **Make procedural macros unit testable.** As a consequence of being
26 //! a macro to be testable in isolation, they must be implemented using
34 //! The skeleton of a typical procedural macro typically looks like this:
43 //! pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
58 //! [`parse_macro_input!`]: https://docs.rs/syn/2.0/syn/macro.parse_macro_input.html
62 //! The default feature set of proc-macro2 tracks the most recent stable
63 //! compiler API. Functionality in `proc_macro` that is not yet stable is not
64 //! exposed by proc-macro2 by default.
68 //! rustc. We will polyfill those nightly-only APIs back to Rust 1.56.0. As
70 //! proc-macro2 may make breaking changes to them at any time.
73 //! RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
80 //! Semver exempt methods are marked as such in the proc-macro2 documentation.
82 //! # Thread-Safety
85 //! types make use of thread-local memory, meaning they cannot be accessed from
88 // Proc-macro2 types in rustdoc of other crates get linked to here.
89 #![doc(html_root_url = "https://docs.rs/proc-macro2/1.0.92")]
124 is turned on for the compilation of the proc-macro2 \
130 feature = "proc-macro",
139 #[cfg(feature = "proc-macro")]
180 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
203 fn _new(inner: imp::TokenStream) -> Self { in _new()
210 fn _new_fallback(inner: fallback::TokenStream) -> Self { in _new_fallback()
218 pub fn new() -> Self { in new()
223 pub fn is_empty(&self) -> bool { in is_empty()
231 fn default() -> Self { in default()
247 fn from_str(src: &str) -> Result<TokenStream, LexError> { in from_str()
258 #[cfg(feature = "proc-macro")]
259 #[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
261 fn from(inner: proc_macro::TokenStream) -> Self { in from()
266 #[cfg(feature = "proc-macro")]
267 #[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
269 fn from(inner: TokenStream) -> Self { in from()
275 fn from(token: TokenTree) -> Self { in from()
295 fn from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self { in from_iter()
300 fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self { in from_iter()
310 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
317 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
323 pub fn span(&self) -> Span { in span()
329 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
335 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
355 fn _new(inner: imp::SourceFile) -> Self { in _new()
367 /// external macro, this may not be an actual path on the filesystem. Use
371 /// `--remap-path-prefix` was passed on the command line, the path as given
375 pub fn path(&self) -> PathBuf { in path()
380 /// generated by an external macro's expansion.
381 pub fn is_real(&self) -> bool { in is_real()
388 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
393 /// A region of source code, along with macro expansion information.
401 fn _new(inner: imp::Span) -> Self { in _new()
408 fn _new_fallback(inner: fallback::Span) -> Self { in _new_fallback()
415 /// The span of the invocation of the current procedural macro.
418 /// written directly at the macro call location (call-site hygiene) and
419 /// other code at the macro call site will be able to refer to them as well.
420 pub fn call_site() -> Self { in call_site()
424 /// The span located at the invocation of the procedural macro, but with
426 /// of the macro. This is the same hygiene behavior as `macro_rules`.
427 pub fn mixed_site() -> Self { in mixed_site()
431 /// A span that resolves at the macro definition site.
436 pub fn def_site() -> Self { in def_site()
442 pub fn resolved_at(&self, other: Span) -> Span { in resolved_at()
448 pub fn located_at(&self, other: Span) -> Span { in located_at()
459 /// Panics if called from outside of a procedural macro. Unlike
461 /// the context of a procedural macro invocation.
463 pub fn unwrap(self) -> proc_macro::Span { in unwrap()
470 pub fn unstable(self) -> proc_macro::Span { in unstable()
479 pub fn source_file(&self) -> SourceFile { in source_file()
485 /// This method requires the `"span-locations"` feature to be enabled.
487 /// When executing in a procedural macro context, the returned range is only
490 /// procedural macro, such as main.rs or build.rs, the byte range is always
493 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
494 pub fn byte_range(&self) -> Range<usize> { in byte_range()
500 /// This method requires the `"span-locations"` feature to be enabled.
502 /// When executing in a procedural macro context, the returned line/column
505 /// outside of a procedural macro, such as main.rs or build.rs, the
508 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
509 pub fn start(&self) -> LineColumn { in start()
515 /// This method requires the `"span-locations"` feature to be enabled.
517 /// When executing in a procedural macro context, the returned line/column
520 /// outside of a procedural macro, such as main.rs or build.rs, the
523 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
524 pub fn end(&self) -> LineColumn { in end()
533 /// nightly-only. When called from within a procedural macro not using a
536 … /// [`proc_macro::Span::join`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.join
537 pub fn join(&self, other: Span) -> Option<Span> { in join()
546 pub fn eq(&self, other: &Span) -> bool { in eq()
554 /// Note: The observable result of a macro should only rely on the tokens
557 pub fn source_text(&self) -> Option<String> { in source_text()
564 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
585 pub fn span(&self) -> Span { in span()
610 fn from(g: Group) -> Self { in from()
616 fn from(g: Ident) -> Self { in from()
622 fn from(g: Punct) -> Self { in from()
628 fn from(g: Literal) -> Self { in from()
638 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
650 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
688 /// coming from a "macro variable" `$var`. It is important to preserve
696 /// of a proc_macro. Only `None`-delimited groups created by a macro_rules macro in the input
697 /// of a proc_macro macro are preserved, and only in very specific circumstances.
698 /// Any `None`-delimited groups (re)created by a proc_macro will therefore not preserve
701 /// [rust-lang/rust#67062](https://github.com/rust-lang/rust/issues/67062).
708 fn _new(inner: imp::Group) -> Self { in _new()
712 fn _new_fallback(inner: fallback::Group) -> Self { in _new_fallback()
723 pub fn new(delimiter: Delimiter, stream: TokenStream) -> Self { in new()
731 pub fn delimiter(&self) -> Delimiter { in delimiter()
739 pub fn stream(&self) -> TokenStream { in stream()
747 /// pub fn span(&self) -> Span {
750 pub fn span(&self) -> Span { in span()
757 /// pub fn span_open(&self) -> Span {
760 pub fn span_open(&self) -> Span { in span_open()
767 /// pub fn span_close(&self) -> Span {
770 pub fn span_close(&self) -> Span { in span_close()
777 pub fn delim_span(&self) -> DelimSpan { in delim_span()
796 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { in fmt()
802 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { in fmt()
807 /// A `Punct` is a single punctuation character like `+`, `-` or `#`.
839 pub fn new(ch: char, spacing: Spacing) -> Self { in new()
840 if let '!' | '#' | '$' | '%' | '&' | '\'' | '*' | '+' | ',' | '-' | '.' | '/' | ':' | ';' in new()
849 panic!("unsupported proc macro punctuation character {:?}", ch); in new()
854 pub fn as_char(&self) -> char { in as_char()
863 pub fn spacing(&self) -> Spacing { in spacing()
868 pub fn span(&self) -> Span { in span()
881 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
887 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { in fmt()
902 /// - The empty string is not an identifier. Use `Option<Ident>`.
903 /// - A lifetime is not an identifier. Use `syn::Lifetime` instead.
928 /// An ident can be interpolated into a token stream using the `quote!` macro.
967 fn _new(inner: imp::Ident) -> Self { in _new()
974 fn _new_fallback(inner: fallback::Ident) -> Self { in _new_fallback()
990 /// As of this time `Span::call_site()` explicitly opts-in to "call-site"
992 /// as if they were written directly at the location of the macro call, and
993 /// other code at the macro call site will be able to refer to them as well.
995 /// Later spans like `Span::def_site()` will allow to opt-in to
996 /// "definition-site" hygiene meaning that identifiers created with this
997 /// span will be resolved at the location of the macro definition and other
998 /// code at the macro call site will not be able to refer to them.
1009 /// style="padding-right:0;">syn::parse_str</code></a><code
1010 /// style="padding-left:0;">::<Ident></code>
1013 pub fn new(string: &str, span: Span) -> Self { in new()
1023 pub fn new_raw(string: &str, span: Span) -> Self { in new_raw()
1028 pub fn span(&self) -> Span { in span()
1040 fn eq(&self, other: &Ident) -> bool { in eq()
1049 fn eq(&self, other: &T) -> bool { in eq()
1057 fn partial_cmp(&self, other: &Ident) -> Option<Ordering> { in partial_cmp()
1063 fn cmp(&self, other: &Ident) -> Ordering { in cmp()
1077 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
1083 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
1108 /// broken into two tokens (`-` and positive literal).
1113 pub fn $name(n: $kind) -> Literal {
1129 /// be broken into two tokens (`-` and positive literal).
1134 pub fn $name(n: $kind) -> Literal {
1141 fn _new(inner: imp::Literal) -> Self { in _new()
1148 fn _new_fallback(inner: fallback::Literal) -> Self { in _new_fallback()
1185 /// Creates a new unsuffixed floating-point literal.
1190 /// Literals created from negative numbers may not survive round-trips
1191 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1198 pub fn f64_unsuffixed(f: f64) -> Literal { in f64_unsuffixed()
1203 /// Creates a new suffixed floating-point literal.
1209 /// round-trips through `TokenStream` or strings and may be broken into two
1210 /// tokens (`-` and positive literal).
1216 pub fn f64_suffixed(f: f64) -> Literal { in f64_suffixed()
1221 /// Creates a new unsuffixed floating-point literal.
1226 /// Literals created from negative numbers may not survive round-trips
1227 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1234 pub fn f32_unsuffixed(f: f32) -> Literal { in f32_unsuffixed()
1239 /// Creates a new suffixed floating-point literal.
1245 /// round-trips through `TokenStream` or strings and may be broken into two
1246 /// tokens (`-` and positive literal).
1252 pub fn f32_suffixed(f: f32) -> Literal { in f32_suffixed()
1258 pub fn string(string: &str) -> Literal { in string()
1263 pub fn character(ch: char) -> Literal { in character()
1268 pub fn byte_character(byte: u8) -> Literal { in byte_character()
1273 pub fn byte_string(bytes: &[u8]) -> Literal { in byte_string()
1278 pub fn c_string(string: &CStr) -> Literal { in c_string()
1283 pub fn span(&self) -> Span { in span()
1293 /// the source bytes in range `range`. Returns `None` if the would-be
1297 /// nightly-only. When called from within a procedural macro not using a
1300 …/// [`proc_macro::Literal::subspan`]: https://doc.rust-lang.org/proc_macro/struct.Literal.html#met…
1301 pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> { in subspan()
1305 // Intended for the `quote!` macro to use when constructing a proc-macro2
1308 // representation. This is not public API other than for quote.
1310 pub unsafe fn from_str_unchecked(repr: &str) -> Self { in from_str_unchecked()
1318 fn from_str(repr: &str) -> Result<Self, LexError> { in from_str()
1330 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
1336 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
1362 fn next(&mut self) -> Option<TokenTree> { in next()
1366 fn size_hint(&self) -> (usize, Option<usize>) { in size_hint()
1372 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { in fmt()
1382 fn into_iter(self) -> IntoIter { in into_iter()