TITLE: Lua: Load and Unpack Script Arguments in CKB
DESCRIPTION: This Lua snippet demonstrates how to load and unpack script arguments within a CKB contract using the `ckb` library. It checks for errors and dumps the arguments if successful, showcasing basic interaction with CKB script context.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_0

LANGUAGE: lua
CODE:
```
local _code_hash, _hash_type, args, err = ckb.load_and_unpack_script()
print(err)
if err == nil then
	ckb.dump(args)
end
```

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

TITLE: Load and Unpack Current Script with ckb.load_and_unpack_script
DESCRIPTION: Loads and unpacks the current script, extracting its code hash, hash type, and arguments. It returns these unpacked values along with an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_20

LANGUAGE: APIDOC
CODE:
```
ckb.load_and_unpack_script():
  description: load and unpack current script
  arguments: none
  returns:
    code_hash: The code hash of current script
    hash_type: The hash type of current script
    args: The args of current script
    err: May be nil object to represent possible error
```

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

TITLE: Lua: ckb.load_witness Partial Loading Examples
DESCRIPTION: Demonstrates various ways to use `ckb.load_witness` with partial loading, including loading whole data, returning data length, loading initial bytes, returning length from offset, and loading specific length from offset. This function allows flexible data retrieval from CKB cells.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_12

LANGUAGE: Lua
CODE:
```
ckb.load_witness(0, ckb.SOURCE_INPUT)
```

LANGUAGE: Lua
CODE:
```
ckb.load_witness(0, ckb.SOURCE_INPUT, 0)
```

LANGUAGE: Lua
CODE:
```
ckb.load_witness(0, ckb.SOURCE_INPUT, 10)
```

LANGUAGE: Lua
CODE:
```
ckb.load_witness(0, ckb.SOURCE_INPUT, 0, 10)
```

LANGUAGE: Lua
CODE:
```
ckb.load_witness(0, ckb.SOURCE_INPUT, 2, 10)
```

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

TITLE: APIDOC: ckb.exit Function
DESCRIPTION: API documentation for `ckb.exit`, a function to terminate the ckb-vm execution with a specified exit code.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_14

LANGUAGE: APIDOC
CODE:
```
ckb.exit(
  code: exit code
)

Return values: none
Side effects: exit the ckb-vm execution
```

LANGUAGE: Lua
CODE:
```
ckb.exit(code)
```

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

TITLE: APIDOC: ckb.load_tx_hash Function
DESCRIPTION: API documentation for `ckb.load_tx_hash`, a function to load the transaction hash. It supports partial loading by optionally accepting length and offset arguments.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_17

LANGUAGE: APIDOC
CODE:
```
ckb.load_tx_hash(
  [length: optional length for partial loading],
  [offset: optional offset for partial loading]
)

Return values: buf (the buffer that contains the transaction hash), err (may be nil object to represent possible error)
```

LANGUAGE: Lua
CODE:
```
buf, err = ckb.load_tx_hash()
```

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

TITLE: APIDOC: ckb.load_script_hash Function
DESCRIPTION: API documentation for `ckb.load_script_hash`, a function to load the hash of the current script. It supports partial loading by optionally accepting length and offset arguments.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_18

LANGUAGE: APIDOC
CODE:
```
ckb.load_script_hash(
  [length: optional length for partial loading],
  [offset: optional offset for partial loading]
)

Return values: buf (the buffer that contains the script hash), err (may be nil object to represent possible error)
```

LANGUAGE: Lua
CODE:
```
buf, error = ckb.load_script_hash()
```

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

TITLE: Load Current Transaction with ckb.load_transaction
DESCRIPTION: Loads the current transaction into a buffer. This function supports partial loading. It returns the transaction buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_21

LANGUAGE: APIDOC
CODE:
```
ckb.load_transaction():
  description: load current transaction
  arguments: none
  partial loading supported: yes
  returns:
    buf: The buffer that contains current transaction
    err: May be nil object to represent possible error
```

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

