Document remaining OS functions (#554)

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

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.<function name>`, 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
+<kbd>Ctrl+T</kbd> 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

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; }

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)

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