/usr/share/doc/monotone/html/Additional-Lua-Functions.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>monotone documentation: Additional Lua Functions</title>

<meta name="description" content="monotone documentation: Additional Lua Functions">
<meta name="keywords" content="monotone documentation: Additional Lua Functions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="General-Index.html#General-Index" rel="index" title="General Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Lua-Reference.html#Lua-Reference" rel="up" title="Lua Reference">
<link href="Implementation-Differences.html#Implementation-Differences" rel="next" title="Implementation Differences">
<link href="Validation-Hooks.html#Validation-Hooks" rel="prev" title="Validation Hooks">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="texinfo.css">


</head>

<body lang="en">
<a name="Additional-Lua-Functions"></a>
<div class="header">
<p>
Next: <a href="Implementation-Differences.html#Implementation-Differences" accesskey="n" rel="next">Implementation Differences</a>, Previous: <a href="Hooks.html#Hooks" accesskey="p" rel="prev">Hooks</a>, Up: <a href="Lua-Reference.html#Lua-Reference" accesskey="u" rel="up">Lua Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Additional-Lua-Functions-1"></a>
<h3 class="section">6.2 Additional Lua Functions</h3>

<p>This section documents the additional Lua functions made available to
hook and user command writers.
</p>
<dl compact="compact">
<dt><code>alias_command(<var>original</var>, <var>alias</var>)</code>
<a name="index-alias_005fcommand_0028original_002c-alias_0029"></a>
</dt>
<dd>
<p>This function adds a new alias for a monotone command.  <var>original</var>
must be an existing montone command, <var>alias</var> is the new alias.
</p>
</dd>
<dt><code>change_workspace(<var>directory</var>)</code>
<a name="index-change_005fworkspace_0028directory_0029"></a>
</dt>
<dd>
<p>Change to workspace <var>directory</var>, which may be absolute or
relative to the directory that was current when monotone was started.
</p>
<p>Throws an error if <var>directory</var> does not exist or is not a
workspace (does not contain <samp>_MTN</samp>).
</p>
<p>After calling <code>change_workspace</code>, the next operation should read
the workspace options. <code><a href="#mtn_005fautomate">mtn_automate</a></code> does this; other Lua
functions do not.
</p>
</dd>
<dt><code>existonpath(<var>command</var>)</code>
<a name="index-existonpath_0028command_0029"></a>
</dt>
<dd>
<p>Return 0 if <var>command</var> (a string) exists on <code>$PATH</code> and is
executable, -1 otherwise.
</p>
<p>For example, <code>existonpath(&quot;xxdiff&quot;)</code> returns 0 if the
program xxdiff is available.
</p>
<p>On Windows, this function automatically appends &ldquo;.exe&rdquo; to the
program name if it is not present. In the previous example,
<code>existonpath</code> would search for &ldquo;xxdiff.exe&rdquo;.
</p>
</dd>
<dt><code>get_confdir()</code>
<a name="index-get_005fconfdir_0028_0029"></a>
</dt>
<dd>
<p>Returns the path to the configuration directory; see <samp><a href="Global-Options.html#g_t_002d_002dconfdir">--confdir</a></samp>.
</p>
</dd>
<dt><code>get_ostype()</code>
<a name="index-get_005fostype_0028_0029"></a>
</dt>
<dd>
<p>Returns the operating system flavor as a string.
</p>
</dd>
<dt><code>guess_binary_file_contents(<var>filespec</var>)</code>
<a name="index-guess_005fbinary_005ffile_005fcontents_0028filespec_0029"></a>
</dt>
<dd>
<p>Returns true if the file contains one or more of the following
bytes:
</p><div class="smallexample">
<pre class="smallexample">0x00 thru 0x06
0x0E thru 0x1f
0x7f
</pre></div>