TITLE: Load Witness with ckb.load_witness
DESCRIPTION: Loads the witness data based on its index, source, length, and offset. This function supports partial loading. It returns the witness buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_25

LANGUAGE: APIDOC
CODE:
```
ckb.load_witness(index: number, source: string, length: number, offset: number):
  description: load the witness
  arguments:
    index: The index of the cell
    source: The source of the cell
    length: The length of the data to load
    offset: The offset to start loading from
  partial loading supported: yes
  returns:
    buf: The buffer that contains the witness
    err: May be nil object to represent possible error
```

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

TITLE: Load Current Script with ckb.load_script
DESCRIPTION: Loads the current script into a buffer. This function supports partial loading. It returns the script buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_19

LANGUAGE: APIDOC
CODE:
```
ckb.load_script():
  description: load current script
  arguments: none
  partial loading supported: yes
  returns:
    buf: The buffer that contains script
    err: May be nil object to represent possible error
```

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

TITLE: APIDOC: ckb.dump Function
DESCRIPTION: API documentation for `ckb.dump`, a function used to print a buffer's content to stdout within the CKB-VM environment.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_13

LANGUAGE: APIDOC
CODE:
```
ckb.dump(
  buf: a buffer returned from syscalls
)

Return values: none
Side effects: the buf is printed
```

LANGUAGE: Lua
CODE:
```
ckb.dump(buf)
```

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

TITLE: Load Input Cell with ckb.load_input
DESCRIPTION: Loads an input cell's data based on its index and source. This function supports partial loading. It returns the input cell buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_23

LANGUAGE: APIDOC
CODE:
```
ckb.load_input(index: number, source: string):
  description: load input cell
  arguments:
    index: The index of the cell
    source: The source of the cell
  partial loading supported: yes
  returns:
    buf: The buffer that contains the input cell
    err: May be nil object to represent possible error
```

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

TITLE: Load Cell Header with ckb.load_header
DESCRIPTION: Loads a cell header based on its index and source. This function supports partial loading. It returns the header buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_24

LANGUAGE: APIDOC
CODE:
```
ckb.load_header(index: number, source: string):
  description: load cell header
  arguments:
    index: The index of the cell
    source: The source of the cell
  partial loading supported: yes
  returns:
    buf: The buffer that contains the header
    err: May be nil object to represent possible error
```

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

TITLE: Load Cell Data with ckb.load_cell_data
DESCRIPTION: Loads cell data based on its index, source, length, and offset. This function supports partial loading. It returns the cell data buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_26

LANGUAGE: APIDOC
CODE:
```
ckb.load_cell_data(index: number, source: string, length: number, offset: number):
  description: load cell data
  arguments:
    index: The index of the cell
    source: The source of the cell
    length: The length of the data to load
    offset: The offset to start loading from
  partial loading supported: yes
  returns:
    buf: The buffer that contains the cell data
    err: May be nil object to represent possible error
```

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

TITLE: Load Cell Data with ckb.load_cell
DESCRIPTION: Loads a cell's data based on its index and source. This function supports partial loading. It returns the cell buffer and an error object if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_22

LANGUAGE: APIDOC
CODE:
```
ckb.load_cell(index: number, source: string):
  description: load cell
  arguments:
    index: The index of the cell
    source: The source of the cell
  partial loading supported: yes
  returns:
    buf: The buffer that contains cell
    err: May be nil object to represent possible error
```

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

TITLE: Unpack CKB WitnessArgs Molecule Structure with ckb.unpack_witnessargs
DESCRIPTION: Unpacks a buffer containing the CKB `WitnessArgs` molecule structure into a Lua table. The returned table includes `lock`, `input_type`, and `output_type` fields. An error object is returned if unpacking fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_31

LANGUAGE: Lua
CODE:
```
ckb.unpack_witnessargs(buf)
```

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_witnessargs(buf: buffer)
  buf: The buffer that contains the molecule structure WitnessArgs
Returns:
  table: A table contains keys lock, input_type and output_type
  err: May be nil object to represent possible error
