Lua 5.4 Reference Manual

https://www.lua.org/manual/5.4
Admin
The official reference manual for the Lua 5.4 programming language, detailing its syntax, semantics,...
Tokens:83,907
Snippets:1,045
Trust Score:9.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Starting a Program in a Separate Process

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to start a program in a separate process and interact with its input/output using `io.popen()`. The mode can be 'r' (default) or 'w'.

```lua
io.popen(prog [, mode])
```

--------------------------------

### Lua Table Constructor Example

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates how a complex table constructor is expanded into equivalent assignments.

```lua
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
```

```lua
do
  local t = {}
  t[f(1)] = g
  t[1] = "x"         -- 1st exp
  t[2] = "y"         -- 2nd exp
  t.x = 1            -- t["x"] = 1
  t[3] = f(x)        -- 3rd exp
  t[30] = 23
  t[4] = 45          -- 4th exp
  a = t
end
```

--------------------------------

### Generic for loop example

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates the structure of a generic for loop with multiple loop variables.

```lua
for _var_1_, ···, _var_n_ in _explist_ do _body_ end
```

--------------------------------

### Lua Function Call Examples

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates how arguments are mapped to parameters and vararg expressions for different function calls.

```lua
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end

```

```lua
CALL             PARAMETERS

f(3)             a=3, b=nil
f(3, 4)          a=3, b=4
f(3, 4, 5)       a=3, b=4
f(r(), 10)       a=1, b=10
f(r())           a=1, b=2

g(3)             a=3, b=nil, ... -->  (nothing)
g(3, 4)          a=3, b=4,   ... -->  (nothing)
g(3, 4, 5, 8)    a=3, b=4,   ... -->  5  8
g(5, r())        a=5, b=1,   ... -->  2  3

```

--------------------------------

### io.popen

Source: https://www.lua.org/manual/5.4/manual.html

Starts a program in a separate process and returns a file handle for reading from or writing to the program's standard input/output.

```APIDOC
## `io.popen (prog [, mode])`

### Description
Starts the program `prog` in a separated process and returns a file handle that you can use to read data from this program (if `mode` is `"r"`, the default) or to write data to this program (if `mode` is `"w"`).

### Parameters
* `prog` (string) - The program to execute.
* `mode` (string, optional) - The mode to open the file handle. Defaults to `"r"`.

### Returns
A file handle for reading or writing to the program's standard input/output.
```

--------------------------------

### C Library Search Path Example

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates the pattern for searching C libraries using `package.cpath`. It shows how different file extensions and initialization files are considered.

```lua
"./?.so;./?.dll;/usr/local/?/init.so"
```

--------------------------------

### Lua Module Search Path Example

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates the pattern for searching Lua libraries using `package.path`. It specifies file extensions and directory structures to be checked.

```lua
"./?.lua;./?.lc;/usr/local/?/init.lua"
```

--------------------------------

### Lua Logical Operators Examples

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates the short-circuit evaluation and return values of Lua's 'and' and 'or' operators.

```lua
10 or 20            --> 10
10 or error()       --> 10
nil or "a"          --> "a"
nil and 10          --> nil
false and error()   --> false
false and nil       --> false
false or nil        --> nil
10 and 20           --> 20
```

--------------------------------

### Lua Tail Call Examples (Not Tail Calls)

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates various return syntaxes that are not considered tail calls in Lua.

```lua
return (f(x))        -- results adjusted to 1
```

```lua
return 2 * f(x)      -- result multiplied by 2
```

```lua
return x, f(x)       -- additional results
```

```lua
f(x); return         -- results discarded
```

```lua
return x or f(x)     -- results adjusted to 1
```

--------------------------------

### Lua Coroutine Example

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates the creation, execution, yielding, and resumption of a Lua coroutine. Shows how values are passed between the main thread and the coroutine.

```lua
function foo (a)
  print("foo", a)
  return coroutine.yield(2*a)
end

co = coroutine.create(function (a,b)
      print("co-body", a, b)
      local r = foo(a+1)
      print("co-body", r)
      local r, s = coroutine.yield(a+b, a-b)
      print("co-body", r, s)
      return b, "end"
end)

print("main", coroutine.resume(co, 1, 10))
print("main", coroutine.resume(co, "r"))
print("main", coroutine.resume(co, "x", "y"))
print("main", coroutine.resume(co, "x", "y"))

```

--------------------------------

### Example: Calling a Lua Function from C

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates the C protocol for calling a Lua function 'f' with arguments and setting its return value to a global variable 'a'. Ensure the stack is balanced after the call.

