|
| 1 | +--- @module code-annotations |
| 2 | +--- @license MIT |
| 3 | +--- @copyright 2026 Mickaël Canouil |
| 4 | +--- @author Mickaël Canouil |
| 5 | +--- @brief Code annotation detection, stripping, and Typst rendering helpers. |
| 6 | +--- Scans CodeBlock elements for inline annotation markers (e.g. # <1>, // <2>) |
| 7 | +--- and provides utilities for converting annotations to Typst output. |
| 8 | + |
| 9 | +-- ============================================================================ |
| 10 | +-- LANGUAGE COMMENT CHARACTERS |
| 11 | +-- ============================================================================ |
| 12 | + |
| 13 | +--- Map of language identifiers to their single-line comment prefix. |
| 14 | +--- @type table<string, string> |
| 15 | +local LANG_COMMENT_CHARS = { |
| 16 | + r = '#', |
| 17 | + python = '#', |
| 18 | + lua = '--', |
| 19 | + javascript = '//', |
| 20 | + typescript = '//', |
| 21 | + go = '//', |
| 22 | + rust = '//', |
| 23 | + bash = '#', |
| 24 | + sh = '#', |
| 25 | + zsh = '#', |
| 26 | + fish = '#', |
| 27 | + c = '//', |
| 28 | + cpp = '//', |
| 29 | + cxx = '//', |
| 30 | + cc = '//', |
| 31 | + cs = '//', |
| 32 | + java = '//', |
| 33 | + scala = '//', |
| 34 | + kotlin = '//', |
| 35 | + swift = '//', |
| 36 | + objc = '//', |
| 37 | + php = '//', |
| 38 | + ruby = '#', |
| 39 | + perl = '#', |
| 40 | + julia = '#', |
| 41 | + haskell = '--', |
| 42 | + elm = '--', |
| 43 | + clojure = ';', |
| 44 | + scheme = ';', |
| 45 | + lisp = ';', |
| 46 | + racket = ';', |
| 47 | + erlang = '%%', |
| 48 | + elixir = '#', |
| 49 | + fortran = '!', |
| 50 | + matlab = '%%', |
| 51 | + ada = '--', |
| 52 | + sql = '--', |
| 53 | + plsql = '--', |
| 54 | + tsql = '--', |
| 55 | + mysql = '--', |
| 56 | + sqlite = '--', |
| 57 | + postgresql = '--', |
| 58 | + vb = "'", |
| 59 | + vbnet = "'", |
| 60 | + fsharp = '//', |
| 61 | + stata = '//', |
| 62 | + yaml = '#', |
| 63 | + toml = '#', |
| 64 | + make = '#', |
| 65 | + cmake = '#', |
| 66 | + dockerfile = '#', |
| 67 | + powershell = '#', |
| 68 | + nix = '#', |
| 69 | + zig = '//', |
| 70 | + dart = '//', |
| 71 | + groovy = '//', |
| 72 | + d = '//', |
| 73 | + nim = '#', |
| 74 | + crystal = '#', |
| 75 | + v = '//', |
| 76 | + odin = '//', |
| 77 | + mojo = '#', |
| 78 | +} |
| 79 | + |
| 80 | +-- ============================================================================ |
| 81 | +-- ANNOTATION RESOLUTION |
| 82 | +-- ============================================================================ |
| 83 | + |
| 84 | +--- Escape a string for use in a Lua pattern. |
| 85 | +--- @param s string |
| 86 | +--- @return string |
| 87 | +local function escape_pattern(s) |
| 88 | + return s:gsub('([%(%)%.%%%+%-%*%?%[%]%^%$])', '%%%1') |
| 89 | +end |
| 90 | + |
| 91 | +--- Resolve annotations in a CodeBlock element. |
| 92 | +--- Scans each line for a trailing annotation marker (e.g. # <1>) using the |
| 93 | +--- language's comment prefix. Strips the marker from the code text and returns |
| 94 | +--- the cleaned text along with an annotations table. |
| 95 | +--- @param block pandoc.CodeBlock |
| 96 | +--- @return string cleaned_text The code with annotation markers removed |
| 97 | +--- @return table|nil annotations Maps line numbers (int) to annotation numbers (int), or nil if none found |
| 98 | +local function resolve_annotations(block) |
| 99 | + if not block.classes or #block.classes == 0 then |
| 100 | + return block.text, nil |
| 101 | + end |
| 102 | + |
| 103 | + local lang = block.classes[1]:lower() |
| 104 | + local comment = LANG_COMMENT_CHARS[lang] |
| 105 | + if not comment then |
| 106 | + return block.text, nil |
| 107 | + end |
| 108 | + |
| 109 | + local escaped_comment = escape_pattern(comment) |
| 110 | + local pattern = '^(.-)%s*' .. escaped_comment .. '%s*<%s*(%d+)%s*>%s*$' |
| 111 | + |
| 112 | + local annotations = {} |
| 113 | + local lines = {} |
| 114 | + local found = false |
| 115 | + |
| 116 | + local line_num = 0 |
| 117 | + for line in (block.text .. '\n'):gmatch('([^\n]*)\n') do |
| 118 | + line_num = line_num + 1 |
| 119 | + local content, annot_num = line:match(pattern) |
| 120 | + if annot_num then |
| 121 | + found = true |
| 122 | + annotations[line_num] = tonumber(annot_num) |
| 123 | + table.insert(lines, content) |
| 124 | + else |
| 125 | + table.insert(lines, line) |
| 126 | + end |
| 127 | + end |
| 128 | + |
| 129 | + if not found then |
| 130 | + return block.text, nil |
| 131 | + end |
| 132 | + |
| 133 | + return table.concat(lines, '\n'), annotations |
| 134 | +end |
| 135 | + |
| 136 | +-- ============================================================================ |
| 137 | +-- TYPST CONVERSION HELPERS |
| 138 | +-- ============================================================================ |
| 139 | + |
| 140 | +--- Convert an annotations table to a Typst dictionary literal. |
| 141 | +--- Keys are stringified line numbers, values are annotation numbers. |
| 142 | +--- Example output: (1: 2, 3: 1) |
| 143 | +--- @param annotations table<int, int> Line number to annotation number mapping |
| 144 | +--- @return string Typst dictionary literal |
| 145 | +local function annotations_to_typst_dict(annotations) |
| 146 | + local pairs_list = {} |
| 147 | + local keys = {} |
| 148 | + for k in pairs(annotations) do |
| 149 | + table.insert(keys, k) |
| 150 | + end |
| 151 | + table.sort(keys) |
| 152 | + for _, line_num in ipairs(keys) do |
| 153 | + table.insert(pairs_list, |
| 154 | + string.format('"%d": %d', line_num, annotations[line_num])) |
| 155 | + end |
| 156 | + return '(' .. table.concat(pairs_list, ', ') .. ')' |
| 157 | +end |
| 158 | + |
| 159 | +--- Check whether a block is an OrderedList that looks like an annotation list. |
| 160 | +--- Annotation lists are OrderedLists immediately following a code block, |
| 161 | +--- where each item corresponds to an annotation number. |
| 162 | +--- @param block pandoc.Block |
| 163 | +--- @return boolean |
| 164 | +local function is_annotation_ordered_list(block) |
| 165 | + return block and block.t == 'OrderedList' |
| 166 | +end |
| 167 | + |
| 168 | +--- Convert an OrderedList to Typst annotation item RawBlocks. |
| 169 | +--- Each list item becomes a #code-window-annotation-item(block-id, n)[...] call. |
| 170 | +--- @param ol pandoc.OrderedList The ordered list to convert |
| 171 | +--- @param wrapper_prefix string Prefix for the Typst function name |
| 172 | +--- @param block_id integer Unique block identifier for bidirectional linking |
| 173 | +--- @return pandoc.List List of RawBlock elements |
| 174 | +local function ordered_list_to_typst_blocks(ol, wrapper_prefix, block_id) |
| 175 | + local blocks = {} |
| 176 | + local start = ol.listAttributes and ol.listAttributes.start or 1 |
| 177 | + for i, item in ipairs(ol.content) do |
| 178 | + local annot_num = start + i - 1 |
| 179 | + local content_blocks = pandoc.Blocks(item) |
| 180 | + local rendered = pandoc.write(pandoc.Pandoc(content_blocks), 'typst') |
| 181 | + rendered = rendered:gsub('%s+$', '') |
| 182 | + table.insert(blocks, pandoc.RawBlock('typst', string.format( |
| 183 | + '#%s-annotation-item(%d, %d)[%s]', |
| 184 | + wrapper_prefix, block_id, annot_num, rendered |
| 185 | + ))) |
| 186 | + end |
| 187 | + return blocks |
| 188 | +end |
| 189 | + |
| 190 | +-- ============================================================================ |
| 191 | +-- MODULE EXPORTS |
| 192 | +-- ============================================================================ |
| 193 | + |
| 194 | +return { |
| 195 | + LANG_COMMENT_CHARS = LANG_COMMENT_CHARS, |
| 196 | + resolve_annotations = resolve_annotations, |
| 197 | + annotations_to_typst_dict = annotations_to_typst_dict, |
| 198 | + is_annotation_ordered_list = is_annotation_ordered_list, |
| 199 | + ordered_list_to_typst_blocks = ordered_list_to_typst_blocks, |
| 200 | +} |
0 commit comments