leo_ast/
lib.rs

1// Copyright (C) 2019-2025 Provable Inc.
2// This file is part of the Leo library.
3
4// The Leo library is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// The Leo library is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
16
17//! The abstract syntax tree (ast) for a Leo program.
18//!
19//! This module contains the [`Ast`] type, a wrapper around the [`Program`] type.
20//! The [`Ast`] type is intended to be parsed and modified by different passes
21//! of the Leo compiler. The Leo compiler can generate a set of R1CS constraints from any [`Ast`].
22
23#![allow(ambiguous_glob_reexports)]
24
25mod r#struct;
26pub use self::r#struct::*;
27
28pub mod common;
29pub use self::common::*;
30
31pub mod constructor;
32pub use self::constructor::*;
33
34mod expressions;
35pub use self::expressions::*;
36
37mod functions;
38pub use self::functions::*;
39
40mod indent_display;
41use indent_display::*;
42
43pub mod interpreter_value;
44
45mod mapping;
46pub use self::mapping::*;
47
48mod module;
49pub use self::module::*;
50
51mod passes;
52pub use self::passes::*;
53
54mod program;
55pub use self::program::*;
56
57mod statement;
58pub use self::statement::*;
59
60mod types;
61pub use self::types::*;
62
63mod stub;
64pub use self::stub::*;
65
66pub use common::node::*;
67
68use leo_errors::{AstError, Result};
69
70/// The abstract syntax tree (AST) for a Leo program.
71///
72/// The [`Ast`] type represents a Leo program as a series of recursive data types.
73/// These data types form a tree that begins from a [`Program`] type root.
74#[derive(Clone, Debug, Default, Eq, PartialEq)]
75pub struct Ast {
76    pub ast: Program,
77}
78
79impl Ast {
80    /// Creates a new AST from a given program tree.
81    pub fn new(program: Program) -> Self {
82        Self { ast: program }
83    }
84
85    /// Returns a reference to the inner program AST representation.
86    pub fn as_repr(&self) -> &Program {
87        &self.ast
88    }
89
90    pub fn into_repr(self) -> Program {
91        self.ast
92    }
93
94    /// Serializes the ast into a JSON string.
95    pub fn to_json_string(&self) -> Result<String> {
96        Ok(serde_json::to_string_pretty(&self.ast).map_err(|e| AstError::failed_to_convert_ast_to_json_string(&e))?)
97    }
98
99    // Converts the ast into a JSON value.
100    // Note that there is no corresponding `from_json_value` function
101    // since we modify JSON values leaving them unable to be converted
102    // back into Programs.
103    pub fn to_json_value(&self) -> Result<serde_json::Value> {
104        Ok(serde_json::to_value(&self.ast).map_err(|e| AstError::failed_to_convert_ast_to_json_value(&e))?)
105    }
106
107    /// Serializes the ast into a JSON file.
108    pub fn to_json_file(&self, mut path: std::path::PathBuf, file_name: &str) -> Result<()> {
109        path.push(file_name);
110        let file = std::fs::File::create(&path).map_err(|e| AstError::failed_to_create_ast_json_file(&path, &e))?;
111        let writer = std::io::BufWriter::new(file);
112        Ok(serde_json::to_writer_pretty(writer, &self.ast)
113            .map_err(|e| AstError::failed_to_write_ast_to_json_file(&path, &e))?)
114    }
115
116    /// Serializes the ast into a JSON value and removes keys from object mappings before writing to a file.
117    pub fn to_json_file_without_keys(
118        &self,
119        mut path: std::path::PathBuf,
120        file_name: &str,
121        excluded_keys: &[&str],
122    ) -> Result<()> {
123        path.push(file_name);
124        let file = std::fs::File::create(&path).map_err(|e| AstError::failed_to_create_ast_json_file(&path, &e))?;
125        let writer = std::io::BufWriter::new(file);
126
127        let mut value = self.to_json_value().unwrap();
128        for key in excluded_keys {
129            value = remove_key_from_json(value, key);
130        }
131        value = normalize_json_value(value);
132
133        Ok(serde_json::to_writer_pretty(writer, &value)
134            .map_err(|e| AstError::failed_to_write_ast_to_json_file(&path, &e))?)
135    }
136
137    /// Deserializes the JSON string into a ast.
138    pub fn from_json_string(json: &str) -> Result<Self> {
139        let ast: Program = serde_json::from_str(json).map_err(|e| AstError::failed_to_read_json_string_to_ast(&e))?;
140        Ok(Self { ast })
141    }
142
143    /// Deserializes the JSON string into a ast from a file.
144    pub fn from_json_file(path: std::path::PathBuf) -> Result<Self> {
145        let data = std::fs::read_to_string(&path).map_err(|e| AstError::failed_to_read_json_file(&path, &e))?;
146        Self::from_json_string(&data)
147    }
148}
149
150impl AsRef<Program> for Ast {
151    fn as_ref(&self) -> &Program {
152        &self.ast
153    }
154}
155
156/// Helper function to recursively filter keys from AST JSON
157pub fn remove_key_from_json(value: serde_json::Value, key: &str) -> serde_json::Value {
158    match value {
159        serde_json::Value::Object(map) => serde_json::Value::Object(
160            map.into_iter().filter(|(k, _)| k != key).map(|(k, v)| (k, remove_key_from_json(v, key))).collect(),
161        ),
162        serde_json::Value::Array(values) => {
163            serde_json::Value::Array(values.into_iter().map(|v| remove_key_from_json(v, key)).collect())
164        }
165        _ => value,
166    }
167}
168
169/// Helper function to normalize AST JSON into a form compatible with tgc.
170/// This function will traverse the original JSON value and produce a new
171/// one under the following rules:
172/// 1. Remove empty object mappings from JSON arrays
173/// 2. If there are two elements in a JSON array and one is an empty object
174///    mapping and the other is not, then lift up the one that isn't
175pub fn normalize_json_value(value: serde_json::Value) -> serde_json::Value {
176    match value {
177        serde_json::Value::Array(vec) => {
178            let orig_length = vec.len();
179            let mut new_vec: Vec<serde_json::Value> = vec
180                .into_iter()
181                .filter(|v| !matches!(v, serde_json::Value::Object(map) if map.is_empty()))
182                .map(normalize_json_value)
183                .collect();
184
185            if orig_length == 2 && new_vec.len() == 1 {
186                new_vec.pop().unwrap()
187            } else {
188                serde_json::Value::Array(new_vec)
189            }
190        }
191        serde_json::Value::Object(map) => {
192            serde_json::Value::Object(map.into_iter().map(|(k, v)| (k, normalize_json_value(v))).collect())
193        }
194        _ => value,
195    }
196}
leo_ast/lib.rs

leo_ast/
lib.rs