```c
lua_getglobal(L, "f");                  /* function to be called */
lua_pushliteral(L, "how");                       /* 1st argument */
lua_getglobal(L, "t");                    /* table to be indexed */
lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
lua_remove(L, -2);                  /* remove 't' from the stack */
lua_pushinteger(L, 14);                          /* 3rd argument */
lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
lua_setglobal(L, "a");                         /* set global 'a' */
```

--------------------------------

### Lua Lexical Scoping Example

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates lexical scoping and variable visibility in Lua, including nested blocks and upvalues.

```lua
     x = 10                -- global variable
     do                    -- new block
       local x = x         -- new 'x', with value 10
       print(x)            --> 10
       x = x+1
       do                  -- another block
         local x = x+1     -- another 'x'
         print(x)          --> 12
       end
       print(x)            --> 11
     end
     print(x)              --> 10  (the global one)


```

--------------------------------

### lua_resume

Source: https://www.lua.org/manual/5.4/manual.html

Starts or resumes a coroutine. It handles pushing arguments, yielding, and returning values from the coroutine.

```APIDOC
## lua_resume

### Description
Starts and resumes a coroutine in the given thread `L`. To start a coroutine, push the main function and arguments onto the stack, then call `lua_resume`. To resume, remove yielded values, push new results, and call `lua_resume` again. The function returns `LUA_YIELD` if the coroutine yields, `LUA_OK` on successful completion, or an error code.

### Signature
```c
int lua_resume (lua_State *L, lua_State *from, int nargs, int *nresults);
```

### Parameters
* **L** (lua_State *) - The coroutine thread to resume.
* **from** (lua_State *) - The coroutine that is resuming `L`, or `NULL` if none.
* **nargs** (int) - The number of arguments to push for starting or resuming.
* **nresults** (int *) - Pointer to store the number of results returned by the coroutine.
```

--------------------------------

### file:seek

Source: https://www.lua.org/manual/5.4/manual.html

Sets and gets the file position.

```APIDOC
## `file:seek ([whence [, offset]])`

### Description
Sets and gets the file position, measured from the beginning of the file, to the position given by `offset` plus a base specified by the string `whence`.

### Parameters
* `whence` (string, optional) - The base for the offset. Can be `"set"` (beginning of file), `"cur"` (current position), or `"end"` (end of file). Defaults to `"cur"`.
* `offset` (number, optional) - The offset from the base position. Defaults to 0.

### Returns
The final file position in bytes from the beginning of the file on success, or **fail** plus an error string on failure.
```

--------------------------------

### Resume Coroutine Execution with lua_resume

Source: https://www.lua.org/manual/5.4/manual.html

Starts or resumes a coroutine. Pushes arguments for starting, or results for resuming, and updates the stack with yielded values or return values. Handles coroutine suspension, completion, and errors.

```c
int lua_resume (lua_State *L, lua_State *from, int nargs,
                          int *nresults);
```

--------------------------------

### Lua Multiple Assignment Example

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates how Lua handles multiple assignments, ensuring correct evaluation order when variables are both read and written within the same statement.

```lua
i = 3
i, a[i] = i+1, 20
```

--------------------------------

### Getting CPU Time Used by Program

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates retrieving an approximation of the CPU time used by the program in seconds using `os.clock()`.

```lua
os.clock()
```

--------------------------------

### Lua Closures and Upvalues Example

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates how closures capture local variables, showing distinct 'y' variables for each closure and a shared 'x'.

```lua
     a = {}
     local x = 20
     for i = 1, 10 do
       local y = 0
       a[i] = function () y = y + 1; return x + y end
     end


```

--------------------------------

### luaL_traceback

Source: https://www.lua.org/manual/5.4/manual.html

Creates and pushes a traceback of the stack. Allows prepending a message and specifying the starting level for the traceback.

```APIDOC
## luaL_traceback

### Description
Creates and pushes a traceback of the stack `L1`. If `msg` is not `NULL`, it is appended at the beginning of the traceback. The `level` parameter tells at which level to start the traceback.

### Function Signature
```c
void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, int level);
```
```

--------------------------------

### Iterate over words in a string

Source: https://www.lua.org/manual/5.4/manual.html

This example demonstrates how to use string.gmatch with the '%a+' pattern to iterate over all sequences of alphabetic characters (words) in a string.

```lua
s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
  print(w)
end
```

--------------------------------

### String Substitution with string.gsub

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates various uses of string.gsub for replacing patterns in strings. Supports string, table, or function as replacement, with examples showing capture group usage and environment variable substitution.

