Improved variable documentation and formatting.

Author: Lethja

arch/INFLATE.LUA

@@ -6,19 +6,18 @@ if not LIB then print("Please run unzip instead") os.exit(1) end
 ---@param f file The output file handle to allow seeking the sliding window
 function inflate(r, w, f)
 
-	--   Z = size of sliding window
-	--   b = buffer
-	--   p = position
-	--  bb = bit buffer
-	--  bc = bit count
-	--  op = output position
-	--  kg = keep going (in a loop)
-	-- lex = length base & extra bits (pairs of bytes)
-	-- dix = distance extra bits (1 byte per entry)
-	-- dib = distance base (packed 32-bit LE)
-	local Z, b, p, bb, bc, op, kg, lex, dix, dib = z and 65536 or 32768, "", 1, 0, 0, 0, 1,
-	-- lex, dix, dib packed strings
-
+	--   b = Buffer
+	--   p = Position
+	--  bb = Bit buffer
+	--  bc = Bit count
+	--  op = Output position
+	--  kg = Keep going (in a loop)
+	-- lex = Length base & extra bits (pairs of bytes)
+	-- dix = Distance extra bits (1 byte per entry)
+	-- dib = Distance base (packed 32-bit LE)
+	local b, p, bb, bc, op, kg, lex, dix, dib = "", 1, 0, 0, 0, 1,
+
+	-- lex, dix & dib are packed string constants
 	"\3\0\4\0\5\0\6\0\7\0\8\0\9\0\10\0\11\1\13\1\15\1\17\1\19\2\23\2\27\2\31\2\35\3\43\3\51\3\59\3\67\4\83\4\99\4\115\4\131\5\163\5\195\5\227\5\2\0",
 	"\0\0\0\0\1\1\2\2\3\3\4\4\5\5\6\6\7\7\8\8\9\9\10\10\11\11\12\12\13\13\14\14\15\15\16\16\17\17\18\18\19\19\20\20\21\21\22\22\23\23\24\24\25\25\26\26\27\27\28\28\29\29\30\30",
 	"\1\0\0\0\2\0\0\0\3\0\0\0\4\0\0\0\5\0\0\0\7\0\0\0\9\0\0\0\13\0\0\0\17\0\0\0\25\0\0\0\33\0\0\0\49\0\0\0\65\0\0\0\97\0\0\0\129\0\0\0\193\0\0\0\1\1\0\0\129\1\0\0\1\2\0\0\1\3\0\0\1\4\0\0\1\6\0\0\1\8\0\0\1\12\0\0\1\16\0\0\1\24\0\0\1\32\0\0\1\48\0\0\1\64\0\0\1\96\0\0\1\128\0\0\1\192\0\0\1\0\1\0\1\128\1\0\1\0\2\0\1\128\2\0\1\0\4\0\1\128\4\0\1\0\8\0\1\128\8\0\1\0\16\0\1\128\16\0\1\0\32\0\1\128\32\0\1\0\64\0\1\128\64\0\1\0\128\0\1\128\128\0\1\0\0\1\1\128\0\1\1\0\0\2\1\128\0\2\1\0\0\4\1\128\0\4\1\0\0\8\1\128\0\8\1\0\0\16\1\128\0\16\1\0\0\32\1\128\0\32\1\0\0\64\1\128\0\64\1\0\0\128\1\128\0\128\1\0\0\0\192"
@@ -53,7 +52,7 @@ function inflate(r, w, f)
 	function rb(n)
 		nb(n)
 
-		-- v = extracted bit value
+		-- v = Extracted bit value
 		local v = bb & ((1 << n) - 1)
 
 		bb, bc = (bb >> n), bc - n
@@ -65,14 +64,14 @@ function inflate(r, w, f)
 	---@return table A Huffman object containing the lookup table (`tab`) and the maximum code length (`max`).
 	function mh(ls)
 
-		-- m = maximum length
-		-- c = counts
-		-- d = code
-		-- n = next code
-		-- t = tab
+		-- m = Maximum length
+		-- c = Counts
+		-- d = Code
+		-- n = Next code
+		-- t = Tab
 		local m, c, d, n, t = 0, {}, 0, {}, {}
 
-		-- l = length
+		-- l = Length
 		for _, l in ipairs(ls) do
 			if l > 0 then
 				c[l] = (c[l] or 0) + 1
@@ -81,7 +80,7 @@ function inflate(r, w, f)
 			end
 		end
 
-		-- i = bits
+		-- i = Bits
 		for i = 1, m do
 			d = (d + (c[i - 1] or 0)) << 1
 			n[i] = d
@@ -102,8 +101,8 @@ function inflate(r, w, f)
 			return y
 		end
 
-		-- s = sym
-		-- l = len
+		-- s = Sym
+		-- l = Len
 		for s, l in ipairs(ls) do
 			if l > 0 then
 				t[rv(n[l], l)] = { sym = s - 1, len = l }
@@ -119,14 +118,14 @@ function inflate(r, w, f)
 	---@return number The decoded symbol value.
 	function rh(h)
 
-		-- c = code
+		-- c = Code
 		local c = 0
 
-		-- l = len
+		-- l = Len
 		for l = 1, h.max do
 			c = c | (rb(1) << (l - 1))
 