```

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

TITLE: API: ckb.unpack_celldep Function
DESCRIPTION: Unpacks a buffer containing the Molecule `CellDep` structure into a Lua table. This function is essential for parsing blockchain data structures within CKB Lua scripts. It returns a table containing `out_point` and `dep_type` keys, along with a potential error object.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_35

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_celldep(buf)

Arguments:
  buf: (buffer) The buffer that contains the molecule structure `CellDep`.

Return Values:
  table: (table) A table containing keys `out_point` and `dep_type`.
  err: (nil | object) May be a nil object to represent a possible error.

See also: The molecule definition of `CellDep` (https://github.com/nervosnetwork/ckb/blob/2e965706d15cf32b06ad96a2e45f2b09a5eddbb7/util/types/schemas/blockchain.mol#L52-L55)
```

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

TITLE: Unpack CKB Script Molecule Structure with ckb.unpack_script
DESCRIPTION: Unpacks a buffer containing the CKB `Script` molecule structure into a Lua table. The returned table includes `code_hash`, `hash_type`, and `args` fields. An error object is returned if unpacking fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_30

LANGUAGE: Lua
CODE:
```
ckb.unpack_script(buf)
```

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_script(buf: buffer)
  buf: The buffer that contains the molecule structure Script
Returns:
  table: A table contains keys code_hash, hash_type and args
  err: May be nil object to represent possible error
```

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

TITLE: Unpack CKB CellOutput Molecule Structure with ckb.unpack_celloutput
DESCRIPTION: Unpacks a buffer containing the CKB `CellOutput` molecule structure into a Lua table. The returned table includes `capacity`, `lock`, and `type` fields. An error object is returned if unpacking fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_34

LANGUAGE: Lua
CODE:
```
ckb.unpack_celloutput(buf)
```

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_celloutput(buf: buffer)
  buf: The buffer that contains the molecule structure CellOutput
Returns:
  table: A table contains keys capacity, lock and type
  err: May be nil object to represent possible error
```

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

TITLE: Unpack CKB CellInput Molecule Structure with ckb.unpack_cellinput
DESCRIPTION: Unpacks a buffer containing the CKB `CellInput` molecule structure into a Lua table. The returned table includes `since` and `previous_output` fields. An error object is returned if unpacking fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_33

LANGUAGE: Lua
CODE:
```
ckb.unpack_cellinput(buf)
```

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_cellinput(buf: buffer)
  buf: The buffer that contains the molecule structure CellInput
Returns:
  table: A table contains keys since and previous_output
  err: May be nil object to represent possible error
```

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

TITLE: Unpack CKB OutPoint Molecule Structure with ckb.unpack_outpoint
DESCRIPTION: Unpacks a buffer containing the CKB `OutPoint` molecule structure into a Lua table. The returned table includes `tx_hash` and `index` fields. An error object is returned if unpacking fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_32

LANGUAGE: Lua
CODE:
```
ckb.unpack_outpoint(buf)
```

LANGUAGE: APIDOC
CODE:
```
ckb.unpack_outpoint(buf: buffer)
  buf: The buffer that contains the molecule structure OutPoint
Returns:
  table: A table contains keys tx_hash and index
  err: May be nil object to represent possible error
```

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

TITLE: Lua: Load and Unpack CKB Script
DESCRIPTION: Illustrates a Lua code snippet that uses `ckb.load_and_unpack_script` to retrieve script details and arguments, and `ckb.dump` for inspecting binary data.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_10

LANGUAGE: Lua
CODE:
```
local _code_hash, _hash_type, args, err = ckb.load_and_unpack_script()
print(err)
if err == nil then
	ckb.dump(args)
end
```

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

TITLE: Load Header Field with ckb.load_header_by_field
DESCRIPTION: Loads a specific field from a CKB block header. This function supports partial loading and returns the requested header data in a buffer, along with an error object if the operation fails. It requires the header's index, source, and the specific field to load.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_29

LANGUAGE: Lua
CODE:
```
ckb.load_header_by_field(index, source, field)
```

LANGUAGE: APIDOC
CODE:
```
ckb.load_header_by_field(index: any, source: any, field: any)
  index: The index of the cell
  source: The source of the cell
  field: The field to load
