allow Node::walk_* functions to terminate early

This commit adds a Result<> to all walk callbacks.

In order to use this, you should change all `Node::walk_*` methods
in your code the following way:

```rust
// replace this:
node.walk(|node, _| {
    dbg!(node);
});

// with this (unwrap is safe here because walk only
// returns error when your function does):
node.walk(|node, _| {
    dbg!(node);
    Ok(())
}).unwrap();
```

Author: rlidwka

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.0 - WIP
+
+### Added
+
+ - added `md.try_parse()` function which may return an error, as opposed to existing
+   `md.parse()` function which never does
+
+ - added optional `try_run()` trait function for rules which can fail and will
+   propagate errors when using `md.try_parse()`
+
+### Changed
+
+ - `Node::walk_*` methods now return `Result`, which allows you to terminate traversing early
+
+### Migration
+
+For all `Node::walk_*` methods change the following:
+
+```rust
+// replace this:
+node.walk(|node, _| {
+    dbg!(node);
+});
+
+// with this (unwrap is safe here because walk only
+// returns error when your function does):
+node.walk(|node, _| {
+    dbg!(node);
+    Ok(())
+}).unwrap();
+```
+
 ## 0.5.0 - 2023-05-13
 
 ### Added

examples/ferris/core_rule.rs

@@ -51,7 +51,8 @@ impl CoreRule for FerrisCounterRule {
             if node.is::<InlineFerris>() || node.is::<BlockFerris>() {
                 counter += 1;
             }
-        });
+            Ok(())
+        }).unwrap();
 
         // append a counter to the root as a custom node
         root.children.push(Node::new(FerrisCounter(counter)))

src/bin.rs

@@ -93,7 +93,8 @@ fn main() {
             } else {
                 println!("{name}");
             }
-        });
+            Ok(())
+        }).unwrap();
         return;
     }
 

src/generics/inline/emph_pair.rs

@@ -265,7 +265,10 @@ fn is_odd_match(opener: &EmphMarker, closer: &EmphMarker) -> bool {
 pub struct FragmentsJoin;
 impl CoreRule for FragmentsJoin {
     fn run(node: &mut Node, _: &MarkdownIt) {
-        node.walk_mut(|node, _| fragments_join(node));
+        node.walk_mut(|node, _| {
+            fragments_join(node);
+            Ok(())
+        }).unwrap();
     }
 }
 

src/parser/node.rs

@@ -7,7 +7,7 @@ use crate::common::TypeKey;
 use crate::parser::extset::NodeExtSet;
 use crate::parser::inline::Text;
 use crate::parser::renderer::HTMLRenderer;
-use crate::Renderer;
+use crate::{Renderer, Result};
 
 /// Single node in the CommonMark AST.
 #[derive(Debug)]
@@ -106,76 +106,91 @@ impl Node {
 
     /// Execute function `f` recursively on every member of AST tree
     /// (using preorder deep-first search).
-    pub fn walk<'a>(&'a self, mut f: impl FnMut(&'a Node, u32)) {
+    ///
+    /// This function will stop early if closure returns any error.
+    pub fn walk<'a>(&'a self, mut f: impl FnMut(&'a Node, u32) -> Result<()>) -> Result<()> {
         // performance note: this is faster than emulating recursion using vec stack
-        fn walk_recursive<'b>(node: &'b Node, depth: u32, f: &mut impl FnMut(&'b Node, u32)) {
-            f(node, depth);
+        fn walk_recursive<'a>(node: &'a Node, depth: u32, f: &mut impl FnMut(&'a Node, u32) -> Result<()>) -> Result<()> {
+            f(node, depth)?;
             for n in node.children.iter() {
-                stacker::maybe_grow(64*1024, 1024*1024, || {
-                    walk_recursive(n, depth + 1, f);
-                });
+                stacker::maybe_grow(64*1024, 1024*1024, || -> Result<()> {
+                    walk_recursive(n, depth + 1, f)
+                })?;
             }
+            Ok(())
         }
 
-        walk_recursive(self, 0, &mut f);
+        walk_recursive(self, 0, &mut f)
     }
 
     /// Execute function `f` recursively on every member of AST tree
     /// (using preorder deep-first search).
-    pub fn walk_mut(&mut self, mut f: impl FnMut(&mut Node, u32)) {
-        // performance note: this is faster than emulating recursion using vec stack
-        fn walk_recursive(node: &mut Node, depth: u32, f: &mut impl FnMut(&mut Node, u32)) {
-            f(node, depth);
+    ///
+    /// This function will stop early if closure returns any error.
+    pub fn walk_mut(&mut self, mut f: impl FnMut(&mut Node, u32) -> Result<()>) -> Result<()> {
+        // note: lifetime constrains are different from non-mut walk due to mutability
+        fn walk_recursive(node: &mut Node, depth: u32, f: &mut impl FnMut(&mut Node, u32) -> Result<()>) -> Result<()> {
+            f(node, depth)?;
             for n in node.children.iter_mut() {
-                stacker::maybe_grow(64*1024, 1024*1024, || {
-                    walk_recursive(n, depth + 1, f);
-                });
+                stacker::maybe_grow(64*1024, 1024*1024, || -> Result<()> {
+                    walk_recursive(n, depth + 1, f)
+                })?;
             }
+            Ok(())
         }
 
-        walk_recursive(self, 0, &mut f);
+        walk_recursive(self, 0, &mut f)
     }
 
     /// Execute function `f` recursively on every member of AST tree
     /// (using postorder deep-first search).
-    pub fn walk_post(&self, mut f: impl FnMut(&Node, u32)) {
-        fn walk_recursive(node: &Node, depth: u32, f: &mut impl FnMut(&Node, u32)) {
+    ///
+    /// This function will stop early if closure returns any error.
+    pub fn walk_post<'a>(&'a self, mut f: impl FnMut(&'a Node, u32) -> Result<()>) -> Result<()> {
+        // performance note: this is faster than emulating recursion using vec stack
+        fn walk_recursive<'a>(node: &'a Node, depth: u32, f: &mut impl FnMut(&'a Node, u32) -> Result<()>) -> Result<()> {
             for n in node.children.iter() {
-                stacker::maybe_grow(64*1024, 1024*1024, || {
-                    walk_recursive(n, depth + 1, f);
-                });
+                stacker::maybe_grow(64*1024, 1024*1024, || -> Result<()> {
+                    walk_recursive(n, depth + 1, f)
+                })?;
             }
-            f(node, depth);
+            f(node, depth)?;
+            Ok(())
         }
 
-        walk_recursive(self, 0, &mut f);
+        walk_recursive(self, 0, &mut f)
     }
 
     /// Execute function `f` recursively on every member of AST tree
     /// (using postorder deep-first search).
-    pub fn walk_post_mut(&mut self, mut f: impl FnMut(&mut Node, u32)) {
-        fn walk_recursive(node: &mut Node, depth: u32, f: &mut impl FnMut(&mut Node, u32)) {
+    ///
+    /// This function will stop early if closure returns any error.
+    pub fn walk_post_mut(&mut self, mut f: impl FnMut(&mut Node, u32) -> Result<()>) -> Result<()> {
+        // note: lifetime constrains are different from non-mut walk due to mutability
+        fn walk_recursive(node: &mut Node, depth: u32, f: &mut impl FnMut(&mut Node, u32) -> Result<()>) -> Result<()> {
             for n in node.children.iter_mut() {
-                stacker::maybe_grow(64*1024, 1024*1024, || {
-                    walk_recursive(n, depth + 1, f);
-                });
+                stacker::maybe_grow(64*1024, 1024*1024, || -> Result<()> {
+                    walk_recursive(n, depth + 1, f)
+                })?;
             }
-            f(node, depth);
+            f(node, depth)?;
+            Ok(())
         }
 
-        walk_recursive(self, 0, &mut f);
+        walk_recursive(self, 0, &mut f)
     }
 
     /// Walk recursively through child nodes and collect all text nodes
     /// into a single string.
     pub fn collect_text(&self) -> String {
         let mut result = String::new();
 
-        self.walk(|node, _| {
+        self.walk(|node: &Node, _| {
             if let Some(text) = node.cast::<Text>() {
                 result.push_str(text.content.as_str());
             }
-        });
+            Ok(())
+        }).unwrap();
 
         result
     }
@@ -185,7 +200,8 @@ impl Drop for Node {
     fn drop(&mut self) {
         self.walk_post_mut(|node, _| {
             drop(std::mem::take(&mut node.children));
-        });
+            Ok(())
+        }).unwrap();
     }
 }
 

src/plugins/extra/heading_anchors.rs

@@ -64,6 +64,7 @@ impl CoreRule for AddHeadingAnchors {
             if node.is::<ATXHeading>() || node.is::<SetextHeader>() {
                 node.attrs.push(("id", slugify(&node.collect_text())));
             }
-        });
+            Ok(())
+        }).unwrap();
     }
 }

src/plugins/extra/smartquotes.rs

@@ -153,7 +153,8 @@ impl<
                 text_node.content = execute_replacements(current_replacements, &text_node.content);
             };
             current_index += 1;
-        });
+            Ok(())
+        }).unwrap();
     }
 }
 