</dd>
<dt><code>guess_terminal_width()</code>
<a name="index-guess_005fterminal_005fwidth_0028_0029"></a>
</dt>
<dd>
<p>Returns the size of the terminal window as number or a sane default
(72) if the information cannot be retrieved.
</p>
</dd>
<dt><code>include(<var>scriptfile</var>)</code>
<a name="index-include_0028scriptfile_0029"></a>
</dt>
<dd>
<p>This function tries to load and execute the Lua script contained in
<var>scriptfile</var>.  It returns true for success and false if there is an
error.
</p>
<p>This is the same as Lua <code>loadfile</code>.
</p>
</dd>
<dt><code>includedir(<var>scriptpath</var>)</code>
<a name="index-includedir_0028scriptpath_0029"></a>
</dt>
<dd>
<p>This function loads and executes in alphabetical order all the scripts
contained in the directory <var>scriptpath</var>.
</p>
<p>If one of the scripts has an error, the function doesn&rsquo;t process the
remaining scripts.
</p>
<p>There is no useful return value.
</p>
</dd>
<dt><code>includedirpattern(<var>scriptpath</var>, <var>pattern</var>)</code>
<a name="index-includedirpattern_0028scriptpath_002c-pattern_0029"></a>
</dt>
<dd>
<p>This function loads and executes in alphabetical order all the scripts
contained into the directory <var>scriptpath</var> that match <var>pattern</var>
(a glob pattern).
</p>
<p>If one of the scripts has an error, the functions doesn&rsquo;t process the
remaining scripts.
</p>
<p>There is no useful return value.
</p>
</dd>
<dt><code>is_executable(<var>file</var>)</code>
<a name="index-is_005fexecutable_0028file_0029"></a>
</dt>
<dd>
<p>This function returns true if <var>file</var> is executable, false
otherwise.  On Windows this function always returns false.
</p>
</dd>
<dt><code>kill(<var>pid</var> [, <var>signal</var>])</code>
<a name="index-kill_0028pid-_005b_002c-signal_005d_0029"></a>
</dt>
<dd>
<p>This function calls the kill() C library function on POSIX systems and
TerminateProcess on Win32 (in that case <var>pid</var> is the process
handle).  If the optional <var>signal</var> parameter is missing, SIGTERM
will be used.
</p>
<p>Returns 0 on success, -1 on error.
</p>
</dd>
<dt><code>make_executable(<var>file</var>)</code>
<a name="index-make_005fexecutable_0028file_0029"></a>
</dt>
<dd>
<p>This function marks <var>file</var> as executable.  On Windows this has no
effect.
</p>
</dd>
<dt><code>globish.match(<var>glob</var>, <var>string</var>)</code>
<a name="index-globish_002ematch_0028glob_002c-string_0029"></a>
</dt>
<dd>
<p>Returns <code>true</code> if <var>glob</var> matches <var>str</var>, return <code>false</code> otherwise.
</p>
</dd>
<dt><code>mkstemp(<var>template</var>)</code>
<a name="index-mkstemp_0028template_0029"></a>
</dt>
<dd>
<p>Returns a unique name for a writeable temporary file. Note that it
does not create the file.
</p>
<p><var>template</var> should be a string that consists of contiguous, legal file
and path name characters followed by six &rsquo;X&rsquo;s.
</p>
<p><code>mkstemp</code> replaces the &rsquo;X&rsquo;s by an alpha-numeric sequence
that is unique in the directory given in <var>template</var>.
</p>
<p>Subsequent calls to <code>mkstemp</code> within the same process
each yield different file names.
</p>
<p>Unlike other implementations, monotone mkstemp allows <var>template</var>
to contain a complete path, not only a filename, allowing users to
create temporary files outside the current directory.
</p>
<p><strong>Important notice:</strong><br>
To create a temporary file, you should use the <code>temp_file</code>
function, unless you need to run monotone with the <samp>--no-builtin-rcfiles</samp>
option.  <code>temp_file()</code> builds on <code>mkstemp()</code> and creates a
file in the standard TMP/TEMP directories.
For the definition of <code>temp_file()</code>, see <a href="Default-hooks.html#Default-hooks">Default hooks</a>.
</p>
<a name="mtn_005fautomate"></a></dd>
<dt><code>mtn_automate(<var>command</var> <var>args...</var> )</code>
<a name="index-mtn_005fautomate_0028command-args_002e_002e_002e-_0029"></a>
</dt>
<dd>
<p><code>mtn_automate</code> calls the monotone <code>automate</code>
<var>command</var>, with <var>args...</var> (may include options). The result of
the call is a pair consisting of a boolean (<code>true</code> on success),
and a string containing the <code>stdout</code> output from
<code>automate <var>command</var></code>.
</p>
<p>This function is not for use in ordinary Lua hooks, but rather for Lua
based commands as defined by the Lua function <a href="#register_005fcommand">register_command</a>.
</p>
<p>Note that keyboard interaction is disabled, just as if <samp>--non-interactive</samp>
is specified. Actions which require operations on password-encrypted private
keys will therefor fail unless the <code><a href="User-Defaults.html#get_005fpassphrase">get_passphrase</a></code> hook is set up locally.
</p>
<a name="parse_005fbasic_005fio"></a></dd>
<dt><code>parse_basic_io(<var>data</var>)</code>
<a name="index-parse_005fbasic_005fio_0028data_0029"></a>
</dt>
<dd>
<p>Parse the string <var>data</var>, which should be in <code>basic_io</code>
format. Returns nil if it can&rsquo;t parse the string; otherwise
returns a table, with each entry in the table corresponding to one
<code>basic_io</code> line, consisting of a <code>name</code> element and a
<code>values</code> element.
</p>
<p>For example, given this as input:
</p>
<div class="smallexample">
<pre class="smallexample">thingy &quot;foo&quot; &quot;bar&quot;
thingy &quot;baz&quot;
spork
frob &quot;oops&quot;
</pre></div>

<p>The output table will be:
</p><div class="smallexample">
<pre class="smallexample">{
   1 = { name = &quot;thingy&quot;, values = { 1 = &quot;foo&quot;, 2 = &quot;bar&quot; } },
   2 = { name = &quot;thingy&quot;, values = { 1 = &quot;baz&quot; } },
   3 = { name = &quot;spork&quot;, values = { } },
   4 = { name = &quot;frob&quot;, values = { 1 = &quot;oops&quot; } }
}
</pre></div>

