Diff options
Diffstat (limited to 'custom/extensions/syntax-highlight.lua')
| -rw-r--r-- | custom/extensions/syntax-highlight.lua | 204 |
1 file changed, 93 insertions, 111 deletions
diff --git a/custom/extensions/syntax-highlight.lua b/custom/extensions/syntax-highlight.lua index b7ed822..862965a 100644 --- a/custom/extensions/syntax-highlight.lua +++ b/custom/extensions/syntax-highlight.lua @@ -1,94 +1,64 @@ --- Server-side syntax highlighting for the tree and blob views, used with the --- source-filter setting in cgitrc and the lua: prefix so it runs in cgit's --- embedded interpreter with no per-request process. +-- Server-side syntax highlighting for cgit's tree and blob views, run inside +-- cgit's embedded Lua interpreter so a coloured blob costs no extra process +-- per request. Colouring is deliberately left out of cgit itself, which +-- serves plain escaped text on its own, so this filter is named by the +-- source-filter setting and any other program could take its place. Tokens +-- come from the Scintillua lexers and reach the page wrapped in span elements +-- carrying the hl- classes that assets/cgit.css styles. Whenever a piece is +-- missing or will not load, from lpeg down to a single lexer, the file falls +-- back to plain escaped text instead of failing, so uncoloured code means a +-- missing dependency rather than an error. It runs on Lua 5.1 through 5.5 and +-- LuaJIT. -- -- source-filter=lua:/usr/lib/cgit/extensions/syntax-highlight.lua --- --- Highlighting is deliberately not built into cgit itself. Without this filter --- cgit serves plain escaped text, and any other program can take its place. --- --- SUPPORTED LUA --- --- Lua 5.1 through 5.5 and LuaJIT. Scintillua 6.7 loads all of its lexers on --- LuaJIT, so the two do not have to be matched up. A lexer that will not load --- is skipped and that file falls back to plain escaped text, so a mismatched --- pair degrades rather than breaking the page. --- --- REQUIREMENTS --- --- Two pieces, and BOTH must be installed. When either is missing the filter --- serves plain escaped text by design, so uncolored code means a missing --- dependency, not an error. --- --- 1. lpeg, the parsing module, for the Lua cgit is linked against. Scintillua --- does NOT bundle it, it must come from the system, and forgetting it is the --- usual reason nothing happens. --- --- # Debian and Ubuntu --- sudo apt install lua-lpeg --- # Fedora --- sudo dnf install lua-lpeg --- # Alpine --- sudo apk add lua5.1-lpeg --- # or with LuaRocks, matched to your Lua version --- sudo luarocks --lua-version 5.1 install lpeg --- --- 2. Scintillua, the lexer collection from the Textadept editor. Around 160 --- languages as plain .lua files, nothing to compile. Download a release and --- unpack it anywhere. Only the lexers directory is needed. --- --- https://orbitalquark.github.io/scintillua/ --- --- The lexers are found by probing, in order --- --- $CGIT_SCINTILLUA_PATH (used alone when set, no fallback) --- <dir of $CGIT_CONFIG>/scintillua/lexers --- the scintillua_dirs list among the configuration values below --- --- so either set the variable in the web server environment, or place (or --- symlink) the scintillua directory next to your cgitrc. --- --- SECURITY --- --- Every probed directory is placed on package.path and its Lua is executed in --- cgit's process. Make sure none of them is writable by other users, or someone --- who can write there gains code execution as the web server. On macOS in --- particular, /opt/homebrew/share is group-writable by default. --- --- LIMITATIONS --- --- cgit sends the filter output through a C string sink that stops at the first --- NUL byte, so a blob containing a NUL is truncated there. This affects binary --- files that slip past cgit's text detection, not ordinary source. --- --- OUTPUT --- --- Tokens are wrapped in <span> elements carrying the hl- classes that --- assets/cgit.css styles. Every input byte up to the first NUL is preserved, so --- the line number gutter stays aligned. --- Files larger than this many bytes are served escaped but unhighlighted, so a --- huge blob does not cost a lexing pass. Kept well below cgit's max-blob-size. +-- Files larger than this many bytes are served escaped but unhighlighted, so +-- a huge blob does not cost a lexing pass. Kept well below cgit's +-- max-blob-size. local max_bytes = 512 * 1024 --- Environment variable that, when set, points straight at the Scintillua --- lexers directory and is used alone. +-- Size of the pieces the unhighlighted fallback is written in, so a large +-- blob does not cost a full-size second copy all at once. +local slice_bytes = 64 * 1024 + +-- Set this in the web server environment to point straight at the Scintillua +-- lexers directory, in which case nothing else is probed. local scintillua_env = "CGIT_SCINTILLUA_PATH" --- Directories probed for the lexers when that variable is not set. The --- directory of $CGIT_CONFIG, when set, is tried ahead of these. Keep every one --- of these unwritable by others, see the SECURITY note above. +-- Directories probed for the lexers when that variable is not set, tried +-- after the directory of $CGIT_CONFIG, so placing or symlinking a scintillua +-- directory next to cgitrc is enough to be found. Scintillua is the lexer +-- collection from the Textadept editor, around 160 languages as plain .lua +-- files with nothing to compile, from +-- https://orbitalquark.github.io/scintillua/. It does not bundle lpeg, which +-- it needs and which has to be built for the Lua cgit is linked against, and +-- forgetting that is the usual reason nothing is coloured. +-- +-- # Debian and Ubuntu +-- sudo apt install lua-lpeg +-- # Fedora +-- sudo dnf install lua-lpeg +-- # Alpine +-- sudo apk add lua5.1-lpeg +-- # or with LuaRocks, matched to your Lua version +-- sudo luarocks --lua-version 5.1 install lpeg +-- +-- Every directory probed goes on package.path and its Lua is executed in +-- cgit's process, so one that other users can write to hands them code +-- execution as the web server. On macOS /opt/homebrew/share is group-writable +-- by default, so check it before leaving it in this list. local scintillua_dirs = { "/usr/local/share/scintillua/lexers", "/usr/share/scintillua/lexers", "/opt/homebrew/share/scintillua/lexers", } --- Scintillua tag name (its first dotted component) to a cgit css class. Only --- the six classes below exist in assets/cgit.css. Add a class there and a row --- here to style more token kinds. Tokens with no row render as plain text, --- which is what most themes want for operators and identifiers. +-- A Scintillua tag name, meaning its first dotted component, mapped to a cgit +-- css class. Only the six classes named here exist in assets/cgit.css, so +-- styling another kind of token means adding a class there and a row here. A +-- tag with no row renders as plain text, which is what most themes want for +-- operators and identifiers. local css = { comment = "hl-comment", string = "hl-string", @@ -106,10 +76,10 @@ local css = { ["function"] = "hl-func", } --- Extension to lexer-name fixes for the fallback path, used only when this --- Scintillua has no detect(). Most extensions already equal their lexer name, --- these are the frequent exceptions. A wrong guess just falls back to plain --- text, so there is no harm in listing best-effort entries. +-- Extension to lexer name fixes for the fallback path, reached only when this +-- Scintillua has no detect(). Most extensions already equal their lexer name +-- and these are the frequent exceptions. A wrong guess only falls back to +-- plain text, so a best-effort entry costs nothing. local ext_lexer = { py = "python", js = "javascript", ts = "typescript", rb = "ruby", pl = "perl", pm = "perl", sh = "bash", @@ -118,13 +88,12 @@ local ext_lexer = { } -local lexer_mod = nil +local scintillua = nil local filename = "" local chunks = {} local escape_map = { ["&"] = "&", ["<"] = "<", [">"] = ">" } --- Escape the three HTML metacharacters in a single pass. local function escape(s) return (string.gsub(s, "[&<>]", escape_map)) end @@ -142,9 +111,12 @@ local function scintillua_path() candidates[#candidates + 1] = dir .. "/scintillua/lexers" end end - for _, d in ipairs(scintillua_dirs) do - candidates[#candidates + 1] = d + for _, dir in ipairs(scintillua_dirs) do + candidates[#candidates + 1] = dir end + -- A candidate counts only when lexer.lua is actually in it, so a + -- directory that exists but holds no lexers does not shadow a + -- later one. for _, dir in ipairs(candidates) do local f = io.open(dir .. "/lexer.lua", "r") if f then @@ -160,38 +132,43 @@ local function load_scintillua() if not dir then return nil end + -- cgit keeps this interpreter alive across requests, so package.path is + -- only extended when the directory is not already on it. if not string.find(package.path, dir, 1, true) then package.path = dir .. "/?.lua;" .. package.path end local ok, mod = pcall(require, "lexer") - -- A real Scintillua exposes load(). Anything else on the path that happens - -- to be called lexer is not usable. + -- A real Scintillua exposes load(), so anything else on the path that + -- happens to be called lexer is rejected rather than used. if ok and type(mod) == "table" and type(mod.load) == "function" then return mod end return nil end +-- Loading a lexer runs its Lua, and one written for another Scintillua can +-- raise, so a failure here just leaves this file uncoloured. local function load_lexer_name(name) if name == nil then return nil end - local ok, lex = pcall(lexer_mod.load, name) - if ok and lex then - return lex + local ok, lexer = pcall(scintillua.load, name) + if ok and lexer then + return lexer end return nil end --- Resolve a lexer for the file, preferring Scintillua's own filename detection --- when this version provides it, then an extension map, then the raw extension. +-- Resolve a lexer for the file, preferring Scintillua's own filename +-- detection where this version provides it, then the extension map above, +-- then the raw extension. local function lexer_for(name) - if type(lexer_mod.detect) == "function" then - local ok, lang = pcall(lexer_mod.detect, name) + if type(scintillua.detect) == "function" then + local ok, lang = pcall(scintillua.detect, name) if ok and lang then - local lex = load_lexer_name(lang) - if lex then - return lex + local lexer = load_lexer_name(lang) + if lexer then + return lexer end end end @@ -204,28 +181,32 @@ local function lexer_for(name) end local function highlight(text) - local lex = lexer_for(filename) - if not lex then + local lexer = lexer_for(filename) + if not lexer then return nil end - local ok, tokens = pcall(lex.lex, lex, text) + local ok, tokens = pcall(lexer.lex, lexer, text) if not ok or type(tokens) ~= "table" then return nil end local out = {} local pos = 1 + -- Scintillua returns one flat list of a tag name and the position + -- just past the token it names, so a token is the text from where + -- the one before it ended. for i = 1, #tokens, 2 do local tag = tokens[i] - local fin = tokens[i + 1] - local part = escape(string.sub(text, pos, fin - 1)) + local stop = tokens[i + 1] + local part = escape(string.sub(text, pos, stop - 1)) local class = css[string.match(tag, "^[%w_]+")] if class and part ~= "" then part = "<span class='" .. class .. "'>" .. part .. "</span>" end out[#out + 1] = part - pos = fin + pos = stop end - -- Anything the lexer left unconsumed is kept, escaped. + -- A lexer can stop short of the end, and every byte still has to reach + -- the page or the line number gutter beside it drifts out of step. if pos <= #text then out[#out + 1] = escape(string.sub(text, pos)) end @@ -241,14 +222,17 @@ function filter_write(str) chunks[#chunks + 1] = str end +-- cgit takes filter output through a C string sink that stops at the first +-- NUL byte, so a blob holding one is truncated there. That reaches binary +-- files which slip past cgit's text detection, not ordinary source. function filter_close() local text = table.concat(chunks) chunks = {} if #text <= max_bytes then - if lexer_mod == nil then - lexer_mod = load_scintillua() or false + if scintillua == nil then + scintillua = load_scintillua() or false end - if lexer_mod then + if scintillua then local ok, marked = pcall(highlight, text) if ok and marked then html(marked) @@ -256,8 +240,6 @@ function filter_close() end end end - -- Fallback, escaped plain text emitted in slices so a large blob does not - -- cost a full-size second copy all at once. local n = #text if n == 0 then html("") @@ -265,8 +247,8 @@ function filter_close() end local pos = 1 while pos <= n do - html(escape(string.sub(text, pos, pos + 65535))) - pos = pos + 65536 + html(escape(string.sub(text, pos, pos + slice_bytes - 1))) + pos = pos + slice_bytes end return 0 end |