lua_std/

lib.rs

//! Reference for the Lua 5.5 standard library.
//!
//! Lua is a dynamically typed language: values carry types, variables do not.
//! Every value belongs to one of the basic types documented here — [`nil`],
//! [`boolean`], [`number`], [`string`], [`table`], [`function`], [`userdata`]
//! and [`thread`].
//!
//! The standard library provides a set of global functions (listed below),
//! functions attached to the [`string`] and [`table`] types, and the
//! [`math`], [`os`], [`io`], [`coroutine`] and [`utf8`] libraries.
//!
//! The behaviour of operators on values can be customised through
//! *metatables* — see the Metatables section below.
//!
//! ```lua
//! print("hello, world")
//! ```
//!
//! ---
//!
//! Lua and its logo are from [Lua.org](https://www.lua.org/) — logo
//! © 1998 Lua.org, graphic design by Alexandre Nakonechnyj.

#![cfg_attr(doc, feature(doc_cfg))]
#![doc(html_logo_url = "/lua-std-doc/lua.png")]
#![doc(html_favicon_url = "/lua-std-doc/lua.png")]
#![allow(non_camel_case_types)]
#![allow(non_upper_case_globals)]
#![allow(unused_variables)]

mod metatable;
mod number_;
mod string_;
mod table_;

#[cfg(feature = "extended")]
mod extended;
#[cfg(feature = "extended")]
pub use extended::*;

pub use metatable::*;
pub use number_::*;
pub use string_::*;
pub use table_::*;

pub mod coroutine;
pub mod io;
pub mod math;
pub mod os;
pub mod utf8;

/// The type of the absence of a value.
///
/// `nil` has a single value, also called **nil**, whose main property is to
/// be different from every other value. It usually represents a missing or
/// deleted value: assigning `nil` to a table field removes that field, and
/// reading a variable that was never assigned yields `nil`.
///
/// In a condition, `nil` (together with `false`) counts as false; every
/// other value counts as true.
pub struct nil;

/// The type of the truth values **true** and **false**.
///
/// Only `false` and [`nil`] are treated as false in conditions; everything
/// else — including `0` and the empty string — is true.
pub struct boolean;

/// The type of Lua and C functions.
///
/// Functions are first-class values: they can be stored in variables and
/// tables, passed as arguments, and returned from other functions.
///
/// A variadic function collects its extra arguments in a *vararg
/// table*, whose field `n` holds their count. Since Lua 5.5 that table
/// can be given a name after the three dots, becoming a read-only local:
///
/// ```lua
/// local function f(...args)
///   print(args.n, args[1])
/// end
/// f("a", "b")    --> 2   a
/// ```
///
/// ```lua
/// local greet = function(name)
///   return "hello, " .. name
/// end
/// print(greet("world"))
/// ```
pub struct function;

/// The type of arbitrary C data.
///
/// A userdata value carries a block of raw memory managed by the host
/// program. Userdata values cannot be created or modified in Lua, only
/// through the C API; they typically represent objects belonging to the
/// host application or to C libraries.
pub struct userdata;

/// The type of independent threads of execution, used to implement
/// coroutines.
///
/// Threads are created with [`coroutine::create`] and are not related to
/// operating-system threads. See the [`coroutine`] library.
pub struct thread;

/// Marker for a variable number of values of type `T` (`...` in Lua).
/// Rendered by custom.html as `...name: T`.
#[doc(hidden)]
pub struct Repeatable<T>(core::marker::PhantomData<T>);

/// Marker for a value that may be `T` or nil.
/// Rendered by custom.html as `T | nil`.
#[doc(hidden)]
#[allow(non_camel_case_types)]
pub struct option<T>(core::marker::PhantomData<T>);

/// Stands for a value of any type.
///
/// This is a documentation convention, not a real Lua type: where a
/// signature says `any`, the function accepts (or may return) a value of
/// any of the basic types — [`nil`], [`boolean`], [`number`],
/// [`string`], [`table`], [`function`], [`userdata`] or [`thread`].
///
/// Use [`type`](crate::type()) to find out at run time which type a
/// value actually has:
///
/// ```lua
/// print(type("hi"), type(42), type({}))    --> string   number   table
/// ```
pub struct any;

