Added comments and nicer formatting of Lua scripts in the 'core' directory.

Author: Lethja

core/BENCH.LUA

@@ -1,53 +1,171 @@
 #!/usr/bin/env lua
 
+---Get the operating system the script is running on
+---@return string A string that will read: DOS, NT, UNIX or Unknown
 function OS()
-	if os.getenv("COMSPEC")then return os.getenv("OS")and"NT"or"DOS"
-	else return os.getenv("SHELL")and"UNIX"or"Unknown"end end
+    if os.getenv("COMSPEC") then
+        return os.getenv("OS") and "NT" or "DOS"
+    else
+        return os.getenv("SHELL") and "UNIX" or "Unknown"
+    end
+end
+
+---Benchmark start, prints the benchmark name and records the current time
+---@param name string The name of the benchmark
+---@param it number The number of times the benchmark will loop
+---@return number The current clock time
 function BS(name, it)
-	local t=#tostring(it)>10 and string.format("%10e",it):gsub("%..-e","e")or it
-	io.write(string.format("%-9s",name).."\t"..string.format("%10s",t).."\t")io.flush()return os.clock()end
+    local t = #tostring(it) > 10 and string.format("%10e", it):gsub("%..-e", "e") or it
+    io.write(string.format("%-9s", name) .. "\t" .. string.format("%10s", t) .. "\t")
+    io.flush()
+    return os.clock()
+end
+
+---Benchmark end, prints the benchmarks duration
+---@param st number The start time returned by BS
 function BE(st)
-	local t=os.clock()-st
-	local m,s=math.floor(t/60),t%60
-	io.write(string.format("%7d:%09.6f\n",m,s))end
+    local t = os.clock() - st
+    local m, s = math.floor(t / 60), t % 60
+    io.write(string.format("%7d:%09.6f\n", m, s))
+end
+
+---A benchmark for calculating Pi using the Nilkantha's series
 local function b_pi()
-	local it,pi,si=S,3,1
-	local b=BS("Nilakantha Pi",it)
-	for i=2,it*2,2 do pi=pi+si*(4/(i*(i+1)*(i+2)))si=-si end BE(b)end
+    local it, pi, si = S, 3, 1
+    local b = BS("Nilakantha Pi", it)
+    for i = 2, it * 2, 2 do
+        pi = pi + si * (4 / (i * (i + 1) * (i + 2)))
+        si = -si
+    end
+    BE(b)
+end
+
+---A benchmark for calculating a common divisor
 local function b_gcd()
-	local function gcd(a,b)while b~=0 do a,b=b,a%b end return a end
-	local r,b=0,BS("Common Divisor",S)
-	for i=1,S do local x,y=i,S-i+1 r=gcd(x,y)end BE(b)end
+    local function gcd(a, b)
+        while b ~= 0 do
+            a, b = b, a % b
+        end
+        return a
+    end
+    local r, b = 0, BS("Common Divisor", S)
+    for i = 1, S do
+        local x, y = i, S - i + 1
+        r = gcd(x, y)
+    end
+    BE(b)
+end
+
+---A benchmark for calculating multiplication performance
 local function b_mul()
-	local r,b=1,BS("Multiplication",B)
-	for _=1,B do r=(r*1.000000001)end BE(b)end
+    local r, b = 1, BS("Multiplication", B)
+    for _ = 1, B do
+        r = (r * 1.000000001)
+    end
+    BE(b)
+end
+
+---A benchmark for calculating division performance
 local function b_div()
-	local m,r=B,1
-	local b=BS("Division",m)m=m+1
-	for i=2,m do r=r/i end BE(b)end
+    local m, r = B, 1
+    local b = BS("Division", m)
+    m = m + 1
+    for i = 2, m do
+        r = r / i
+    end
+    BE(b)
+end
+
+---A benchmark for calculating addition performance
 local function b_add()
-	local r,b=1,BS("Addition",B)
-	for i=1,B do r=r+i end BE(b)end
+    local r, b = 1, BS("Addition", B)
+    for i = 1, B do
+        r = r + i
+    end
+    BE(b)
+end
+
+---A benchmark for calculating floating point addition performance
 local function b_flt()
