Built-in Modules

Globals

The following global variables are available in any lua environment:

• WORKSPACE: table - Contains information about the workspace
  • dir: string - Absolute path to the workspace directory
• PLATFORM: table - Contains information about the platform Cobble is able to discover
  • arch: string - the platform architecture. One of std::env::consts::ARCH
  • os_family: string - the platform OS family. One of std::env::consts::FAMILY
  • os: string - the platform OS. One of std::env::consts::OS

Cobble Modules

cmd

The cmd module is a function that invokes a command, providing some additional functionality over Lua's os.execute function, as well as integration with Cobble actions.

Note that the cmd module is different from the built-in cmd tool. The cmd module will use the workspace directory as CWD by default, not any project directory.

cmd

function - Execute a command

cmd(args)

Arguments

• args: table
  • cwd: string | nil - Current working directory to run the command with
  • out: string | false | nil - Callback to be called with any stdout output. If false or nil are passed, no callback will be called with stdout output, but stdout will still be provided in the return value.
  • err: string | false | nil - Callback to be called with any stderr output. If false or nil are passed, no callback will be called with stderr output, but stderr will still be provided in the return value.
  • ... (sequence values): string - Any positional (numeric index) table elements are interpreted as the command and command args to execute

Returns

• table - Status and output of the launched process
  • status: int - The return status of the launched process
  • stdout: string - The stdout output of the process
  • stderr: string - The stderr output of the process

path

path.SEP

string - The path separator character for the current OS

path.glob

function - Get files matching a pattern in a directory tree

path.glob([base], pattern, [options])

Arguments

• base (optional): string - Base path to search from. Returned file paths are relative to the base path. (Default: CWD)
• pattern: string - Pattern to match files with. Can include * or ** wildcards.
• options (optionsal): table - Options to customize the glob behavior
• include: string | table | nil - Additional glob patterns to include in the search
• exclude: string | table | nil - Glob patterns to exclude from the search. If a file path matches both include/pattern and exclude patterns, exclude takes precedence.
• include_dirs: bool | nil - Whether to include directories in the result list. (Default: true)
• include_files: bool | nil - Whether to include files in the result list. (Default: true)

Returns

• table - A list of paths found that match the given pattern
  • ... (sequence values): string

path.join

function - Join path segments using the OS-specific path separator

path.join(...)

Arguments

• ...: string - path segments to join

Returns

• string - the joined path

path.is_dir

function - Test whether a path exists and is a directory

path.is_dir(path)

Arguments

• path: string - The path to test

Returns

• boolean - True if the path exists and is a directory. False otherwise.

path.is_file

function - Test whether a path exists and is a file

path.is_file(path)

Arguments

• path: string - The path to test

Returns

• boolean - True if the path exists and is a file. False otherwise.

iter

The iter module provides a convenient, functional interface for manipulating lists lazily and efficiently.

The iter constructor function and module-level functions are intended to be used with Lua's ipairs or pairs functions, or any set of values intended to used with Lua's generic for loop. For example:

local iter = require("iter")

local original_words = { "dais", "squirrel", "fort", "part" }
local new_words = iter(ipairs(original_words))
                    :filter(function(i, w) return w ~= "squirrel" end)
                    :map(function(i, w) return i, w.."y" end)
                    :to_table()
assert(
    new_words[1] == "daisy" and
    new_words[2] == "forty" and
    new_words[3] == "party"
)

iter

function - Wrap a set of iterator functions in an iter object.

iter(iter_fn, state, init_val, close)

Arguments

• iter_fn: function - Iterator function
• state: any - State to be passed to the iterator function at each iteration
• init_val: any - Initial value for the control variable
• close: to-be-closed - Variable that will be closed when the loop ends

Returns

• iter - An iter object

iter object

iter:map

function - Apply a map operation to the iterator

iter_obj:map(map_fn)

Arguments