/// A global variable that holds the global environment itself.
///
/// Lua does not use this value; changing it does not affect any
/// environment. Setting a field in `_G` is the same as assigning to a
/// global variable.
///
/// # Examples
///
/// ```lua
/// x = 10
/// print(_G.x)    --> 10
/// _G.y = 20
/// print(y)       --> 20
/// ```
pub static _G: table = table;

/// A global variable containing the running Lua version, as a string —
/// currently `"Lua 5.5"`.
///
/// # Examples
///
/// ```lua
/// print(_VERSION)    --> Lua 5.5
/// ```
pub static _VERSION: string = string;

/// Raises an error if the value of its argument `v` is false (i.e. `nil`
/// or `false`); otherwise, returns all its arguments. On error, `message`
/// is used as the error object; when absent, it defaults to
/// `"assertion failed!"`.
///
/// ```lua
/// local f = assert(io.open("config.txt"))  -- error if the open failed
/// ```
pub fn assert(v: any, message: option<string>) -> Repeatable<any> {
    todo!()
}

/// A generic interface to the garbage collector. Performs different jobs
/// according to `opt`: `"collect"` runs a full collection cycle (the
/// default), `"stop"` and `"restart"` pause and resume the collector,
/// `"count"` returns the total memory in use by Lua in kilobytes,
/// `"step"` performs an incremental step, `"isrunning"` tells whether
/// the collector is stopped, and `"incremental"` / `"generational"`
/// select the collector mode.
///
/// **Changed in Lua 5.5:** collector parameters are read and set through
/// the new `"param"` option — `collectgarbage("param", name [, value])`
/// — where `name` is one of `"pause"`, `"stepmul"`, `"stepsize"` (for
/// the incremental collector) or `"minormul"`, `"minormajor"`,
/// `"majorminor"` (for the generational collector). In 5.5 major
/// collections of the generational collector are done incrementally.
///
/// # Examples
///
/// ```lua
/// print(collectgarbage("count"))   --> 24.35  (kilobytes in use)
/// collectgarbage()                 -- run a full collection cycle
/// ```
pub fn collectgarbage(opt: option<string>) -> any {
    todo!()
}

/// Opens the named file and executes its contents as a Lua chunk. When
/// called without arguments, executes the contents of the standard input.
/// Returns all values returned by the chunk. In case of errors, `dofile`
/// propagates the error to its caller: it does not run in protected mode.
///
/// # Examples
///
/// ```lua
/// dofile("config.lua")     -- run config.lua in the current environment
/// ```
pub fn dofile(filename: option<string>) -> Repeatable<any> {
    todo!()
}

/// Raises an error with `message` as the error object. This function never
/// returns.
///
/// Usually, `error` adds some information about the error position at the
/// beginning of the message, if the message is a string. The `level`
/// argument specifies how to get the error position: with level 1 (the
/// default), the error position is where `error` was called; level 2
/// points the error to where the function that called `error` was called;
/// level 0 avoids adding position information.
///
/// # Examples
///
/// ```lua
/// local ok, err = pcall(function()
///   error("something broke")
/// end)
/// print(ok, err)    --> false   input:2: something broke
/// error({ code = 42 })         -- any value can be an error object
/// ```
pub fn error(message: any, level: option<number>) {
    todo!()
}

/// If `object` does not have a metatable, returns `nil`. Otherwise, if the
/// metatable has a `__metatable` field, returns the associated value.
/// Otherwise, returns the metatable of the given object.
///
/// # Examples
///
/// ```lua
/// print(getmetatable({}))            --> nil
/// print(getmetatable(""))            --> table: 0x...  (the string metatable)
/// local t = setmetatable({}, { __metatable = "locked" })
/// print(getmetatable(t))             --> locked
/// ```
pub fn getmetatable(object: any) -> option<table> {
    todo!()
}

/// Returns three values (an iterator function, `t`, and 0) so that the
/// construction
///
/// ```lua
/// for i, v in ipairs(t) do body end
/// ```
///
/// will iterate over the key–value pairs `(1, t[1])`, `(2, t[2])`, ...,
/// up to the first absent index.
pub fn ipairs(t: table) -> (function, table, number) {
    todo!()
}

