From 93068402a2ffec00eedb8fe2d859ebdc005a1989 Mon Sep 17 00:00:00 2001 From: Drew Lemmy Date: Sun, 11 Oct 2020 22:38:18 +0100 Subject: [PATCH] Document remaining OS functions (#554) --- doc/stub/global.lua | 55 +++++++++ doc/stub/os.lua | 115 ++++++++++++++++++ doc/styles.css | 16 ++- illuaminate.sexp | 7 +- .../dan200/computercraft/core/apis/OSAPI.java | 19 ++- 5 files changed, 205 insertions(+), 7 deletions(-) create mode 100644 doc/stub/global.lua diff --git a/doc/stub/global.lua b/doc/stub/global.lua new file mode 100644 index 000000000..c0609a1c3 --- /dev/null +++ b/doc/stub/global.lua @@ -0,0 +1,55 @@ +--[[- +Global functions defined by `bios.lua`. This does not include standard Lua +functions. + +@module _G +]] + +--[[- Pauses execution for the specified number of seconds. + +As it waits for a fixed amount of world ticks, `time` will automatically be +rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines +or the @{parallel|parallel API}, it will only pause execution of the current +thread, not the whole program. + +**Note** Because sleep internally uses timers, it is a function that yields. +This means that you can use it to prevent "Too long without yielding" errors, +however, as the minimum sleep time is 0.05 seconds, it will slow your program +down. + +**Warning** Internally, this function queues and waits for a timer event (using +@{os.startTimer}), however it does not listen for any other events. This means +that any event that occurs while sleeping will be entirely discarded. If you +need to receive events while sleeping, consider using @{os.startTimer|timers}, +or the @{parallel|parallel API}. + +@tparam number time The number of seconds to sleep for, rounded up to the +nearest multiple of 0.05. + +@see os.startTimer +]] +function sleep(time) end + +function write(text) end +function print(...) end +function printError(...) end + +function read(replaceChar, history, completeFn, default) end + +--- The ComputerCraft and Minecraft version of the current computer environment. +-- +-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`. +_HOST = _HOST + +--[[- The default computer settings as defined in the ComputerCraft +configuration. + +This is a comma-separated list of settings pairs defined by the mod +configuration or server owner. By default, it is empty. + +An example value to disable autocompletion: + + shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false + +]] +_CC_DEFAULT_SETTINGS = _CC_DEFAULT_SETTINGS diff --git a/doc/stub/os.lua b/doc/stub/os.lua index 2c9f730f4..7da3ea0c3 100644 --- a/doc/stub/os.lua +++ b/doc/stub/os.lua @@ -1,6 +1,121 @@ -- Defined in bios.lua + +--[[- Loads the given API into the global environment. + +**Warning** This function is deprecated. Use of this function will pollute the +global table, use @{require} instead. + +This function loads and executes the file at the given path, and all global +variables and functions exported by it will by available through the use of +`myAPI.`, where `myAPI` is the base name of the API file. + +@tparam string path The path of the API to load. +@treturn boolean Whether or not the API was successfully loaded. + +@deprecated Use @{require}. +]] function loadAPI(path) end + +--- Unloads an API which was loaded by @{os.loadAPI}. +-- +-- This effectively removes the specified table from `_G`. +-- +-- @tparam string name The name of the API to unload. +-- @deprecated Use @{require}. +function unloadAPI(name) end + +--[[- Pause execution of the current thread and waits for any events matching +`filter`. + +This function @{coroutine.yield|yields} the current process and waits for it +to be resumed with a vararg list where the first element matches `filter`. +If no `filter` is supplied, this will match all events. + +Unlike @{os.pullEventRaw}, it will stop the application upon a "terminate" +event, printing the error "Terminated". + +@tparam[opt] string filter Event to filter for. +@treturn string event The name of the event that fired. +@treturn any param... Optional additional parameters of the event. +@usage Listen for `mouse_click` events. + + while true do + local event, button, x, y = os.pullEvent("mouse_click") + print("Button", button, "was clicked at", x, ",", y) + end + +@usage Listen for multiple events. + + while true do + local eventData = {os.pullEvent()} + local event = eventData[1] + + if event == "mouse_click" then + print("Button", eventData[2], "was clicked at", eventData[3], ",", eventData[4]) + elseif event == "key" then + print("Key code", eventData[2], "was pressed") + end + end + +@see os.pullEventRaw To pull the terminate event. +]] function pullEvent(filter) end + +--[[- Pause execution of the current thread and waits for events, including the +`terminate` event. + +This behaves almost the same as @{os.pullEvent}, except it allows you to handle +the `terminate` event yourself - the program will not stop execution when +Ctrl+T is pressed. + +@tparam[opt] string filter Event to filter for. +@treturn string event The name of the event that fired. +@treturn any param... Optional additional parameters of the event. +@usage Listen for `terminate` events. + + while true do + local event = os.pullEventRaw() + if event == "terminate" then + print("Caught terminate event!") + end + end + +@see os.pullEvent To pull events normally. +]] function pullEventRaw(filter) end + +--- Pauses execution for the specified number of seconds, alias of @{_G.sleep}. +function sleep(time) end + +--- Get the current CraftOS version (for example, `CraftOS 1.8`). +-- +-- This is defined by `bios.lua`. For the current version of CC:Tweaked, this +-- should return `CraftOS 1.8`. +-- +-- @treturn string The current CraftOS version. function version() end + +--[[- Run the program at the given path with the specified environment and +arguments. + +This function does not resolve program names like the shell does. This means +that, for example, `os.run("edit")` will not work. As well as this, it does not +provide access to the @{shell} API in the environment. For this behaviour, use +@{shell.run} instead. + +If the program cannot be found, or failed to run, it will print the error and +return `false`. If you want to handle this more gracefully, use an alternative +such as @{loadfile}. + +@tparam table env The environment to run the program with. +@tparam string path The exact path of the program to run. +@param ... The arguments to pass to the program. +@treturn boolean Whether or not the program ran successfully. +@usage Run the default shell from within your program: + + os.run({}, "/rom/programs/shell") + +@see shell.run +@see loadfile +]] function run(env, path, ...) end diff --git a/doc/styles.css b/doc/styles.css index da9fbec6a..41f8fe05b 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 { +code, pre, kbd, .parameter, .type, .definition-name, .reference-code { font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; } @@ -183,6 +183,20 @@ span.parameter:after { content:":"; padding-left: 0.3em; } vertical-align: middle; } +/** Fancy keyboard shortcut styling, inspired by GitHub markdown. */ +kbd { + display: inline-block; + padding: 4px 5px; + font-size: 0.8em; + line-height: 10px; + color: #444d56; + vertical-align: middle; + background-color: #fafbfc; + border: 1px solid #d1d5da; + border-radius: 3px; + box-shadow: inset 0 -1px 0 #d1d5da; +} + /* styles for prettification of source */ .highlight .comment { color: #558817; } .highlight .constant { color: #a8660d; } diff --git a/illuaminate.sexp b/illuaminate.sexp index d28a3fd44..b06417843 100644 --- a/illuaminate.sexp +++ b/illuaminate.sexp @@ -50,7 +50,7 @@ ;; colours imports from colors, and we don't handle that right now. ;; keys is entirely dynamic, so we skip it. - (dynamic-modules colours keys) + (dynamic-modules colours keys _G) (globals :max @@ -79,6 +79,7 @@ /doc/stub/http.lua /doc/stub/os.lua /doc/stub/turtle.lua + /doc/stub/global.lua ; Java generated APIs /doc/javadoc/turtle.lua ; Peripherals @@ -100,6 +101,10 @@ /doc/stub/fs.lua) (linters -doc:unresolved-reference)) +;; Suppress warnings for the BIOS using its own deprecated members for now. +(at /src/main/resources/*/computercraft/lua/bios.lua + (linters -var:deprecated)) + (at /src/test/resources/test-rom ; We should still be able to test deprecated members. (linters -var:deprecated) diff --git a/src/main/java/dan200/computercraft/core/apis/OSAPI.java b/src/main/java/dan200/computercraft/core/apis/OSAPI.java index 43a5c473f..be5dbb2dd 100644 --- a/src/main/java/dan200/computercraft/core/apis/OSAPI.java +++ b/src/main/java/dan200/computercraft/core/apis/OSAPI.java @@ -171,12 +171,18 @@ public final void queueEvent( String name, IArguments args ) /** * Starts a timer that will run for the specified number of seconds. Once - * the timer fires, a timer event will be added to the queue with the ID - * returned from this function as the first parameter. + * the timer fires, a {@code timer} event will be added to the queue with + * the ID returned from this function as the first parameter. + * + * As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up + * to the nearest multiple of 0.05 seconds, as it waits for a fixed amount + * of world ticks. * * @param timer The number of seconds until the timer fires. - * @return The ID of the new timer. + * @return The ID of the new timer. This can be used to filter the + * {@code timer} event, or {@link #cancelTimer cancel the timer}. * @throws LuaException If the time is below zero. + * @see #cancelTimer To cancel a timer. */ @LuaFunction public final int startTimer( double timer ) throws LuaException @@ -199,11 +205,14 @@ public final void cancelTimer( int token ) /** * Sets an alarm that will fire at the specified world time. When it fires, - * an alarm event will be added to the event queue. + * an {@code alarm} event will be added to the event queue with the ID + * returned from this function as the first parameter. * * @param time The time at which to fire the alarm, in the range [0.0, 24.0). - * @return The ID of the alarm that was set. + * @return The ID of the new alarm. This can be used to filter the + * {@code alarm} event, or {@link #cancelAlarm cancel the alarm}. * @throws LuaException If the time is out of range. + * @see #cancelAlarm To cancel an alarm. */ @LuaFunction public final int setAlarm( double time ) throws LuaException