Returns:
  buf: The buffer that contains the header field
  err: May be nil object to represent possible error
```

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

TITLE: Load Cell Data Field with ckb.load_cell_by_field
DESCRIPTION: Loads a specific data field from a CKB cell. This function supports partial loading and returns the requested data in a buffer, along with an error object if the operation fails. It requires the cell's index, source, and the specific field to load.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_27

LANGUAGE: Lua
CODE:
```
buf, error = ckb.load_cell_by_field(index, source, field)
```

LANGUAGE: APIDOC
CODE:
```
ckb.load_cell_by_field(index: any, source: any, field: any)
  index: The index of the cell
  source: The source of the cell
  field: The field to load
Returns:
  buf: The buffer that contains the cell data field
  err: May be nil object to represent possible error
```

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

TITLE: Load Input Field with ckb.load_input_by_field
DESCRIPTION: Loads a specific field from a CKB transaction input. This function supports partial loading and returns the requested input data in a buffer, along with an error object if the operation fails. It requires the input's index, source, and the specific field to load.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_28

LANGUAGE: Lua
CODE:
```
buf, error = ckb.load_input_by_field(index, source, field)
```

LANGUAGE: APIDOC
CODE:
```
ckb.load_input_by_field(index: any, source: any, field: any)
  index: The index of the cell
  source: The source of the cell
  field: The field to load
Returns:
  buf: The buffer that contains the input field
  err: May be nil object to represent possible error
```

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

TITLE: Concatenate Command Line Arguments and Return Result in Lua
DESCRIPTION: This Lua code snippet, designed to be executed as part of a ckb-lua subprocess, concatenates the second and third command-line arguments (`arg[2]` and `arg[3]`) and returns the combined string to the main script using `ckb.set_content`. This demonstrates how a subprocess can process inputs and return results.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/spawn.md#_snippet_0

LANGUAGE: Lua
CODE:
```
local m = arg[2] .. arg[3]; ckb.set_content(m)
```

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

TITLE: Mounting Simple Lua File System in ckb-lua
DESCRIPTION: Demonstrates how to mount a Simple Lua File System from a CKB cell using `ckb.mount`. The function takes a source and an index, returning nil on success or an integer error code on failure. Multiple file systems can be mounted, with later mounts overriding earlier ones for conflicting file names.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/fs.md#_snippet_0

LANGUAGE: Lua
CODE:
```
ckb.mount(ckb.SOURCE_OUTPUT, 0)
```

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

TITLE: APIDOC: ckb.mount Function
DESCRIPTION: API documentation for `ckb.mount`, a function that loads cell data and attempts to mount a file system contained within it. It returns an error if the operation fails.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_16

LANGUAGE: APIDOC
CODE:
```
ckb.mount(
  source: the source of the cell to load,
  index: the index of the cell to load within all cells with source `source`
)

Return values: err (may be nil object to represent possible error)
Side effects: the files within the file system will be available to use if no error happened
```

LANGUAGE: Lua
CODE:
```
ckb.mount(source, index)
```

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

TITLE: C: Dynamically Load Shared Library in CKB Script
DESCRIPTION: This C snippet shows how to use `ckb_dlopen2` from `ckb-c-stdlib` to dynamically load a shared library from a dependent cell in a CKB script. It takes `code_hash` and `hash_type` to locate the library and returns a handle for accessing its functions.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_1

LANGUAGE: c
CODE:
```
err = ckb_dlopen2(code_hash, hash_type, code_buff, code_buff_size, handle, &consumed_size);
```

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

TITLE: Running CKB Simulator Executables with JSON Configuration
DESCRIPTION: This bash script demonstrates how to execute the compiled CKB simulator binaries, such as `sighash_all` and `sudt`, by passing the root JSON configuration file (e.g., `data.json`) as the first argument. These examples show typical usage patterns for different simulator functionalities.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/include/ckb-c-stdlib/simulator/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
../build.simulator/sighash_all data.json
../build.simulator/sighash_all data2.json
../build.simulator/sighash_all data3.json
../build.simulator/sudt sudt_data.json
```

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