```lua
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"
```

```lua
x = string.gsub("hello world", "%w+", "%0 %0", 1)
--> x="hello hello world"
```

```lua
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
--> x="world hello Lua from"
```

```lua
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
--> x="home = /home/roberto, user = roberto"
```

```lua
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
          return load(s)()
        end)
--> x="4+5 = 9"
```

```lua
local t = {name="lua", version="5.4"}
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
--> x="lua-5.4.tar.gz"
```

--------------------------------

### Generate Stack Traceback

Source: https://www.lua.org/manual/5.4/manual.html

Creates and pushes a traceback of the stack `L1` onto the stack of `L`. Allows prepending a message and specifying the starting level for the traceback.

```c
void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, int level);
```

--------------------------------

### Getting UTF-8 Character Offset

Source: https://www.lua.org/manual/5.4/manual.html

Finds the byte position where the n-th UTF-8 character starts in a string. Assumes the string is valid UTF-8.

```lua
utf8.offset(s, n, i)
```

--------------------------------

### Get Lua Memory Allocator Function

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the memory-allocation function associated with a Lua state using `lua_getallocf`. If `ud` is not NULL, it also stores the opaque pointer provided during allocator setup.

```c
lua_Alloc lua_getallocf (lua_State *L, void **ud);
```

--------------------------------

### Traversing a table with next()

Source: https://www.lua.org/manual/5.4/manual.html

Use next() to iterate through a table's fields. Provide an index to get the next key-value pair, or nil to start. Modifying the table during traversal is allowed for existing fields.

```lua
next(table, index)
```

--------------------------------

### Getting the Current File Position

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to get the current file position without changing it by calling `file:seek()` with default arguments.

```lua
file:seek()
```

--------------------------------

### Selecting arguments

Source: https://www.lua.org/manual/5.4/manual.html

Use select() to retrieve arguments passed to a function. Specify a numeric index to get subsequent arguments or '#' to get the total count of extra arguments.

```lua
select(index, ···)
```

--------------------------------

### Raw Table Get by Pointer Key

Source: https://www.lua.org/manual/5.4/manual.html

Pushes the value t[p] onto the stack, where t is the table at 'index' and p is a pointer represented as a light userdata. Access is raw, bypassing __index metamethod. Returns the type of the pushed value.

```c
int lua_rawgetp (lua_State *L, int index, const void *p);
```

--------------------------------

### Create Lua Table

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new empty table and pushes it onto the stack. Hints for array and record size can be provided for preallocation.

```c
void lua_createtable (lua_State *L, int narr, int nrec);
```

--------------------------------

### C Continuation Function and Rewritten Original Function

Source: https://www.lua.org/manual/5.4/manual.html

This example shows a continuation function 'k' designed to handle tasks after a Lua call, and how the original function is rewritten to incorporate it. The continuation function contains the 'code 2' logic.

```c
int k (lua_State *L, int status, lua_KContext ctx) {
  ...  /* code 2 */
}

int original_function (lua_State *L) {
  ...     /* code 1 */
  return k(L, lua_pcall(L, n, m, h), ctx);
}
```

--------------------------------

### Handling Command-Line Arguments in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates how the `arg` table is populated with command-line arguments, including the interpreter name, options, script name, and script arguments.

```bash
$ lua -la b.lua t1 t2
```

```lua
arg = { [-2] = "lua", [-1] = "-la",
        [0] = "b.lua",
        [1] = "t1", [2] = "t2" }
```

--------------------------------

### Prepare Buffer with Predefined Size

Source: https://www.lua.org/manual/5.4/manual.html

Equivalent to luaL_prepbuffsize with the predefined size LUAL_BUFFERSIZE.

```c
char *luaL_prepbuffer (luaL_Buffer *B);
```

--------------------------------

### Get Lua core version

Source: https://www.lua.org/manual/5.4/manual.html

Returns the version number of the Lua core.

```c
lua_Number lua_version (lua_State *L);
```

--------------------------------

### Extract key-value pairs from a string

Source: https://www.lua.org/manual/5.4/manual.html

This example uses string.gmatch with capturing parentheses to extract key-value pairs from a string formatted as 'key=value'. The captured keys and values are then stored in a table.

```lua
t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
  t[k] = v
end
```

--------------------------------

### Getting Lua String Buffer Length

Source: https://www.lua.org/manual/5.4/manual.html

Returns the current length of the content stored in a luaL_Buffer.

```c
size_t luaL_bufflen (luaL_Buffer *B);
```

--------------------------------

