Skip to main content

parsyng_core/
lib.rs

1//! Core parsing and quoting primitives for `parsyng`.
2//!
3//! This crate provides the token-stream wrapper, parsing traits, AST types,
4//! and quote helpers used by the proc-macro front-end.
5
6#![cfg_attr(docsrs, feature(doc_cfg))]
7#![deny(
8    clippy::all,
9    clippy::pedantic,
10    clippy::nursery,
11    clippy::cargo,
12    rustdoc::all,
13    rustdoc::redundant_explicit_links,
14    invalid_doc_attributes,
15    unused_doc_comments,
16    missing_docs
17    // rustdoc::missing_doc_code_examples,
18)]
19// The docs link to the whole grammar, part of which is behind `full`.
20#![cfg_attr(not(feature = "full"), allow(rustdoc::broken_intra_doc_links))]
21#![allow(
22    clippy::option_if_let_else,
23    clippy::same_functions_in_if_condition,
24    clippy::too_many_lines
25)]
26
27// Put proc_macro in a private module to avoid being able to use `proc_macro::...` directly in this crate
28// This way the `fallback` feature works out of the box.
29#[cfg(not(feature = "fallback"))]
30mod sealed {
31    pub extern crate proc_macro;
32}
33#[cfg(not(feature = "fallback"))]
34pub use sealed::proc_macro;
35
36/// The token types: the compiler's `proc_macro`, or `parsyng_fallback` with
37/// the `fallback` feature.
38#[cfg(feature = "fallback")]
39pub use parsyng_fallback as proc_macro;
40
41#[cfg(feature = "parsing")]
42pub mod ast;
43#[cfg(feature = "parsing")]
44pub mod combinator;
45pub mod error;
46#[cfg(feature = "parsing")]
47pub mod parse;
48/// Helpers for proc-macro specific token manipulation.
49pub mod proc_macro_ext;
50/// Quote-related token construction helpers and macros.
51#[doc(hidden)]
52pub mod quote;
53
54#[cfg(feature = "parsing")]
55pub use parse::Parse;
56
57/// Build an [`Ident`](crate::proc_macro::Ident) using `format!`-style syntax,
58/// spanned at [`Span::call_site`](crate::proc_macro::Span::call_site).
59///
60/// ```
61/// # use parsyng_core as parsyng;
62/// use parsyng::format_ident;
63///
64/// let index = 3;
65/// let ident = format_ident!("field_{}", index); // `field_3`
66/// # assert_eq!(ident.to_string(), "field_3");
67/// ```
68#[macro_export]
69macro_rules! format_ident {
70    ($($args:tt)*) => {
71        $crate::proc_macro::Ident::new(&format!($($args)*), $crate::proc_macro::Span::call_site())
72    };
73}
74
75/// A type that can be appended to a [`TokenStream`](crate::proc_macro::TokenStream).
76///
77/// This is the counterpart to [`Parse`]: every [`ast`] node, and
78/// every combinator it is built from, implements `ToTokens` so it can be fed
79/// straight into `quote!`'s `#interpolation` or converted to a stand-alone
80/// token stream with [`to_token_stream`](Self::to_token_stream). The
81/// `#[derive(ToTokens)]` macro (exported from `parsyng-proc-macros`, and
82/// re-exported at the top of the `parsyng` facade crate) implements it
83/// automatically for structs whose fields are all themselves `ToTokens`.
84pub trait ToTokens {
85    /// Append this value's tokens to the end of `tokens`.
86    fn to_tokens(&self, tokens: &mut crate::proc_macro::TokenStream);
87
88    /// Convert this value into a new, stand-alone token stream.
89    fn to_token_stream(&self) -> crate::proc_macro::TokenStream {
90        let mut token_stream = crate::proc_macro::TokenStream::new();
91        self.to_tokens(&mut token_stream);
92        token_stream
93    }
94}
95
96/// The index of a tuple field, turning into an *unsuffixed* integer literal.
97///
98/// Interpolating a plain `usize` in `quote!` produces a suffixed literal
99/// (`0usize`), which is not a valid field name: use `Index` to generate
100/// `self.0`-style accesses instead.
101///
102/// ```
103/// # use parsyng_core as parsyng;
104/// use parsyng::Index;
105/// # use parsyng_quote_macros::quote;
106///
107/// let mut fields = (0..3).map(Index::from);
108/// let sum = quote! { 0 #(+ self.#fields)* }; // `0 + self.0 + self.1 + self.2`
109/// # assert_eq!(sum.to_string(), "0 + self .0 + self .1 + self .2");
110/// ```
111#[derive(Clone, Copy, Debug)]
112pub struct Index {
113    /// The field's position.
114    pub index: usize,
115    /// The span of the generated literal.
116    pub span: crate::proc_macro::Span,
117}
118
119impl From<usize> for Index {
120    fn from(index: usize) -> Self {
121        Self {
122            index,
123            span: crate::proc_macro::Span::call_site(),
124        }
125    }
126}
127
128impl ToTokens for Index {
129    fn to_tokens(&self, tokens: &mut crate::proc_macro::TokenStream) {
130        let mut literal = crate::proc_macro::Literal::usize_unsuffixed(self.index);
131        literal.set_span(self.span);
132        tokens.extend(Some(crate::proc_macro::TokenTree::Literal(literal)));
133    }
134}
135
136#[doc(hidden)]
137/// Print the generated output of a proc-macro when debug mode is enabled.
138pub fn debug_stream(macro_name: &str, call_location: &str, input: &crate::proc_macro::TokenStream) {
139    let output;
140    #[cfg(feature = "debug-pretty")]
141    {
142        use std::{
143            io::Write,
144            path::PathBuf,
145            process::{Command, Stdio},
146        };
147
148        fn catch_rustfmt_errors(input: &crate::proc_macro::TokenStream) -> Option<String> {
149            // Wrap the input in a dummy function, otherwise statements like `let` can't be formatted
150            let prefix = "fn __dummy() {\n";
151            let suffix = "\n}";
152            let input = format!("{prefix}{input}{suffix}");
153
154            let cargo = PathBuf::from(std::option_env!("CARGO")?);
155            let mut rustfmt = cargo.parent()?.to_owned();
156            rustfmt.push("rustfmt");
157
158            let mut command = Command::new(rustfmt);
159            let command = command.stdin(Stdio::piped()).stdout(Stdio::piped());
160            let mut exec = command.spawn().ok()?;
161            exec.stdin.take()?.write_all(input.as_bytes()).unwrap();
162            let output = exec.wait_with_output().ok().and_then(|output| {
163                if output.status.success() {
164                    String::from_utf8(output.stdout).ok()
165                } else {
166                    None
167                }
168            })?;
169
170            let output = output
171                .trim()
172                .strip_prefix(prefix)?
173                .strip_suffix(suffix)?
174                .trim();
175            let output = output.replace("\n    ", "\n");
176
177            Some(output)
178        }
179
180        output = catch_rustfmt_errors(input).unwrap_or_else(|| input.to_string());
181    }
182    #[cfg(not(feature = "debug-pretty"))]
183    {
184        output = input;
185    }
186    eprintln!("[DEBUG] proc-macro `{macro_name}` called at {call_location}\n{output}");
187}