File: zoem.html

package info (click to toggle)
zoem 07-333-3
links: PTS
area: main
in suites: lenny
size: 2,700 kB
ctags: 2,050
sloc: ansic: 17,942; sh: 790; makefile: 228
file content (690 lines) | stat: -rw-r--r-- 43,133 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<!-- Copyright (c) 2007 Stijn van Dongen -->
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
body {
text-align: justify;
color: #001111;
background: white;
margin-left: 8%;
margin-right: 8%;
font-family: Helvetica, Univers, Verdana, sans-serif;
}
p.default {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
p.L53 { font-size: 30pt; }
p.L52 { font-size: 20pt; }
p.L51 { font-size: 15pt; }
p.L50 { font-size: 12pt; }
p.L49 { font-size: 10pt; }
p.L48 { font-size: 9pt; }
p.L47 { font-size: 8pt; }
td {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
h3 { margin-top:1em; }
h2 { margin-top:2em; }
.left { text-align: left; align: left; }
.right { text-align: right; align: right; }
.center { text-align: center; align: center; }
.nowrap { white-space: nowrap; }
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.copy
{ font-size: 12pt;
font-family: monospace;
text-align: left;
white-space: pre;
margin-left: 2em;
margin-top: 1em;
margin-bottom: 1em;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
</style>
<title>zoem</title>
</head>
<body>
<p style="text-align:right">
29 Nov 2007&nbsp;&nbsp;&nbsp;
<a class="local" href="zoem.ps"><b>zoem</b></a>
1.002, 07-333
</p>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=48 valign="top" class="left nowrap">1.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#name">NAME</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">2.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#synopsis">SYNOPSIS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">3.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#description">DESCRIPTION</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">4.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#options">OPTIONS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">5.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#session">SESSION MACROS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">6.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#inspect">THE INSPECT SUBLANGUAGE</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">7.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#tr">THE TR SUBLANGUAGE</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">8.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#tildexp">TILDE EXPANSION</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">9.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#environment">ENVIRONMENT</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">10.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#diagnostics">DIAGNOSTICS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">11.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#bugs">BUGS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">12.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#seealso">SEE ALSO</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">13.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#examples">EXAMPLES</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">14.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#author">AUTHOR</a>
</div></td></tr>
</table>

</div>

<a name="name"></a>
<h2>NAME</h2>
<p class="default L50" style="margin-bottom:0">
zoem - macro processor for the Zoem macro/programming language.</p>

<a name="synopsis"></a>
<h2>SYNOPSIS</h2>
<p class="default L50" style="margin-bottom:0">
<b>zoem</b>
<a class="intern" href="#opt-i"><b>[-i</b> &lt;file name&gt;[.azm] (<i>entry file name</i>)<b>]</b></a>
<a class="intern" href="#opt-I"><b>[-I</b> &lt;file name&gt; (<i>entry file name</i>)<b>]</b></a>
<a class="intern" href="#opt-o"><b>[-o</b> &lt;file name&gt; (<i>output file name</i>)<b>]</b></a>
<a class="intern" href="#opt-d"><b>[-d</b> &lt;device&gt; (<i>set device key</i>)<b>]</b></a></p>
<p class="default L50" style="margin-bottom:0">
<b>zoem</b><br>
(enter interactive mode - happens when none of <b>-i</b>,
<b>-I</b>, <b>-o</b> is given)</p>
<p class="default L50" style="margin-bottom:0">
<b>zoem</b>
<a class="intern" href="#opt-i"><b>-i</b> &lt;file name&gt;[.azm] (<i>entry file name</i>)</a>
<a class="intern" href="#opt-I"><b>-I</b> &lt;file name&gt; (<i>entry file name</i>)</a>
<a class="intern" href="#opt-o"><b>[-o</b> &lt;file name&gt; (<i>output file name</i>)<b>]</b></a>
<a class="intern" href="#opt-d"><b>[-d</b> &lt;device&gt; (<i>set device key</i>)<b>]</b></a>
<a class="intern" href="#opt-x"><b>[-x</b> (<i>enter interactive mode on error</i>)<b>]</b></a>
<a class="intern" href="#opt-s"><b>[-s</b> &lt;key&gt;[=&lt;val&gt;] (<i>set key to val</i>)<b>]</b></a>
<a class="intern" href="#opt-e"><b>[-e</b> &lt;any&gt; (<i>evaluate any, exit</i>)<b>]</b></a>
<a class="intern" href="#opt-E"><b>[-E</b> &lt;any&gt; (<i>evaluate any, proceed</i>)<b>]</b></a>
<a class="intern" href="#opt-chunk-size"><b>[-chunk-size</b> &lt;num&gt; (<i>process chunks of size num</i>)<b>]</b></a>
<a class="intern" href="#opt--trace"><b>[--trace</b> (<i>trace mode, default</i>)<b>]</b></a>
<a class="intern" href="#opt--trace-all-long"><b>[--trace-all-long</b> (<i>long trace mode</i>)<b>]</b></a>
<a class="intern" href="#opt--trace-all-short"><b>[--trace-all-short</b> (<i>short trace mode</i>)<b>]</b></a>
<a class="intern" href="#opt--trace-regex"><b>[--trace-regex</b> (<i>trace regexes</i>)<b>]</b></a>
<a class="intern" href="#opt--show-tracebits"><b>[--show-tracebits</b> (<i>show trace bits</i>)<b>]</b></a>
<a class="intern" href="#opt-trace"><b>[-trace</b> k (<i>trace mode, explicit</i>)<b>]</b></a>
<a class="intern" href="#opt--stats"><b>[--stats</b> (<i>show symbol table stats after run</i>)<b>]</b></a>
<a class="intern" href="#opt--split"><b>[--split</b> (<i>assume \writeto usage, set \__split__</i>)<b>]</b></a>
<a class="intern" href="#opt--stress-write"><b>[--stress-write</b> (<i>make \write#3 recover</i>)<b>]</b></a>
<a class="intern" href="#opt--unsafe"><b>[--unsafe</b> (<i>prompt for \system#3</i>)<b>]</b></a>
<a class="intern" href="#opt--unsafe-silent"><b>[--unsafe-silent</b> (<i>simply allow \system#3</i>)<b>]</b></a>
<a class="intern" href="#opt-allow"><b>[-allow</b> cmd1[:cmdx]+ (<i>allowable commands</i>)<b>]</b></a>
<a class="intern" href="#opt--system-honor"><b>[--system-honor</b> (<i>require \system#3 to succeed</i>)<b>]</b></a>
<a class="intern" href="#opt-nuser"><b>[-nuser</b> k (<i>user dict stack size</i>)<b>]</b></a>
<a class="intern" href="#opt-ndollar"><b>[-ndollar</b> k (<i>dollar dict stack size</i>)<b>]</b></a>
<a class="intern" href="#opt-nsegment"><b>[-nsegment</b> k (<i>maximum simple nesting depth</i>)<b>]</b></a>
<a class="intern" href="#opt-nstack"><b>[-nstack</b> k (<i>maximum eval nesting depth</i>)<b>]</b></a>
<a class="intern" href="#opt-buser"><b>[-buser</b> (<i>initial user dict capacity</i>)<b>]</b></a>
<a class="intern" href="#opt-bzoem"><b>[-bzoem</b> (<i>initial zoem dict capacity</i>)<b>]</b></a>
<a class="intern" href="#opt-tl"><b>[-tl</b> k (<i>tab length</i>)<b>]</b></a>
<a class="intern" href="#opt-l"><b>[-l</b> &lt;str&gt; (<i>list items</i>)<b>]</b></a>
<a class="intern" href="#opt-h"><b>[-h</b> (<i>show options</i>)<b>]</b></a>
<a class="intern" href="#opt--apropos"><b>[--apropos</b> (<i>show options</i>)<b>]</b></a></p>

<a name="description"></a>
<h2>DESCRIPTION</h2>
<p class="default L50" style="margin-bottom:0">
Zoem is a macro/programming language. It is fully described in the
<a class="local" href="zum.html">Zoem User Manual</a> , currently available
in HTML only. This manual page documents the zoem processor, not the
zoem language.</p>
<p class="default L50" style="margin-bottom:0">
If the input file is specified using the <a class="intern" href="#opt-i"><b>-i</b> option</a> and
is a regular file (i.e. not STDIN - which is specified by using a single
hyphen), it must have the extension <tt>.azm</tt>. This extension can but need
not be specified. The zoem key <b>\__fnbase__</b> will be set to the file base
name stripped of the <tt>.azm</tt> extension and any leading path components.
If the input file is specified
using the <a class="intern" href="#opt-I"><b>-I</b> option</a>, no extension is assumed, and
<b>\__fnbase__</b> is set to the file base name, period. The file base name is
the file name with any leading path components stripped away.</p>
<p class="default L50" style="margin-bottom:0">
If neither <b>-i</b> nor <b>-o</b> is specified, zoem enters interactive
mode. Zoem should fully recover from any error it encounters in the input.
If you find an exception to this rule, consider filing a bug report. In
interactive mode, zoem start interpreting once it encounters a line
containing a single dot. Zoem's input behaviour can be modified by setting
the key <b>\__parmode__</b>. See the section <a class="intern" href="#session">SESSION MACROS</a> for the details.
In interactive mode, zoem does <i>not</i> preprocess the interactive
input, implying that it does not accept inline files and it does not
recognize comments. Both types of sequence will generate syntax errors.</p>
<p class="default L50" style="margin-bottom:0">
From within the entry file and included files it is possible to open and
write to arbitrary files using the <b>\write#3</b> primitive. Arbitrary files
can be read in various modes using the <b>\dofile#2</b> macro (providing four
different modes with respect to file existence and output), <b>\finsert#1</b>,
and <b>\zinsert#1</b>.
Zoem will write the default output to a single file, the name of which is
either specified by the <b>-o</b> option, or constructed as described
below. Zoem can split the default output among multiple files. This is
governed from within the input files by issuing <b>\writeto#1</b> calls. Refer
to the <a class="intern" href="#opt--split"><b>--split</b> option</a> and the
<a class="local" href="zum.html">Zoem User Manual</a>.</p>
<p class="default L50" style="margin-bottom:0">
If none of <b>-i</b> or <b>-o</b> is given, then zoem will enter
interactive mode. In this mode, zoem interprets by default chunks of
text that are ended by a single dot on a line of its own. This can be
useful for testing or debugging. In interactive mode, zoem should recover
from any failure it encounters. Interactive mode can also be accessed from
within a file by issuing <tt>\zinsert{stdia}</tt>, and it can be triggered as
the mode to enter should an error occur (by adding the
<a class="intern" href="#opt-x"><b>-x</b> option</a> to the command line).</p>
<p class="default L50" style="margin-bottom:0">
If <b>-o</b> is given and <b>-i</b> is not,
zoem reads input from STDIN.</p>
<p class="default L50" style="margin-bottom:0">
If <b>-i</b> is given and <b>-o</b> is not, zoem will construct an
output file name as follows. If the <b>-d</b> option was used with
argument <tt>&lt;dev&gt;</tt>, zoem will write to the file which results from
expanding <b>\__fnbase__.&lt;dev&gt;</b>. Otherwise, zoem writes to (the expansion
of) <b>\__fnbase__.ozm</b>.</p>
<p class="default L50" style="margin-bottom:0">
For <b>-i</b> and <b>-o</b>, the argument <tt>-</tt>
is interpreted as respectively <tt>stdin</tt> and <tt>stdout</tt>.</p>

<a name="options"></a>
<h2>OPTIONS</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td colspan=3><a name="opt-i"></a><b>-i</b> &lt;file name&gt;[.azm] (<i>entry file name</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Specify the entry file name. The file must have the <tt>.azm</tt>
extension, but it need not be specified.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-I"></a><b>-I</b> &lt;file name&gt;[.azm] (<i>entry file name</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Specify the entry file name, without restrictions on the file name.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-o"></a><b>-o</b> &lt;file name&gt; (<i>output file name</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Specify the output file name.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-d"></a><b>-d</b> &lt;device&gt; (<i>set key \__device__</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set the key <b>\__device__</b> to <tt>&lt;device&gt;</tt>.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-x"></a><b>-x</b> (<i>enter interactive mode on error</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The afterlife option. If zoem encounters an error during
regular processing, it will emit error messages as usual,
and then enter interactive mode. This allows you e.g.
to inspect the values of keys used or defined within
the problematic area.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-s"></a><b>-s</b> &lt;key&gt;[=&lt;val&gt;] (<i>set key to val</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set the key <b>\key</b> to <b>val</b> if present, <b>1</b> otherwise.
Any type of key can be set, including keys taking arguments and keys
surrounded in quotes. Beware of the shell's quote and backslash
interpolation.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-e"></a><b>-e</b> &lt;any&gt; (<i>evaluate any, exit</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This causes zoem to evaluate <tt>&lt;any&gt;</tt>,
write any result text to stdout, and exit.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-E"></a><b>-E</b> &lt;any&gt; (<i>evaluate any, proceed</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This causes zoem to evaluate <tt>&lt;any&gt;</tt>,
write any result text to stdout, and proceed e.g. with
the entry file or an interactive session.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-chunk-size"></a><b>-chunk-size</b> &lt;num&gt; (<i>process chunks of size num</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Zoem reads its input in chunks. It fully processes a chunk before moving on
with the next one. This option defines the
(minimum) size of the chunks. The size or count of the
chunks does not at all affect zoem's output. The default minimum
chunk size equals one megabyte.</p>
<p class="default L50" style="margin-bottom:0">
Zoem will read files in their entirety before further processsing
if <b>-chunk-size</b>&nbsp;<b>0</b> is specified.</p>
<p class="default L50" style="margin-bottom:0">
Zoem does not chunk input files arbitrarily. It will append to
a chunk until it is in the outermost scope (not contained within
any block) and the chunk will end with a line that was fully read.</p>
<p class="default L50" style="margin-bottom:0">
Consequently, if e.g. a file contains a block (delimited by
balanced curlies) spanning the entire file then zoem is forced
to read it in its entirety.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--trace"></a><b>--trace</b> (<i>trace mode, default</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Trace in default mode.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--trace-all-long"></a><b>--trace-all-long</b> (<i>long trace mode</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Sets on <i>most</i> trace options in long mode.
Trace options <tt>xxx</tt> not set
have their own <b>--trace-xxx</b> entry (see below).</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--trace-all-short"></a><b>--trace-all-short</b> (<i>short trace mode</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Sets on <i>most</i> trace options in short mode.
Trace options <tt>xxx</tt> not set
have their own <b>--trace-xxx</b> entry (see below).</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--trace-keys"></a><b>--trace-keys</b> (<i>trace keys</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Trace keys.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--trace-regex"></a><b>--trace-regex</b> (<i>trace regexes</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Trace regexes (i.e. the <b>\inspect#4</b> primitive).</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-trace"></a><b>-trace</b> k (<i>trace mode, explicit</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set trace options by adding their representing bits.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--stress-write"></a><b>--stress-write</b> (<i>stress test using write</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This makes <b>\write#3</b> recover from errors.
It is a special purpose option used for creating zoem
stress test suites, such as <tt>stress.azm</tt>
in the zoem distribution <tt>/examples</tt> subdirectory.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3 class=left><a name="opt--unsafe"></a><b>--unsafe</b> (<i>prompt for \system#3</i>)</td></tr><tr><td colspan=3 class=left><a name="opt--unsafe-silent"></a><b>--unsafe-silent</b> (<i>simply allow \system#3</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-allow"></a><b>-allow</b> cmd1[:cmdx]+ (<i>allowable commands</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
With <b>--unsafe</b> system calls are allowed but the user
is prompted for each invocation. The command and its arguments (if any)
are shown, but the STDIN information (if any) is withheld.
With <b>--unsafe-silent</b> system calls are allowed and
the user is never prompted.</p>
<p class="default L50" style="margin-bottom:0">Use <b>-allow</b>&nbsp;<i>str</i> or <b>--allow</b>=<i>str</i> to
specify a list of allowable commands, as a string
in which the commands are separated by colons.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--system-honor"></a><b>--system-honor</b> (<i>require \system#3 to succeed</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
With this option any <tt>\system#3</tt> failure (for whatever reason,
including safe behaviour) is regarded as a zoem failure.
By default, failing system calls are ignored under either
safe mode, unsafe mode (--unsafe), or silent unsafe mode
(--unsafe-silent).</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--split"></a><b>--split</b> (<i>assume split output</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This assumes zoem input that allows output to multiple files (e.g.
chapters). It sets the default output stream to <tt>stdout</tt> (anticipating
custom output redirection with <b>\writeto#1</b>) and sets the session macro
<b>\__split__</b> to <tt>1</tt>.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt--stats"></a><b>--stats</b> (<i>show symbol table stats after run</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Show symbol table chacteristics. Symbol tables are
maintained as hashes.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-tl"></a><b>-tl</b> k (<i>set tab length</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set the tab length. HTML output can be indented according
to nesting structure, using tabs which are expanded
to simple spaces. By default, the tab length is zero,
meaning that no indent is shown.
The maximum value the tab length can be set to is four.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3 class=left><a name="opt-nsegment"></a><b>-nsegment</b> k (<i>level of macro nesting allowed</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-nstack"></a><b>-nstack</b> k (<i>stack count</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-nuser"></a><b>-nuser</b> k (<i>user dictionary stack size</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-ndollar"></a><b>-ndollar</b> k (<i>dollar dictionary stack size</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-buser"></a><b>-buser</b> k (<i>initial user dict capacity</i>)</td></tr><tr><td colspan=3 class=left><a name="opt-bzoem"></a><b>-bzoem</b> k (<i>initial zoem dict capacity</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Probably needed only if you have some obscure and extreme use
for zoem. The segment limit applies to simple nesting of macros. The
stack limit applies to nesting of macros that evaluate an argument before
use. Each such evaluation creates a new stack. The user limit applies to
<b>\push{user}</b>, the dollar limit applies to <b>\push{dollar}</b>. The user
dict capacity pertains to the initial number of buckets allocated for
user and dollar dictionaries, and the zoem dict capacity pertains to the
dictionary containing the zoem primitives.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-l"></a><b>-l</b> &lt;str&gt; (<i>list items</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
List items identified by <tt>&lt;str&gt;</tt>. It can be any of
<b>all</b>,
<b>filter</b>.
<b>legend</b>,
<b>macro</b>,
<b>session</b>,
<b>trace</b>, or
<b>zoem</b>,
Multiple identifiers
can be joined in a string, e.g. <tt>-l legendzoem</tt> prints a legend
followed by a listing of zoem primitives.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-h"></a><b>-h</b> (<i>show options</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Show short synopsis of options.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><a name="opt-h"></a><b>-h</b> (<i>show options</i>)</td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Show one-line synopsis of all options.</p>
</div></td></tr>
</table>

</div>

<a name="session"></a>
<h2>SESSION MACROS</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td colspan=3><b>\__parmode__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
This macro affects zoem's read behaviour in interactive mode.
It can be set on the command line using the <b>-s</b> option.
Bits that can be set:
<pre>1    chomp newlines (remove the newline character)
2    skip empty newlines
4    read paragraphs (an empty line triggers input read)
8    newlines can be escaped using a backslash
16   read large paragraphs (a single dot on a line
     triggers input read)</pre>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__device__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The current output device, set by <a class="intern" href="#opt-d">the command line option
<b>-d</b></a>. The <b>man</b> and <b>faq</b> packages support <b>html</b> and
<b>roff</b> as its values.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnbase__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The base name of the input file name. Leading path components are stripped
away. If the <b>-i</b> option is used the input file is required to have
the <tt>.azm</tt> suffix. In that case the suffix is also stripped to obtain the
base name.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnentry__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The name of the entry file.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnin__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The file currently being processed.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnout__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The name of the default output file.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnpath__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The leading component of the input file name, possibly empty.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnup__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The file that included the current file, if applicable.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__fnwrite__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This key is set by <tt>\write#3</tt> to its first argument. It can be used by
macros that are expanded during evaluation of the third argument. Possible
usage is to branch on the name of the <i>write</i> output stream. For example
a file called <i>index.html</i> may be treated differently from other files.
The key is deleted afterwards. Nested invocations of <tt>\write#3</tt> may
corrupt the status of this key.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__line__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The line number in the file currently being processed.
This number will be correct for any invocation outside the scope
of a macro. For any invocation within a macro the result will be
the line number of the closing curly of the outermost containing
macro. The following</p>
<pre>   \__line__
   \__line__
   \__line__
   \group{
   \__line__
   \group{\__line__}
   \__line__}</pre>
<p class="default L50" style="margin-bottom:0">Results in</p>
<pre>   1
   2
   3
   7
   7
   7</pre>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__searchpath__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
A vararg containing a list of paths to search when a file is to be
included/imported/read/loaded. When you start zoem, this key should
contain the location of the <b>man.zmm</b> and <b>faq.zmm</b> package files.
It is advisable not to overwrite this key but to append to it instead.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__zoemstat__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set to one of <tt>ok</tt>, <tt>towel</tt> (that one is a bit lame),
or <tt>error</tt> by either the interpreter, an occurrence of <tt>\catch#2</tt>,
or <tt>\try#1</tt>.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__zoemput__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Set by <tt>\try#1</tt> to the possibly truncated result of processing
its argument.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__lc__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Expands to a left curly. It is hard to find a need for this - the zoem
stress suite uses it to generate a particular syntax error at a deeper
interpretation level.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td></td></tr><tr><td colspan=3><b>\__rc__</b></td></tr><tr><td width=32>&nbsp;</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Expands to a right curly.</p>
</div></td></tr>
</table>

</div>

<a name="inspect"></a>
<h2>THE INSPECT SUBLANGUAGE</h2>
<p class="default L50" style="margin-bottom:0">
The <tt>\inspect#4</tt> primitive takes four arguments. The languages
accepted by the first two arguments are described below. The third
argument is a replacement string or a replacement macro accepting
back-references (supplied as an anonymous macro). The fourth
argument is the data to be processed.</p>
<p class="default L50" style="margin-bottom:0"><b>arg 1</b><br>
Is a vararg. Currently it accepts a single key
<i>mods</i> for which the value should be a comma-separated list over the words
<i>posix</i>,
<i>icase</i>,
<i>dotall</i>,
<i>iter-lines</i>
<i>iter-args</i>,
<i>match-once</i>,
<i>discard-nmp</i>,
<i>discard-nil-out</i>,
<i>discard-miss</i>,
<i>count-matches</i>.
Alternatively repeated use of <i>mods</i> is allowed.</p>
<p class="default L50" style="margin-bottom:0"><b>arg 2</b><br>
Is a regular expression. Tilde patterns
are expanded according to all of the ZOEM, UNIX, and REGEX schemes.
Refer to <a class="intern" href="#tildexp">TILDE EXPANSION</a> for these.</p>
<p class="default L50" style="margin-bottom:0">
The third argument is a constant string or an anonymous key,
the fourth argument is data.</p>

<a name="tr"></a>
<h2>THE TR SUBLANGUAGE</h2>
<p class="default L50" style="margin-bottom:0">
The <tt>\tr#2</tt> primitive takes two arguments. The first argument contains
key-value pairs. The accepted keys are <i>from</i> and <i>to</i> which must
always occur together, and <i>delete</i> and <i>squash</i>.
The values of these keys must be valid <i>translation</i> specifications.
This primitive transforms the data in the second argument by successively
applying translation, deletion and squashing in that order. Only the
transformations that are needed need be specified.</p>
<p class="default L50" style="margin-bottom:0">
Translation specifications are subjected to UNIX tilde expansion as
described below.</p>
<p class="default L50" style="margin-bottom:0">
The syntax accepted by translation specifications is almost
fully compliant with the syntax accepted by <b>tr</b>(1), with
three exceptions. First, repeats are introduced as
<tt>[*a*20]</tt> rather than <tt>[a*20]</tt>. Second, ranges can (for
now) only be entered as <tt>X-Y</tt>, not as <tt>[X-Y]</tt>.
<tt>X</tt> and <tt>Y</tt> <i>can</i> be entered in either octal or
hexadecimal notation (see further below).
As an additional feature, the magic repeat operator <tt>[*a#]</tt> stops on both
class and range boundaries. Character specifications can be
complemented by preceding them with the caret <tt>^</tt>.
</p>
<p class="default L50" style="margin-bottom:0">
Specifications may contain ranges of characters such as <tt>a-z</tt> and <tt>0-9</tt>.
Posix character classes are allowed. The available classes are</p>
<pre>   [:alnum:]
   [:alpha:]
   [:cntrl:]
   [:digit:]
   [:graph:]
   [:lower:]
   [:print:]
   [:punct:]
   [:space:]
   [:upper:]
   [:xdigit:]</pre>
<p class="default L50" style="margin-bottom:0">
Characters can be specified using octal notation, e.g.
<tt>\012</tt> encodes the newline. Use <tt>\173</tt> for the opening curly,
<tt>\175</tt> for the closing curly, <tt>\134</tt> for the backslash, and <tt>\036</tt> for
the caret if it is the first character in a specification. <i>DON'T</i> use
<tt>\\</tt>, <tt>\{</tt>, or&nbsp;<tt>\}</tt> in this case! Hexadecimal notation is written
as <tt>\x7b</tt> (the left curly in this instance).</p>
<p class="default L50" style="margin-bottom:0">
See <a class="intern" href="#examples">EXAMPLES</a> for an example of <tt>tr#2</tt> usage.</p>

<a name="tildexp"></a>
<h2>TILDE EXPANSION</h2>
<p class="default L50" style="margin-bottom:0">
Some primitives interface with UNIX libraries that require backslash escape
sequences to encode certain tokens or characters. The backslash is special
in zoem too and without further measures it can become very cumbersome to
encode the correct escape sequences as it is not always clear which tokens
should be escaped or unprotected at what point. It is especially difficult
to handle the zoem characters with special meaning, <tt>{</tt>, <tt>}</tt> and
<tt>\</tt>.</p>
<p class="default L50" style="margin-bottom:0">
The two primitives under consideration are are <b>\inspect#4</b> and <b>\tr#2</b>.
Both treat the tilde as an additional escape character for certain arguments
(as documented in the user manual). These arguments are subjected to tilde
expansion, where the tilde and the character it proceeds are translated to a
new character or character sequence. There are three different sets of tilde
escapes, ZOEM, UNIX and REGEX escapes. <b>\tr#2</b> only accepts UNIX escapes,
<b>\inspect#4</b> accepts all. Tilde expansion is always the last processing
step before strings are passed on to external libraries.</p>
<p class="default L50" style="margin-bottom:0">The ZOEM scheme contains some convenience escapes, such
as <tt>\E</tt> to encode a double backslash.</p>
<p class="default L50" style="margin-bottom:0"><b>ZOEM tilde expansion</b></p>
<pre><b> meta sequence   replacement
.-----------------------------.
|     ~~       |      ~       |
|     ~E       |      \\      |
|     ~e       |      \       |
|     ~I       |      \{      |
|     ~J       |      \}      |
|     ~x       |      \x      |
|     ~i       |      {       |
|     ~j       |      }       |
`-----------------------------'</b></pre>
<p class="default L50" style="margin-top:0em; margin-bottom:0em">The zoem tr specification language accepts <tt>\x**</tt> as hexadecimal
notation, e.g. <tt>\x0a</tt> denotes a newline in the ASCII character set</p>.
<p class="default L50" style="margin-bottom:0"><b>UNIX tilde expansion</b></p>
<pre><b> meta sequence   replacement
.-----------------------------.
|     ~a       |      \a      |
|     ~b       |      \b      |
|     ~f       |      \f      |
|     ~n       |      \n      |
|     ~r       |      \r      |
|     ~t       |      \t      |
|     ~v       |      \v      |
|     ~0       |      \0      |
|     ~1       |      \1      |
|     ~2       |      \2      |
|     ~3       |      \3      |
`-----------------------------'</b></pre>
<p class="default L50" style="margin-bottom:0"><b>REGEX tilde expansion</b></p>
<pre><b> meta sequence   replacement
.-----------------------------.
|     ~^       |      \^      |
|     ~.       |      \.      |
|     ~[       |      \[      |
|     ~$       |      \$      |
|     ~(       |      \(      |
|     ~)       |      \)      |
|     ~|       |      \|      |
|     ~*       |      \*      |
|     ~+       |      \+      |
|     ~?       |      \?      |
`-----------------------------'</b></pre>

<a name="environment"></a>
<h2>ENVIRONMENT</h2>
<p class="default L50" style="margin-bottom:0">
The environment variable ZOEMSEARCHPATH may contain a colon and/or
whitespace separated list of paths. It will be used when searching
for files included via one of the <tt>dofile</tt> aliases
<tt>\input</tt>, <tt>\import</tt>, <tt>\read</tt>, and <tt>\load</tt>.
Note that the zoem macro <tt>\__searchpath__</tt> contains the location where
the zoem macro files were copied at the time of installation of zoem.</p>

<a name="diagnostics"></a>
<h2>DIAGNOSTICS</h2>
<p class="default L50" style="margin-bottom:0">
On error, Zoem prints a file name and a line number to which it was able to
trace the error. The number reported is the same as the one stored in the
session macro <tt>\__line__</tt>. For an error-trigering macro which is not
nested within another macro the line number should be correct. For a macro
that does occur nested within another macro the line number will be the line
number of the closing curly in the outermost containing macro.</p>
<p class="default L50" style="margin-bottom:0">
If in despair, use one of the tracing modes, <b>--trace-keys</b> is one of the
first to come to mind. Another possibility is to supply the
<a class="intern" href="#opt-x"><b>-x</b> option</a>.</p>

<a name="bugs"></a>
<h2>BUGS</h2>
<p class="default L50" style="margin-bottom:0">
No known bugs. <b>\inspect#4</b> has not received thorough stress-testing,
and the more esoteric parts of its interface will probably change.</p>

<a name="seealso"></a>
<h2>SEE ALSO</h2>
<p class="default L50" style="margin-bottom:0">
<a class="extern" href="http://micans.org/pud/">Portable Unix Documentation</a>
provides two mini-languages for authoring in the unix environment. These
languages, pud-man and pud-faq are both written in zoem.</p>

<a name="examples"></a>
<h2>EXAMPLES</h2>
<p class="default L50" style="margin-bottom:0">
This is a relatively new section, aimed at assembling useful or explanatory snippets.
</p>
<p class="default L50" style="margin-bottom:0">
Create a vararg containing file names matching a pattern (<tt>png</tt> in
this example).</p>
<pre>\setx{images}{
   \inspect{
      {mods}{iter-lines,discard-miss}
   }{(.*~.png)}{_#1{{\1}}}{\system{ls}}
}</pre>
<p class="default L50" style="margin-bottom:0">
Use magic boundary stops with <tt>tr#2</tt>.</p>
<pre>\tr{
   {from}{[:lower:][:upper:][:digit:][:space:][:punct:]}
   {to}{[*L#][*U#][*D#][*S#][*P#]}}{
 !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@
ABCDEFGHIJKLMNOPQRSTUVWXYZ
[\\]^_`
abcdefghijklmnopqrstuvwxyz
\{|\}~]}</pre>

<a name="author"></a>
<h2>AUTHOR</h2>
<p class="default L50" style="margin-bottom:0">
Stijn van Dongen.</p>
</body>
</html>