### Printing to standard output

Source: https://www.lua.org/manual/5.4/manual.html

Use print() for basic output to stdout, suitable for debugging. For formatted output, use string.format and io.write.

```lua
print (···)
```

--------------------------------

### Load and Register Module

Source: https://www.lua.org/manual/5.4/manual.html

Loads a module by calling its openf function if it hasn't been loaded. Optionally stores the module in the global environment. Leaves a copy of the module on the stack.

```c
void luaL_requiref (lua_State *L, const char *modname,
                    lua_CFunction openf, int glb);
```

--------------------------------

### Open All Standard Lua Libraries

Source: https://www.lua.org/manual/5.4/manual.html

Opens all standard Lua libraries into the given state.

```c
void luaL_openlibs (lua_State *L);
```

--------------------------------

### Valid Integer Constants in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Examples of valid integer constants in Lua. These can be decimal or hexadecimal.

```lua
3   345   0xff   0xBEBADA
```

--------------------------------

### Raw table length

Source: https://www.lua.org/manual/5.4/manual.html

Use rawlen() to get the length of a value without invoking __len metamethods.

```lua
rawlen(v)
```

--------------------------------

### Example: C Function for Lua (Average and Sum)

Source: https://www.lua.org/manual/5.4/manual.html

A C function that calculates the average and sum of a variable number of numeric arguments passed from Lua. It pushes results onto the stack and returns the count of results. Includes basic type checking.

```c
static int foo (lua_State *L) {
  int n = lua_gettop(L);    /* number of arguments */
  lua_Number sum = 0.0;
  int i;
  for (i = 1; i <= n; i++) {
    if (!lua_isnumber(L, i)) {
      lua_pushliteral(L, "incorrect argument");
      lua_error(L);
    }
    sum += lua_tonumber(L, i);
  }
  lua_pushnumber(L, sum/n);        /* first result */
  lua_pushnumber(L, sum);         /* second result */
  return 2;                   /* number of results */
}
```

--------------------------------

### luaL_prepbuffer

Source: https://www.lua.org/manual/5.4/manual.html

Prepares a buffer for adding a string. This is an equivalent to `luaL_prepbuffsize` with a predefined size `LUAL_BUFFERSIZE`.

```APIDOC
## luaL_prepbuffer

### Description
Prepares a buffer for adding a string. This is an equivalent to `luaL_prepbuffsize` with a predefined size `LUAL_BUFFERSIZE`.

### Signature
```c
char *luaL_prepbuffer (luaL_Buffer *B);
```
```

--------------------------------

### Get Type Name of Lua Value

Source: https://www.lua.org/manual/5.4/manual.html

Returns the name of the type of the Lua value at the specified index.

```c
const char *luaL_typename (lua_State *L, int index);
```

--------------------------------

### Lua string.gsub with pattern captures and multiple matches

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates how string.gsub handles multiple matches of a pattern with captures, illustrating the behavior when empty strings are matched.

```lua
string.gsub("abc", "()a*()", print)
--> 1   2
--> 3   3
--> 4   4
```

--------------------------------

### Get pseudo-index for upvalue

Source: https://www.lua.org/manual/5.4/manual.html

Returns the pseudo-index for the i-th upvalue of the running function. 'i' must be between 1 and 256.

```c
int lua_upvalueindex (int i);
```

--------------------------------

### io.input

Source: https://www.lua.org/manual/5.4/manual.html

Manages the default input file, opening a new file or setting an existing handle as the default.

```APIDOC
## io.input ([file])

### Description
Manages the default input file. When called with a file name, it opens the file in text mode and sets it as the default input file. When called with a file handle, it sets that handle as the default input file. When called without arguments, it returns the current default input file. Errors during file opening will raise an error.

### Parameters
* `file` (string or file handle, optional) - The file name to open or the file handle to set as default.

### Returns
* The current default input file handle if called without arguments.
* On success when setting a file, a success value is returned (implicitly, as errors raise exceptions).
* Raises an error on failure to open the file.
```

--------------------------------

### debug.traceback

Source: https://www.lua.org/manual/5.4/manual.html

Generates a traceback string for the current call stack, optionally starting from a specific level and including a message.

```APIDOC
## debug.traceback ([thread,] [message [, level]])

### Description
Returns a string with a traceback of the call stack.

### Parameters
* `thread` (thread) - Optional - The thread for which to generate the traceback.
* `message` (string or nil) - Optional - A message to prepend to the traceback.
* `level` (number) - Optional - The stack level at which to start the traceback (default is 1).

### Returns
* `traceback` (string) - The formatted traceback string.

### Notes
If `message` is present but is neither a string nor **nil**, the function returns `message` without further processing.
```

