# The Lua Runtime

Lulu provides a set of global functions and modules available to all your `.lua` scripts when they are run or bundled with Lulu. This "standard library" makes it easy to perform common tasks without needing external dependencies.

## Process Management

- **`argv`**: A global table (array) containing the command-line arguments passed to your script.
- **`exit(code)`**: Exits the program with the given status code (e.g., `exit(0)` for success, `exit(1)` for failure).
- **`exec(command, inherit_stdio)`**: Executes a shell command.
  - `command` (string): The command to run.
  - `inherit_stdio` (boolean): If `true`, the command will share the parent's stdin/stdout/stderr.
  - Returns the output of the command as a string.

## Filesystem (FS)

- **`reads(path)`**: Reads the entire content of a file into a string.
- **`read(path)`**: Reads the entire content of a file into a [ByteArray](./helper-classes.md#bytearray).
- **`exists(path)`**: Returns `true` if a file or directory exists at the path.
- **`mkdir(...)`**: Recursively creates a directory.
- **`cp(source, destination)`**: Copies a single file.
- **`mv(source, destination)`**: Moves a file.
- **`rm(path)`**: Removes a file or directory.

## Regular Expressions (`re`)

A global module for regular expressions.

- **`re.exec(pattern, text)`**: Returns `true` if the pattern matches the text, `false` otherwise.
- **`re.match(pattern, text)`**: Returns a table of capture groups from the first match.
- **`re.replace(pattern, text, replacement)`**: Replaces matches in the text. The `replacement` can be a string (e.g., `"$0 $1"`) or a function that receives capture groups as arguments.

## Serialization (`serde`)

A global module for handling JSON and YAML.

- **`serde.json.encode(table)`**: Converts a Lua table to a JSON string.
- **`serde.json.decode(string)`**: Converts a JSON string to a Lua table.
- **`serde.yaml.encode(table)`**: Converts a Lua table to a YAML string.
- **`serde.yaml.decode(string)`**: Converts a YAML string to a Lua table.

## Cryptography & Utilities

- **`crypto.sha256(string)`**: Computes the SHA-256 hash of a string.
- **`uuid.v4()`**: Generates a version 4 UUID.
- **`rand.from(min, max)`**: Returns a random integer between `min` and `max` (inclusive).
- **`range(start, finish)`**: Returns a table containing a sequence of numbers from `start` to `finish`.
- **`fprint(table)`**: A formatted print function for tables, useful for debugging.

## Archives (`zip`, `tar`)

- **`zip.create(output_path, files_table)`**: Creates a `.zip` archive.
- **`zip.extract(archive_path, destination_path)`**: Extracts a `.zip` archive.
- **`tar.create(output_path, files_table)`**: Creates a `.tar.gz` archive.
- **`tar.extract(archive_path, destination_path)`**: Extracts a `.tar.gz` archive.

## Networking (`net`)

- **`net.http.request(url, method, body, headers)`**: Performs an HTTP request.

## Module Environment

Within each module, Lulu also provides a few special variables:

- **`mod`**: A table containing information about the current module, including `mod.name` and `mod.conf`.
- **`current_path`**: The path of the currently executing script.
- **`lookup_dylib(name)`**: Finds a dynamic library in the project's `.lib` directory or the system path.
