m2_syn/
parsed_file.rs

1//! Convenient ownership and projection of one parsed Macaulay2 source file.
2//!
3//! [`ParsedFile`] is the high-level entry point for applications that do not
4//! need to assemble the lexer and parser pipeline themselves. It owns the
5//! generated typed [`SourceFile`] and exposes fresh projections of that tree as
6//! tokens, cells, normalized source, or indented debug output. The typed CST is
7//! the sole mutable representation, so changing it cannot leave a cached token
8//! stream out of sync.
9
10use std::fmt::{Display, Formatter};
11use std::io;
12
13use crate::pretty::{
14    PrettyOptions, PrettyReport, PrettyTree, format_tokens, format_tree, print_report,
15};
16use crate::{
17    CellStream, Lex, NativeParseError, SourceFile, Span, Spanned, TokenStream, parse_native,
18};
19#[cfg(feature = "tree-sitter")]
20use crate::{ParseError, parse_file};
21
22/// An owned typed CST together with the original input.
23///
24/// With the `tree-sitter` feature, `from_source` selects that adapter;
25/// [`ParsedFile::from_source_native`] always selects the direct precedence
26/// parser. After parsing, callers may mutate [`Self::cst_mut`] or use
27/// [`Self::edit`], then project the resulting tree through
28/// [`Self::token_stream`] or [`Self::to_source`].
29///
30/// The original string is retained as an immutable snapshot for diagnostics.
31/// Cell and source-file comment ownership is retained by the typed graph;
32/// source-backed layout is recovered from spans during emission.
33#[derive(Debug)]
34pub struct ParsedFile {
35    /// The original source.
36    original_source: String,
37    /// The CST.
38    cst: SourceFile,
39}
40
41impl ParsedFile {
42    /// Parses source with the Tree-sitter adapter.
43    ///
44    /// # Errors
45    ///
46    /// Returns [`ParseError`] when Tree-sitter rejects the source or typed
47    /// migration fails.
48    #[cfg(feature = "tree-sitter")]
49    pub fn from_source(source: impl Into<String>) -> Result<Self, ParseError> {
50        let original_source = source.into();
51        let cst = parse_file(&original_source)?;
52        Ok(Self {
53            original_source,
54            cst,
55        })
56    }
57
58    /// Parses source with the native precedence parser.
59    ///
60    /// # Errors
61    ///
62    /// Returns [`NativeParseError`] when lexing or native parsing fails.
63    pub fn from_source_native(source: impl Into<String>) -> Result<Self, NativeParseError> {
64        let original_source = source.into();
65        let cst = parse_native(&original_source)?;
66        Ok(Self {
67            original_source,
68            cst,
69        })
70    }
71
72    /// Returns the input snapshot exactly as supplied to the parser.
73    pub fn original_source(&self) -> &str {
74        &self.original_source
75    }
76
77    /// Borrows the generated typed CST root.
78    pub fn cst(&self) -> &SourceFile {
79        &self.cst
80    }
81
82    /// Mutably borrows the generated typed CST root.
83    pub fn cst_mut(&mut self) -> &mut SourceFile {
84        &mut self.cst
85    }
86
87    /// Applies an edit and returns the file for further method chaining.
88    pub fn edit(mut self, edit: impl FnOnce(&mut SourceFile)) -> Self {
89        edit(&mut self.cst);
90        self
91    }
92
93    /// Consumes the facade and returns its generated typed CST.
94    pub fn into_cst(self) -> SourceFile {
95        self.cst
96    }
97
98    /// Flattens the current CST into one token stream.
99    pub fn token_stream(&self) -> TokenStream {
100        self.cst.to_token_stream()
101    }
102
103    /// Projects the current CST as independently parseable cells.
104    ///
105    /// This is the normal macro-facing representation after tokenisation. Use
106    /// [`Self::token_stream`] when a function-like transformation intentionally
107    /// needs the less structured lexical representation.
108    pub fn cell_stream(&self) -> CellStream {
109        CellStream::from_source_file(&self.cst)
110    }
111
112    /// Emits the current CST as normalized Macaulay2 source.
113    pub fn to_source(&self) -> String {
114        self.cell_stream().to_string()
115    }
116
117    /// Formats the current raw token representation as a recursively flattened
118    /// table with explicit group boundaries.
119    pub fn pretty_tokens(&self) -> String {
120        format_tokens(&self.token_stream(), PrettyOptions::PLAIN)
121    }
122
123    /// Formats the complete generated typed CST as a Unicode tree.
124    pub fn pretty_cst(&self) -> String {
125        format_tree(&self.cst.pretty_tree(), PrettyOptions::PLAIN)
126    }
127
128    /// Builds a combined source, flat-token, and typed-CST inspection report.
129    pub fn pretty_report(&self) -> PrettyReport<'_> {
130        PrettyReport::new(
131            &self.original_source,
132            self.token_stream(),
133            self.cst.pretty_tree(),
134        )
135    }
136
137    /// Prints the combined report to standard output, enabling ANSI styling
138    /// only when standard output is an interactive terminal.
139    ///
140    /// # Errors
141    ///
142    /// Returns an I/O error when standard output cannot be written.
143    pub fn print_pretty(&self) -> io::Result<()> {
144        print_report(self.pretty_report())
145    }
146}
147
148impl AsRef<SourceFile> for ParsedFile {
149    fn as_ref(&self) -> &SourceFile {
150        self.cst()
151    }
152}
153
154impl AsMut<SourceFile> for ParsedFile {
155    fn as_mut(&mut self) -> &mut SourceFile {
156        self.cst_mut()
157    }
158}
159
160impl Display for ParsedFile {
161    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
162        self.cell_stream().fmt(formatter)
163    }
164}
165
166impl Spanned for ParsedFile {
167    fn span(&self) -> Span {
168        self.cst.span()
169    }
170}
171
172impl Lex for ParsedFile {
173    fn to_tokens(&self, output: &mut TokenStream) {
174        self.cst.to_tokens(output);
175    }
176}
m2_syn/parsed_file.rs

m2_syn/
parsed_file.rs
