graph_api_lib/walker/steps/
dbg.rs

1use crate::walker::builder::{EdgeWalkerBuilder, VertexWalkerBuilder};
2use crate::walker::steps::{EdgeProbe, VertexProbe};
3use crate::walker::{EdgeWalker, VertexWalker};
4use include_doc::function_body;
5use std::fmt::Debug;
6
7impl<'graph, Mutability, Graph, Walker> VertexWalkerBuilder<'graph, Mutability, Graph, Walker>
8where
9    Graph: crate::graph::Graph,
10    Walker: VertexWalker<'graph, Graph = Graph>,
11{
12    /// # Debug Step
13    ///
14    /// The `dbg` step prints elements as they are traversed through the graph, making it
15    /// easier to debug complex traversals. Each element is tagged with the provided label.
16    ///
17    /// ## Visual Diagram
18    ///
19    /// Before dbg step:
20    /// ```text
21    ///   [A]* --- edge1 ---> [B]* --- edge2 ---> [C]*  
22    ///    ^                                         
23    ///    |                                         
24    ///   edge3                                       
25    ///    |                                         
26    ///   [D]*                                        
27    /// ```
28    ///
29    /// After dbg step (elements continue in traversal, but are also printed to console):
30    /// ```text
31    ///   [A]* --- edge1 ---> [B]* --- edge2 ---> [C]*  
32    ///    ^                                         
33    ///    |                                         
34    ///   edge3                                       
35    ///    |                                         
36    ///   [D]*                                        
37    ///
38    ///   Console output:
39    ///   [stage1] Vertex(A)
40    ///   [stage1] Vertex(B)
41    ///   [stage1] Vertex(C)
42    ///   [stage1] Vertex(D)
43    /// ```
44    ///
45    /// ## Parameters
46    ///
47    /// - `tag`: A string label that will prefix all debug output to help identify which debug step is printing
48    ///
49    /// ## Return Value
50    ///
51    /// Returns the same traversal that was passed in, allowing the traversal to continue unmodified.
52    ///
53    /// ## Example
54    ///
55    /// ```rust
56    #[doc = function_body!("examples/dbg.rs", basic_example, [])]
57    /// ```
58    ///
59    /// ## Notes
60    ///
61    /// - The `dbg` step is non-destructive - it does not modify the traversal path
62    /// - Debug output goes to the console using the standard Debug trait implementation
63    /// - Remember that traversals are typically depth-first, so the output order may not be immediately intuitive
64    /// - For complex graphs, consider using more descriptive tags at each debug point
65    /// - This step is particularly useful for understanding how graph elements flow through a complex traversal
66    /// - The `dbg` step has minimal performance impact when not in debug mode
67    pub fn dbg(
68        self,
69        tag: &'static str,
70    ) -> VertexWalkerBuilder<
71        'graph,
72        Mutability,
73        Graph,
74        VertexProbe<'graph, Walker, impl FnMut(&Graph::VertexReference<'_>, &Walker::Context)>,
75    >
76    where
77        Walker::Context: Debug,
78    {
79        let callback = move |vertex: &Graph::VertexReference<'_>, ctx: &Walker::Context| {
80            println!("{}: {:?} {:?}", tag, vertex, ctx);
81        };
82        self.probe(callback)
83    }
84}
85
86impl<'graph, Mutability, Graph, Walker> EdgeWalkerBuilder<'graph, Mutability, Graph, Walker>
87where
88    Graph: crate::graph::Graph,
89    Walker: EdgeWalker<'graph, Graph = Graph>,
90{
91    /// # Debug Step
92    ///
93    /// Prints edges as they are traversed through the graph, making it easier to debug complex traversals.
94    ///
95    /// See the documentation for [`VertexWalkerBuilder::dbg`] for more details.
96    pub fn dbg(
97        self,
98        tag: &'static str,
99    ) -> EdgeWalkerBuilder<
100        'graph,
101        Mutability,
102        Graph,
103        EdgeProbe<'graph, Walker, impl FnMut(&Graph::EdgeReference<'_>, &Walker::Context)>,
104    >
105    where
106        Walker::Context: Debug,
107    {
108        let callback = move |edge: &Graph::EdgeReference<'_>, ctx: &Walker::Context| {
109            println!("{}: {:?} {:?}", tag, edge, ctx);
110        };
111        self.probe(callback)
112    }
113}
graph_api_lib/walker/steps/dbg.rs

graph_api_lib/walker/steps/
dbg.rs
