cm::escape_inline: add function to escape input for inline text.

Author: kivikakk

changelog.txt

@@ -1,5 +1,11 @@
 # [v0.42.0] - unreleased
 
+New APIs:
+
+* `cm::escape_inline` (aliased at crate level as `escape_commonmark_inline`)
+  is added; escapes input text suitable for inclusion in a CommonMark document
+  where regular inline processing takes place.
+
 Changed APIs:
 
 * `html::collect_text` now returns a `String`.  `html::collect_text_append` is

src/cm.rs

@@ -1038,3 +1038,48 @@ fn minimize_commonmark(text: &mut Vec<u8>, original_options: &Options) {
         }
     }
 }
+
+/// Escapes the input, rendering it suitable for inclusion in a CommonMark
+/// document in a place where regular inline parsing is occurring. Note that
+/// this is not minimal --- there will be more escaping backslashes in the
+/// output than is strictly necessary. The rendering will not be affected,
+/// however.
+pub fn escape_inline(text: &str) -> String {
+    use std::fmt::Write;
+
+    let mut result = String::with_capacity(text.len() * 3 / 2);
+
+    for c in text.chars() {
+        if c < '\x20'
+            || c == '*'
+            || c == '_'
+            || c == '['
+            || c == ']'
+            || c == '#'
+            || c == '<'
+            || c == '>'
+            || c == '\\'
+            || c == '`'
+            || c == '!'
+            || c == '&'
+            || c == '!'
+            || c == '-'
+            || c == '+'
+            || c == '='
+            || c == '.'
+            || c == '('
+            || c == ')'
+            || c == '"'
+        {
+            if ispunct(c as u8) {
+                write!(&mut result, "\\{}", c).unwrap();
+            } else {
+                write!(&mut result, "&#{};", c as u8).unwrap();
+            }
+        } else {
+            result.push(c);
+        }
+    }
+
+    result
+}

src/lib.rs

@@ -81,6 +81,7 @@ mod strings;
 mod tests;
 mod xml;
 
+pub use cm::escape_inline as escape_commonmark_inline;
 pub use cm::format_document as format_commonmark;
 pub use cm::format_document_with_plugins as format_commonmark_with_plugins;
 pub use html::format_document as format_html;

src/tests.rs

@@ -12,6 +12,7 @@ mod commonmark;
 mod core;
 mod description_lists;
 mod empty;
+mod escape;
 mod escaped_char_spans;
 mod footnotes;
 mod front_matter;

src/tests/escape.rs

@@ -0,0 +1,36 @@
+use crate::{cm::escape_inline, entity, markdown_to_html, Options};
+
+/// Assert that the input escapes to the expected result, and that the expected
+/// result renders to HTML which displays the input text.
+#[track_caller]
+fn assert_escape_inline(input: &str, expected: &str) {
+    let actual = escape_inline(input);
+    assert_eq!(expected, actual);
+    let mut html = markdown_to_html(expected, &Options::default());
+    html = html
+        .strip_prefix("<p>")
+        .expect("html should be one paragraph")
+        .to_string();
+    html = html
+        .strip_suffix("</p>\n")
+        .expect("html should be one paragraph")
+        .to_string();
+    assert_eq!(
+        input,
+        std::str::from_utf8(&entity::unescape_html(html.as_bytes())).unwrap()
+    );
+}
+
+#[test]
+fn escape_inline_baseline() {
+    assert_escape_inline("abcdefg", "abcdefg");
+    assert_escape_inline("*hello*", r#"\*hello\*"#);
+    assert_escape_inline(
+        "[A link](https://link.com)",
+        r#"\[A link\]\(https://link\.com\)"#,
+    );
+    assert_escape_inline(
+        r#"some <"complicated"> & '/problematic\' input"#,
+        r#"some \<\"complicated\"\> \& '/problematic\\' input"#,
+    );
+}