--------------------------------

### Executing Lua Code from Stdin with Argument Handling

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to execute Lua code from standard input when no script is provided, and how the `arg` table reflects this scenario.

```bash
$ lua -e "print(arg[1])"
```

--------------------------------

### Valid Float Constants in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Examples of valid float constants in Lua, including decimal and hexadecimal with exponents.

```lua
3.0     3.1416     314.16e-2     0.31416E1     34e1
     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
```

--------------------------------

### Setting File Position to the Beginning

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates setting the file position to the beginning of the file using `file:seek('set')`.

```lua
file:seek("set")
```

--------------------------------

### Get Current Hook Function

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the currently set hook function in Lua. This function does not modify the Lua state.

```c
lua_Hook lua_gethook (lua_State *L);
```

--------------------------------

### lua_newtable

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new empty table and pushes it onto the Lua stack. This is equivalent to calling `lua_createtable` with zero initial size for array and hash parts.

```APIDOC
## `lua_newtable`

### Description
Creates a new empty table and pushes it onto the stack. It is equivalent to `lua_createtable(L, 0, 0)`.

### Function Signature
```c
void lua_newtable (lua_State *L);
```
```

--------------------------------

### Setting File Buffering Mode

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to set the buffering mode for a file using `file:setvbuf()`. Available modes are 'no', 'full', and 'line'.

```lua
file:setvbuf(mode [, size])
```

--------------------------------

### io.open

Source: https://www.lua.org/manual/5.4/manual.html

Opens a file with a specified mode and returns a file handle.

```APIDOC
## io.open (filename [, mode])

### Description
Opens a file with the specified `mode` and returns a new file handle. The `mode` string determines how the file is opened (read, write, append, update, binary).

### Parameters
* `filename` (string) - The name of the file to open.
* `mode` (string, optional) - The mode in which to open the file. Defaults to '`r`'.
  * '`r`': read mode (default).
  * '`w`': write mode.
  * '`a`': append mode.
  * '`r+`': update mode, all previous data is preserved.
  * '`w+`': update mode, all previous data is erased.
  * '`a+`': append update mode, previous data is preserved, writing only at the end.
  * A '`b`' can be appended to any mode for binary mode.

### Returns
* A new file handle on success.
* **fail** plus an error message and error code on failure.
```

--------------------------------

### Lua Method Emulation Syntax

Source: https://www.lua.org/manual/5.4/manual.html

Shows the syntactic sugar for defining methods using the colon syntax in Lua.

```lua
function t.a.b.c:f (_params_) _body_ end

```

```lua
t.a.b.c.f = function (self, _params_) _body_ end

```

--------------------------------

### Raw table get

Source: https://www.lua.org/manual/5.4/manual.html

Use rawget() to access a table's value at a specific index without invoking __index metamethods.

```lua
rawget(table, index)
```

--------------------------------

### Get Length of Value in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Returns the 'length' of a value at a given index, similar to the '#' operator. Raises an error if the result is not an integer.

```c
lua_Integer luaL_len (lua_State *L, int index);
```

--------------------------------

### Load Lua Chunk from File (Default Mode)

Source: https://www.lua.org/manual/5.4/manual.html

Equivalent to `luaL_loadfilex` with `mode` equal to `NULL`.

```c
int luaL_loadfile (lua_State *L, const char *filename);
```

--------------------------------

### debug.setupvalue

Source: https://www.lua.org/manual/5.4/manual.html

Assigns a new value to an upvalue of a given function.

```APIDOC
## debug.setupvalue (f, up, value)

### Description
Assigns the value `value` to the upvalue with index `up` of the function `f`.

### Parameters
* `f` (function) - The function whose upvalue is to be set.
* `up` (number) - The index of the upvalue.
* `value` - The new value to assign to the upvalue.

### Returns
* `name` (string) - The name of the upvalue.

### Notes
Returns **fail** if there is no upvalue with the given index.
```

--------------------------------

### Raw Table Get

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves a value from a table at a given index without using metamethods. The value at 'index' must be a table.

```c
int lua_rawget (lua_State *L, int index);
```

--------------------------------

### Load and Run File in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Executes a Lua file. Returns 0 on success, 1 on error. This is a macro equivalent to luaL_loadfile followed by lua_pcall.

```c
int luaL_dofile (lua_State *L, const char *filename);
```

```c
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
```

--------------------------------

