Lua APIs

Kenchiku provides a bunch of Lua globals to scaffolds to do anything useful.

Note

These are only defined when running the construct or run functions, otherwise fetching the metadata of Scaffolds could

1. allow code execution
2. annoy everyone with prompts

See LuaLS Setup for setting up the lua-Language-Server.

General

warn(message)

Creates a warning log like this:

<date>  WARN kenchiku_lua::log: Warning from scaffold: <message>

print(message)

Prints message to stdout.

fs Module

fs.exists(path)

Checks whether a file/path exists.

Example

fs.exists("example.txt")

fs.mkdir(path)

Creates all directories up to and including path.

Example

fs.mkdir("example/directory/here")

fs.copy(from, to)

Copies file from scaffold dir to workdir.

Example

fs.copy("a.txt", "b.txt")

fs.read(path, opts?)

Reads the content of a file at path. Use opts to specify whether the file should be read from the working directory or scaffold directory:

Example

fs.read("example.txt", { source = "workdir" })
fs.read("example.txt", { source = "scaffold" })

fs.write(path, content)

Writes a file to path containing content.

Example

fs.write("example.txt", "hello world!")

re Module

re.replace(content, pattern, replacement, opts)

Replace pattern with the replacement in content. Basically a regex replace, so pattern can contain capture groups and replacement can refer to them using $1 for example. Opts can specify a table with limit limiting the amount of replaces.

Example

re.replace("hello world", "w+", "konnichiwa", { limit = 1, })

re.match(content, pattern)

Regex match the pattern in content. Returns a table of capture groups (named and unnamed).

Example

re.match("hello world", "(hello) world")

tmpl Module

tmpl.template(template_string, vars)

Renders a MiniJinja template string with the given variables. See Template Extras for more filters & functions.

Example

tmpl.template("Hello {{ name }}!", { name = "World" })

tmpl.template_file(file_path, vars)

Reads a file from the scaffold directory and renders it as a template. See Template Extras for more filters & functions.

Example

tmpl.template_file("templates/main.rs.j2", { name = "my_project" })

values Module

values.get(name)

Retrieves the value for the given name. If the value wasn't provided via CLI flags, Kenchiku will interactively prompt the user based on the value definition in scaffold.lua.

Example

local name = values.get("project_name")

exec Module

exec.run(command)

Confirmation Level: 2

Run a command using sh -c. Returns a table with:

• stdout (string): Standard output
• stderr (string): Standard error
• exit_code (integer): Exit code of the command

Example

local result = exec.run("pwd")
print(result.stdout)

json Module

json.encode(data any)

Encodes data to a json string.

Example

json.encode({ hello = "world" })

json.decode(data string)

Decodes data json string to a lua value.

Example

json.decode('{"hello": "world"}')