Merge branch 'yasu/mrkdwn-escape-slash'

* yasu/mrkdwn-escape-slash:
  mrkdwn: use correct escape function
  tests: promote with escaping cases
  mrkdwn: document commonmark escaping behavior
  mrkdwn: escape backslash in code elements

Author: yasunariw

lib/mrkdwn.ml

@@ -11,11 +11,26 @@ let escape_mrkdwn =
     | '&' -> "&"
     | c -> String.make 1 c)
 
-let unescape_omd =
-  Staged.unstage @@ String.Escaping.unescape_gen_exn ~escapeworthy_map:[ '(', '('; ')', ')' ] ~escape_char:'\\'
+(** Unescape markdown characters escaped because "any ASCII punctuation
+    character may be backslash-escaped"
+    https://spec.commonmark.org/0.30/#backslash-escapes
+
+    This pertains to '\\', '[', ']', '(', ')', '`', '*' unconditionally,
+    and '.', '-', '+', '!', '<', '>', '#' depending on chars before/after.
+    Argument escapeworthy_map can be left blank because escaped chars are
+    unescaped to themselves. *)
+let unescape_omd = Staged.unstage @@ String.Escaping.unescape_gen_exn ~escapeworthy_map:[] ~escape_char:'\\'
+
+(** Escape the `escape_char` '\\' for use with `unescape_omd` later *)
+let escape_omd = Staged.unstage @@ String.Escaping.escape_gen_exn ~escapeworthy_map:[] ~escape_char:'\\'
 
 let transform_text = escape_mrkdwn
 
+(** `Omd.to_markdown` escapes backslash (and other applicable chars) in
+    `Text` elements but not `Code` elements, so do the same for the latter so
+    that `unescape_omd` can apply uniformly to the whole mrkdwn string later *)
+let transform_code s = escape_omd @@ escape_mrkdwn s
+
 let rec transform_list = List.map ~f:transform
 
 and transform_flatten = List.map ~f:transform_list
@@ -43,9 +58,9 @@ and transform = function
   | Html_block _ as e -> Code_block ("", to_markdown [ e ])
   | Blockquote t -> Blockquote (transform_list t)
   | Img (alt, src, title) -> transform @@ Url (src, [ Text alt ], title)
-  | Code_block (_, str) -> Code_block ("", str)
+  | Code_block (_, str) -> Code_block ("", transform_code str)
+  | Code (_, str) -> Code ("", transform_code str)
   | Text s -> Text (transform_text s)
-  | (Code _ | Br | Hr | NL | Ref _ | Img_ref _ | Raw _ | Raw_block _ | X _) as e -> e
+  | (Br | Hr | NL | Ref _ | Img_ref _ | Raw _ | Raw_block _ | X _) as e -> e
 
-(* unescaping here is a workaround of to_markdown escaping parentheses in text (bug?) *)
 let mrkdwn_of_markdown str = unescape_omd @@ to_markdown @@ transform_list @@ of_string str

mock_payloads/commit_comment.mrkdwn_comment.json

@@ -32,7 +32,7 @@
     "created_at": "2020-06-07T15:11:50Z",
     "updated_at": "2020-06-07T15:11:50Z",
     "author_association": "OWNER",
-    "body": "**bold**, *italic*\n> blockquote\n\n* list-element 1\n* list-element 2\n  * list-element2.1\n  * [list-element2.2](www.google.com)\n\n<div>html block</div>\n```ocaml\nStdio.printf \"hello ocaml\"\n```"
+    "body": "**bold**, *italic*\n> blockquote\n\n* list-element 1\n* list-element 2\n  * list-element2.1\n  * [list-element2.2](www.google.com)\n\n<div>html block</div>\n```ocaml\nStdio.printf \"hello ocaml\"\n```\nescaped chars \\\\\\(\\)\\[\\]\\`\\*\n`keep \\`\n```\nkeep \\\n```"
   },
   "repository": {
     "id": 265741348,

test/slack_payloads.expected

@@ -76,7 +76,7 @@ will notify #all-push-events
       "pretext":
         "<https://github.com/xinyuluo/pr_test|[xinyuluo/pr_test]> *xinyuluo* commented on `<https://github.com/xinyuluo/pr_test/commit/cd5b85afa306840e0790b62e349ee1f828b2a3c2#commitcomment-39729580|cd5b85af>` add new line at EOF",
       "text":
-        "this can be written shorter:\n`\n| Some serpDomain -> Domain.is_subdomain serpDomain domain\n| None -> false`",
+        "this can be written shorter:\n`\n| Some serpDomain -&gt; Domain.is_subdomain serpDomain domain\n| None -&gt; false`",
       "footer":
         "New comment by xinyuluo in <https://github.com/xinyuluo/pr_test/commit/cd5b85afa306840e0790b62e349ee1f828b2a3c2#commitcomment-39729580|runner/chat.ml>"
     }
@@ -95,7 +95,7 @@ will notify #all-push-events
       "pretext":
         "<https://github.com/xinyuluo/pr_test|[xinyuluo/pr_test]> *xinyuluo* commented on `<https://github.com/xinyuluo/pr_test/commit/cd5b85afa306840e0790b62e349ee1f828b2a3c2#commitcomment-39729580|cd5b85af>` add new line at EOF",
       "text":
-        "*bold*, _italic_\n\n> blockquote\n\n\n- list-element 1\n- list-element 2\n    - list-element2.1\n    - <www.google.com|list-element2.2>\n\n\n```\n<div>html block</div>\n```\n```\nStdio.printf \"hello ocaml\"\n```",
+        "*bold*, _italic_\n\n> blockquote\n\n\n- list-element 1\n- list-element 2\n    - list-element2.1\n    - <www.google.com|list-element2.2>\n\n\n```\n<div>html block</div>\n```\n```\nStdio.printf \"hello ocaml\"\n```\nescaped chars \\()[]`*\n`keep \\`\n\n```\nkeep \\\n```",
       "footer":
         "New comment by xinyuluo in <https://github.com/xinyuluo/pr_test/commit/cd5b85afa306840e0790b62e349ee1f828b2a3c2#commitcomment-39729580|runner/chat.ml>"
     }