Previous: Hooks, Up: Hook Reference


6.2 Additional Lua Functions

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

alias_command(original, alias)
This function adds a new alias for a monotone command. A call to this function would normally be placed directly in the monotonerc file, rather than in a hook function.
existonpath(possible_command)
This function receives a string containing the name of an external program and returns 0 if it exists on path and is executable, -1 otherwise. As an example, existonpath("xxdiff") returns 0 if the program xxdiff is available. On Windows, this function automatically appends “.exe” to the program name. In the previous example, existonpath would search for “xxdiff.exe”.
get_confdir()
Returns the path to the configuration directory, either implied or given with --confdir.
get_ostype()
Returns the operating system flavor as a string.
guess_binary_file_contents(filespec)
Returns true if the file appears to be binary, i.e. contains one or more of the following characters:
     0x00 thru 0x06
     0x0E thru 0x1a
     0x1c thru 0x1f

include(scriptfile)
This function tries to load and execute the script contained into scriptfile. It returns true for success and false if there is an error.
includedir(scriptpath)
This function loads and executes in alphabetical order all the scripts contained into the directory scriptpath. If one of the scripts has an error, the functions doesn't process the remaining scripts and immediately returns false.
includedirpattern(scriptpath, pattern)
This function loads and executes in alphabetical order all the scripts contained into the directory scriptpath that match the given pattern. If one of the scripts has an error, the functions doesn't process the remaining scripts and immediately returns false.
is_executable(filespec)
This function returns true if the file is executable, false otherwise. On Windows this function returns always 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(filespec)
This function marks the named file as executable. On Windows has no effect.
match(glob, string)
Returns true if glob matches str, return false otherwise.
mkstemp(template)
Like its C library counterpart, mkstemp creates a unique name and returns a file descriptor for the newly created file. The value of template should be a pointer to a character buffer loaded with a null-terminated string that consists of contiguous, legal file ad path name characters followed by six Xs. The function mkstemp replaces the Xs by an alpha-numeric sequence that is chosen to ensure that no file in the chosen directory has that name. Furthermore, subsequent calls to mkstemp within the same process each yield different file names. Unlike other implementations, monotone mkstemp allows the template string 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 must use the temp_file() function, unless you need to run monotone with the --nostd 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( ... )
The mtn_automate Lua function calls the Monotone automate command passed in its arguments. The result of the call is a pair consisting of a boolean return code, indicating whether the call was successful or not, and a string being the stdout output from the 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. It returns nil if it can't parse the string; otherwise it returns a table. This will be a list of all statements, with each entry being a table having a "name" element that is the symbol beginning the statement and a "values" element that is a list of all the arguments.

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, return 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. This function is normally called directly from a monotonerc file rather than a hook. 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.
server_request_sync(what, address, include, exclude)
Initiate a netsync connection to the server at address, with the given include and exclude patterns, of type sync, push, or pull, as given by the what argument.

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