Previous: Hooks, Up: Hook Reference


6.2 Additional Lua Functions

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

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”.
guess_binary(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.
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.

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.

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.
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", args = { 1 = "foo", 2 = "bar" } },
             2 = { name = "thingy", args = { 1 = "baz" } },
             3 = { name = "spork", args = { } },
             4 = { name = "frob", args = { 1 = "oops" } }
          }