qubit_json/value/traverse/
json_tree_mut_visitor.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Defines callbacks for mutable JSON tree processing.
9
10use serde_json::Value;
11
12use super::JsonTreeContext;
13use super::JsonTreeControl;
14
15/// Mutates JSON nodes after the complete input tree has passed admission.
16///
17/// Output admission runs only after every visitor callback succeeds. Returning
18/// [`JsonTreeControl::SkipSubtree`] skips descendant callbacks but does not
19/// skip final output accounting.
20///
21/// # Examples
22///
23/// ```
24/// use qubit_json::value::traverse::{
25///     JsonTreeContext, JsonTreeControl, JsonTreeMutVisitor,
26/// };
27/// use serde_json::Value;
28///
29/// struct Visitor;
30/// impl JsonTreeMutVisitor for Visitor {
31///     type Error = std::convert::Infallible;
32///
33///     fn visit(
34///         &mut self,
35///         value: &mut Value,
36///         _: JsonTreeContext<'_>,
37///     ) -> Result<JsonTreeControl, Self::Error> {
38///         *value = Value::Null;
39///         Ok(JsonTreeControl::SkipSubtree)
40///     }
41/// }
42///
43/// let _visitor = Visitor;
44/// ```
45pub trait JsonTreeMutVisitor {
46    /// Domain-specific failure returned by this visitor.
47    type Error;
48
49    /// Mutates one node and selects whether descendant callbacks run.
50    ///
51    /// # Parameters
52    ///
53    /// * `value` - Current node available for mutation.
54    /// * `context` - Root-relative location and depth of the node.
55    ///
56    /// # Returns
57    ///
58    /// The traversal control decision for descendant callbacks.
59    fn visit(&mut self, value: &mut Value, context: JsonTreeContext<'_>) -> Result<JsonTreeControl, Self::Error>;
60}
qubit_json/value/traverse/json_tree_mut_visitor.rs

qubit_json/value/traverse/
json_tree_mut_visitor.rs
