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. ```