From 2f42a4e85b7b905b4d4cc1842044b290eacbcee0 Mon Sep 17 00:00:00 2001 From: Jonathan Coates Date: Wed, 22 Apr 2020 14:39:39 +0100 Subject: [PATCH 1/5] Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p. --- doc/styles.css | 2 +- illuaminate.sexp | 62 +++-- .../assets/computercraft/lua/bios.lua | 5 +- .../computercraft/lua/rom/apis/disk.lua | 2 +- .../computercraft/lua/rom/apis/settings.lua | 4 +- .../rom/modules/main/cc/shell/completion.lua | 9 +- .../lua/rom/programs/advanced/multishell.lua | 76 ++++- .../computercraft/lua/rom/programs/shell.lua | 263 +++++++++++++++--- 8 files changed, 339 insertions(+), 84 deletions(-) diff --git a/doc/styles.css b/doc/styles.css index ef14a7d94..436a8c535 100644 --- a/doc/styles.css +++ b/doc/styles.css @@ -23,7 +23,7 @@ body { "Droid Sans", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; } -code, pre, .parameter, .type, .definition-name, .reference { +code, pre, .parameter, .type, .definition-name, .reference-code { font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; } diff --git a/illuaminate.sexp b/illuaminate.sexp index f727a3a8e..32acc06de 100644 --- a/illuaminate.sexp +++ b/illuaminate.sexp @@ -2,8 +2,8 @@ (sources /doc/stub/ - /src/main/resources/assets/computercraft/lua/bios.lua - /src/main/resources/assets/computercraft/lua/rom/ + /src/main/resources/*/computercraft/lua/bios.lua + /src/main/resources/*/computercraft/lua/rom/ /src/test/resources/test-rom) @@ -15,13 +15,13 @@ (library-path /doc/stub/ - /src/main/resources/assets/computercraft/lua/rom/apis - /src/main/resources/assets/computercraft/lua/rom/apis/command - /src/main/resources/assets/computercraft/lua/rom/apis/turtle + /src/main/resources/*/computercraft/lua/rom/apis + /src/main/resources/*/computercraft/lua/rom/apis/command + /src/main/resources/*/computercraft/lua/rom/apis/turtle - /src/main/resources/assets/computercraft/lua/rom/modules/main - /src/main/resources/assets/computercraft/lua/rom/modules/command - /src/main/resources/assets/computercraft/lua/rom/modules/turtle)) + /src/main/resources/*/computercraft/lua/rom/modules/main + /src/main/resources/*/computercraft/lua/rom/modules/command + /src/main/resources/*/computercraft/lua/rom/modules/turtle)) (at / (linters @@ -35,9 +35,7 @@ ;; be good to find a compromise in the future, but this works for now. -var:unused-arg - ;; Suppress a couple of documentation comments warnings for now. We'll - ;; hopefully be able to remove them in the future. - -doc:undocumented -doc:undocumented-arg -doc:unresolved-reference + ;; Some APIS (keys, colour and os mainly) are incomplete right now. -var:unresolved-member) (lint (bracket-spaces @@ -50,8 +48,8 @@ ;; We disable the unused global linter in bios.lua and the APIs. In the future ;; hopefully we'll get illuaminate to handle this. (at - (/src/main/resources/assets/computercraft/lua/bios.lua - /src/main/resources/assets/computercraft/lua/rom/apis/) + (/src/main/resources/*/computercraft/lua/bios.lua + /src/main/resources/*/computercraft/lua/rom/apis/) (linters -var:unused-global) (lint (allow-toplevel-global true))) @@ -60,19 +58,27 @@ (linters -var:unused-global) (lint (allow-toplevel-global true))) -;; Ensure any fully documented modules stay fully documented. +;; Suppress warnings for currently undocumented modules. (at - (/src/main/resources/assets/computercraft/lua/rom/apis/colors.lua - /src/main/resources/assets/computercraft/lua/rom/apis/colours.lua - /src/main/resources/assets/computercraft/lua/rom/apis/disk.lua - /src/main/resources/assets/computercraft/lua/rom/apis/gps.lua - /src/main/resources/assets/computercraft/lua/rom/apis/help.lua - /src/main/resources/assets/computercraft/lua/rom/apis/keys.lua - /src/main/resources/assets/computercraft/lua/rom/apis/paintutils.lua - /src/main/resources/assets/computercraft/lua/rom/apis/parallel.lua - /src/main/resources/assets/computercraft/lua/rom/apis/peripheral.lua - /src/main/resources/assets/computercraft/lua/rom/apis/rednet.lua - /src/main/resources/assets/computercraft/lua/rom/apis/settings.lua - /src/main/resources/assets/computercraft/lua/rom/apis/texutils.lua - /src/main/resources/assets/computercraft/lua/rom/apis/vector.lua) - (linters doc:undocumented doc:undocumented-arg)) + (/doc/stub/commands.lua + /doc/stub/fs.lua + /doc/stub/http.lua + /doc/stub/os.lua + /doc/stub/redstone.lua + /doc/stub/term.lua + /doc/stub/turtle.lua + /src/main/resources/*/computercraft/lua/rom/apis/command/commands.lua + /src/main/resources/*/computercraft/lua/rom/apis/io.lua + /src/main/resources/*/computercraft/lua/rom/apis/window.lua + /src/main/resources/*/computercraft/lua/rom/modules/main/cc/shell/completion.lua) + + (linters -doc:undocumented -doc:undocumented-arg)) + +;; These currently rely on unknown references. +(at + (/src/main/resources/*/computercraft/lua/rom/apis/textutils.lua + /src/main/resources/*/computercraft/lua/rom/modules/main/cc/completion.lua + /src/main/resources/*/computercraft/lua/rom/modules/main/cc/shell/completion.lua + /src/main/resources/*/computercraft/lua/rom/programs/advanced/multishell.lua + /src/main/resources/*/computercraft/lua/rom/programs/shell.lua) + (linters -doc:unresolved-reference)) diff --git a/src/main/resources/assets/computercraft/lua/bios.lua b/src/main/resources/assets/computercraft/lua/bios.lua index f1e80cef4..a2f737416 100644 --- a/src/main/resources/assets/computercraft/lua/bios.lua +++ b/src/main/resources/assets/computercraft/lua/bios.lua @@ -521,14 +521,11 @@ function os.run(_tEnv, _sPath, ...) expect(1, _tEnv, "table") expect(2, _sPath, "string") - local tArgs = table.pack(...) local tEnv = _tEnv setmetatable(tEnv, { __index = _G }) local fnFile, err = loadfile(_sPath, nil, tEnv) if fnFile then - local ok, err = pcall(function() - fnFile(table.unpack(tArgs, 1, tArgs.n)) - end) + local ok, err = pcall(fnFile, ...) if not ok then if err and err ~= "" then printError(err) diff --git a/src/main/resources/assets/computercraft/lua/rom/apis/disk.lua b/src/main/resources/assets/computercraft/lua/rom/apis/disk.lua index fcc907121..9e136b22c 100644 --- a/src/main/resources/assets/computercraft/lua/rom/apis/disk.lua +++ b/src/main/resources/assets/computercraft/lua/rom/apis/disk.lua @@ -106,7 +106,7 @@ end -- This generally returns the same as @{disk.getLabel} for records. -- -- @tparam string name The name of the disk drive. --- @treturn string|false|nil The track title, `false` if there is not a music +-- @treturn string|false|nil The track title, @{false} if there is not a music -- record in the drive or `nil` if no drive is present. function getAudioTitle(name) if isDrive(name) then diff --git a/src/main/resources/assets/computercraft/lua/rom/apis/settings.lua b/src/main/resources/assets/computercraft/lua/rom/apis/settings.lua index c1fcb45f6..f9925d36f 100644 --- a/src/main/resources/assets/computercraft/lua/rom/apis/settings.lua +++ b/src/main/resources/assets/computercraft/lua/rom/apis/settings.lua @@ -32,7 +32,7 @@ for _, v in ipairs(valid_types) do valid_types[v] = true end -- you to provide defaults and additional metadata. -- -- @tparam string name The name of this option --- @tparam[opt] { description? = string, default? = value, type? = string } options +-- @tparam[opt] { description? = string, default? = any, type? = string } options -- Options for this setting. This table accepts the following fields: -- -- - `description`: A description which may be printed when running the `set` program. @@ -127,7 +127,7 @@ end --- Get details about a specific setting. -- -- @tparam string name The name of the setting to get. --- @treturn { description? = string, default? = value, type? = string, value? = value } +-- @treturn { description? = string, default? = any, type? = string, value? = any } -- Information about this setting. This includes all information from @{settings.define}, -- as well as this setting's value. function getDetails(name) diff --git a/src/main/resources/assets/computercraft/lua/rom/modules/main/cc/shell/completion.lua b/src/main/resources/assets/computercraft/lua/rom/modules/main/cc/shell/completion.lua index d89c72a91..6be54fe2f 100644 --- a/src/main/resources/assets/computercraft/lua/rom/modules/main/cc/shell/completion.lua +++ b/src/main/resources/assets/computercraft/lua/rom/modules/main/cc/shell/completion.lua @@ -16,7 +16,7 @@ local completion = require "cc.completion" --- Complete the name of a file relative to the current working directory. -- --- @tparam shell shell The shell we're completing in +-- @tparam table shell The shell we're completing in -- @tparam { string... } choices The list of choices to complete from. -- @treturn { string... } A list of suffixes of matching files. local function file(shell, text) @@ -25,7 +25,7 @@ end --- Complete the name of a directory relative to the current working directory. -- --- @tparam shell shell The shell we're completing in +-- @tparam table shell The shell we're completing in -- @tparam { string... } choices The list of choices to complete from. -- @treturn { string... } A list of suffixes of matching directories. local function dir(shell, text) @@ -35,7 +35,7 @@ end --- Complete the name of a file or directory relative to the current working -- directory. -- --- @tparam shell shell The shell we're completing in +-- @tparam table shell The shell we're completing in -- @tparam { string... } choices The list of choices to complete from. -- @tparam { string... } previous The shell arguments before this one. -- @tparam[opt] boolean add_space Whether to add a space after the completed item. @@ -61,9 +61,10 @@ end --- Complete the name of a program. -- --- @tparam shell shell The shell we're completing in +-- @tparam table shell The shell we're completing in -- @tparam { string... } choices The list of choices to complete from. -- @treturn { string... } A list of suffixes of matching programs. +-- @see shell.completeProgram local function program(shell, text) return shell.completeProgram(text) end diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/advanced/multishell.lua b/src/main/resources/assets/computercraft/lua/rom/programs/advanced/multishell.lua index c675f2dc6..1ff73ab9f 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/advanced/multishell.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/advanced/multishell.lua @@ -1,3 +1,21 @@ +--- Multishell allows multiple programs to be run at the same time. +-- +-- When multiple programs are running, it displays a tab bar at the top of the +-- screen, which allows you to switch between programs. New programs can be +-- launched using the `fg` or `bg` programs, or using the @{shell.openTab} and +-- @{multishell.launch} functions. +-- +-- Each process is identified by its ID, which corresponds to its position in +-- the tab list. As tabs may be opened and closed, this ID is _not_ constant +-- over a program's run. As such, be careful not to use stale IDs. +-- +-- As with @{shell}, @{multishell} is not a "true" API. Instead, it is a +-- standard program, which launches a shell and injects its API into the shell's +-- environment. This API is not available in the global environment, and so is +-- not available to @{os.loadAPI|APIs}. +-- +-- @module[module] multishell + local expect = dofile("rom/modules/main/cc/expect.lua").expect -- Setup process switching @@ -190,12 +208,26 @@ local function setMenuVisible(bVis) end end -local multishell = {} +local multishell = {} --- @export +--- Get the currently visible process. This will be the one selected on +-- the tab bar. +-- +-- Note, this is different to @{getCurrent}, which returns the process which is +-- currently executing. +-- +-- @treturn number The currently visible process's index. +-- @see setFocus function multishell.getFocus() return nCurrentProcess end +--- Change the currently visible process. +-- +-- @tparam number n The process index to switch to. +-- @treturn boolean If the process was changed successfully. This will +-- return @{false} if there is no process with this id. +-- @see getFocus function multishell.setFocus(n) expect(1, n, "number") if n >= 1 and n <= #tProcesses then @@ -206,6 +238,13 @@ function multishell.setFocus(n) return false end +--- Get the title of the given tab. +-- +-- This starts as the name of the program, but may be changed using +-- @{multishell.setTitle}. +-- @tparam number n The process index. +-- @treturn string|nil The current process title, or @{nil} if the +-- process doesn't exist. function multishell.getTitle(n) expect(1, n, "number") if n >= 1 and n <= #tProcesses then @@ -214,19 +253,45 @@ function multishell.getTitle(n) return nil end -function multishell.setTitle(n, sTitle) +--- Set the title of the given process. +-- +-- @tparam number n The process index. +-- @tparam string title The new process title. +-- @see getTitle +-- @usage Change the title of the current process +-- +-- multishell.setTitle(multishell.getCurrent(), "Hello") +function multishell.setTitle(n, title) expect(1, n, "number") - expect(2, sTitle, "string") + expect(2, title, "string") if n >= 1 and n <= #tProcesses then - setProcessTitle(n, sTitle) + setProcessTitle(n, title) redrawMenu() end end +--- Get the index of the currently running process. +-- +-- @treturn number The currently running process. function multishell.getCurrent() return nRunningProcess end +--- Start a new process, with the given environment, program and arguments. +-- +-- The returned process index is not constant over the program's run. It can be +-- safely used immediately after launching (for instance, to update the title or +-- switch to that tab). However, after your program has yielded, it may no +-- longer be correct. +-- +-- @tparam table tProgramEnv The environment to load the path under. +-- @tparam string sProgramPath The path to the program to run. +-- @param ... Additional arguments to pass to the program. +-- @treturn number The index of the created process. +-- @see os.run +-- @usage Run the "hello" program, and set its title to "Hello!" +-- local id = multishell.launch({}, "/rom/programs/fun/hello.lua") +-- multishell.setTitle(id, "Hello!") function multishell.launch(tProgramEnv, sProgramPath, ...) expect(1, tProgramEnv, "table") expect(2, sProgramPath, "string") @@ -238,6 +303,9 @@ function multishell.launch(tProgramEnv, sProgramPath, ...) return nResult end +--- Get the number of processes within this multishell. +-- +-- @treturn number The number of processes. function multishell.getCount() return #tProcesses end diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/shell.lua b/src/main/resources/assets/computercraft/lua/rom/programs/shell.lua index 0d4b9f337..c36cc9abf 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/shell.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/shell.lua @@ -1,3 +1,15 @@ +--- The shell API provides access to CraftOS's command line interface. +-- +-- It allows you to @{run|start programs}, @{setCompletionFunction|add +-- completion for a program}, and much more. +-- +-- @{shell} is not a "true" API. Instead, it is a standard program, which its +-- API into the programs that it launches. This allows for multiple shells to +-- run at the same time, but means that the API is not available in the global +-- environment, and so is unavailable to other @{os.loadAPI|APIs}. +-- +-- @module[module] shell + local expect = dofile("rom/modules/main/cc/expect.lua").expect local multishell = multishell @@ -15,7 +27,7 @@ local tAliases = parentShell and parentShell.aliases() or {} local tCompletionInfo = parentShell and parentShell.getCompletionInfo() or {} local tProgramStack = {} -local shell = {} +local shell = {} --- @export local function createShellEnv(sDir) local tEnv = {} tEnv.shell = shell @@ -172,6 +184,18 @@ local function tokenise(...) end -- Install shell API + +--- Run a program with the supplied arguments. +-- +-- All arguments are concatenated together and then parsed as a command line. As +-- a result, `shell.run("program a b")` is the same as `shell.run("program", +-- "a", "b")`. +-- +-- @tparam string ... The program to run and its arguments. +-- @treturn boolean Whether the program exited successfully. +-- @usage Run `paint my-image` from within your program: +-- +-- shell.run("paint", "my-image") function shell.run(...) local tWords = tokenise(...) local sCommand = tWords[1] @@ -181,38 +205,83 @@ function shell.run(...) return false end +--- Exit the current shell. +-- +-- This does _not_ terminate your program, it simply makes the shell terminate +-- after your program has finished. If this is the toplevel shell, then the +-- computer will be shutdown. function shell.exit() bExit = true end +--- Return the current working directory. This is what is displayed before the +-- `> ` of the shell prompt, and is used by @{shell.resolve} to handle relative +-- paths. +-- +-- @treturn string The current working directory. +-- @see setDir To change the working directory. function shell.dir() return sDir end -function shell.setDir(_sDir) - expect(1, _sDir, "string") - if not fs.isDir(_sDir) then +--- Set the current working directory. +-- +-- @tparam string dir The new working directory. +-- @throws If the path does not exist or is not a directory. +-- @usage Set the working directory to "rom" +-- +-- shell.setDir("rom") +function shell.setDir(dir) + expect(1, dir, "string") + if not fs.isDir(dir) then error("Not a directory", 2) end - sDir = fs.combine(_sDir, "") + sDir = fs.combine(dir, "") end +--- Set the path where programs are located. +-- +-- The path is composed of a list of directory names in a string, each separated +-- by a colon (`:`). On normal turtles will look in the current directory (`.`), +-- `/rom/programs` and `/rom/programs/turtle` folder, making the path +-- `.:/rom/programs:/rom/programs/turtle`. +-- +-- @treturn string The current shell's path. +-- @see setPath To change the current path. function shell.path() return sPath end -function shell.setPath(_sPath) - expect(1, _sPath, "string") - sPath = _sPath +--- Set the @{path|current program path}. +-- +-- Be careful to prefix directories with a `/`. Otherwise they will be searched +-- for from the @{shell.dir|current directory}, rather than the computer's root. +-- +-- @tparam string path The new program path. +function shell.setPath(path) + expect(1, path, "string") + sPath = path end -function shell.resolve(_sPath) - expect(1, _sPath, "string") - local sStartChar = string.sub(_sPath, 1, 1) +--- Resolve a relative path to an absolute path. +-- +-- The @{fs} and @{io} APIs work using absolute paths, and so we must convert +-- any paths relative to the @{dir|current directory} to absolute ones. This +-- does nothing when the path starts with `/`. +-- +-- @tparam string path The path to resolve. +-- @usage Resolve `startup.lua` when in the `rom` folder. +-- +-- shell.setDir("rom") +-- print(shell.resolve("startup.lua")) +-- -- => rom/startup.lua +function shell.resolve(path) + expect(1, path, "string") + local sStartChar = string.sub(path, 1, 1) if sStartChar == "/" or sStartChar == "\\" then - return fs.combine("", _sPath) + return fs.combine("", path) else - return fs.combine(sDir, _sPath) + return fs.combine(sDir, path) end end @@ -226,16 +295,25 @@ local function pathWithExtension(_sPath, _sExt) return _sPath .. "." .. _sExt end -function shell.resolveProgram(_sCommand) - expect(1, _sCommand, "string") +--- Resolve a program, using the @{path|program path} and list of @{aliases|aliases}. +-- +-- @tparam string command The name of the program +-- @treturn string|nil The absolute path to the program, or @{nil} if it could +-- not be found. +-- @usage Locate the `hello` program. +-- +-- shell.resolveProgram("hello") +-- -- => rom/programs/fun/hello.lua +function shell.resolveProgram(command) + expect(1, command, "string") -- Substitute aliases firsts - if tAliases[_sCommand] ~= nil then - _sCommand = tAliases[_sCommand] + if tAliases[command] ~= nil then + command = tAliases[command] end -- If the path is a global path, use it directly - if _sCommand:find("/") or _sCommand:find("\\") then - local sPath = shell.resolve(_sCommand) + if command:find("/") or command:find("\\") then + local sPath = shell.resolve(command) if fs.exists(sPath) and not fs.isDir(sPath) then return sPath else @@ -249,7 +327,7 @@ function shell.resolveProgram(_sCommand) -- Otherwise, look on the path variable for sPath in string.gmatch(sPath, "[^:]+") do - sPath = fs.combine(shell.resolve(sPath), _sCommand) + sPath = fs.combine(shell.resolve(sPath), command) if fs.exists(sPath) and not fs.isDir(sPath) then return sPath else @@ -264,7 +342,15 @@ function shell.resolveProgram(_sCommand) return nil end -function shell.programs(_bIncludeHidden) +--- Return a list of all programs on the @{shell.path|path}. +-- +-- @tparam[opt] boolean include_hidden Include hidden files. Namely, any which +-- start with `.`. +-- @treturn { string } A list of available programs. +-- @usage textutils.tabulate(shell.programs()) +function shell.programs(include_hidden) + expect(1, include_hidden, "boolean", "nil") + local tItems = {} -- Add programs from the path @@ -275,7 +361,7 @@ function shell.programs(_bIncludeHidden) for n = 1, #tList do local sFile = tList[n] if not fs.isDir(fs.combine(sPath, sFile)) and - (_bIncludeHidden or string.sub(sFile, 1, 1) ~= ".") then + (include_hidden or string.sub(sFile, 1, 1) ~= ".") then if #sFile > 4 and sFile:sub(-4) == ".lua" then sFile = sFile:sub(1, -5) end @@ -351,6 +437,21 @@ local function completeProgramArgument(sProgram, nArgument, sPart, tPreviousPart return nil end +--- Complete a shell command line. +-- +-- This accepts an incomplete command, and completes the program name or +-- arguments. For instance, `l` will be completed to `ls`, and `ls ro` will be +-- completed to `ls rom/`. +-- +-- Completion handlers for your program may be registered with +-- @{shell.setCompletionFunction}. +-- +-- @tparam string sLine The input to complete. +-- @treturn { string }|nil The list of possible completions. +-- @see read For more information about completion. +-- @see shell.completeProgram +-- @see shell.setCompletionFunction +-- @see shell.getCompletionInfo function shell.complete(sLine) expect(1, sLine, "string") if #sLine > 0 then @@ -388,23 +489,66 @@ function shell.complete(sLine) return nil end -function shell.completeProgram(sProgram) - expect(1, sProgram, "string") - return completeProgram(sProgram) +--- Complete the name of a program. +-- +-- @tparam string program The name of a program to complete. +-- @treturn { string } A list of possible completions. +-- @see cc.shell.completion.program +function shell.completeProgram(program) + expect(1, program, "string") + return completeProgram(program) end -function shell.setCompletionFunction(sProgram, fnComplete) - expect(1, sProgram, "string") - expect(2, fnComplete, "function") - tCompletionInfo[sProgram] = { - fnComplete = fnComplete, +--- Set the completion function for a program. When the program is entered on +-- the command line, this program will be called to provide auto-complete +-- information. +-- +-- The completion function accepts four arguments: +-- +-- 1. The current shell. As completion functions are inherited, this is not +-- guaranteed to be the shell you registered this function in. +-- 2. The index of the argument currently being completed. +-- 3. The current argument. This may be the empty string. +-- 4. A list of the previous arguments. +-- +-- For instance, when completing `pastebin put rom/st` our pastebin completion +-- function will receive the shell API, an index of 2, `rom/st` as the current +-- argument, and a "previous" table of `{ "put" }`. This function may then wish +-- to return a table containing `artup.lua`, indicating the entire command +-- should be completed to `pastebin put rom/startup.lua`. +-- +-- You completion entries may also be followed by a space, if you wish to +-- indicate another argument is expected. +-- +-- @tparam string program The path to the program. This should be an absolute path +-- _without_ the leading `/`. +-- @tparam function(shell: table, index: number, argument: string, previous: { string }):({ string }|nil) complete +-- The completion function. +-- @see cc.shell.completion Various utilities to help with writing completion functions. +-- @see shell.complete +-- @see read For more information about completion. +function shell.setCompletionFunction(program, complete) + expect(1, program, "string") + expect(2, complete, "function") + tCompletionInfo[program] = { + fnComplete = complete, } end +--- Get a table containing all completion functions. +-- +-- This should only be needed when building custom shells. Use +-- @{setCompletionFunction} to add a completion function. +-- +-- @treturn { [string] = { fnComplete = function } } A table mapping the +-- absolute path of programs, to their completion functions. function shell.getCompletionInfo() return tCompletionInfo end +--- Returns the path to the currently running program. +-- +-- @treturn string The absolute path to the running program. function shell.getRunningProgram() if #tProgramStack > 0 then return tProgramStack[#tProgramStack] @@ -412,17 +556,38 @@ function shell.getRunningProgram() return nil end -function shell.setAlias(_sCommand, _sProgram) - expect(1, _sCommand, "string") - expect(2, _sProgram, "string") - tAliases[_sCommand] = _sProgram +--- Add an alias for a program. +-- +-- @tparam string command The name of the alias to add. +-- @tparam string program The name or path to the program. +-- @usage Alias `vim` to the `edit` program +-- +-- shell.setAlias("vim", "edit") +function shell.setAlias(command, program) + expect(1, command, "string") + expect(2, program, "string") + tAliases[command] = program end -function shell.clearAlias(_sCommand) - expect(1, _sCommand, "string") - tAliases[_sCommand] = nil +--- Remove an alias. +-- +-- @tparam string command The alias name to remove. +function shell.clearAlias(command) + expect(1, command, "string") + tAliases[command] = nil end +--- Get the current aliases for this shell. +-- +-- Aliases are used to allow multiple commands to refer to a single program. For +-- instance, the `list` program is aliased `dir` or `ls`. Running `ls`, `dir` or +-- `list` in the shell will all run the `list` program. +-- +-- @treturn { [string] = string } A table, where the keys are the names of +-- aliases, and the values are the path to the program. +-- @see shell.setAlias +-- @see shell.resolveProgram This uses aliases when resolving a program name to +-- an absolute path. function shell.aliases() -- Copy aliases local tCopy = {} @@ -433,6 +598,20 @@ function shell.aliases() end if multishell then + --- Open a new @{multishell} tab running a command. + -- + -- This behaves similarly to @{shell.run}, but instead returns the process + -- index. + -- + -- This function is only available if the @{multishell} API is. + -- + -- @tparam string ... The command line to run. + -- @see shell.run + -- @see multishell.launch + -- @usage Launch the Lua interpreter and switch to it. + -- + -- local id = shell.openTab("lua") + -- shell.switchTab(id) function shell.openTab(...) local tWords = tokenise(...) local sCommand = tWords[1] @@ -448,9 +627,13 @@ if multishell then end end - function shell.switchTab(nID) - expect(1, nID, "number") - multishell.setFocus(nID) + --- Switch to the @{multishell} tab with the given index. + -- + -- @tparam number id The tab to switch to. + -- @see multishell.setFocus + function shell.switchTab(id) + expect(1, id, "number") + multishell.setFocus(id) end end From 7f57a977a1c6134d5570ce36492fc7c738abc9c5 Mon Sep 17 00:00:00 2001 From: Jonathan Coates Date: Wed, 22 Apr 2020 14:48:42 +0100 Subject: [PATCH 2/5] Make the CF link https on tweaked.cc It doesn't play nice on GH, but we need it on our actual website. --- doc/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.md b/doc/index.md index c22acd230..9aca61855 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,4 +1,4 @@ -# ![CC: Tweaked](logo.png) [![Download CC: Tweaked on CurseForge](http://cf.way2muchnoise.eu/title/cc-tweaked.svg)](https://minecraft.curseforge.com/projects/cc-tweaked "Download CC: Tweaked on CurseForge") +# ![CC: Tweaked](logo.png) [![Download CC: Tweaked on CurseForge](https://cf.way2muchnoise.eu/title/cc-tweaked.svg)](https://minecraft.curseforge.com/projects/cc-tweaked "Download CC: Tweaked on CurseForge") CC: Tweaked is a fork of [ComputerCraft], adding programmable computers, turtles and more to Minecraft. From da419b24e701229eee3afa06315969c5d2a4f972 Mon Sep 17 00:00:00 2001 From: SquidDev Date: Wed, 22 Apr 2020 17:44:13 +0100 Subject: [PATCH 3/5] Enable motd on non-pocket and command computers - I'm excluding pocket computers, as they have such a tiny screen I'm not sure the screen estate is worth it. Pocket computers /generally/ aren't people's starter machine, so I think this is fine. - Prune the motd list, and try to make them a little shorter. I think this list is more of the interesting ones. We can modify this list in the future, as we get more feedback.[^1] - Also fix paint/edit not adding an extension when they should. This was caused by the settings rewrite, as the explicitly provided default shadowed the one provided by bios.lua. [^1]: ~5 months ago I asked for some feedback about enabling motds by default. I only got something constructive back today >_>. --- .../assets/computercraft/lua/bios.lua | 2 +- .../assets/computercraft/lua/rom/motd.txt | 36 +++++-------------- .../computercraft/lua/rom/programs/edit.lua | 2 +- .../lua/rom/programs/fun/advanced/paint.lua | 2 +- 4 files changed, 11 insertions(+), 31 deletions(-) diff --git a/src/main/resources/assets/computercraft/lua/bios.lua b/src/main/resources/assets/computercraft/lua/bios.lua index a2f737416..687c9c798 100644 --- a/src/main/resources/assets/computercraft/lua/bios.lua +++ b/src/main/resources/assets/computercraft/lua/bios.lua @@ -923,7 +923,7 @@ settings.define("list.show_hidden", { }) settings.define("motd.enable", { - default = false, + default = pocket == nil, description = "Display a random message when the computer starts up.", type = "boolean", }) diff --git a/src/main/resources/assets/computercraft/lua/rom/motd.txt b/src/main/resources/assets/computercraft/lua/rom/motd.txt index 87f3f0503..8c8f16945 100644 --- a/src/main/resources/assets/computercraft/lua/rom/motd.txt +++ b/src/main/resources/assets/computercraft/lua/rom/motd.txt @@ -1,43 +1,23 @@ -View the source code at https://github.com/SquidDev-CC/CC-Tweaked +Please report bugs at https://github.com/SquidDev-CC/CC-Tweaked. Thanks! View the documentation at https://wiki.computercraft.cc -Visit the forum at https://forums.computercraft.cc +Show off your programs or ask for help at our forum: https://forums.computercraft.cc You can disable these messages by running "set motd.enable false". -You can create directories with "mkdir". -Want to see hidden files? Run "set list.show_hidden true". -Run "list" or "ls" to see all files in a directory. -You can delete files and directories with "delete" or "rm". Use "pastebin put" to upload a program to pastebin. -Use "pastebin get" to download a program from pastebin. -Use "pastebin run" to run a program from pastebin. Use the "edit" program to create and edit your programs. -You can copy files with "copy" or "cp". -You can use "wget run " to run a program from the internet. You can use "wget" to download a file from the internet. On an advanced computer you can use "fg" or "bg" to run multiple programs at the same time. -Use "type" to see if a path is a file or a directory. -Get a list of all programs with "programs". Use an advanced computer to use colours and the mouse. With a speaker you can play sounds. -Use "motd" to print the Message of the Day. -You can disable the startup from a computer with "set shell.allow_startup false". -You can disable the startup from a disk with "set shell.allow_disk_startup false". Programs that are placed in the "startup" folder in the root of a computer are started on boot. Use a modem to connect with other computers. With the "gps" program you can get the position of a computer. Use "monitor" to run a program on a attached monitor. -View all attached peripherals with "peripherals". -Use "time" to see the in-game time. -You can set the label of a computer with "label set". -A computer needs a label to keep its files if it is destroyed. -You can disable auto completion in the shell with "set shell.autocomplete false". -You can disable auto completion in edit with "set edit.autocomplete false". +Don't forget to label your computer with "label set". Feeling creative? Use a printer to print a book! -Files beginning with a "." character are hidden from "list" by default. +Files beginning with a "." are hidden from "list" by default. Running "set" lists the current values of all settings. -Some programs are only available on advanced computers, turtles, pocket computers, or command computers. -The "equip" and "unequip" programs let you add or remove supported upgrades from a turtle or pocket computer without crafting. -You can change the color of a disk by crafting it with dye. -Right-clicking a turtle with a dye changes its color. +Some programs are only available on advanced computers, turtles, pocket computers or command computers. +The "equip" programs let you add upgrades to a turtle without crafting. +You can change the color of a disk by crafting or right clicking it with dye. You can print on a printed page again to get multiple colors. -Holding the Control and T keys terminates the running program. -Holding Control and S or R shuts down or reboots the computer you are using. +Holding the Ctrl and T keys terminates the running program. diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua b/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua index a6ea4d8d0..9e57effd1 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua @@ -15,7 +15,7 @@ end -- Create .lua files by default if not fs.exists(sPath) and not string.find(sPath, "%.") then - local sExtension = settings.get("edit.default_extension", "") + local sExtension = settings.get("edit.default_extension") if sExtension ~= "" and type(sExtension) == "string" then sPath = sPath .. "." .. sExtension end diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua b/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua index fbe228091..08ac53116 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua @@ -46,7 +46,7 @@ end -- Create .nfp files by default if not fs.exists(sPath) and not string.find(sPath, "%.") then - local sExtension = settings.get("paint.default_extension", "") + local sExtension = settings.get("paint.default_extension") if sExtension ~= "" and type(sExtension) == "string" then sPath = sPath .. "." .. sExtension end From 9748679484d45f72a739c045b2afaac10fb6b160 Mon Sep 17 00:00:00 2001 From: JakobDev Date: Thu, 23 Apr 2020 10:33:35 +0200 Subject: [PATCH 4/5] Add mouse support for the menu in edit and paint (#419) --- .../computercraft/lua/rom/programs/edit.lua | 28 +++++- .../lua/rom/programs/fun/advanced/paint.lua | 89 ++++++++++++------- 2 files changed, 83 insertions(+), 34 deletions(-) diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua b/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua index 9e57effd1..007f37a24 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/edit.lua @@ -61,7 +61,12 @@ if peripheral.find("printer") then end table.insert(tMenuItems, "Exit") -local sStatus = "Press Ctrl to access menu" +local sStatus +if term.isColour() then + sStatus = "Press Ctrl or click here to access menu" +else + sStatus = "Press Ctrl to access menu" +end if #sStatus > w - 5 then sStatus = "Press Ctrl for menu" end @@ -725,16 +730,35 @@ while bRunning do end elseif sEvent == "mouse_click" then + local cx, cy = param2, param3 if not bMenu then if param == 1 then -- Left click - local cx, cy = param2, param3 if cy < h then local newY = math.min(math.max(scrollY + cy, 1), #tLines) local newX = math.min(math.max(scrollX + cx, 1), #tLines[newY] + 1) setCursor(newX, newY) + else + bMenu = true + redrawMenu() end end + else + if cy == h then + local nMenuPosEnd = 1 + local nMenuPosStart = 1 + for n, sMenuItem in ipairs(tMenuItems) do + nMenuPosEnd = nMenuPosEnd + #sMenuItem + 1 + if cx > nMenuPosStart and cx < nMenuPosEnd then + doMenuItem(n) + end + nMenuPosEnd = nMenuPosEnd + 1 + nMenuPosStart = nMenuPosEnd + end + else + bMenu = false + redrawMenu() + end end elseif sEvent == "mouse_scroll" then diff --git a/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua b/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua index 08ac53116..b7c44526a 100644 --- a/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua +++ b/src/main/resources/assets/computercraft/lua/rom/programs/fun/advanced/paint.lua @@ -19,7 +19,7 @@ local canvas = {} local mChoices = { "Save", "Exit" } -- The message displayed in the footer bar -local fMessage = "Press Ctrl to access menu" +local fMessage = "Press Ctrl or click here to access menu" ------------------------- -- Initialisation -- @@ -252,6 +252,29 @@ local function drawCanvas() end end +local menu_choices = { + Save = function() + if bReadOnly then + fMessage = "Access denied" + return false + end + local success, err = save(sPath) + if success then + fMessage = "Saved to " .. sPath + else + if err then + fMessage = "Error saving to " .. err + else + fMessage = "Error saving to " .. sPath + end + end + return false + end, + Exit = function() + return true + end, +} + --[[ Draws menu options and handles input from within the menu. returns: true if the program is to be exited; false otherwise @@ -261,6 +284,7 @@ local function accessMenu() local selection = 1 term.setBackgroundColour(colours.black) + while true do -- Draw the menu term.setCursorPos(1, h) @@ -269,27 +293,28 @@ local function accessMenu() for k, v in pairs(mChoices) do if selection == k then term.setTextColour(colours.yellow) - local ox = term.getCursorPos() - term.write("[" .. string.rep(" ", #v) .. "]") - term.setCursorPos(ox + 1, h) + term.write("[") term.setTextColour(colours.white) term.write(v) - term.setCursorPos(term.getCursorPos() + 1, h) + term.setTextColour(colours.yellow) + term.write("]") + term.setTextColour(colours.white) else term.write(" " .. v .. " ") end end -- Handle input in the menu - local id, key = os.pullEvent("key") + local id, param1, param2, param3 = os.pullEvent() if id == "key" then - -- S and E are shortcuts - if key == keys.s then - selection = 1 - key = keys.enter - elseif key == keys.e then - selection = 2 - key = keys.enter + local key = param1 + + -- Handle menu shortcuts. + for _, menu_item in ipairs(mChoices) do + local k = keys[menu_item:sub(1, 1):lower()] + if k and k == key then + return menu_choices[menu_item]() + end end if key == keys.right then @@ -308,29 +333,25 @@ local function accessMenu() elseif key == keys.enter then -- Select an option - if mChoices[selection] == "Save" then - if bReadOnly then - fMessage = "Access denied" - return false - end - local success, err = save(sPath) - if success then - fMessage = "Saved to " .. sPath - else - if err then - fMessage = "Error saving to " .. err - else - fMessage = "Error saving to " .. sPath - end - end - return false - elseif mChoices[selection] == "Exit" then - return true - end + return menu_choices[mChoices[selection]]() elseif key == keys.leftCtrl or keys == keys.rightCtrl then -- Cancel the menu return false end + elseif id == "mouse_click" then + local cx, cy = param2, param3 + if cy ~= h then return false end -- Exit the menu + + local nMenuPosEnd = 1 + local nMenuPosStart = 1 + for _, sMenuItem in ipairs(mChoices) do + nMenuPosEnd = nMenuPosEnd + #sMenuItem + 1 + if cx > nMenuPosStart and cx < nMenuPosEnd then + return menu_choices[sMenuItem]() + end + nMenuPosEnd = nMenuPosEnd + 1 + nMenuPosStart = nMenuPosEnd + end end end end @@ -378,6 +399,10 @@ local function handleEvents() canvas[p3][p2] = paintColour drawCanvasPixel(p2, p3) + elseif p3 == h and id == "mouse_click" then + -- Open menu + programActive = not accessMenu() + drawInterface() end elseif id == "key" then if p1 == keys.leftCtrl or p1 == keys.rightCtrl then From ae7ef66dfa19a752f3a3265b14a9996f776f9ddb Mon Sep 17 00:00:00 2001 From: SquidDev Date: Thu, 23 Apr 2020 09:56:56 +0100 Subject: [PATCH 5/5] Bump version Oh no. I don't want to have to beta test this :D:. --- gradle.properties | 2 +- .../computercraft/lua/rom/help/changelog.txt | 30 +++++++++++++++++++ .../computercraft/lua/rom/help/whatsnew.txt | 30 +++++++++++++++++-- 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/gradle.properties b/gradle.properties index 0f6aa539a..d61ef4e0f 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,5 +1,5 @@ # Mod properties -mod_version=1.86.2 +mod_version=1.87.0 # Minecraft properties mc_version=1.12.2 diff --git a/src/main/resources/assets/computercraft/lua/rom/help/changelog.txt b/src/main/resources/assets/computercraft/lua/rom/help/changelog.txt index ae073d005..36a482fb4 100644 --- a/src/main/resources/assets/computercraft/lua/rom/help/changelog.txt +++ b/src/main/resources/assets/computercraft/lua/rom/help/changelog.txt @@ -1,3 +1,33 @@ +# New features in CC: Tweaked 1.87.0 + +* Add documentation to many Lua functions. This is published online at https://tweaked.cc/. +* Replace to pretty-printer in the Lua REPL. It now supports displaying functions and recursive tables. This printer is may be used within your own code through the `cc.pretty` module. +* Add `fs.getCapacity`. A complement to `fs.getFreeSpace`, this returns the capacity of the supplied drive. +* Add `fs.getAttributes`. This provides file size and type, as well as creation and modification time. +* Update Cobalt version. This backports several features from Lua 5.2 and 5.3: + - The `__len` metamethod may now be used by tables. + - Add `\z`, hexadecimal (`\x00`) and unicode (`\u0000`) string escape codes. + - Add `utf8` lib. + - Mirror Lua's behaviour of tail calls more closely. Native functions are no longer tail called, and tail calls are displayed in the stack trace. + - `table.unpack` now uses `__len` and `__index` metamethods. + - Parser errors now include the token where the error occured. +* Add `textutils.unserializeJSON`. This can be used to decode standard JSON and stringified-NBT. +* Switch the monitor renderer to use VBOs, providing a _significant_ performance boost in some cases. You can switch back to the display list renderer via the config. +* The `settings` API now allows "defining" settings. This allows settings to specify a default value and description. +* Enable the motd on non-pocket computers. +* Allow using the menu with the mouse in edit and paint (JakobDev). +* Add Danish and Korean translations (ChristianLW, mindy15963) +* Fire `mouse_up` events in the monitor program. +* Allow specifying a timeout to `websocket.receive`. +* Increase the maximimum limit for websocket messages. +* Optimise capacity checking of computer/disk folders. + +And several bug fixes: +* Fix turtle texture being incorrectly oriented (magiczocker10). +* Prevent copying folders into themselves. +* Fix race condition within ID assignment. +* Normalise file paths within shell.setDir (JakobDev) + # New features in CC: Tweaked 1.86.2 * Fix peripheral.getMethods returning an empty table diff --git a/src/main/resources/assets/computercraft/lua/rom/help/whatsnew.txt b/src/main/resources/assets/computercraft/lua/rom/help/whatsnew.txt index 0ded4f8d3..29e395d9f 100644 --- a/src/main/resources/assets/computercraft/lua/rom/help/whatsnew.txt +++ b/src/main/resources/assets/computercraft/lua/rom/help/whatsnew.txt @@ -1,5 +1,31 @@ -New features in CC: Tweaked 1.86.2 +New features in CC: Tweaked 1.87.0 -* Fix peripheral.getMethods returning an empty table +* Add documentation to many Lua functions. This is published online at https://tweaked.cc/. +* Replace to pretty-printer in the Lua REPL. It now supports displaying functions and recursive tables. This printer is may be used within your own code through the `cc.pretty` module. +* Add `fs.getCapacity`. A complement to `fs.getFreeSpace`, this returns the capacity of the supplied drive. +* Add `fs.getAttributes`. This provides file size and type, as well as creation and modification time. +* Update Cobalt version. This backports several features from Lua 5.2 and 5.3: + - The `__len` metamethod may now be used by tables. + - Add `\z`, hexadecimal (`\x00`) and unicode (`\u0000`) string escape codes. + - Add `utf8` lib. + - Mirror Lua's behaviour of tail calls more closely. Native functions are no longer tail called, and tail calls are displayed in the stack trace. + - `table.unpack` now uses `__len` and `__index` metamethods. + - Parser errors now include the token where the error occured. +* Add `textutils.unserializeJSON`. This can be used to decode standard JSON and stringified-NBT. +* Switch the monitor renderer to use VBOs, providing a _significant_ performance boost in some cases. You can switch back to the display list renderer via the config. +* The `settings` API now allows "defining" settings. This allows settings to specify a default value and description. +* Enable the motd on non-pocket computers. +* Allow using the menu with the mouse in edit and paint (JakobDev). +* Add Danish and Korean translations (ChristianLW, mindy15963) +* Fire `mouse_up` events in the monitor program. +* Allow specifying a timeout to `websocket.receive`. +* Increase the maximimum limit for websocket messages. +* Optimise capacity checking of computer/disk folders. + +And several bug fixes: +* Fix turtle texture being incorrectly oriented (magiczocker10). +* Prevent copying folders into themselves. +* Fix race condition within ID assignment. +* Normalise file paths within shell.setDir (JakobDev) Type "help changelog" to see the full version history.