TITLE: Example Root JSON Configuration for CKB Simulator
DESCRIPTION: This JSON snippet demonstrates the structure of the `data.json` file required by the CKB simulator. It specifies whether the script to run is a lock or type script, its index in the input, the transaction hash of the dumped JSON, and the filename mapping for the dumped transaction data.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/include/ckb-c-stdlib/simulator/README.md#_snippet_0

LANGUAGE: json
CODE:
```
{
  "is_lock_script": true,
  "script_index": 0,
  "main": "0xa98c212cf055cedbbb665d475c0561b56c68ea735c8aa830c493264effaf18bd",
  "0xa98c212cf055cedbbb665d475c0561b56c68ea735c8aa830c493264effaf18bd": "original.json"
}
```

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

TITLE: ckb-lua Exported Constants
DESCRIPTION: A comprehensive list of constants exported by the ckb-lua library. These include constants directly from `ckb_consts.h` and ckb-lua specific constants like `ckb.LUA_ERROR_INTERNAL`. They define various status codes, data sources, and cell/input/header field identifiers for use in CKB Lua scripts.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_36

LANGUAGE: Lua
CODE:
```
ckb.SUCCESS
ckb.INDEX_OUT_OF_BOUND
ckb.ITEM_MISSING
ckb.LENGTH_NOT_ENOUGH
ckb.INVALID_DATA
ckb.LUA_ERROR_INTERNAL
ckb.LUA_ERROR_OUT_OF_MEMORY
ckb.LUA_ERROR_ENCODING
ckb.LUA_ERROR_SCRIPT_TOO_LONG
ckb.LUA_ERROR_INVALID_ARGUMENT

ckb.SOURCE_INPUT
ckb.SOURCE_OUTPUT
ckb.SOURCE_CELL_DEP
ckb.SOURCE_HEADER_DEP
ckb.SOURCE_GROUP_INPUT
ckb.SOURCE_GROUP_OUTPUT

ckb.CELL_FIELD_CAPACITY
ckb.CELL_FIELD_DATA_HASH
ckb.CELL_FIELD_LOCK
ckb.CELL_FIELD_LOCK_HASH
ckb.CELL_FIELD_TYPE
ckb.CELL_FIELD_TYPE_HASH
ckb.CELL_FIELD_OCCUPIED_CAPACITY

ckb.INPUT_FIELD_OUT_POINT
ckb.INPUT_FIELD_SINCE

ckb.HEADER_FIELD_EPOCH_NUMBER
ckb.HEADER_FIELD_EPOCH_START_BLOCK_NUMBER
ckb.HEADER_FIELD_EPOCH_LENGTH
```

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

TITLE: C: Initialize and Run CKB-Lua Instance
DESCRIPTION: Demonstrates a C code example for initializing a CKB-Lua instance, loading necessary functions, allocating memory, executing Lua code, and properly closing the instance.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_9

LANGUAGE: C
CODE:
```
    CreateLuaInstanceFuncType create_func =
        must_load_function(handle, "lua_create_instance");
    EvaluateLuaCodeFuncType evaluate_func =
        must_load_function(handle, "lua_run_code");
    CloseLuaInstanceFuncType close_func =
        must_load_function(handle, "lua_close_instance");

    const size_t mem_size = 1024 * 512;
    uint8_t mem[mem_size];

    void* l = create_func((uintptr_t)mem, (uintptr_t)(mem + mem_size));
    if (l == NULL) {
        printf("creating lua instance failed\n");
        return;
    }

    int ret = evaluate_func(l, code, code_size, "test");

    if (ret != 0) {
        printf("evaluating lua code failed: %d\n", ret);
        return;
    }
    close_func(l);
```

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