### Making Lua Scripts Executable on Unix

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates how to make a Lua script executable by adding a shebang line pointing to the Lua interpreter. This allows direct execution of the script.

```bash
#!/usr/local/bin/lua
```

```bash
#!/usr/bin/env lua
```

--------------------------------

### lua_getallocf

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the memory-allocation function associated with a Lua state. It can also retrieve an opaque pointer provided during the allocator's setup.

```APIDOC
## lua_getallocf

### Description
Returns the memory-allocation function of a given state. If `ud` is not `NULL`, Lua stores in `*ud` the opaque pointer given when the memory-allocator function was set.

### Method
```
lua_Alloc lua_getallocf (lua_State *L, void **ud);
```

### Parameters
* `L` (lua_State *) - The Lua state.
* `ud` (void **) - A pointer to store the opaque user data pointer, if provided.

### Returns
The memory-allocation function (`lua_Alloc`).
```

--------------------------------

### Create and Register Library Functions

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new table and registers functions from the provided list `l`. The array `l` must be the actual array, not a pointer.

```c
void luaL_newlib (lua_State *L, const luaL_Reg l[]);
```

```c
(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
```

--------------------------------

### Get Metatable by Name in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Pushes the metatable associated with a name from the registry onto the stack. Returns the type of the pushed value or nil.

```c
int luaL_getmetatable (lua_State *L, const char *tname);
```

--------------------------------

### Creating a Temporary File

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates creating a temporary file that is automatically removed when the program ends using `io.tmpfile()`.

```lua
io.tmpfile()
```

--------------------------------

### Get Current Hook Count

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the current hook count setting in Lua. This value determines how often the hook function is called.

```c
int lua_gethookcount (lua_State *L);
```

--------------------------------

### Creating a Table with Function Results

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to create a table where the elements are derived from all the multiple results of a function call. The function's results directly populate the table.

```lua
{f()}
```

--------------------------------

### io.output

Source: https://www.lua.org/manual/5.4/manual.html

Manages the default output file, opening a new file or setting an existing handle as the default.

```APIDOC
## io.output ([file])

### Description
Similar to `io.input`, but operates over the default output file. When called with a file name, it opens the file in text mode and sets it as the default output file. When called with a file handle, it sets that handle as the default output file. When called without arguments, it returns the current default output file. Errors during file opening will raise an error.

### Parameters
* `file` (string or file handle, optional) - The file name to open or the file handle to set as default.

### Returns
* The current default output file handle if called without arguments.
* On success when setting a file, a success value is returned (implicitly, as errors raise exceptions).
* Raises an error on failure to open the file.
```

--------------------------------

### Getting the type of a value

Source: https://www.lua.org/manual/5.4/manual.html

Use type() to determine the type of a Lua value, returning a string representation like 'nil', 'number', 'string', etc.

```lua
type(v)
```

--------------------------------

### lua_createtable

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new, empty table and pushes it onto the Lua stack. Hints for the number of array and record elements can be provided for pre-allocation.

```APIDOC
## lua_createtable

### Description
Creates a new empty table and pushes it onto the stack. Parameter `narr` is a hint for how many elements the table will have as a sequence; parameter `nrec` is a hint for how many other elements the table will have. Lua may use these hints to preallocate memory for the new table.

### Method
`void`

### Signature
`void lua_createtable (lua_State *L, int narr, int nrec);`
```

--------------------------------

### Get Subtable in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Ensures a value at a given index is a table and pushes it. Returns true if a table existed, false if a new one was created.

```c
int luaL_getsubtable (lua_State *L, int idx, const char *fname);
```

--------------------------------

### Writing to a File

Source: https://www.lua.org/manual/5.4/manual.html

This snippet demonstrates writing strings or numbers to a file using `file:write()`. The function returns the file handle on success.

```lua
file:write(···)
```

--------------------------------

### Get Metatable Field in Lua

Source: https://www.lua.org/manual/5.4/manual.html

Pushes the specified field from an object's metatable onto the stack. Returns the type of the pushed value or LUA_TNIL.

```c
int luaL_getmetafield (lua_State *L, int obj, const char *e);
```

--------------------------------

### Getting Lua String Buffer Address

Source: https://www.lua.org/manual/5.4/manual.html

Returns the memory address of the current content of a luaL_Buffer. Any subsequent addition to the buffer may invalidate this address.

```c
char *luaL_buffaddr (luaL_Buffer *B);
```

--------------------------------

### Creating a Table with Vararg Arguments

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates creating a table directly from all the vararg arguments passed to a function. The varargs are treated as a list of expressions for the table constructor.

```lua
{...}
```

