API references

The brocatel module

The brocatel module, containing the core brocatel.VM implementation.

brocatel.load_vm(content, save, extra_env)

Creates a VM from a string chunk compiled by the Brocatel compiler.

The save argument is equivalent to load_vm and then calling VM.load.

Parameters:

  • content (str) – the compile brocatel chunk

  • save (str or nil) – the savedata content, from brocatel.VM.save

  • extra_env (table or nil) – extra Lua environment globals (only extern, print and require permitted)

Returns:

vm

Return type:

brocatel.VM

The VM class

class brocatel.VM

The brocatel runtime VM.

Basic usage:

code: Code

the compiled brocatel scripts

env: StackedEnv

the environment handle

savedata: SaveData

save data

flags: Flags

inner api for data storage, cleaned on each next call

gettext: Gettext

GNU Gettext config

config: Config

the VM config

call_with_env(env, func)

Calls a function with the supplied environment pushed into the stacked env.

It simply executes push(env); result = func(…); pop() and returns the result. However, the actual environment of the function is not changed, which means it should already bind to vm.env.env to make the environment change effective.

Parameters:

  • env (table or nil) –

  • func (function) –

eval_with_env(env, ip, env_keys)

Evaluates a node at the supplied pointer with the environment pushed.

It yields values just like next, unless any if-else statement yields false, when it will return nil instead.

Parameters:

  • env (table or nil) –

  • ip (TablePath) –

  • env_keys (table or nil) –

set_gettext(gettext, ngettext)

GNU gettext interface supplied by the user to offload translation to GNU gettext.

Configures the gettext functionality.

Although GNU Gettext requires msgid-plural for ngettext, you don’t always write your plots in languages with a plural form (nor have we a way to write this in Markdown in a neat way). If you are wrapping gettext library calls and using PO fields generated by our lgettext, you can just pass an empty string as msgid-plural. See also gettext(3) and ngettext(3).

Parameters:

  • gettext (fun(str):str) – see gettext(3)

  • ngettext (fun(str, number):str) – see ngettext(3)

set_config(config)

Runtime VM config.

Configures the VM.

The supplied config will be merged with the default config.

Parameters:

config (Config) – the config

push_stack_frame(params, ip, extra_keys)

Performs a function call by pushing a new stack frame (with return address and params)

and jumping to the supplied ip.

Parameters:

  • params (table) – the parameters

  • ip (TablePath) – the return address

  • extra_keys (list[str]) – names of function local variables

pop_stack_frame()

Pops a stack frame and jumps to the return address.

Returns:

success false if no function call in stack

Return type:

boolean

next(input)

Yields the next line.

Parameters:

input (number or nil) – the input when the previous line is a list of options

Returns:

line the next line or nil if the story has ended

Return type:

Output or nil

current()

Returns the current line.

Returns:

the current line or nil if the story has ended

Return type:

Output or nil

interpolate(text, values, translate, plural)

Interpolates the text with the supplied values.

Parameters:

  • text (str) –

  • values (dict[str, function]) –

  • translate (boolean) –

  • plural (str or nil) –

translate(msgid, count)

Translates a message if a gettext backend is configured.

Parameters:

  • msgid (str) – the message

  • count (number or nil) – the plural

lookup_label(keys)

Looks up a label relative to the current IP.

Parameters:

keys (table) – relative label path

Return type:

TablePath or nil

Return type:

Element or nil

ip_debug_info(ip)

Returns the debug information of the current IP or the supplied pointer.

Parameters:

ip (TablePath or nil) – the pointer (defaults to the current IP)

Returns:

info the current node info

Return type:

InvalidNode

The function is mainly called by the compiler to detect invalid links. The users need not to check link validity themselves.

Returns:

incorrect incorrect link nodes

Return type:

list[InvalidNode]

save()

Returns a string that can be loaded to restore the VM state.

Internally, the returned string is just a serialized Lua table, without any obfuscation.

Returns:

state the VM state serialized to a string

Return type:

str

load(state)

Loads a string generated by save() to restore to a certain VM.

Parameters:

state (str) – the VM state serialized to a string

The Output type

class Output
tags: dict[str, str] or boolean or nil

