Add support for replacing markdown in Gleam comments

.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: erlef/setup-beam@v1
         with:
           otp-version: "26.0.2"
-          gleam-version: "1.11.1"
+          gleam-version: "1.13.0"
           rebar3-version: "3"
       - run: gleam deps download
       - run: gleam build --warnings-as-errors

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+### Deprecated
+- `file` was deprecated for clarity reasons. Use `document` instead.
+
+### Added
+
+- Adds support for replacing snippets in code comments,
+  using `comments_in` instead of `document`.
+
 ## v2.0.0 - 2025-08-02
 
 This is a complete rewrite. Instead of checking or running gleam code via checkmark,

README.md

@@ -19,7 +19,7 @@ import simplifile
 
 pub fn example_test() {
   assert checkmark.new(simplifile.read, simplifile.write)
-    |> checkmark.file("README.md")
+    |> checkmark.document("README.md")
     |> checkmark.should_contain_contents_of("./example.sh", tagged: "sh")
     |> checkmark.should_contain_contents_of(
       "./test/example_test.gleam",

src/checkmark.gleam

@@ -22,7 +22,12 @@ pub opaque type Checker(e) {
 /// A markdown file to check, which can be linked to snippets in multiple other files.
 /// The error type depends on the IO library used.
 pub opaque type File(e) {
-  File(name: String, checker: Checker(e), expectations: List(#(String, String)))
+  File(
+    name: String,
+    checker: Checker(e),
+    check_in_comments: Bool,
+    expectations: List(#(String, String)),
+  )
 }
 
 /// Any error that can happen during checking or updating a markdown file.
@@ -44,8 +49,19 @@ pub fn new(
 }
 
 /// Configures a markdown file to be checked or updated.
+@deprecated("Use document instead")
 pub fn file(checker: Checker(e), filename: String) -> File(e) {
-  File(filename, checker, [])
+  document(checker, filename)
+}
+
+/// Configures a markdown document to be checked or updated.
+pub fn document(checker: Checker(e), filename: String) -> File(e) {
+  File(filename, checker, False, [])
+}
+
+/// Configures comments in a gleam source file to be checked or updated.
+pub fn comments_in(checker: Checker(e), filename: String) -> File(e) {
+  File(filename, checker, True, [])
 }
 
 /// Specify that the markdown file should contain the contents of another file as a code block.
@@ -119,10 +135,11 @@ fn render_replacements(
   contents
   |> list.map(fn(section) {
     case section {
-      parser.FencedCode(_, content, start_fence, end_fence) -> {
+      parser.FencedCode(content:, start_fence:, end_fence:, prefix:, ..) -> {
         case dict.get(replacements, string.trim(start_fence.info)) {
-          Ok(replacement) -> render_code(start_fence, replacement, end_fence)
-          Error(_) -> render_code(start_fence, content, end_fence)
+          Ok(replacement) ->
+            render_code(start_fence, prefix, replacement, end_fence)
+          Error(_) -> render_code(start_fence, prefix, content, end_fence)
         }
       }
       parser.Other(_, content) -> content
@@ -133,26 +150,27 @@ fn render_replacements(
 
 fn render_code(
   start_fence: Fence,
+  prefix: String,
   content: String,
   end_fence: Option(Fence),
 ) -> String {
   // This is not very optimized, but we probably don't need to care...
 
-  let content = case start_fence.indent {
-    0 -> content
-    amount ->
+  let content = case start_fence.indent, prefix {
+    0, "" -> content
+    amount, _ ->
       indent(
         splitter.new(["\n", "\r\n"]),
-        string.repeat(" ", amount),
+        prefix <> string.repeat(" ", amount),
         content,
         [],
       )
   }
 
-  let without_end = render_fence(start_fence) <> content
+  let without_end = render_fence(prefix, start_fence) <> content
   case end_fence {
     option.None -> without_end
-    option.Some(end_fence) -> without_end <> render_fence(end_fence)
+    option.Some(end_fence) -> without_end <> render_fence(prefix, end_fence)
   }
 }
 
@@ -171,16 +189,16 @@ fn indent(
   }
 }
 
-fn render_fence(fence: Fence) -> String {
-  string.repeat(" ", fence.indent) <> fence.fence <> fence.info
+fn render_fence(prefix: String, fence: Fence) -> String {
+  prefix <> string.repeat(" ", fence.indent) <> fence.fence <> fence.info
 }
 
 fn parse_file(
   file: File(e),
 ) -> Result(List(parser.Section), List(CheckError(e))) {
   read_file(file.checker, file.name)
   |> result.map_error(list.wrap)
-  |> result.map(parser.parse)
+  |> result.map(parser.parse(_, file.check_in_comments))
 }
 
 fn read_file(
@@ -223,10 +241,13 @@ fn find_match(
           ))
       }
 
-    [parser.FencedCode(line, content, start_fence, end_fence), ..rest] -> {
+    [
+      parser.FencedCode(start_line:, content:, start_fence:, end_fence:, ..),
+      ..rest
+    ] -> {
       case string.trim(start_fence.info) == tag {
         True -> {
-          let result = #(line, Snippet(content, start_fence, end_fence))
+          let result = #(start_line, Snippet(content, start_fence, end_fence))
           find_match(rest, tag, [result, ..found])
         }
         False -> find_match(rest, tag, found)