--------------------------------

### Get Current Hook Mask

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the current hook mask, which specifies which events trigger the hook function. This function does not alter the Lua state.

```c
int lua_gethookmask (lua_State *L);
```

--------------------------------

### Lua Syntactic Sugar for Function Definitions

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates syntactic sugar for defining regular and local functions in Lua.

```lua
stat ::= **function** funcname funcbody
stat ::= **local** **function** Name funcbody
funcname ::= Name {‘**.**’ Name} [‘**:**’ Name]

```

--------------------------------

### Lua Table Constructor Syntax

Source: https://www.lua.org/manual/5.4/manual.html

Defines the general syntax for creating tables and initializing fields in Lua.

```lua
tableconstructor ::= ‘**{**’ [fieldlist] ‘**}**’
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= ‘**[**’ exp ‘**]**’ ‘**=**’ exp | Name ‘**=**’ exp | exp
fieldsep ::= ‘**,**’ | ‘**;**’
```

--------------------------------

### Get name of Lua type

Source: https://www.lua.org/manual/5.4/manual.html

Returns the string name of a given Lua type code. The type code must be one returned by lua_type.

```c
const char *lua_typename (lua_State *L, int tp);
```

--------------------------------

### Iterating over table elements with ipairs

Source: https://www.lua.org/manual/5.4/manual.html

Use ipairs to iterate over a table's key-value pairs starting from index 1 up to the first absent index.

```lua
for i,v in ipairs(t) do _body_ end
```

--------------------------------

### Initializing Lua String Buffer with Preallocated Size

Source: https://www.lua.org/manual/5.4/manual.html

Initializes a luaL_Buffer and preallocates a space of a given size. This is an equivalent to calling luaL_buffinit followed by luaL_prepbuffsize.

```c
char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);
```

--------------------------------

### Getting UTF-8 Character Length

Source: https://www.lua.org/manual/5.4/manual.html

Calculates the number of UTF-8 characters within a byte range of a string. Returns fail and position on invalid byte sequences.

```lua
utf8.len(s, i, j, lax)
```

--------------------------------

### Create New Library Table

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new table with a size optimized to store entries from array `l`. It is intended for use with `luaL_setfuncs`. The array `l` must be the actual array, not a pointer.

```c
void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);
```

--------------------------------

### Getting UTF-8 Codepoints

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves the integer code points of UTF-8 characters within a specified byte range of a string. Errors on invalid byte sequences.

```lua
utf8.codepoint(s, i, j, lax)
```

--------------------------------

### Using lua_pcallk with a Continuation Function

Source: https://www.lua.org/manual/5.4/manual.html

This demonstrates the correct way to use lua_pcallk to allow Lua code to yield. The continuation function 'k' is passed as an argument, and its return value is used to continue the original function's execution.

```c
int original_function (lua_State *L) {
  ...     /* code 1 */
  return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
}
```

--------------------------------

### Getting a Unique Identifier for a Closure's Upvalue

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves a unique identifier for a specific upvalue of a closure. This can be used to determine if different closures share the same upvalue.

```c
void *lua_upvalueid (lua_State *L, int funcindex, int n);
```

--------------------------------

### luaL_dofile

Source: https://www.lua.org/manual/5.4/manual.html

Loads and executes a Lua file. It returns 0 for success (LUA_OK) and 1 for errors.

```APIDOC
## luaL_dofile

### Description
Loads and runs the given file. It is defined as the following macro: `(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))`. It returns 0 (`LUA_OK`) if there are no errors, or 1 in case of errors.

### Signature
```c
int luaL_dofile (lua_State *L, const char *filename);
```
```

--------------------------------

### Get Function Information with lua_getinfo

Source: https://www.lua.org/manual/5.4/manual.html

Use lua_getinfo with the '>S' option to retrieve source information, line numbers, and function type for a function pushed onto the stack.

```c
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
```

```c
     lua_Debug ar;
     lua_getglobal(L, "f");  /* get global 'f' */
     lua_getinfo(L, ">S", &ar);
     printf("%d\n", ar.linedefined);

```

--------------------------------

### luaL_newlib

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new table and registers functions from a provided list into it. It's implemented using `luaL_newlibtable` and `luaL_setfuncs`.

```APIDOC
## luaL_newlib

### Description
Creates a new table and registers there the functions in the list `l`. It is implemented as the following macro: `(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))`. The array `l` must be the actual array, not a pointer to it.

### Function Signature
```c
void luaL_newlib (lua_State *L, const luaL_Reg l[]);
```
```

--------------------------------