/// Loads a chunk. If `chunk` is a string, the chunk is that string; if it
/// is a function, `load` calls it repeatedly to get the chunk pieces. If
/// there are no syntactic errors, returns the compiled chunk as a
/// function; otherwise, returns `nil` plus the error message.
///
/// `chunkname` is used in error messages and debug information; `mode`
/// controls whether the chunk can be text or binary; `env` sets the first
/// upvalue (`_ENV`) of the resulting function.
///
/// # Examples
///
/// ```lua
/// local f = load("return 1 + 2")
/// print(f())                         --> 3
/// local bad, msg = load("return +")
/// print(bad, msg)                    --> nil   [string "return +"]:1: unexpected symbol
/// ```
pub fn load(
    chunk: any,
    chunkname: option<string>,
    mode: option<string>,
    env: option<any>,
) -> option<function> {
    todo!()
}

/// Allows a program to traverse all fields of a table. Its first argument
/// is a table and its second argument is an index in this table. A call
/// returns the next index of the table and its associated value; when
/// called with `nil` as its second argument, returns an initial index and
/// its associated value. When called with the last index, or with `nil`
/// in an empty table, returns `nil`.
///
/// The order in which the indices are enumerated is not specified, *even
/// for numeric indices*.
///
/// # Examples
///
/// ```lua
/// local t = { a = 1 }
/// print(next(t))         --> a   1
/// print(next(t, "a"))    --> nil       (no more fields)
/// print(next({}))        --> nil       (empty table)
/// ```
pub fn next(t: table, index: option<any>) -> (any, any) {
    todo!()
}

/// Returns three values (the [`next`] function, the table `t`, and `nil`)
/// so that the construction
///
/// ```lua
/// for k, v in pairs(t) do body end
/// ```
///
/// will iterate over all key–value pairs of the table.
///
/// If `t` has a metamethod `__pairs`, calls it with `t` as argument and
/// returns the first three results from the call instead.
pub fn pairs(t: table) -> (function, table, nil) {
    todo!()
}

/// Calls the function `f` with the given arguments in *protected mode*:
/// errors inside `f` are not propagated. Returns a status code (a
/// boolean) followed, on success, by all results of the call, or, on
/// failure, by the error object.
///
/// ```lua
/// local ok, err = pcall(function() error("boom") end)
/// print(ok, err)  --> false   input:1: boom
/// ```
pub fn pcall(f: function, args: Repeatable<any>) -> (boolean, Repeatable<any>) {
    todo!()
}

/// Receives any number of arguments and prints their values to the
/// standard output, converting each to a string following the same rules
/// as [`tostring()`], separated by tabs and followed by a newline.
///
/// `print` is meant for quick debugging, not for formatted output — for
/// that, use [`string::format`] and [`io::write`].
///
/// # Examples
///
/// ```lua
/// print("x", 42, true)      --> x   42   true
/// print()                   --> (just a newline)
/// ```
pub fn print<T: tostring>(values: Repeatable<T>) {
    todo!()
}

/// Checks whether `v1` is equal to `v2`, without invoking the `__eq`
/// metamethod. Returns a boolean.
///
/// # Examples
///
/// ```lua
/// local mt = { __eq = function() return true end }
/// local a, b = setmetatable({}, mt), setmetatable({}, mt)
/// print(a == b)           --> true    (uses __eq)
/// print(rawequal(a, b))   --> false   (different tables)
/// print(rawequal(a, a))   --> true
/// ```
pub fn rawequal(v1: any, v2: any) -> boolean {
    todo!()
}

/// Gets the real value of `t[index]`, without using the `__index`
/// metamethod. `t` must be a table.
///
/// # Examples
///
/// ```lua
/// local t = setmetatable({}, { __index = function() return "fallback" end })
/// print(t.missing)             --> fallback
/// print(rawget(t, "missing"))  --> nil
/// ```
pub fn rawget(t: table, index: any) -> any {
    todo!()
}

/// Returns the length of the object `v`, which must be a table or a
/// string, without invoking the `__len` metamethod.
///
/// # Examples
///
/// ```lua
/// local t = setmetatable({1, 2, 3}, { __len = function() return 42 end })
/// print(#t)          --> 42
/// print(rawlen(t))   --> 3
/// print(rawlen("hello"))   --> 5
/// ```
pub fn rawlen<T: length>(v: T) -> number {
    todo!()
}

/// Sets the real value of `t[index]` to `value`, without using the
/// `__newindex` metamethod. `t` must be a table, `index` any value
/// different from `nil` and NaN. Returns `t`.
///
/// # Examples
///
/// ```lua
/// local t = setmetatable({}, { __newindex = function() error("read-only") end })
/// rawset(t, "k", 1)      -- bypasses __newindex
/// print(t.k)             --> 1
/// ```
pub fn rawset(t: table, index: any, value: any) -> table {
    todo!()
}

