From b89ff14d5ca5424dbb1f3973a8e3571cc908f47a Mon Sep 17 00:00:00 2001 From: XeonSquared Date: Tue, 12 May 2020 17:55:05 +1000 Subject: [PATCH] added type annotations and descriptions for functions where appropriate --- lib/shutil.lua | 16 ++++++++-------- lib/unionfs.lua | 2 +- lib/vtansi.lua | 4 ++-- luapreproc.lua | 1 + module/buffer.lua | 2 +- module/devfs.lua | 2 +- module/fs.lua | 25 +++++++++++++------------ module/io.lua | 6 +++--- module/loadfile.lua | 10 +++++----- module/osutil.lua | 2 +- module/sched.lua | 10 +++++----- module/syslog.lua | 1 + 12 files changed, 42 insertions(+), 39 deletions(-) diff --git a/lib/shutil.lua b/lib/shutil.lua index e093bd3..1ee2a6c 100644 --- a/lib/shutil.lua +++ b/lib/shutil.lua @@ -19,7 +19,7 @@ local function wrapUnits(n) return tostring(math.floor(n))..(scale[count] or "") end -function shutil.import(lib) +function shutil.import(lib) -- string -- boolean -- Imports the functions from library *lib* into the shell environment. local cE = os.getenv("INCLUDE") or shell.include local nE = {} for k,v in pairs(cE) do @@ -31,7 +31,7 @@ function shutil.import(lib) return true end -function shutil.unimport(lib) +function shutil.unimport(lib) -- string -- boolean -- Removes the functions from *lib* from the shell environment. local cE = os.getenv("INCLUDE") or shell.include local nE = {} for k,v in pairs(cE) do @@ -43,7 +43,7 @@ function shutil.unimport(lib) return true end -function shutil.ls(...) +function shutil.ls(...) -- string -- -- Prints contents of directories specified as *...*. local tA = {...} if not tA[1] then tA[1] = "." end for _,d in ipairs(tA) do @@ -56,7 +56,7 @@ function shutil.ls(...) end end -function shutil.cat(...) +function shutil.cat(...) -- string -- -- Outputs the contents of files specified in *...* to the standard output. for _,fn in ipairs({...}) do local f = io.open(fn,"rb") io.write(f:read("*a")) @@ -64,7 +64,7 @@ function shutil.cat(...) end end -function shutil.ps() +function shutil.ps() -- Prints the processes running on the system. print("PID# Parent | Name") for k,v in pairs(os.tasks()) do local t = os.taskInfo(v) @@ -72,7 +72,7 @@ function shutil.ps() end end -function shutil.df() +function shutil.df() -- Prints free disk space. local mt = fs.mounts() local ml = 0 for k,v in pairs(mt) do @@ -88,7 +88,7 @@ function shutil.df() end end -function shutil.mount(addr,path) +function shutil.mount(addr,path) -- string string -- boolean string -- Mounts filesystem component with address *addr* to *path* in the filesystem. if not addr then local mt = fs.mounts() for k,v in pairs(mt) do @@ -114,7 +114,7 @@ function shutil.mount(addr,path) end end -function shutil.free() +function shutil.free() -- Displays used and free memory. print("Total Used Free") print(string.format("%5s %5s %5s",wrapUnits(computer.totalMemory()),wrapUnits(computer.totalMemory()-computer.freeMemory()),wrapUnits(computer.freeMemory()))) end diff --git a/lib/unionfs.lua b/lib/unionfs.lua index 3bd0c01..ca4051d 100644 --- a/lib/unionfs.lua +++ b/lib/unionfs.lua @@ -4,7 +4,7 @@ local function normalise(path) return table.concat(fs.segments(path),"/") end -function unionfs.create(...) +function unionfs.create(...) -- string -- table -- Returns a unionfs object of the directories specified in *...*. local paths,fids,fc = {...}, {}, 0 for k,v in pairs(paths) do paths[k] = "/"..normalise(v) diff --git a/lib/vtansi.lua b/lib/vtansi.lua index a7bfd11..7c41858 100644 --- a/lib/vtansi.lua +++ b/lib/vtansi.lua @@ -1,5 +1,5 @@ local vtansi = {} -function vtansi.vtemu(gpu) -- takes GPU component proxy *gpu* and returns a function to write to it in a manner like an ANSI terminal +function vtansi.vtemu(gpu) -- table -- function -- takes GPU component proxy *gpu* and returns a function to write to it in a manner like an ANSI terminal local colours = {0x0,0xFF0000,0x00FF00,0xFFFF00,0x0000FF,0xFF00FF,0x00B6FF,0xFFFFFF} local mx, my = gpu.maxResolution() local cx, cy = 1, 1 @@ -142,7 +142,7 @@ function vtansi.vtemu(gpu) -- takes GPU component proxy *gpu* and returns a func return termwrite end -function vtansi.vtsession(gpua,scra) -- creates a process to handle the GPU and screen address combination *gpua*/*scra*. Returns read, write and "close" functions. +function vtansi.vtsession(gpua,scra) -- string string -- table -- creates a process to handle the GPU and screen address combination *gpua*/*scra*. Returns read, write and "close" functions. local gpu = component.proxy(gpua) gpu.bind(scra) local write = vtansi.vtemu(gpu) diff --git a/luapreproc.lua b/luapreproc.lua index 00b2a8b..e2d6118 100755 --- a/luapreproc.lua +++ b/luapreproc.lua @@ -181,6 +181,7 @@ env:process(arg[1]) local tmpfile = os.tmpname() if tmpfile:sub(#tmpfile) == "." then tmpfile = tmpfile:sub(1, #tmpfile - 1) end local tmpf = io.open(tmpfile, "wb") +env.code = env.code:gsub("%-%-.-\n","\n"):gsub("\n\n","\n") tmpf:write(env.code) tmpf:close() --if (os.execute("lua minify.lua "..tmpfile.." > "..arg[2])) then diff --git a/module/buffer.lua b/module/buffer.lua index 5609d0a..6fe1b29 100644 --- a/module/buffer.lua +++ b/module/buffer.lua @@ -2,7 +2,7 @@ buffer = {} -function buffer.new(mode, stream) -- create a new buffer in mode *mode* backed by stream object *stream* +function buffer.new(mode, stream) -- string table -- table -- create a new buffer in mode *mode* backed by stream object *stream* local result = { mode = {}, stream = stream, diff --git a/module/devfs.lua b/module/devfs.lua index 64630d7..5c7ea77 100644 --- a/module/devfs.lua +++ b/module/devfs.lua @@ -64,7 +64,7 @@ end devfs.component.address = "devfs" devfs.component.type = "devfs" -function devfs.register(fname,fopen) -- Register a new devfs node with the name *fname* that will run the function *fopen* when opened. This function should return a function for read, a function for write, function for close, and optionally, a function for seek, in that order. +function devfs.register(fname,fopen) -- string function -- -- Register a new devfs node with the name *fname* that will run the function *fopen* when opened. This function should return a function for read, a function for write, function for close, and optionally, a function for seek, in that order. devfs.files[fname] = fopen end diff --git a/module/fs.lua b/module/fs.lua index b99ed6a..c1aa163 100644 --- a/module/fs.lua +++ b/module/fs.lua @@ -3,14 +3,14 @@ fs = {} local fsmounts = {} -- basics -function fs.segments(path) -- splits *path* on each / +function fs.segments(path) -- string -- table -- Splits *path* on each / local segments = {} for segment in path:gmatch("[^/]+") do segments[#segments+1] = segment end return segments end -function fs.resolve(path) -- resolves *path* to a specific filesystem mount and path +function fs.resolve(path) -- string -- string string -- Resolves *path* to a specific filesystem mount and path if not path or path == "." then path = os.getenv("PWD") end if path:sub(1,1) ~= "/" then path=(os.getenv("PWD") or "").."/"..path end local segments, rpath, rfs= fs.segments(path) @@ -44,7 +44,7 @@ local function fclose(self) return fsmounts[self.fs].close(self.fid) end -function fs.open(path,mode) -- opens file *path* with mode *mode* +function fs.open(path,mode) -- string string -- table -- Opens file *path* with mode *mode*, returning a file object. mode = mode or "rb" local fsi,path = fs.resolve(path) if not fsmounts[fsi] then return false end @@ -62,7 +62,7 @@ function fs.open(path,mode) -- opens file *path* with mode *mode* return false end -function fs.copy(from,to) -- copies a file from *from* to *to* +function fs.copy(from,to) -- string string -- boolean -- copies a file from *from* to *to* local of = fs.open(from,"rb") local df = fs.open(to,"wb") if not of or not df then @@ -71,33 +71,34 @@ function fs.copy(from,to) -- copies a file from *from* to *to* df:write(of:read("*a")) df:close() of:close() + return true end -function fs.rename(from,to) -- moves file *from* to *to* +function fs.rename(from,to) -- string string -- boolean -- Moves file *from* to *to* local ofsi, opath = fs.resolve(from) local dfsi, dpath = fs.resolve(to) if ofsi == dfsi then fsmounts[ofsi].rename(opath,dpath) return true end - fs.copy(from,to) - fs.remove(from) + if not fs.copy(from,to) then return false end + if not fs.remove(from) then return false end return true end -function fs.mount(path,proxy) -- mounts the filesystem *proxy* to the mount point *path* if it is a directory. BYO proxy. +function fs.mount(path,proxy) -- string table -- boolean -- Mounts the filesystem *proxy* to the mount point *path* if it is a directory. BYO proxy. if fs.isDirectory(path) and not fsmounts[table.concat(fs.segments(path),"/")] then fsmounts[table.concat(fs.segments(path),"/")] = proxy return true end return false, "path is not a directory" end -function fs.umount(path) +function fs.umount(path) -- string -- -- Unmounts filesystem from *path*. local fsi,_ = fs.resolve(path) fsmounts[fsi] = nil end -function fs.mounts() -- returns a table containing the mount points of all mounted filesystems +function fs.mounts() -- -- table -- Returns a table containing the mount points of all mounted filesystems local rt = {} for k,v in pairs(fsmounts) do rt[#rt+1] = k,v.address or "unknown" @@ -105,11 +106,11 @@ function fs.mounts() -- returns a table containing the mount points of all mount return rt end -function fs.address(path) -- returns the address of the filesystem at a given path, if applicable; do not expect a sensical response +function fs.address(path) -- string -- string -- Returns the address of the filesystem at a given path, if applicable; do not expect a sensical response local fsi,_ = fs.resolve(path) return fsmounts[fsi].address end -function fs.type(path) -- returns the component type of the filesystem at a given path, if applicable +function fs.type(path) -- string -- string -- Returns the component type of the filesystem at a given path, if applicable local fsi,_ = fs.resolve(path) return fsmounts[fsi].type or "filesystem" end diff --git a/module/io.lua b/module/io.lua index 79b69ed..7ff9dea 100644 --- a/module/io.lua +++ b/module/io.lua @@ -1,12 +1,12 @@ io = {} -function io.open(path,mode) -- Open file *path* in *mode*. Returns a buffer object. +function io.open(path,mode) -- string string -- table -- Open file *path* in *mode*. Returns a buffer object. local f,e = fs.open(path, mode) if not f then return false, e end return buffer.new(mode,f) end -function io.input(fd) -- Sets the default input stream to *fd* if provided, either as a buffer as a path. Returns the default input stream. +function io.input(fd) -- table -- table -- Sets the default input stream to *fd* if provided, either as a buffer as a path. Returns the default input stream. if type(fd) == "string" then fd=io.open(fd,"rb") end @@ -15,7 +15,7 @@ function io.input(fd) -- Sets the default input stream to *fd* if provided, eith end return os.getenv("STDIN") end -function io.output(fd) -- Sets the default output stream to *fd* if provided, either as a buffer as a path. Returns the default output stream. +function io.output(fd) -- table -- table -- Sets the default output stream to *fd* if provided, either as a buffer as a path. Returns the default output stream. if type(fd) == "string" then fd=io.open(fd,"wb") end diff --git a/module/loadfile.lua b/module/loadfile.lua index 99a88f2..686f97a 100644 --- a/module/loadfile.lua +++ b/module/loadfile.lua @@ -1,19 +1,19 @@ -function loadfile(p) -- reads file *p* and returns a function if possible +function loadfile(p) -- string -- function -- reads file *p* and returns a function if possible local f = io.open(p,"rb") local c = f:read("*a") f:close() return load(c,p,"t") end -function runfile(p,...) -- runs file *p* with arbitrary arguments in the current thread +function runfile(p,...) -- string -- -- runs file *p* with arbitrary arguments in the current thread return loadfile(p)(...) end -function os.spawnfile(p,n,...) -- spawns a new process from file *p* with name *n*, with arguments following *n*. +function os.spawnfile(p,n,...) -- string string -- number -- spawns a new process from file *p* with name *n*, with arguments following *n*. local tA = {...} return os.spawn(function() local res={pcall(loadfile(p), table.unpack(tA))} computer.pushSignal("process_finished", os.pid(), table.unpack(res)) dprint(table.concat(res)) end,n or p) end _G.package = {} package.loaded = {computer=computer,component=component,fs=fs,buffer=buffer} -function require(f,force) -- searches for a library with name *f* and returns what the library returns, if possible. if *force* is set, loads the library even if it is cached +function require(f,force) -- string boolean -- table -- searches for a library with name *f* and returns what the library returns, if possible. if *force* is set, loads the library even if it is cached if not package.loaded[f] or force then local lib = os.getenv("LIB") or "/boot/lib" for d in lib:gmatch("[^\n]+") do @@ -29,6 +29,6 @@ function require(f,force) -- searches for a library with name *f* and returns wh end error("library not found: "..f) end -function reload(f) +function reload(f) -- string -- table -- Reloads library *f* from disk into memory. return require(f,true) end diff --git a/module/osutil.lua b/module/osutil.lua index 979a52d..d29be02 100644 --- a/module/osutil.lua +++ b/module/osutil.lua @@ -1,4 +1,4 @@ -function os.chdir(p) -- changes the current working directory of the calling process to the directory specified in *p*, returning true or false, error +function os.chdir(p) -- string -- boolean string -- changes the current working directory of the calling process to the directory specified in *p*, returning true or false, error if not (p:sub(1,1) == "/") then local np = {} for k,v in pairs(fs.segments(os.getenv("PWD").."/"..p)) do diff --git a/module/sched.lua b/module/sched.lua index 9cda5d9..960f826 100644 --- a/module/sched.lua +++ b/module/sched.lua @@ -1,6 +1,6 @@ do local tTasks,nPid,nTimeout,cPid = {},1,0.25,0 -- table of tasks, next process ID, event timeout, current PID -function os.spawn(f,n) -- creates a process from function *f* with name *n* +function os.spawn(f,n) -- function string -- number -- creates a process from function *f* with name *n* tTasks[nPid] = { c=coroutine.create(f), -- actual coroutine n=n, -- process name @@ -16,20 +16,20 @@ function os.spawn(f,n) -- creates a process from function *f* with name *n* nPid = nPid + 1 return nPid - 1 end -function os.kill(pid) -- removes process *pid* from the task list +function os.kill(pid) -- number -- -- removes process *pid* from the task list tTasks[pid] = nil end -function os.pid() -- returns the current process' PID +function os.pid() -- -- number -- returns the current process' PID return cPid end -function os.tasks() -- returns a table of process IDs +function os.tasks() -- -- table -- returns a table of process IDs local rt = {} for k,v in pairs(tTasks) do rt[#rt+1] = k end return rt end -function os.taskInfo(pid) -- returns info on process *pid* as a table with name and parent values +function os.taskInfo(pid) -- number -- table -- returns info on process *pid* as a table with name and parent values pid = pid or os.pid() if not tTasks[pid] then return false end return {name=tTasks[pid].n,parent=tTasks[pid].P} diff --git a/module/syslog.lua b/module/syslog.lua index ecfc323..f28e7ec 100644 --- a/module/syslog.lua +++ b/module/syslog.lua @@ -9,6 +9,7 @@ syslog.notice = 5 syslog.info = 6 syslog.debug = 7 +-- function syslog(msg, level, service) -- string number string -- -- Output *msg* to the system log, with severity *level*, from *service*. local rdprint=dprint or function() end setmetatable(syslog,{__call = function(_,msg, level, service) level, service = level or syslog.info, service or (os.taskInfo(os.pid()) or {}).name or "unknown"