</dd>
<dt><code>regex.search(<var>regexp</var>, <var>string</var>)</code>
<a name="index-regex_002esearch_0028regexp_002c-string_0029"></a>
</dt>
<dd>
<p>Returns <code>true</code> if a match for <var>regexp</var> is found in <var>str</var>,
<code>false</code> otherwise.  See <a href="Regexps.html#Regexps">Regexps</a>, for the syntax of
<var>regexp</var>.
</p>
<a name="register_005fcommand"></a></dd>
<dt><code>register_command(<var>name</var>, <var>params</var>, <var>abstract</var>, <var>description</var>, <var>function</var>)</code>
<a name="index-register_005fcommand_0028name_002c-params_002c-abstract_002c-description_002c-function_0029"></a>
</dt>
<dd>
<p>Add a command named <var>name</var> to the user command group in monotone.
When the user issues the registered command, monotone will call the
lua <var>function</var> name supplied.  That function would then normally
use <code><a href="#mtn_005fautomate">mtn_automate</a></code> calls to service the
request. <var>params</var> is a string with the list of parameters for the
command, <var>abstract</var> gives a brief description, <var>description</var> a
longer description. <var>params</var>, <var>abstract</var>, <var>description</var>
are output by <code>mtn help</code>.
</p>
</dd>
<dt><code>server_request_sync(<var>what</var>, <var>address</var>, <var>include</var>, <var>exclude</var>)</code>
<a name="index-server_005frequest_005fsync_0028what_002c-address_002c-include_002c-exclude_0029"></a>
</dt>
<dd>
<p>Initiate a netsync connection to the server at <var>address</var>, with the
given <var>include</var> and <var>exclude</var> branch patterns. <var>what</var> is
one of <samp>sync</samp>, <samp>push</samp>, or <samp>pull</samp>, indicating
netsync operation.
</p>
<p>When called by a monotone instance which is not running the <samp>serve</samp>
command, this function has no effect.
</p>
</dd>
<dt><code>server_set_listening(<var>boolean</var>)</code>
<a name="index-server_005fset_005flistening_0028boolean_0029"></a>
</dt>
<dd>
<p>If the argument is <var>false</var>, make the server not listen for incoming
connections, and exit when all existing connections have closed.
</p>
<p>If the argument is <var>true</var>, cancel an earlier call with <var>false</var> given.
</p>
</dd>
<dt><code>sleep(<var>seconds</var>)</code>
<a name="index-sleep_0028seconds_0029"></a>
</dt>
<dd>
<p>Makes the calling process sleep for the specified number of seconds.
</p>
</dd>
<dt><code>spawn(<var>executable</var> [, <var>args ...</var>])</code>
<a name="index-spawn_0028executable-_005b_002c-args-_002e_002e_002e_005d_0029"></a>
</dt>
<dd>
<p>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.
</p>
<p>Calls fork/execvp on POSIX, CreateProcess on Win32.
</p>
<p><strong>Important notice:</strong><br>
To spawn a process and wait for its completion, use the <code>execute()</code>
function, unless you need to run monotone with the <samp>--no-builtin-rcfiles</samp>
option.  <code>execute()</code> builds on <code>spawn()</code> and <code>wait()</code>
in a standardized way.
</p>
</dd>
<dt><code>spawn_pipe(<var>executable</var> [, <var>args ...</var>])</code>
<a name="index-spawn_005fpipe_0028executable-_005b_002c-args-_002e_002e_002e_005d_0029"></a>
</dt>
<dd>
<p>Like spawn(), but returns three values, where the first two are the
subprocess&rsquo; 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.
</p>
</dd>
<dt><code>spawn_redirected(<var>infile</var>, <var>outfile</var>, <var>errfile</var>, <var>executable</var> [, <var>args ...</var>])</code>
<a name="index-spawn_005fredirected_0028infile_002c-outfile_002c-errfile_002c-executable-_005b_002c-args-_002e_002e_002e_005d_0029"></a>
</dt>
<dd>
<p>Like spawn(), but with standard input, standard output and standard
error redirected to the given files.
</p>
</dd>
<dt><code>wait(<var>pid</var>)</code>
<a name="index-wait_0028pid_0029"></a>
</dt>
<dd>
<p>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.
</p>
<p>The exit code is meaningful only if the result value is 0.
</p>
</dd>
</dl>


<hr>
<div class="header">
<p>
Next: <a href="Implementation-Differences.html#Implementation-Differences" accesskey="n" rel="next">Implementation Differences</a>, Previous: <a href="Hooks.html#Hooks" accesskey="p" rel="prev">Hooks</a>, Up: <a href="Lua-Reference.html#Lua-Reference" accesskey="u" rel="up">Lua Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
monotone-doc 1.1-9 / usr / share / doc / monotone / html / Additional-Lua-Functions.html