TITLE: API: lua_create_instance Function
DESCRIPTION: Explains the purpose of `lua_create_instance`, its memory allocation requirements, return value, and how it integrates with `lua_run_code` and `lua_close_instance`.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_3

LANGUAGE: APIDOC
CODE:
```
lua_create_instance(mem_lower_bound: uintptr_t, mem_upper_bound: uintptr_t) -> opaque_pointer
  mem_lower_bound: The lower bound of memory exclusively for Lua.
  mem_upper_bound: The upper bound of memory exclusively for Lua.
  Returns: An opaque pointer to the new Lua instance.
  Notes: Memory bounds are a contract enforced by the host program. Resources can be reclaimed with lua_close_instance.
```

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

TITLE: APIDOC: Exported C Functions for CKB Lua Shared Library
DESCRIPTION: Documentation for the C functions exported by the `libckblua.so` shared library, used for managing Lua instances and executing Lua code within CKB contracts. These functions allow creating, running, and closing Lua environments.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_2

LANGUAGE: APIDOC
CODE:
```
void *lua_create_instance(uintptr_t min, uintptr_t max)
int lua_run_code(void *l, const char *code, size_t code_size, char *name)
void close_lua_instance(void *L)
void lua_toggle_exit(void *L, int enabled)
```

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

TITLE: API: lua_run_code Function
DESCRIPTION: Details the `lua_run_code` function, including its arguments, acceptance of both source and binary code, and the various return values based on execution outcome or `ckb.exit_script` calls.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_4

LANGUAGE: APIDOC
CODE:
```
lua_run_code(l: opaque_pointer, code: pointer, code_size: size_t, name: string) -> int
  l: The opaque pointer returned from lua_create_instance.
  code: A pointer to the code buffer (Lua source or bytecode).
  code_size: The size of the code buffer.
  name: The name of the Lua program, helpful for debugging.
  Returns: The code passed to ckb.exit_script if called, 0 on successful execution without ckb.exit_script, or a negative number on interpreter error.
  Notes: Binary code is less resource-hungry. Lua script should pass non-negative numbers to ckb.exit_script.
```

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

TITLE: Creating a Simple Lua File System from files
DESCRIPTION: Instructions for packing Lua files into a Simple Lua File System using the `fs.lua` utility script. It shows two methods: piping file paths from `find` or directly listing files. Relative paths are required for input files.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/fs.md#_snippet_1

LANGUAGE: Shell
CODE:
```
find . -name '*lua' -type f | lua "./utils/fs.lua" pack "$packed_file"
```

LANGUAGE: Shell
CODE:
```
lua "./utils/fs.lua" pack "$packed_file" *.lua
```

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

TITLE: API: lua_close_instance Function
DESCRIPTION: Describes the `lua_close_instance` function, its purpose of releasing resources, and its single parameter.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
lua_close_instance(l: opaque_pointer) -> void
  l: The opaque pointer returned from lua_create_instance.
  Notes: Releases all resources used by the Lua instance.
```

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

TITLE: Unpacking Simple Lua File System to directory
DESCRIPTION: Explains how to unpack the contents of a Simple Lua File System file into a specified directory using the `fs.lua` utility script. The command requires the packed file path and the target directory.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/fs.md#_snippet_2

LANGUAGE: Shell
CODE:
```
lua "./utils/fs.lua" unpack "$packed_file" "$directory"
```

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

TITLE: APIDOC: ckb.exit_script Function
DESCRIPTION: API documentation for `ckb.exit_script`, which stops the current Lua script execution and returns control to the ckb-vm caller with a positive return code.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_15

LANGUAGE: APIDOC
CODE:
```
ckb.exit_script(
  code: this will be the return code of `lua_run_code`, should be positive
)