• map_fn: function - A function that takes in the value(s) produced by an iteration of the iterator and returns new values.

Returns

iter - A new iter object that produces values that are the result of applying map_fn to the original iterator's values

iter:reduce

function - Apply a reduce operation to the iterator

iter_obj:reduce(init, reduce_fn)

Arguments

• init: any - Initial value to use as the accumulator
• reduce_fn: function - A function that takes the accumulator value as its first argument, followed by the value(s) produced by an iteration of the iterator, and returns a new accumulator value to be used with the next iteration.

Returns

any - The accumulator value returned by the reduce_fn call on the last iteration

iter:filter

function - Apply a filter operation to the iterator

iter_obj:filter(filter_fn)

Arguments

• filter_fn: function - A function that takes the value(s) produced by an iteration of the iterator, and returns a boolean value expressing whether or not the value(s) should be included in the resulting iterator.

Returns

iter - An iter object that produces all values produced by the original iterator for which filter_fn returns true

iter:enumerate

function - Append an iteration count to the beginning of each set of values produced by the iterator

iter_obj:enumerate()

Returns

iter - An iter object that produces the same values as the original iterator, but with a counter value appended to the beginning, starting at 1 for the first iteration

iter:for_each

function - Execute a function for each value or set of values produced by the iterator

iter_obj:for_each(fn)

Arguments

• fn: function - A function that takes in the value(s) produced by an iteration of the iterator

Returns

nil

iter:to_table

function - Iterate over the iterator and collect the values into a table. The iterator is expected to produce two values for each iteration: a key and a value. This is the structure of values produced by ipairs and pairs, which produce a key and value pair on each iteration.

Returns

table - The table into which the iterator values were collected

json

Module for (de)serializing json values. When converting between Lua and json types:

• JSON numbers are always converted to Lua floats, regardless of whether or not they contain integral values
• If a Lua table contains consecutive integer keys starting from 1, it is converted to a json array. Otherwise, it is converted to a json object.
• JSON objects are deserialized into an order-preserving Lua table, so deserialization followed by serialization of a JSON object is stable.

json.load

function - Read and parse json from a file

json.load(path)

Arguments

• path: string - Path to the json file to read

Returns

• any - The json data converted to a Lua value

json.loads

function - Parse a json string

json.load(s)

Arguments

• s: string - The json string to parse

Returns

any - The json data converted to a Lua value

json.dump

function - Convert a Lua value to json and write it to a file

json.dump(path, val)

Arguments

• path: string - Path to the file where the json data should be written
• val: any - The Lua value to serialize to json

Returns

nil

json.dumps

function - Convert a Lua value to a json string

json.dumps(val)

Arguments

• val: any - The Lua value to serialize to json

Returns

string - The serialized json value

toml

Module for (de)serializing toml values. When converting between Lua and toml types:

• TOML datetime values are converted to a Lua userdata, which can be converted to a string or serialized back to a toml datetime value.
• If a Lua table contains consecutive integer keys starting at 1, it is converted into a toml array. Otherwise, it is converted to a toml table.
• TOML tables are deserialized into an order-preserving Lua table, so deserialization followed by serialization of a TOML document is stable, however any comments in a deserialized TOML document are not preserved.

toml.load

function - Read and parse toml from a file

toml.load(path)

Arguments

• path: string - Path to the toml file to read

Returns

any - The toml data converted to a Lua value

toml.loads

function - Parse a toml string

toml.load(s)

Arguments

• s: string - The toml string to parse

Returns

any - The toml data converted to a Lua value

toml.dump

function - Convert a Lua value to toml and write it to a file

toml.dump(path, val)

Arguments

• path: string - Path to the file where the toml data should be written
• val: any - The Lua value to serialize to toml

Returns

nil

toml.dumps

function - Convert a Lua value to a toml string

toml.dumps(val)

Arguments

• val: any - The Lua value to serialize to toml

Returns