-	local r,b=1.0,BS("Float Addition",B)
-	for _=1,B do r=r+0.01 end BE(b)end
+    local r, b = 1.0, BS("Float Addition", B)
+    for _ = 1, B do
+        r = r + 0.01
+    end
+    BE(b)
+end
+
+---A benchmark for calculating subtraction performance
 local function b_sub()
-	local r,b=1,BS("Subtraction",B)
-	for i=B,1,-1 do r=r-i end BE(b)end
+    local r, b = 1, BS("Subtraction", B)
+    for i = B, 1, -1 do
+        r = r - i
+    end
+    BE(b)
+end
+
+---A benchmark for calculating array iteration performance
 local function b_arr()
-	local b,a,s=BS("Array Loop",S),{},0
-	for i=1,S do a[i]=i%10 end
-	for i=1,S do a[i]=a[i]*2 end
-	for i=1,S do s=s+a[i]end BE(b)end
-local function L()print(string.rep('_',49))end
-print("Runtime:",_VERSION)print("OS Family:",OS())
-print("Minimum Int:",math.mininteger or"Unknown")
-print("Maximum Int:",math.maxinteger or"Unknown")
-M=tonumber(arg[1])if not M or M<1980 then print("\nTo benchmark,run again and specify a year > 1979")os.exit()end
-print("\nRunning benchmark: "..M)M=(M-1955)/25
-B,S=math.floor(500^M),math.floor(100^M)
-print("\nBenchmark","Iterations","Time (min:sec.ms)")L()
-b=os.clock()b_add()b_flt()b_sub()b_mul()b_div()b_pi()b_gcd()b_arr()
-LIB=true package.path=package.path..";?.LUA" pcall(require,"EXBENCH")L()
-io.write("Total:\t\t"..string.format("%8.3fkB",collectgarbage("count")).."\t")BE(b)
-print("Press Enter to Exit...")io.read()os.exit()
+    local b, a, s = BS("Array Loop", S), {}, 0
+    for i = 1, S do
+        a[i] = i % 10
+    end
+    for i = 1, S do
+        a[i] = a[i] * 2
+    end
+    for i = 1, S do
+        s = s + a[i]
+    end
+    BE(b)
+end
+
+---Print a horizontal line on the screen
+local function L()
+    print(string.rep('_', 49))
+end
+
+--Print basic system and Lua information
+print("Runtime:", _VERSION)
+print("OS Family:", OS())
+print("Minimum Int:", math.mininteger or "Unknown")
+print("Maximum Int:", math.maxinteger or "Unknown")
+
+--Check what benchmark to run
+M = tonumber(arg[1])
+if not M or M < 1980 then
+    print("\nTo benchmark,run again and specify a year > 1979")
+    os.exit()
+end
+
+print("\nRunning benchmark: " .. M)
+
+--Make the benchmark do more iterations of every test for each year above 1980
+M = (M - 1955) / 25
+B, S = math.floor(500 ^ M), math.floor(100 ^ M)
+
+print("\nBenchmark", "Iterations", "Time (min:sec.ms)")
+L()
+--Benchmark Start
+b = os.clock()
+b_add()
+b_flt()
+b_sub()
+b_mul()
+b_div()
+b_pi()
+b_gcd()
+b_arr()
+
+--Run extended benchmarks if available
+LIB = true
+package.path = package.path .. ";?.LUA" --In case of a case sensitive operating system
+pcall(require, "EXBENCH")
+
+--Benchmark Finish
+L()
+io.write("Total:\t\t" .. string.format("%8.3fkB", collectgarbage("count")) .. "\t")
+BE(b)
+
+--Wait for user input so the benchmark results can be read on operating systems that would automatically close the window
+print("Press Enter to Exit...")
+io.read()
+os.exit()

core/README.LUA

@@ -6,7 +6,9 @@
 To run the script, pass it to a lua binary as an argument.
 For full Lua language documentation visit https://www.lua.org/docs.html --]]
 
