docs: add some notes on recent lifetime learnings

1 files changed, 58 insertions, 23 deletions

diff --git a/src/main.rs b/src/main.rs
index d03d5f8..a8b8198 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -9,34 +9,66 @@ use pandoc_ast::Block;
 
 type Blocks<'a> = HashMap<String,Cow<'a,str>>;
 
-fn build_block(blocks: &Blocks, code: &Cow<str>) -> String {
+/*
+ * Here are some notes on the following function
+ *
+ *      lazy_static! {
+ *          static ref MACRO: Regex = Regex::new(r"regex").unwrap();
+ *      }
+ *
+ *      let mut text = Cow::from("This is some text...");
+ *
+ * The problem with this version is that due to how `Cow` works, the value returned by
+ * `replace_all` cannot live more than the borrowed `text` passed as a parameter. This is
+ * because the function returns a reference to `text` (Cow::Borrowed) if no replacement takes
+ * place, so for the returned value to be valid, `text` still needs to be available.
+ * But text gets overridden right away, so, in principle, if no replacement takes place `text`
+ * gets overridden by a reference to it (losing data).
+ *
+ * Note that this doesn't happen in practice (but the compiler doesn't know about this) because
+ * the `replace_all` function is applied as long as some replacement is possible (`while`
+ * condition). In other words, all calls to `replace_all` always return an `Cow::Owned` value.
+ * 
+ *      while MACRO.is_match(&text) {
+ *          text = MACRO.replace_all(&text, _closure);
+ *      }
+ *
+ * This is how you would solve the problem instead:
+ *
+ *      while let Cow::Owned(new_text) = MACRO.replace_all(&text, _closure) {
+ *          text = Cow::from(new_text);
+ *      }
+ *
+ * In this case, the matched `Cow::Owned` is not concerned by any lifetime (type is `Cow<'_,str>`)
+ * of the borrowed value `text`. Moreover `text` takes ownership of `new_text: String` using
+ * the `Cow::from()` function. No heap allocation is performed, and the string is not copied.
+ *
+ *      println!("{}", text)
+ *
+ */
+fn build(blocks: &Blocks) {
     lazy_static! {
+        static ref PATH: Regex = Regex::new(r"^(?:[[:word:]\.-]+/)*[[:word:]\.-]+\.[[:alpha:]]+$").unwrap();
         static ref MACRO: Regex = Regex::new(r"(?m)^([[:blank:]]*)<<([^>\s]+)>>").unwrap();
     }
-    if MACRO.is_match(&code) {
-        let code = MACRO.replace_all(&code, |caps: &Captures| {
+    blocks.iter().for_each(|(k,v)| if PATH.is_match(k) { 
+        let mut code = v.clone(); // No clone is happening because the value is a `Borrowed`
+        // Here `replace_all` returns a `Owned` value only when a replacement takes place.
+        // We can use it to recursively build blocks of code until no more substitutions are
+        // necessary (i.e., `replace_all` returns a `Borrowed`).
+        while let Cow::Owned(step) = MACRO.replace_all(&code, |caps: &Captures| {
             let indent = caps[1].len();
             blocks.get(&caps[2])
-                  .expect("Block not present")
-                  .lines()
-                  .map(|l| format!("{:indent$}{}", "", l) )
-                  .collect::<Vec<_>>()
-                  .join("\n")
+                .expect("Block not present")
+                .lines()
+                .map(|l| format!("{:indent$}{}", "", l) )
+                .collect::<Vec<_>>()
+                .join("\n")
             }
-        );
-        build_block(blocks, &code)
-    } else {
-        code.to_string()
-    }
-}
-
-fn build(blocks: &Blocks) {
-    lazy_static! {
-        static ref PATH: Regex = Regex::new(r"^(?:[[:word:]\.-]+/)+[[:word:]\.-]+\.[[:alpha:]]+$").unwrap();
-    }
-    blocks.iter().for_each(|(k,v)| if PATH.is_match(k) { 
-        let string = build_block(blocks, v);
-        println!("[[{}]]\n{}", k, string);
+        ) {
+            code = Cow::from(step);
+        }
+        println!("[[{}]]\n{}", k, code);
     })
 }
 
@@ -60,7 +92,10 @@ fn main() -> Result<()> {
                         .find_map(|(k,v)| if k == "path" { Some(v.clone()) } else { None })
                         .unwrap_or(String::from(""));
                     key.push_str(&attr.0);
-                    /* Insert (or replace) block of code */
+                    /* Insert (or replace) block of code.
+                     * NOTE: we are always "borrowing" the snippets of code with `Cow`, i.e., it
+                     * will always be a `Cow::Borrowed` value, until we process the string
+                     * substituting macros. */
                     blocks.insert(key, Cow::from(code));
                 } else {
                     // println!("The following code has no ID:");