tags

text: str or nil

the translated and interpolated text

visited: boolean

whether the text or the select has been visited

select: list[Selectable] or nil

the selectable options

class Selectable
key: number

a number referring to the option, to be passed to VM.next to select to option

option: Text

the displayed text

class Text
tags: dict[str, str] or boolean or nil

tags

text: str or nil

the translated and interpolated text

visited: boolean

whether the text has been visited

The TablePath class

alias TablePathSeg: string|number
class TablePath

Simplified JSONPath for Lua tables.

It recognizes basic elements (only arrays for now) in the brocatel runtime format, to allow easier navigation through the tree structure.

static from(t)

Creates a path from an array.

The table is copied into the new path. Listeners are not copied.

Parameters:

t (list[TablePathSeg] or TablePath) – the path

Return type:

TablePath

copy()

Returns a copy of the current pointer.

Return type:

TablePath

set_listener(listener)

Sets the path change listener.

When the path is changed, it calls the listener, passing the new path and the new path.

Parameters:

listener (function or nil) –

set(t)

Sets the path in place.

Parameters:

t (table or TablePath) – the new path

Returns:

self

Return type:

TablePath

equals(path)

Returns true if the two paths equal.

Parameters:

path (table or TablePath) – the other path

Returns:

eq

Return type:

boolean

get(t, parents)

Fetches the element of the table at the current path.

Sets the parents parameter to 1 to fetch the parent node instead, or to 2 to fetch a grandparent node, etc.

Parameters:

  • t (table) –

  • parents (number or nil) – the levels to go up

Returns:

node

Return type:

Element or nil

resolve(...)

Points the path to a new path relative to the current one.

Use nil as a parameter to “go up”. Examples:

TablePath.new():resolve(“a”, b”, 1) points the path to {“a”, “b”, 1}. TablePath.from({1, 1, 1}):resolve(nil, nil, 2) points the path to {1, 2}.

Parameters:

vararg (table or str or number or nil) – the relative path

Returns:

self the new current path, not a new one

Return type:

TablePath

is_array(t, parents)

Returns true if the pointer is pointing to an brocatel array.

Parameters:

  • t (table) –

  • parents (number or nil) –

Returns:

is_array

Return type:

boolean

Returns:

node

Return type:

Element or nil

is_parent_to(path)
Parameters:

path (TablePath) –

Return type:

boolean

step(t, init)

Points the path to the next element.

The iteration follows the brocatel runtime format specification. It repeats the following until it finds a valid “next element”.

## Procedure

(1). If the parent node of the current element is not an array node, go to that parent node and start over.

(2). If it is an array node:

(2.1). If the current element is the last child node, go to that parent node and start over from (1).

(2.2). If the current element is not the last child node, go to the next sibling and

(2.2.1). If we are now at an non-array node, then it is a valid “next element”. Returns.

(2.2.2). If we are now at an array node and

(2.2.2.1). If its first element (excluding the metadata element) is nil, start over from (1).

(2.2.2.2). If its first element is an array, go there and start over from (2.2.2).

(2.2.2.3). If its first element is an non-array node, go there and we are done. Returns.

## Details

It tells whether a Lua table node is an array, by looking at its first element. An array expects a metadata element (a Lua table), while others never.

## Usage

The function steps the pointer to the next valid element. For a root node like {{}, “A”, “B”}, a pointer {2} points to “A”. And stepping the pointer makes it point to “B”.

However, you cannot step any pointer to point to the first valid element, which is not “the next element” to any. In order to initialize a pointer by letting it point to the first valid element, call step with its init parameter set to true on an empty pointer.

It may be clearer to state it this way: init = false: looks up the next valid element, current element excluded, while init = true: looks up the next valid element, current element included.

Parameters:

  • t (table) –

  • init (boolean or nil) – see the above usage tips

Returns:

success false if the tree is exhausted and no valid next element can be found

Return type:

boolean

Returns:

gone_up true if the process exhausted at least one array and started looking at its siblings

Return type:

boolean

is_done()

Returns true if the pointer cannot get further incremented (pointing to the root).

Returns:

done

Return type:

boolean