string - The serialized toml value

maybe

Object type for elegantly handling values that might be nil. The maybe object implements nearly all metamethods, (it does not implement __newindex,) allowing for use with most operators.

Maybe objects are particularly useful for accessing values in nested data structures without having to check for nil at every level.

Example usage:

(maybe(nil) + 5).value -- nil
(maybe(5) + 5).value -- 10
(maybe({chapter_1={section_1="this is section 1"}})["chapter_1"]["section_1"]).value -- "this is section 1"
(maybe({chapter_1={section_1="this is section 1"}})["chapter_2"]["section_7"]).value -- nil
(maybe(nil)["chapter_1"]).value -- nil
(maybe("hello world"):and_then(function(v) return v:gsub("world", "universe") end)).value -- "hello universe"
(maybe(nil):and_then(function(v) return v:gsub("world", "universe") end)).value -- nil
(maybe(nil)
  :or_else(function () return "hello world" end)
  :and_then(function (v) return v:gsub("world", "universe") end)
).value -- "hello universe"

maybe

function - Create a maybe object

maybe(val)

Arguments

• val: any - The value to wrap in a maybe object

Returns

• maybe - A maybe object

maybe object

maybe.value

any - The wrapped value held by the maybe object

maybe:and_then

function - Perform an operation on the wrapped value if the wrapped value is non-nil

maybe_obj:and_then(fn)

Arguments

• fn: function - A function that will be called with the wrapped value if it is a non-nil value

Returns

• maybe - If the current wrapped value is nil, then maybe(nil) is returned, otherwise maybe(fn(self.value)) is returned

maybe:or_else

function - Call a function to provide a value if the wrapped value is nil

maybe_obj:or_else(fn)

Arguments

• fn: function - A function that takes no arguments, and returns a value to be used if the current wrapped value is nil

Returns

maybe - If the current wrapped value is nil, then maybe(fn()) is returned, otherwise self is returned

scope

Provides functionality for executing some logic when a scope is exited

scope.on_exit

function - Execute some logic on scope exit

scope.on_exit(fn)

Arguments

• fn: function - The function to exit when the returned object goes out of scope

Returns

• any - A to-be-closed variable that will execute fn when it goes out of scope

Example

local scope = require("scope")

function ()
  local scoped = scope.on_exit(function() print("function complete") end)
  -- do some stuff
end -- prints "function complete" upon exiting the function

script_dir

script_dir

function - returns the directory that contains the lua script file currently being run

script_dir()

Returns

string - Path of the directory containing the lua script file currently being executed

version

Provides logic for comparing version numbers. A version object, created with the version constructor function, supports comparison operators <, >, ==, ~= to compare with other version objects or string representations of versions.

Version comparison should work for most dot-delimited version numbers.

version

function - Create a version object

version(version_str)

Arguments

version_str: string - A string representation of a version number

Returns

version - A version object

tblext

Provides additional table manipulation functionality on top of Lua's table module. Unlike the tablemodule, tblext is intended for use with tables both used as sequences or maps.

tblext.extend

function - Merge entries from one table into another

If a key exists in both source and target, the value from source overwrites the value in target. Integer keys behave differently from other keys. Integer keys are offset by start_index-1 and then merged. The default value for start_index is #target+1, meaning sequence values in source will be appended to the existing sequence values in target. If you'd like sequence values in source to be merged into target just like any other key type, pass in 1 for start_index.

tblext.extend(target, source, [start_index])

Arguments

• target: table - The table into which entries will be merged
• source: table - The source table for entries to be merged from
• start_index (optional): int - The index at which to start appending values with integer keys.

Returns

table - This function returns the table that was passed in as target

tblext.format

function - Create a string representation of a table value that includes all of the key/value pairs in the table. Table keys and values will also be formatted with tblext.format

tblext.format(value)

Arguments

• value: table - The table value to format

Returns

string - A string representation of the table