-H=tonumber(os.date('%H'))
-T=(H<4 or H>20)and'night'or H<9 and'morning'or H>16 and'evening'or'day'
-print('Good '..T..' from '.._VERSION..'.')
-print("Press Enter to Exit...")io.read()os.exit()
+H = tonumber(os.date('%H'))
+T = (H < 4 or H > 20) and 'night' or H < 9 and 'morning' or H > 16 and 'evening' or 'day'
+print('Good ' .. T .. ' from ' .. _VERSION .. '.')
+print("Press Enter to Exit...")
+io.read()
+os.exit()

core/S256SUM.LUA

@@ -4,33 +4,122 @@
 ---@param file file The file
 ---@return string SHA-256 checksum
 function sha256_file(file)
-	local M,K=0xFFFFFFFF,{0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2}
-	local function RR(x,n)return (x>>n)|((x&M)<<(32-n))end
-	local function TF(k,H)local W={}for i=0,15 do local o=i*4+1 W[i]=string.byte(k,o)<<24|string.byte(k,o+1)<<16|string.byte(k,o+2)<<8|string.byte(k,o+3)end
-		for i=16,63 do
-			local s0,s1=RR(W[i-15],7)~RR(W[i-15],18)~(W[i-15]>>3),RR(W[i-2],17)~RR(W[i-2],19)~(W[i-2]>>10) --#squish keep-eol
-			W[i]=(W[i-16]+s0+W[i-7]+s1)&M end
-		local a,b,c,d,e,f,g,h=table.unpack(H)for i=0,63 do
-			local S0,S1,ch,maj=RR(a,2)~RR(a,13)~RR(a,22),RR(e,6)~RR(e,11)~RR(e,25),(e&f)~((~e)&g),(a&b)~(a&c)~(b&c) --#squish keep-eol
-			local t1,t2=(h+S1+ch+K[i+1]+W[i])&M,(S0+maj)&M
-			h=g g=f f=e e=(d+t1)&M d=c c=b b=a a=(t1+t2)&M end
-		H[1]=(H[1]+a)&M H[2]=(H[2]+b)&M H[3]=(H[3]+c)&M H[4]=(H[4]+d)&M H[5]=(H[5]+e)&M H[6]=(H[6]+f)&M H[7]=(H[7]+g)&M H[8]=(H[8]+h)&M end
+    -- M = Maximum value of number (32-bits)
+    -- K = SHA256 round constants
+    local M, K = 0xFFFFFFFF, {
+		0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+		0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+		0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+		0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+		0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+		0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+		0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+		0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+		0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+		0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+		0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+	}
 
-	local function P(l)local ml,p,pl=l*8,"\128",56-(l%64) --#squish keep-eol
-		if pl<=0 then pl=pl+64 end p=p..string.rep("\0",pl-1) --#squish keep-eol
-		for i=7,0,-1 do p=p..string.char((ml>>(i*8))&0xFF)end return p end
+    ---Right rotate a 32-bit value
+    ---@param x number The 32-bit value to be rotated
+    ---@param n number The number of rotations to the right that should be done
+    ---@return number The right shifted value
+    local function RR(x, n)
+        return (x >> n) | ((x & M) << (32 - n))
+    end
 