/// Loads the given module. Starts by looking into the `package.loaded`
/// table to determine whether `modname` is already loaded; if so, returns
/// the stored value. Otherwise, finds a loader for the module by
/// consulting the searchers in `package.searchers`, runs it, and caches
/// its result in `package.loaded[modname]`.
///
/// # Examples
///
/// ```lua
/// local socket = require("socket")
/// print(require("socket") == socket)    --> true  (cached in package.loaded)
/// ```
pub fn require(modname: string) -> any {
    todo!()
}

/// If `index` is a number, returns all arguments after argument number
/// `index`; a negative number indexes from the end (−1 is the last
/// argument). Otherwise, `index` must be the string `"#"`, and `select`
/// returns the total number of extra arguments it received.
///
/// # Examples
///
/// ```lua
/// print(select("#", "a", "b", "c"))    --> 3
/// print(select(2, "a", "b", "c"))      --> b   c
/// print(select(-1, "a", "b", "c"))     --> c
/// ```
pub fn select(index: any, values: Repeatable<any>) -> Repeatable<any> {
    todo!()
}

/// Sets the metatable for the given table. If `metatable` is `nil`,
/// removes the metatable of the table. If the original metatable has a
/// `__metatable` field, raises an error.
///
/// Returns `t`. (To change the metatable of other types from Lua code,
/// you must use the debug library.)
///
/// # Examples
///
/// ```lua
/// local parent = { greet = function() print("hi") end }
/// local child = setmetatable({}, { __index = parent })
/// child.greet()    --> hi   (found through __index)
/// ```
pub fn setmetatable(t: table, metatable: option<table>) -> table {
    todo!()
}

/// When called with no `base`, tries to convert its argument to a number.
/// If the argument is already a number or a string convertible to a
/// number, returns that number; otherwise, returns `nil`.
///
/// When called with a `base`, `v` must be a string to be interpreted as an
/// integer numeral in that base (from 2 to 36, letters `A`–`Z` standing
/// for 10–35).
///
/// # Examples
///
/// ```lua
/// print(tonumber("42"))        --> 42
/// print(tonumber("0x1F"))      --> 31
/// print(tonumber("3.7e2"))     --> 370.0
/// print(tonumber("ff", 16))    --> 255
/// print(tonumber("hello"))     --> nil
/// ```
pub fn tonumber(v: any, base: option<number>) -> option<number> {
    todo!()
}

/// Receives a value of any type and converts it to a string in a
/// human-readable format.
///
/// If the metatable of `v` has a `__tostring` field, `tostring` calls the
/// corresponding value with `v` as argument and uses the result. If it
/// has a `__name` field with a string value, that string is used in the
/// result. For full control of how numbers are converted, use
/// [`string::format`].
///
/// # Examples
///
/// ```lua
/// print(tostring(42))       --> 42
/// print(tostring(nil))      --> nil
/// local pt = setmetatable({}, { __tostring = function() return "Point" end })
/// print(tostring(pt))       --> Point
/// ```
pub fn tostring<T: tostring>(v: T) -> string {
    todo!()
}

/// Returns the type of its only argument, coded as a string. The possible
/// results are `"nil"`, `"boolean"`, `"number"`, `"string"`, `"table"`,
/// `"function"`, `"userdata"` and `"thread"`.
///
/// # Examples
///
/// ```lua
/// print(type(nil))         --> nil
/// print(type(42))          --> number
/// print(type("hi"))        --> string
/// print(type({}))          --> table
/// print(type(print))       --> function
/// ```
pub fn r#type(v: any) -> string {
    todo!()
}

/// Like [`pcall`], but sets `msgh` as a message handler: in case of error,
/// `msgh` is called with the error object before the stack unwinds, and
/// its return value becomes the error object returned by `xpcall`.
///
/// # Examples
///
/// ```lua
/// local ok, err = xpcall(function()
///   error("boom")
/// end, function(e)
///   return "handled: " .. e
/// end)
/// print(ok, err)    --> false   handled: input:2: boom
/// ```
pub fn xpcall(f: function, msgh: function, args: Repeatable<any>) -> (boolean, Repeatable<any>) {
    todo!()
}