generate: demote headings, and group link reference definitions

src/generate/generate.nim

@@ -1,5 +1,11 @@
-import std/[strbasics, strformat, strscans, terminal]
-import ".."/[cli, helpers]
+import std/[parseutils, strbasics, strformat, strscans, tables, terminal]
+import ".."/[cli, helpers, types_track_config]
+
+proc getSlugLookup(trackDir: Path): Table[string, string] =
+  let concepts = TrackConfig.init(readFile(trackDir / "config.json")).concepts
+  result = initTable[string, string](concepts.len)
+  for `concept` in concepts:
+    result[`concept`.slug] = `concept`.name
 
 proc writeError(description: string, path: Path) =
   let descriptionPrefix = description & ":"
@@ -10,21 +16,43 @@ proc writeError(description: string, path: Path) =
   stderr.writeLine(path)
   stderr.write "\n"
 
-proc conceptIntroduction(trackDir: Path, slug: string,
+func alterHeaders(s: string, title: string): string =
+  # Markdown implementations differ on whether a space is required after the
+  # final '#' character that begins the header.
+  result = newStringOfCap(s.len)
+  var i = 0
+  i += s.skipWhitespace()
+  # Skip the top-level header (if any)
+  if i < s.len and s[i] == '#' and i+1 < s.len and s[i+1] == ' ':
+    i += s.skipUntil('\n', i)
+  result.add &"## {title}"
+  # Demote other headers
+  var inFencedCodeBlock = false
+  while i < s.len:
+    result.add s[i]
+    if s[i] == '\n':
+      # When inside a fenced code block, don't alter a line that begins with '#'
+      if i+1 < s.len and s[i+1] == '#' and not inFencedCodeBlock:
+        result.add '#'
+      elif i+3 < s.len and s[i+1] == '`' and s[i+2] == '`' and s[i+3] == '`':
+        inFencedCodeBlock = not inFencedCodeBlock
+        result.add "```"
+        i += 3
+    inc i
+  strip result
+
+proc conceptIntroduction(trackDir: Path, slug: string, title: string,
                          templatePath: Path): string =
-  ## Returns the contents of the `introduction.md` file for a `slug`, but
-  ## without any top-level heading, and without any leading/trailing whitespace.
+  ## Returns the contents of the `introduction.md` file for a `slug`, but:
+  ## - Without a first top-level header.
+  ## - Adding a starting a second-level header containing `title`.
+  ## - Demoting the level of any other header.
+  ## - Without any leading/trailing whitespace.
   let conceptDir = trackDir / "concepts" / slug
   if dirExists(conceptDir):
     let path = conceptDir / "introduction.md"
     if fileExists(path):
-      result = readFile(path)
-      var i = 0
-      # Strip the top-level heading (if any)
-      if scanp(result, i, *{' ', '\t', '\v', '\c', '\n', '\f'}, "#", +' ',
-               +(~'\n')):
-        result.setSlice(i..result.high)
-      strip result
+      result = path.readFile().alterHeaders(title)
     else:
       writeError(&"File {path} not found for concept '{slug}'", templatePath)
       quit(1)
@@ -33,7 +61,8 @@ proc conceptIntroduction(trackDir: Path, slug: string,
                templatePath)
     quit(1)
 
-proc generateIntroduction(trackDir: Path, templatePath: Path): string =
+proc generateIntroduction(trackDir: Path, templatePath: Path,
+                          slugLookup: Table[string, string]): string =
   ## Reads the file at `templatePath` and returns the content of the
   ## corresponding `introduction.md` file.
   let content = readFile(templatePath)
@@ -48,7 +77,8 @@ proc generateIntroduction(trackDir: Path, templatePath: Path): string =
     if scanp(content, i,
              "%{", *{' '}, "concept", *{' '}, ':', *{' '},
              +{'a'..'z', '-'} -> conceptSlug.add($_), *{' '}, '}'):
-      result.add conceptIntroduction(trackDir, conceptSlug, templatePath)
+      let title = slugLookup[conceptSlug]
+      result.add conceptIntroduction(trackDir, conceptSlug, title, templatePath)
     else:
       result.add content[i]
       inc i
@@ -60,9 +90,11 @@ proc generate*(conf: Conf) =
 
   let conceptExercisesDir = trackDir / "exercises" / "concept"
   if dirExists(conceptExercisesDir):
+    let slugLookup = getSlugLookup(trackDir)
     for conceptExerciseDir in getSortedSubdirs(conceptExercisesDir):
       let introductionTemplatePath = conceptExerciseDir / ".docs" / "introduction.md.tpl"
       if fileExists(introductionTemplatePath):
-        let introduction = generateIntroduction(trackDir, introductionTemplatePath)
+        let introduction = generateIntroduction(trackDir, introductionTemplatePath,
+                                                slugLookup)
         let introductionPath = introductionTemplatePath.string[0..^5] # Removes `.tpl`
         writeFile(introductionPath, introduction)

tests/all_tests.nim

@@ -1,6 +1,7 @@
 import "."/[
   test_binary,
   test_fmt,
+  test_generate,
   test_json,
   test_lint,
   test_probspecs,

tests/test_binary.nim

@@ -872,17 +872,16 @@ proc testsForSync(binaryPath: static string) =
                          &"failed to merge '{mainBranchName}' in " &
                          &"problem-specifications directory: '{probSpecsDir}'")
 
-proc prepareIntroductionFiles(trackDir, header, placeholder: string;
-                              removeIntro: bool) =
+proc prepareIntroductionFiles(trackDir, placeholder: string; removeIntro: bool) =
   # Writes an `introduction.md.tpl` file for the `bird-count` Concept Exercise,
-  # containing the given `header` and `placeholder`. Also removes the
-  # `introduction.md` file if `removeIntro` is `true`.
+  # containing the given `placeholder`. Also removes the `introduction.md` file
+  # if `removeIntro` is `true`.
   let
     docsPath = trackDir / "exercises" / "concept" / "bird-count" / ".docs"
     introPath = docsPath / "introduction.md"
     templatePath = introPath & ".tpl"
     templateContents = fmt"""
-      # {header}
+      # Introduction
 
       {placeholder}
     """.unindent()
@@ -897,7 +896,7 @@ proc testsForGenerate(binaryPath: string) =
 
     # Setup: clone a track repo, and checkout a known state
     setupExercismRepo("elixir", trackDir,
-                      "f3974abf6e0d4a434dfe3494d58581d399c18edb") # 2021-05-09
+                      "91ccf91940f32aff3726c772695b2de167d8192a") # 2022-06-12
 
     test "`configlet generate` exits with 0 when there are no `.md.tpl` files":
       execAndCheck(0, generateCmd, "")
