CC-Tweaked/doc/stub/global.lua

-- SPDX-FileCopyrightText: 2020 The CC: Tweaked Developers
--
-- SPDX-License-Identifier: MPL-2.0

--[[-
Functions in the global environment, defined in `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 API][`parallel`], it will only pause execution of the current
thread, not the whole program.

> [!TIP]
> 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 [timers][`os.startTimer`],
> or the [parallel API][`parallel`].

@tparam number time The number of seconds to sleep for, rounded up to the
nearest multiple of 0.05.

@see os.startTimer
@usage Sleep for three seconds.

    print("Sleeping for three seconds")
    sleep(3)
    print("Done!")
]]
function sleep(time) end

--- Writes a line of text to the screen without a newline at the end, wrapping
-- text if necessary.
--
-- @tparam string text The text to write to the string
-- @treturn number The number of lines written
-- @see print A wrapper around write that adds a newline and accepts multiple arguments
-- @usage write("Hello, world")
function write(text) end

--- Prints the specified values to the screen separated by spaces, wrapping if
-- necessary. After printing, the cursor is moved to the next line.
--
-- @param ... The values to print on the screen
-- @treturn number The number of lines written
-- @usage print("Hello, world!")
function print(...) end

--- Prints the specified values to the screen in red, separated by spaces,
-- wrapping if necessary. After printing, the cursor is moved to the next line.
--
-- @param ... The values to print on the screen
-- @usage printError("Something went wrong!")
function printError(...) end

--[[- Reads user input from the terminal. This automatically handles arrow keys,
pasting, character replacement, history scrollback, auto-completion, and
default values.

@tparam[opt] string replaceChar A character to replace each typed character with.
This can be used for hiding passwords, for example.
@tparam[opt] table history A table holding history items that can be scrolled
back to with the up/down arrow keys. The oldest item is at index 1, while the
newest item is at the highest index.
@tparam[opt] function(partial: string):({ string... }|nil) completeFn A function
to be used for completion. This function should take the partial text typed so
far, and returns a list of possible completion options.
@tparam[opt] string default Default text which should already be entered into
the prompt.

@treturn string The text typed in.

@see cc.completion For functions to help with completion.
@usage Read a string and echo it back to the user

    write("> ")
    local msg = read()
    print(msg)

@usage Prompt a user for a password.

    while true do
      write("Password> ")
      local pwd = read("*")
      if pwd == "let me in" then break end
      print("Incorrect password, try again.")
    end
    print("Logged in!")

@usage A complete example with completion, history and a default value.

    local completion = require "cc.completion"
    local history = { "potato", "orange", "apple" }
    local choices = { "apple", "orange", "banana", "strawberry" }
    write("> ")
    local msg = read(nil, history, function(text) return completion.choice(text, choices) end, "app")
    print(msg)

@changed 1.74 Added `completeFn` parameter.
@changed 1.80pr1 Added `default` parameter.
]]
function read(replaceChar, history, completeFn, default) end

--- Stores the current ComputerCraft and Minecraft versions.
--
-- Outside of Minecraft (for instance, in an emulator) [`_HOST`] will contain the
-- emulator's version instead.
--
-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
-- @usage Print the current computer's environment.
--
--     print(_HOST)
-- @since 1.76
_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

@usage _CC_DEFAULT_SETTINGS
@since 1.77
]]
_CC_DEFAULT_SETTINGS = _CC_DEFAULT_SETTINGS