Return values: none
Side effects: stop lua script execution, return to the ckb-vm caller
```

LANGUAGE: Lua
CODE:
```
ckb.exit_script(code)
```

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

TITLE: API: lua_toggle_exit Function
DESCRIPTION: Explains `lua_toggle_exit`, its use in enabling or disabling `ckb.exit`, its default disabled state, and the impact of `ckb.exit` on VM execution.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_6

LANGUAGE: APIDOC
CODE:
```
lua_toggle_exit(l: opaque_pointer, enable: int) -> void
  l: The Lua instance opaque pointer.
  enable: 1 to enable ckb.exit, 0 to disable.
  Notes: Toggles whether ckb.exit is enabled. Default is disabled. ckb.exit(code) stops VM execution and returns code to ckb-vm.
```

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

TITLE: Run Hello World Example in ckb-lua Playground
DESCRIPTION: Executes the 'hello,world' test case located in the 'tests/test_cases' directory. This requires ckb-debugger to be installed as described in the CI scripts.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
make -C tests/test_cases hello_world
```

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

TITLE: CKB-Lua: Standard Library Functions
DESCRIPTION: Provides an overview of the Lua standard library functions ported to ckb-lua, highlighting the availability of platform-independent functions and the absence of platform-dependent ones.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_7

LANGUAGE: APIDOC
CODE:
```
Lua Standard Library Functions in CKB-Lua:
  - Most platform-independent functions are ported and expected to work.
  - Platform-dependent functions (e.g., all functions in the 'os' module) are NOT provided.
  - TODO: A list of unavailable functions will be added.
```

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

TITLE: CKB-Lua: CKB Specific Functions
DESCRIPTION: Describes the CKB-specific helper functions added to ckb-lua for interacting with ckb-vm, including their purpose and location within the `ckb` Lua module.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_8

LANGUAGE: APIDOC
CODE:
```
CKB Specific Functions in CKB-Lua:
  - Purpose: Added helper functions to interact with ckb-vm.
  - Functionality: Includes functions for issuing syscalls, debugging, and unpacking data structures.
  - Location: All functions are located in the 'ckb' Lua module.
  - Reference: See the appendix for a list of exported constants and functions.
```

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

TITLE: Simple Lua File System On-disk Data Structures
DESCRIPTION: Defines the C-like structures representing the on-disk format of the Simple Lua File System. It includes `Blob` for offset/length pairs, `Metadata` for file name and content blobs, and `SimpleFileSystem` for the overall structure including file count, metadata array, and payload.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/fs.md#_snippet_3

LANGUAGE: C
CODE:
```
struct Blob {
	uint32_t offset;
	uint32_t length;
}

struct Metadata {
	struct Blob file_name;
	struct Blob file_content;
}

struct SimpleFileSystem {
	uint32_t file_count;
	struct Metadata metadata[..];
	uint8_t payload[..];
}
```

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

TITLE: Binary Dump Example of Simple Lua File System
DESCRIPTION: A hexadecimal dump illustrating the on-disk representation of a Simple Lua File System containing a single file, `main.lua`, with content `print('hello world!')`. This shows the serialized form of the file count, metadata, and payload.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/fs.md#_snippet_4

LANGUAGE: Hexdump
CODE:
```
00000000: 0100 0000 0000 0000 0900 0000 0900 0000  ................
00000010: 1500 0000 6d61 696e 2e6c 7561 0070 7269  ....main.lua.pri
00000020: 6e74 2827 6865 6c6c 6f20 776f 726c 6421  nt('hello world!
00000030: 2729                                     ')
```

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

TITLE: Build ckb-lua Project
DESCRIPTION: This command compiles the ckb-lua project using Docker, ensuring all dependencies are met within a containerized environment.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
make all-via-docker
```

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

TITLE: API: CKB Module Exported Functions and Constants
DESCRIPTION: Introduces the appendix section which lists all functions and constants exported by the CKB module in ckb-lua.
SOURCE: https://github.com/contrun/ckb-lua/blob/master/docs/dylib.md#_snippet_11

LANGUAGE: APIDOC
CODE:
```
Appendix: Exported Lua Functions and Constants in the CKB Module:
  - This section lists functions and constants exported by the 'ckb' Lua module.
```