@@ -906,8 +905,7 @@ proc testsForGenerate(binaryPath: string) =
       checkNoDiff(trackDir)
 
     # Valid placeholder syntax without spaces, and invalid slug
-    prepareIntroductionFiles(trackDir, "Recursion",
-                             "%{concept:not-a-real-concept-slug}",
+    prepareIntroductionFiles(trackDir, "%{concept:not-a-real-concept-slug}",
                              removeIntro = false)
 
     test "`configlet generate` exits with 1 for an invalid placeholder usage":
@@ -917,7 +915,7 @@ proc testsForGenerate(binaryPath: string) =
       checkNoDiff(trackDir)
 
     # Valid placeholder syntax without spaces, and valid slug
-    prepareIntroductionFiles(trackDir, "Recursion", "%{concept:recursion}",
+    prepareIntroductionFiles(trackDir, "%{concept:recursion}",
                              removeIntro = true)
 
     test "`configlet generate` exits with 0 for a valid `.md.tpl` file":
@@ -927,7 +925,7 @@ proc testsForGenerate(binaryPath: string) =
       checkNoDiff(trackDir)
 
     # Valid placeholder syntax with spaces, and valid slug
-    prepareIntroductionFiles(trackDir, "Recursion", "%{ concept : recursion }",
+    prepareIntroductionFiles(trackDir, "%{ concept : recursion }",
                              removeIntro = true)
 
     test "`configlet generate` exits with 0 for valid placeholder usage with spaces":

tests/test_generate.nim

@@ -0,0 +1,70 @@
+import std/[strutils, unittest]
+from "."/generate/generate {.all.} import alterHeaders
+
+proc testGenerate =
+  suite "generate":
+    test "alterHeaders":
+      const s = """
+        # Header 1
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.
+
+        ## Header 2
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.
+
+        ### Header 3
+
+        The quick brown fox jumps over a lazy dog.
+
+        ```nim
+        # This line is not a header
+        echo "hi"
+        ```
+
+        ## Header 4
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.
+      """.unindent()
+
+      const expected = """
+        ## Operator Overloading
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.
+
+        ### Header 2
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.
+
+        #### Header 3
+
+        The quick brown fox jumps over a lazy dog.
+
+        ```nim
+        # This line is not a header
+        echo "hi"
+        ```
+
+        ### Header 4
+
+        The quick brown fox jumps over a lazy dog.
+
+        The five boxing wizards jump quickly.""".unindent() # No final newline
+
+      check alterHeaders(s, "Operator Overloading") == expected
+
+proc main =
+  testGenerate()
+
+main()
+{.used.}