-			-- e = entry
+			-- e = Entry
 			local e = h.tab[c & ((1 << l) - 1)]
 
 			if e and e.len == l then return e.sym end
@@ -137,21 +136,21 @@ function inflate(r, w, f)
 
 	while kg > 0 do
 
-		-- a = final
-		-- t = block type
+		-- a = Final
+		-- t = Block type
 		local a, t = rb(1), rb(2)
 
-		if t == 0 then -- uncompressed block
+		if t == 0 then -- Uncompressed block
 
-			-- lo = lower bits of 16-bit value
-			-- hi = higher bits of 16-bit value
-			--  l = length of value
+			-- lo = Lower bits of 16-bit value
+			-- hi = Higher bits of 16-bit value
+			--  l = Length of value
 			local lo, hi, l
 
-			bb, bc = 0, 0 -- align and disregard remaining bits
-			lo, hi = rb(8), rb(8) -- read length
-			l = lo + hi * 256 -- calculate length
-			lo, hi = rb(8), rb(8) -- read n-length
+			bb, bc = 0, 0 -- Align and disregard remaining bits
+			lo, hi = rb(8), rb(8) -- Read length
+			l = lo + hi * 256 -- Calculate length
+			lo, hi = rb(8), rb(8) -- Read n-length
 			if (l ~ (lo + hi * 256)) ~= 0xFFFF then error("stored block LEN/NLEN mismatch", 0) end
 
 			-- Copy raw data
@@ -171,14 +170,14 @@ function inflate(r, w, f)
 
 		elseif t == 1 or t == 2 then
 
-			-- ll = literal length
-			-- dl = distance length
-			--  h = huffman
-			--  d = distances
+			-- ll = Literal/length bit-lengths
+			-- dl = Distance bit-lengths
+			--  h = Literal/length Huffman decoding table
+			--  d = Distance Huffman decoding table
 			local ll, dl, h, d = {}, {}
 
 			if t == 1 then
-				-- fixed Huffman
+				-- Fixed Huffman
 				for _ = 0, 143 do ll[#ll + 1] = 8 end
 				for _ = 144, 255 do ll[#ll + 1] = 9 end
 				for _ = 256, 279 do ll[#ll + 1] = 7 end
@@ -187,15 +186,15 @@ function inflate(r, w, f)
 				for _ = 0, 31 do dl[#dl + 1] = 5 end
 				d = mh(dl)
 			else
-				-- dynamic Huffman
-
-				-- hl = hlit
-				-- hd = hdist
-				-- hc = hclen
-				-- od = order
-				-- cl = clen
-				-- le = lens
-				-- ch = chuff
+				-- Dynamic Huffman
+
+				-- hl = Literal/length code count (HLIT)
+				-- hd = Distance code count (HDIST)
+				-- hc = Meta-code length count (HCLEN)
+				-- od = Permutation order for code lengths
+				-- cl = Code lengths for the meta-table
+				-- le = Decoded bit-lengths for literal/distance tables
+				-- ch = Huffman table for decoding bit-lengths
 				local hl, hd, hc, od, cl, le, ch = rb(5) + 257, rb(5) + 1, rb(4) + 4, "\16\17\18\0\8\7\9\6\10\5\11\4\12\3\13\2\14\1\15", {}, {}
 
 				for i = 1, 19 do cl[i] = 0 end
@@ -204,9 +203,9 @@ function inflate(r, w, f)
 
 				while #le < hl + hd do
 
-					-- s = symbol
-					-- x = repeat count
-					-- l = code length
+					-- s = Symbol
+					-- x = Repeat count
+					-- l = Code length
 					local s, x, l = rh(ch)
 
 					if s <= 15 then
@@ -229,7 +228,7 @@ function inflate(r, w, f)
 
 			while true do
 
-				-- s = symbol
+				-- s = Symbol
 				local s = rh(h)
 
 				if s < 256 then
@@ -239,11 +238,11 @@ function inflate(r, w, f)
 					break
 				else
 
-					-- li = length index
-					-- ba = base
-					--  x = extra
-					--  a = add
-					--  l = length
+					-- li = Length index
+					-- ba = Base
+					--  x = Extra
+					--  a = Add
+					--  l = Length
 					local li, ba, x, l = (s - 257) * 2 + 1
 
 					ba, x = lex:byte(li), lex:byte(li + 1)
@@ -252,10 +251,10 @@ function inflate(r, w, f)
 
 					if d.max > 0 and #d.tab > 0 then
 
-						-- ds = distance symbol
-						-- db = distance base
-						-- dx = distance extra bits
-						-- dv = distance value
+						-- ds = Distance symbol
+						-- db = Distance base
+						-- dx = Distance extra bits
+						-- dv = Distance value
 						local ds, db, dx, dv = rh(d)
 
 						-- Extract 32-bit unsigned little-endian integer (I4) and extra bits byte
@@ -270,7 +269,7 @@ function inflate(r, w, f)
 						-- Read from output history using the file-backed sliding window
 						f:seek("end", -dv)
 
-						-- n = pattern
+						-- n = Pattern
 						local n = f:read(math.min(dv, l))
 
 						n = n:rep(l // dv) .. n:sub(1, l % dv)