-	local H,l={0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19},0
-	while 1 do local c=file:read(64)if not c then break end l=l+#c if #c<64 then c=c..P(l)TF(c,H)break end TF(c,H)end
-	local function h(x)return string.format("%08x",x)end
-	return table.concat({h(H[1]),h(H[2]),h(H[3]),h(H[4]),h(H[5]),h(H[6]),h(H[7]),h(H[8])}) --#squish keep-eol
+    ---SHA-256 transformation function
+    ---@param k string A 64-byte chunk of the message
+    ---@param H table The current hash state (8 32-bit values)
+    local function TF(k, H)
+        local W = {}
+        for i = 0, 15 do -- Convert chunk into 32-bit list
+            local o = i * 4 + 1
+            W[i] = string.byte(k, o) << 24 | string.byte(k, o + 1) << 16 | string.byte(k, o + 2) << 8 | string.byte(k, o + 3)
+        end
+        for i = 16, 63 do -- Message expansion
+            local s0, s1 = RR(W[i - 15], 7) ~ RR(W[i - 15], 18) ~ (W[i - 15] >> 3), RR(W[i - 2], 17) ~ RR(W[i - 2], 19) ~ (W[i - 2] >> 10) --#squish keep-eol
+            W[i] = (W[i - 16] + s0 + W[i - 7] + s1) & M
+        end
+        local a, b, c, d, e, f, g, h = table.unpack(H)
+        for i = 0, 63 do
+            local S0, S1, ch, maj = RR(a, 2) ~ RR(a, 13) ~ RR(a, 22), RR(e, 6) ~ RR(e, 11) ~ RR(e, 25), (e & f) ~ ((~e) & g), (a & b) ~ (a & c) ~ (b & c) --#squish keep-eol
+            local t1, t2 = (h + S1 + ch + K[i + 1] + W[i]) & M, (S0 + maj) & M
+            h = g
+            g = f
+            f = e
+            e = (d + t1) & M
+            d = c
+            c = b
+            b = a
+            a = (t1 + t2) & M
+        end
+        H[1] = (H[1] + a) & M
+        H[2] = (H[2] + b) & M
+        H[3] = (H[3] + c) & M
+        H[4] = (H[4] + d) & M
+        H[5] = (H[5] + e) & M
+        H[6] = (H[6] + f) & M
+        H[7] = (H[7] + g) & M
+        H[8] = (H[8] + h) & M
+    end
+
+    ---Create SHA-256 padding for message
+    ---@param l number The length of the message in bytes
+    ---@return string The padding string to append to the message
+    local function P(l)
+        local ml, p, pl = l * 8, "\128", 56 - (l % 64) --#squish keep-eol
+        if pl <= 0 then
+            pl = pl + 64
+        end
+        p = p .. string.rep("\0", pl - 1) --#squish keep-eol
+        for i = 7, 0, -1 do
+            p = p .. string.char((ml >> (i * 8)) & 0xFF)
+        end
+        return p
+    end
+
+    local H, l = { 0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19 }, 0
+    while 1 do
+        local c = file:read(64)
+        if not c then
+            break
+        end
+        l = l + #c
+        if #c < 64 then
+            c = c .. P(l)
+            TF(c, H)
+            break
+        end
+        TF(c, H)
+    end
+    local function h(x)
+        return string.format("%08x", x)
+    end
+    return table.concat({ h(H[1]), h(H[2]), h(H[3]), h(H[4]), h(H[5]), h(H[6]), h(H[7]), h(H[8]) }) --#squish keep-eol
+end
+
+if LIB then
+    return -- Don't run below code if brought in as a library
 end
 
-if LIB then return end
-if #arg<1 then print((arg[-1] or "?").." "..(arg[0] or "?").." [FILE]...")os.exit(1) --#squish keep-eol
-else for i=1,#arg do local f,e=io.open(arg[i],"rb") --#squish keep-eol
-		if not f then print(e)os.exit(1)end
-		local sum=sha256_file(f)f:close() --#squish keep-eol
-		if sum then print(sum.."  "..arg[i])else print(arg[i]..": ".."Unknown error")os.exit(-1)end
-	end
+if #arg < 1 then
+    print((arg[-1] or "?") .. " " .. (arg[0] or "?") .. " [FILE]...")
+    os.exit(1) --#squish keep-eol
+else
+    for i = 1, #arg do
+        local f, e = io.open(arg[i], "rb") --#squish keep-eol
+        if not f then
+            print(e)
+            os.exit(1)
+        end
+        local sum = sha256_file(f)
+        f:close() --#squish keep-eol
+        if sum then
+            print(sum .. "  " .. arg[i])
+        else
+            print(arg[i] .. ": " .. "Unknown error")
+            os.exit(-1)
+        end
+    end
 end