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.