6.2 Additional Lua Functions

This section documents the additional Lua functions made available to hook and user command writers.

alias_command(original, alias)

This function adds a new alias for a monotone command. original must be an existing montone command, alias is the new alias.

change_workspace(directory)

Change to workspace directory, which may be absolute or relative to the directory that was current when monotone was started.

Throws an error if directory does not exist or is not a workspace (does not contain _MTN).

After calling change_workspace, the next operation should read the workspace options. mtn_automate does this; other Lua functions do not.

existonpath(command)

Return 0 if command (a string) exists on $PATH and is executable, -1 otherwise.

For example, existonpath("xxdiff") returns 0 if the program xxdiff is available.

On Windows, this function automatically appends “.exe” to the program name if it is not present. In the previous example, existonpath would search for “xxdiff.exe”.

get_confdir()

Returns the path to the configuration directory; see --confdir.

get_ostype()

Returns the operating system flavor as a string.

guess_binary_file_contents(filespec)

Returns true if the file contains one or more of the following bytes:

0x00 thru 0x06
0x0E thru 0x1f
0x7f

guess_terminal_width()

Returns the size of the terminal window as number or a sane default (72) if the information cannot be retrieved.

include(scriptfile)

This function tries to load and execute the Lua script contained in scriptfile. It returns true for success and false if there is an error.

This is the same as Lua loadfile.

includedir(scriptpath)

This function loads and executes in alphabetical order all the scripts contained in the directory scriptpath.

If one of the scripts has an error, the function doesn’t process the remaining scripts.

There is no useful return value.

includedirpattern(scriptpath, pattern)

This function loads and executes in alphabetical order all the scripts contained into the directory scriptpath that match pattern (a glob pattern).

If one of the scripts has an error, the functions doesn’t process the remaining scripts.

There is no useful return value.

is_executable(file)

This function returns true if file is executable, false otherwise. On Windows this function always returns false.

kill(pid [, signal])

This function calls the kill() C library function on POSIX systems and TerminateProcess on Win32 (in that case pid is the process handle). If the optional signal parameter is missing, SIGTERM will be used.

Returns 0 on success, -1 on error.

make_executable(file)

This function marks file as executable. On Windows this has no effect.

globish.match(glob, string)

Returns true if glob matches str, return false otherwise.

mkstemp(template)

Returns a unique name for a writeable temporary file. Note that it does not create the file.

template should be a string that consists of contiguous, legal file and path name characters followed by six ’X’s.

mkstemp replaces the ’X’s by an alpha-numeric sequence that is unique in the directory given in template.

Subsequent calls to mkstemp within the same process each yield different file names.

Unlike other implementations, monotone mkstemp allows template to contain a complete path, not only a filename, allowing users to create temporary files outside the current directory.

Important notice:
To create a temporary file, you should use the temp_file function, unless you need to run monotone with the --no-builtin-rcfiles option. temp_file() builds on mkstemp() and creates a file in the standard TMP/TEMP directories. For the definition of temp_file(), see Default hooks.

mtn_automate(command args... )

mtn_automate calls the monotone automate command, with args... (may include options). The result of the call is a pair consisting of a boolean (true on success), and a string containing the stdout output from automate command.

This function is not for use in ordinary Lua hooks, but rather for Lua based commands as defined by the Lua function register_command.

Note that keyboard interaction is disabled, just as if --non-interactive is specified. Actions which require operations on password-encrypted private keys will therefor fail unless the get_passphrase hook is set up locally.

parse_basic_io(data)

Parse the string data, which should be in basic_io format. Returns nil if it can’t parse the string; otherwise returns a table, with each entry in the table corresponding to one basic_io line, consisting of a name element and a values element.

For example, given this as input:

thingy "foo" "bar"
thingy "baz"
spork
frob "oops"

The output table will be:

{
   1 = { name = "thingy", values = { 1 = "foo", 2 = "bar" } },
   2 = { name = "thingy", values = { 1 = "baz" } },
   3 = { name = "spork", values = { } },
   4 = { name = "frob", values = { 1 = "oops" } }
}

regex.search(regexp, string)

Returns true if a match for regexp is found in str, false otherwise. See Regexps, for the syntax of regexp.

register_command(name, params, abstract, description, function)

Add a command named name to the user command group in monotone. When the user issues the registered command, monotone will call the lua function name supplied. That function would then normally use mtn_automate calls to service the request. params is a string with the list of parameters for the command, abstract gives a brief description, description a longer description. params, abstract, description are output by mtn help.

server_request_sync(what, address, include, exclude)

Initiate a netsync connection to the server at address, with the given include and exclude branch patterns. what is one of sync, push, or pull, indicating netsync operation.

When called by a monotone instance which is not running the serve command, this function has no effect.

server_set_listening(boolean)

If the argument is false, make the server not listen for incoming connections, and exit when all existing connections have closed.

If the argument is true, cancel an earlier call with false given.

sleep(seconds)

Makes the calling process sleep for the specified number of seconds.

spawn(executable [, args ...])

Starts the named executable with the given arguments. Returns the process PID on POSIX systems, the process handle on Win32 or -1 if there was an error.

Calls fork/execvp on POSIX, CreateProcess on Win32.

Important notice:
To spawn a process and wait for its completion, use the execute() function, unless you need to run monotone with the --no-builtin-rcfiles option. execute() builds on spawn() and wait() in a standardized way.

spawn_pipe(executable [, args ...])

Like spawn(), but returns three values, where the first two are the subprocess’ standard input and standard output, and the last is the process PID on POSIX systems, the process handle on Win32 or -1 if there was an error.

spawn_redirected(infile, outfile, errfile, executable [, args ...])

Like spawn(), but with standard input, standard output and standard error redirected to the given files.

wait(pid)

Wait until the process with given PID (process handle on Win32) exits. Returns two values: a result value and the exit code of the waited-for process.

The exit code is meaningful only if the result value is 0.