1#![allow(missing_docs)]
2
3//! Document tree traversal to walk a shared borrow of a document tree.
4//!
5//! Each method of the [`Visit`] trait is a hook that can be overridden
6//! to customize the behavior when mutating the corresponding type of node.
7//! By default, every method recursively visits the substructure of the
8//! input by invoking the right visitor method of each of its fields.
9//!
10//! ```
11//! # use toml_edit::{Item, ArrayOfTables, Table, Value};
12//!
13//! pub trait Visit<'doc> {
14//! /* ... */
15//!
16//! fn visit_item(&mut self, i: &'doc Item) {
17//! visit_item(self, i);
18//! }
19//!
20//! /* ... */
21//! # fn visit_value(&mut self, i: &'doc Value);
22//! # fn visit_table(&mut self, i: &'doc Table);
23//! # fn visit_array_of_tables(&mut self, i: &'doc ArrayOfTables);
24//! }
25//!
26//! pub fn visit_item<'doc, V>(v: &mut V, node: &'doc Item)
27//! where
28//! V: Visit<'doc> + ?Sized,
29//! {
30//! match node {
31//! Item::None => {}
32//! Item::Value(value) => v.visit_value(value),
33//! Item::Table(table) => v.visit_table(table),
34//! Item::ArrayOfTables(array) => v.visit_array_of_tables(array),
35//! }
36//! }
37//! ```
38//!
39//! The API is modeled after [`syn::visit`](https://docs.rs/syn/1/syn/visit).
40//!
41//! # Examples
42//!
43//! This visitor stores every string in the document.
44//!
45//! ```
46//! # #[cfg(feature = "parse")] {
47//! # use toml_edit::*;
48//! use toml_edit::visit::*;
49//!
50//! #[derive(Default)]
51//! struct StringCollector<'doc> {
52//! strings: Vec<&'doc str>,
53//! }
54//!
55//! impl<'doc> Visit<'doc> for StringCollector<'doc> {
56//! fn visit_string(&mut self, node: &'doc Formatted<String>) {
57//! self.strings.push(node.value().as_str());
58//! }
59//! }
60//!
61//! let input = r#"
62//! laputa = "sky-castle"
63//! the-force = { value = "surrounds-you" }
64//! "#;
65//!
66//! let mut document: Document = input.parse().unwrap();
67//! let mut visitor = StringCollector::default();
68//! visitor.visit_document(&document);
69//!
70//! assert_eq!(visitor.strings, vec!["sky-castle", "surrounds-you"]);
71//! # }
72//! ```
73//!
74//! For a more complex example where the visitor has internal state, see `examples/visit.rs`
75//! [on GitHub](https://github.com/toml-rs/toml/blob/main/crates/toml_edit/examples/visit.rs).
76
77use crate::{
78 Array, ArrayOfTables, Datetime, Document, Formatted, InlineTable, Item, Table, TableLike, Value,
79};
80
81/// Document tree traversal to mutate an exclusive borrow of a document tree in-place.
82///
83/// See the [module documentation](self) for details.
84pub trait Visit<'doc> {
85 fn visit_document(&mut self, node: &'doc Document) {
86 visit_document(self, node);
87 }
88
89 fn visit_item(&mut self, node: &'doc Item) {
90 visit_item(self, node);
91 }
92
93 fn visit_table(&mut self, node: &'doc Table) {
94 visit_table(self, node);
95 }
96
97 fn visit_inline_table(&mut self, node: &'doc InlineTable) {
98 visit_inline_table(self, node)
99 }
100
101 fn visit_table_like(&mut self, node: &'doc dyn TableLike) {
102 visit_table_like(self, node);
103 }
104
105 fn visit_table_like_kv(&mut self, key: &'doc str, node: &'doc Item) {
106 visit_table_like_kv(self, key, node);
107 }
108
109 fn visit_array(&mut self, node: &'doc Array) {
110 visit_array(self, node);
111 }
112
113 fn visit_array_of_tables(&mut self, node: &'doc ArrayOfTables) {
114 visit_array_of_tables(self, node);
115 }
116
117 fn visit_value(&mut self, node: &'doc Value) {
118 visit_value(self, node);
119 }
120
121 fn visit_boolean(&mut self, node: &'doc Formatted<bool>) {
122 visit_boolean(self, node)
123 }
124
125 fn visit_datetime(&mut self, node: &'doc Formatted<Datetime>) {
126 visit_datetime(self, node);
127 }
128
129 fn visit_float(&mut self, node: &'doc Formatted<f64>) {
130 visit_float(self, node)
131 }
132
133 fn visit_integer(&mut self, node: &'doc Formatted<i64>) {
134 visit_integer(self, node)
135 }
136
137 fn visit_string(&mut self, node: &'doc Formatted<String>) {
138 visit_string(self, node)
139 }
140}
141
142pub fn visit_document<'doc, V>(v: &mut V, node: &'doc Document)
143where
144 V: Visit<'doc> + ?Sized,
145{
146 v.visit_table(node:node.as_table());
147}
148
149pub fn visit_item<'doc, V>(v: &mut V, node: &'doc Item)
150where
151 V: Visit<'doc> + ?Sized,
152{
153 match node {
154 Item::None => {}
155 Item::Value(value: &Value) => v.visit_value(node:value),
156 Item::Table(table: &Table) => v.visit_table(node:table),
157 Item::ArrayOfTables(array: &ArrayOfTables) => v.visit_array_of_tables(node:array),
158 }
159}
160
161pub fn visit_table<'doc, V>(v: &mut V, node: &'doc Table)
162where
163 V: Visit<'doc> + ?Sized,
164{
165 v.visit_table_like(node)
166}
167
168pub fn visit_inline_table<'doc, V>(v: &mut V, node: &'doc InlineTable)
169where
170 V: Visit<'doc> + ?Sized,
171{
172 v.visit_table_like(node)
173}
174
175pub fn visit_table_like<'doc, V>(v: &mut V, node: &'doc dyn TableLike)
176where
177 V: Visit<'doc> + ?Sized,
178{
179 for (key: &str, item: &Item) in node.iter() {
180 v.visit_table_like_kv(key, node:item)
181 }
182}
183
184pub fn visit_table_like_kv<'doc, V>(v: &mut V, _key: &'doc str, node: &'doc Item)
185where
186 V: Visit<'doc> + ?Sized,
187{
188 v.visit_item(node)
189}
190
191pub fn visit_array<'doc, V>(v: &mut V, node: &'doc Array)
192where
193 V: Visit<'doc> + ?Sized,
194{
195 for value: &Value in node.iter() {
196 v.visit_value(node:value);
197 }
198}
199
200pub fn visit_array_of_tables<'doc, V>(v: &mut V, node: &'doc ArrayOfTables)
201where
202 V: Visit<'doc> + ?Sized,
203{
204 for table: &Table in node.iter() {
205 v.visit_table(node:table);
206 }
207}
208
209pub fn visit_value<'doc, V>(v: &mut V, node: &'doc Value)
210where
211 V: Visit<'doc> + ?Sized,
212{
213 match node {
214 Value::String(s: &Formatted) => v.visit_string(node:s),
215 Value::Integer(i: &Formatted) => v.visit_integer(node:i),
216 Value::Float(f: &Formatted) => v.visit_float(node:f),
217 Value::Boolean(b: &Formatted) => v.visit_boolean(node:b),
218 Value::Datetime(dt: &Formatted) => v.visit_datetime(node:dt),
219 Value::Array(array: &Array) => v.visit_array(node:array),
220 Value::InlineTable(table: &InlineTable) => v.visit_inline_table(node:table),
221 }
222}
223
224macro_rules! empty_visit {
225 ($name: ident, $t: ty) => {
226 fn $name<'doc, V>(_v: &mut V, _node: &'doc $t)
227 where
228 V: Visit<'doc> + ?Sized,
229 {
230 }
231 };
232}
233
234empty_visit!(visit_boolean, Formatted<bool>);
235empty_visit!(visit_datetime, Formatted<Datetime>);
236empty_visit!(visit_float, Formatted<f64>);
237empty_visit!(visit_integer, Formatted<i64>);
238empty_visit!(visit_string, Formatted<String>);
239