Restyle the filter extension headers and markup

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 = { ["&"] = "&amp;", ["<"] = "&lt;", [">"] = "&gt;" }
 
--- 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