@@ -318,7 +319,7 @@ impl<
 fn all_text_tokens(root: &Node) -> Vec<FlatToken> {
     let mut result = Vec::new();
     let mut walk_index = 0;
-    root.walk(|node, nesting_level| {
+    root.walk(|node: &Node, nesting_level| {
         if let Some(text_node) = node.cast::<Text>() {
             result.push(FlatToken::Text {
                 content: &text_node.content,
@@ -335,7 +336,8 @@ fn all_text_tokens(root: &Node) -> Vec<FlatToken> {
             result.push(FlatToken::Irrelevant);
         }
         walk_index += 1;
-    });
+        Ok(())
+    }).unwrap();
     result
 }
 

src/plugins/extra/syntect.rs

@@ -69,6 +69,7 @@ impl CoreRule for SyntectRule {
                     node.replace(SyntectSnippet { html });
                 }
             }
-        });
+            Ok(())
+        }).unwrap();
     }
 }

src/plugins/extra/typographer.rs

@@ -82,7 +82,7 @@ pub struct TypographerRule;
 impl CoreRule for TypographerRule {
     fn run(root: &mut Node, _: &MarkdownIt) {
         root.walk_mut(|node, _| {
-            let Some(mut text_node) = node.cast_mut::<Text>() else { return; };
+            let Some(mut text_node) = node.cast_mut::<Text>() else { return Ok(()); };
 
             if SCOPED_RE.is_match(&text_node.content) {
                 text_node.content = SCOPED_RE
@@ -119,6 +119,7 @@ impl CoreRule for TypographerRule {
                     text_node.content = s;
                 }
             }
-        });
+            Ok(())
+        }).unwrap();
     }
 }

src/plugins/sourcepos.rs

@@ -35,7 +35,8 @@ impl CoreRule for SyntaxPosRule {
                 let ((startline, startcol), (endline, endcol)) = map.get_positions(&mapping);
                 node.attrs.push(("data-sourcepos", format!("{}:{}-{}:{}", startline, startcol, endline, endcol)));
             }
-        });
+            Ok(())
+        }).unwrap();
         Ok(())
     }