### Get type of Lua value

Source: https://www.lua.org/manual/5.4/manual.html

Returns the type of the Lua value at the given index. Returns LUA_TNONE for invalid indices. Types are defined by constants in lua.h.

```c
int lua_type (lua_State *L, int index);
```

--------------------------------

### Get length of value

Source: https://www.lua.org/manual/5.4/manual.html

Use `lua_len` to retrieve the length of the value at a given stack index, equivalent to the '#' operator in Lua. The result is pushed onto the stack.

```c
void lua_len (lua_State *L, int index);
```

--------------------------------

### Get Stack Top Index

Source: https://www.lua.org/manual/5.4/manual.html

Returns the index of the top element in the Lua stack using `lua_gettop`. This value is equal to the number of elements currently in the stack.

```c
int lua_gettop (lua_State *L);
```

--------------------------------

### Reading the Entire File

Source: https://www.lua.org/manual/5.4/manual.html

Illustrates reading the entire remaining content of a file from the current position using the 'a' format with `file:read()`. This format never fails.

```lua
file:read("a")
```

--------------------------------

### Create and Return Reference

Source: https://www.lua.org/manual/5.4/manual.html

Creates a unique integer reference to the object on top of the stack within the table at index 't', and pops the object. Returns LUA_REFNIL if the object is nil.

```c
int luaL_ref (lua_State *L, int t);
```

--------------------------------

### Method-like Function Definition Translation

Source: https://www.lua.org/manual/5.4/manual.html

Demonstrates the translation of a method-like function definition using dot notation.

```lua
function t.a.b.c.f () _body_ end

```

```lua
t.a.b.c.f = function () _body_ end

```

--------------------------------

### Create a new userdata with user values

Source: https://www.lua.org/manual/5.4/manual.html

Creates a new full userdata with specified memory size and associated user values. Returns the address of the memory block.

```c
void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);
```

--------------------------------

### Get Optional String Argument

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves a string argument from the Lua stack, providing a default value if the argument is absent or nil. Raises an error for invalid types.

```c
const char *luaL_optstring (lua_State *L,
                            int arg,
                            const char *d);
```

--------------------------------

### Flushing File Buffers

Source: https://www.lua.org/manual/5.4/manual.html

Shows how to ensure all written data is saved to the file using `file:flush()`.

```lua
file:flush()
```

--------------------------------

### Get Optional Number Argument

Source: https://www.lua.org/manual/5.4/manual.html

Retrieves a number argument from the Lua stack, providing a default value if the argument is absent or nil. Raises an error for invalid types.

```c
lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);
```

--------------------------------

### Prepare Buffer for String

Source: https://www.lua.org/manual/5.4/manual.html

Returns a pointer to a space of a specified size within a luaL_Buffer where a string can be copied. The size must be added to the buffer using luaL_addsize after copying.

```c
char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);
```

--------------------------------

### Get Optional Integer Argument

Source: https://www.lua.org/manual/5.4/manual.html

Returns the integer argument `arg` if it's an integer or convertible. Returns default `d` if `arg` is absent or nil. Raises an error otherwise.

```c
lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);
```

--------------------------------

### Lua Goto and Label Syntax

Source: https://www.lua.org/manual/5.4/manual.html

Specifies the syntax for the goto statement and labels in Lua, used for unconditional jumps within a block.

```lua
stat ::= "goto" Name
stat ::= label
label ::= "::" Name "::"
```

--------------------------------

### Get Global Variable

Source: https://www.lua.org/manual/5.4/manual.html

Pushes the value of a global variable onto the stack using `lua_getglobal`. Returns the type of the value. Ensure the global variable name is valid.

```c
int lua_getglobal (lua_State *L, const char *name);
```

--------------------------------

### lua_newuserdatauv

Source: https://www.lua.org/manual/5.4/manual.html

Creates and pushes a new full userdata onto the stack with a specified memory size and a number of associated Lua values (user values). Returns a pointer to the raw memory block.

```APIDOC
## `lua_newuserdatauv`

### Description
This function creates and pushes on the stack a new full userdata, with `nuvalue` associated Lua values, called `user values`, plus an associated block of raw memory with `size` bytes. (The user values can be set and read with the functions `lua_setiuservalue` and `lua_getiuservalue`.) The function returns the address of the block of memory. Lua ensures that this address is valid as long as the corresponding userdata is alive (see §2.5). Moreover, if the userdata is marked for finalization (see §2.5.3), its address is valid at least until the call to its finalizer.

### Function Signature
```c
void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);
```
```
Tokens:
Raw