File: zum.html

package info (click to toggle)
zoem 21-341-2
links: PTS, VCS
area: main
in suites: forky, sid
size: 1,980 kB
sloc: ansic: 9,386; sh: 1,113; makefile: 108
file content (4710 lines) | stat: -rw-r--r-- 262,741 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2021 Stijn van Dongen -->
<head>
<meta name="keywords" content="macro processing, programming, template expansion, mark-up, character filtering">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
.slartibartfast { background-color: pink; text-decoration: blink; }

   /* open base2 */
/* start aephea.base.css */

   body
      {  text-align: justify;
         margin-left: 0%;
         margin-right: 0%;
      }

   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; }

   p.asd_par         {  margin-bottom:0em }
   p.asd_cpar        {  margin-bottom:0em }
   span.asd_cpar_caption  {  font-weight: bold; display: block }

   p.asd_car         {  margin-top:0em; margin-bottom:0em }
   p.asd_ccar        {  margin-top:0em; margin-bottom:0em }
   span.asd_ccar_caption  {  font-weight: bold; display: block }

   div.verbatim
      {  font-family: monospace;
         margin-top: 1em;
         margin-bottom: 1em;
         font-size: 10pt;
         margin-left: 2em;
         white-space: pre;
      }

   div.indent
      {  margin-left: 8%;
         margin-right: 0%;
      }

   .right   { text-align: right; }
   .left    { text-align: left; }
   .nowrap  { white-space: nowrap; }

   .item_leader 
      {  position: relative;
         margin-left: 8%;
      }
   
   .item_compact     {  position: absolute; vertical-align: baseline; }
   .item_cascade     {  position: relative; }

   .item_leftalign   {  text-align: left; }

   .item_rightalign
      {  width: 2em;
         text-align: right;
      }
   .item_compact .item_rightalign
      {  position: absolute;
         width: 52em;
         right: -2em;
         text-align: right;
      }

   .item_text
      {  position: relative;
         margin-left: 3em;
      }  

   .smallcaps { font-size: smaller; text-transform: uppercase }
   .underline { text-decoration: underline }

   acronym.ucase { font-size: smaller; text-transform: uppercase }
   abbr.ucase { font-size: smaller; text-transform: uppercase }

/* end aephea.base.css */
/* close base2 */
/* open simpledocument2 */
/* start aephea.asd.css */

   body {
      margin:0px;
      padding:0px;
      border: 0px;
   }


   .sec_leader
      {  margin-top: 1em;
         margin-bottom: 0em;
         position: relative;
         right: 0px;
         left: 0px;
         top: 0px;
      }

   .sec_title
      {  color: black;
         position: relative;
         margin-bottom: 0px;
         margin-top: 0px;
         margin-right: 5em;
         margin-left: 5em;
         text-align: center
      }

   .sec_num
      {  color: black;
         position: absolute;
         right: 0px;
         text-align: right;
         width: 5em;
         top: 0px;
      }

   .sec_lev1 { font-size: 20px; }
   .sec_lev2 { font-size: 18px; }
   .sec_lev3 { font-size: 16px; }
   .sec_lev4 { font-size: 14px; }
   .sec_lev5 { font-size: 12px; }
   .sec_lev6 { font-size: 12px; }

   .toc_toplevel
      {  margin-top: 1em;
      }

   .toc_leader
      {  margin-top: 0em;
         margin-bottom: 0em;
         position: relative;
         right: 0px;
         left: 0px;
      }

   .toc_title { position: relative; }

   .toc_num
      {  position: absolute;
         text-align: left;
         top: 0px;
         left: 0px;
      }

   .toc_title1 { margin-left: 3em; }
   .toc_title2 { margin-left: 6em; }
   .toc_title3 { margin-left: 9em; }
   .toc_title4 { margin-left: 12em; }

   .toc_num1   { left: 1em; }
   .toc_num2   { left: 3em; }
   .toc_num3   { left: 6em; }
   .toc_num4   { left: 9em; }

   div.box { border:solid; border-width:thin; width:100%; padding:1em}
   div.flushright { text-align: right }

/* end aephea.asd.css */
/* close simpledocument2 */
/* open css_append */

      body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
      body
         {  text-align: justify;
            margin-left: 8%;
            margin-right: 8%;
            font-size: 14pt;
         }
      .toc_and_date_DATE { text-decoration: none; }
      .zpr { text-decoration: none; }


      acronym.ucase { font-size: smaller; text-transform: uppercase }
      abbr.ucase { font-size: smaller; text-transform: uppercase }

      #asd_document_outer { position: relative; }
      #asd_document { position: relative; }
      #asd_title { text-align: center; font-size: 30pt; margin-top: 40pt; }
      #asd_subtitle { text-align: center; font-size: 18pt; margin-top: 10pt; margin-bottom: 40pt; }

      #asd_date { position: absolute; left: 0pt; top: 10pt; }
      #asd_version { position: absolute; right: 0pt; top: 10pt; }

   
/* close css_append */
</style>
<title>Zoem User's Manual</title>
</head>
<body>
<div id=asd_document_outer>
<a name="asd_body_start"></a>
<div id=asd_document>
&nbsp;
<div id="asd_date">December 10, 2021</div>
<div id="asd_version">zoem-21-341
</div>
<div id="asd_title">Zoem User's Manual</div>
<div id="asd_subtitle"></div>

<a name="intro"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#intro">Introduction</a></div><div class="sec_num"><a class="intern" href="#toc1"><span class="sec_num">1</span></a></div></div>
<p class="asd_par">
<b>Zoem:</b> &lt;Dutch&gt; The sound made by electrical devices and flying bugs.
Pronounced: <i>zoom</i> or <i>zum</i>; the vowel is short.
</p>
<p class="asd_par">
Zoem is a general macro/programming language with filtering capabilities.
It transforms text in two stages.</p>
<p class="asd_par">
In the first stage the text is scanned for macro escape sequences.
The core zoem language consists of so-called primitive macros.
They provide a wide spectre of functional behaviour, including
data storage,
arithmetic evaluation,
<span class="smallcaps">I/O</span> facilities,
iteration and flow control,
dictionary stacks,
system interaction,
and
regular expressions.
As with any macro/programming language, the real power comes from
the ability to create new user-defined macros in terms of primitives
and other user-defined macros.
Macro expansion can be arbitrarily delayed, and inside-out evaluation is
supported.</p>
<p class="asd_par">
A useful feature is the combination of anonymous macros, lists, and the
<a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> primitive, constituting a callback mechanism in zoem.
Another feature is the automatic popping and pushing of dictionaries with
the begin/end environment, providing shadowing and localization.</p>
<p class="asd_par">
In the optional second stage, the text is filtered. Two filter scopes are
distinguished. The first is called <i>device scope</i> and is always enclosed
in a filter escape sequence. The second, <i>plain scope</i>, is everything
else. Filtering mechanisms are provided for both. The filtering language
is useful when the output is meant to be in an external format with
device-specific escape sequences, such as <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> or troff. Conversions are
specified in device specific filtering rules that are applied in plain scope,
so that the zoem input is device agnostic. By setting up different
filtering rules the same input can be used to generate different outputs.</p>
<p class="asd_par">
This manual covers the whole zoem language. A large part of it is only
interesting for someone writing a reusable macro package. A smaller part is
still interesting for someone who is just using such a package, but might
want to add some utilities and shortcuts of his own. The part where file
inclusion, macro definitions, and macro expansions are explained is required
reading for anyone considering or planning to use zoem.</p>

<a name="section_1_1"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#section_1_1">Other documentation</a></div><div class="sec_num"><a class="intern" href="#toc1"><span class="sec_num">1.1</span></a></div></div>
<p class="asd_par">
<a class="local sibling" href="zoem.html">The manual page of the zoem interpreter</a>.
</p>
<p class="asd_par">
Zoem is used by
<a target="_parent" class="extern" href="http://micans.org/pud">Portable Unix Documentation</a> (<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym>)
and
<a target="_parent" class="extern" href="http://micans.org/aephea">Aephea</a>.
The latter is a general authoring tool for writing <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> documents and provides both useful
abstractions and a framework for creating new abstractions. It uses and
promotes the use of <abbr class="ucase" title="Cascading Style Sheets">CSS</abbr>.
A small core of Aephea has been ported to the typesetting language <em>troff</em>.
This core is used in <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym>, which provides
mini-languages for <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents and <span class="smallcaps">UNIX</span> manual pages.
Documents written in <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> can be output to troff and html,
and further to plain text, PostScript, and <abbr class="ucase" title="Portable Document Format">PDF</abbr>.
</p>

<a name="click"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#click">About this document</a></div><div class="sec_num"><a class="intern" href="#toc1"><span class="sec_num">1.2</span></a></div></div>
<p class="asd_par">
Clicking on the number next to a section title (e.g.
the 1.2 to the right of the title <b>About this document</b> of
this section) will get you to the corresponding section of the table of
contents.
</p>
<p class="asd_par">
Zoem input and zoem output are <i>both</i> generally shown in a typeface
font, <tt>like this</tt>.
</p>
<p class="asd_par">
<a name="colours"></a>
Links that point to locations within this document are shown in
<a class="intern" href="#colours">blueish colors</a>. Links that point to documents originating
from the same package (project) or perhaps the same site are shown in in
<a class="local" href="zum.html">greenish colors</a>. Links that point to other stations on the
internet or perhaps other packages on the same site are shown in in
<a target="_parent" class="extern" href="http://www.google.com">reddish colors</a>.
</p>

<a name="toc"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#toc">Table of Contents</a></div><div class="sec_num"><a class="intern" href="#toc2"><span class="sec_num">2</span></a></div></div>
<div id=asd_toc>
<div class="toc_toplevel">
<a name="thetoc"></a>
<div class="toc_leader">
<div class="toc_num toc_num1"><a class="intern" href="#asd_body_start">Start</a>.</div>
<div class="toc_title toc_title1"><a name="toc_asd_body_start"></a><a class="intern" href="#asd_body_start">&nbsp;</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc1">1</a>.</div>
<div class="toc_title toc_title1"><a name="toc_intro"></a><a class="intern" href="#intro">Introduction</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">1.1.</div>
<div class="toc_title toc_title2"><a name="toc_section_1_1"></a><a class="intern" href="#section_1_1">Other documentation</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">1.2.</div>
<div class="toc_title toc_title2"><a name="toc_click"></a><a class="intern" href="#click">About this document</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc2">2</a>.</div>
<div class="toc_title toc_title1"><a name="toc_toc"></a><a class="intern" href="#toc">Table of Contents</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc3">3</a>.</div>
<div class="toc_title toc_title1"><a name="toc_nutshell"></a><a class="intern" href="#nutshell">Zoem in a nutshell</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">3.1.</div>
<div class="toc_title toc_title2"><a name="toc_features"></a><a class="intern" href="#features">Features</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc4">4</a>.</div>
<div class="toc_title toc_title1"><a name="toc_cline"></a><a class="intern" href="#cline">Invoking zoem from the command line</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc5">5</a>.</div>
<div class="toc_title toc_title1"><a name="toc_syntax"></a><a class="intern" href="#syntax">Zoem syntax and parsing</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.1.</div>
<div class="toc_title toc_title2"><a name="toc_nomenclature"></a><a class="intern" href="#nomenclature">Syntax and nomenclature</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.2.</div>
<div class="toc_title toc_title2"><a name="toc_namespaces"></a><a class="intern" href="#namespaces">Primitives, built-ins and user macros</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.3.</div>
<div class="toc_title toc_title2"><a name="toc_escape"></a><a class="intern" href="#escape">List of escape sequence classes</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.4.</div>
<div class="toc_title toc_title2"><a name="toc_stages"></a><a class="intern" href="#stages">Parsing stages</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.5.</div>
<div class="toc_title toc_title2"><a name="toc_fileread"></a><a class="intern" href="#fileread">File read</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.6.</div>
<div class="toc_title toc_title2"><a name="toc_searchpath"></a><a class="intern" href="#searchpath">File search path</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.7.</div>
<div class="toc_title toc_title2"><a name="toc_macro"></a><a class="intern" href="#macro">Macro expansion</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.8.</div>
<div class="toc_title toc_title2"><a name="toc_section_5_8"></a><a class="intern" href="#section_5_8">File inclusion</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.9.</div>
<div class="toc_title toc_title2"><a name="toc_protection"></a><a class="intern" href="#protection">Protection</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.10.</div>
<div class="toc_title toc_title2"><a name="toc_dichotomy"></a><a class="intern" href="#dichotomy">Scope dichotomy</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.11.</div>
<div class="toc_title toc_title2"><a name="toc_dscope"></a><a class="intern" href="#dscope">Device scope</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num3">5.11.1.</div>
<div class="toc_title toc_title3"><a name="toc_special"></a><a class="intern" href="#special">Device scope resulting from mapping special characters</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num3">5.11.2.</div>
<div class="toc_title toc_title3"><a name="toc_glyph"></a><a class="intern" href="#glyph">Device scope resulting from glyph definitions</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">5.12.</div>
<div class="toc_title toc_title2"><a name="toc_xmlsugar"></a><a class="intern" href="#xmlsugar"><abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>/<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>/<abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntactic sugar cubes</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc6">6</a>.</div>
<div class="toc_title toc_title1"><a name="toc_section_6"></a><a class="intern" href="#section_6">Zoem miscellanea</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.1.</div>
<div class="toc_title toc_title2"><a name="toc_signature"></a><a class="intern" href="#signature">Key signatures</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.2.</div>
<div class="toc_title toc_title2"><a name="toc_anonymous"></a><a class="intern" href="#anonymous">Anonymous keys</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.3.</div>
<div class="toc_title toc_title2"><a name="toc_grape"></a><a class="intern" href="#grape">Tree data</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.4.</div>
<div class="toc_title toc_title2"><a name="toc_vararg"></a><a class="intern" href="#vararg">Of blocks and varargs</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.5.</div>
<div class="toc_title toc_title2"><a name="toc_session"></a><a class="intern" href="#session">Session keys</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.6.</div>
<div class="toc_title toc_title2"><a name="toc_builtin"></a><a class="intern" href="#builtin">Built-in macros</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">6.7.</div>
<div class="toc_title toc_title2"><a name="toc_dictionary"></a><a class="intern" href="#dictionary">Dictionary stacks</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc7">7</a>.</div>
<div class="toc_title toc_title1"><a name="toc_tour"></a><a class="intern" href="#tour">A zoem tour</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc8">8</a>.</div>
<div class="toc_title toc_title1"><a name="toc_language"></a><a class="intern" href="#language">The zoem language</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">8.1.</div>
<div class="toc_title toc_title2"><a name="toc_section_8_1"></a><a class="intern" href="#section_8_1">Alphabetic index</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">8.2.</div>
<div class="toc_title toc_title2"><a name="toc_topicindex"></a><a class="intern" href="#topicindex">Topic index</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num2">8.3.</div>
<div class="toc_title toc_title2"><a name="toc_section_8_3"></a><a class="intern" href="#section_8_3">Primitives</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc9">9</a>.</div>
<div class="toc_title toc_title1"><a name="toc_pitfalls"></a><a class="intern" href="#pitfalls">Pitfalls</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a name="toc10">10</a>.</div>
<div class="toc_title toc_title1"><a name="toc_glossary"></a><a class="intern" href="#glossary">Glossary</a></div>
</div>
<div class="toc_leader">
<div class="toc_num toc_num1"><a class="intern" href="#asd_body_end">End</a>.</div>
<div class="toc_title toc_title1"><a name="toc_asd_body_end"></a><a class="intern" href="#asd_body_end">&nbsp;</a></div>
</div>
</div>
</div>

<a name="nutshell"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#nutshell">Zoem in a nutshell</a></div><div class="sec_num"><a class="intern" href="#toc3"><span class="sec_num">3</span></a></div></div>
<p class="asd_par">
Zoem supports several programming constructs, immediate and postponed
expansions, stream character filtering, easy <span class="smallcaps">I/O</span> facilities, integer
arithmetic, and a whole lot more.
Its main aims are:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Providing the building blocks for a structural and programmable approach.
<a class="intern" href="#features">Section 3.1</a>
contains an overview of the zoem primitives and their use.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Accepting a pleasant syntax that does not require much thinking,
favouring simplicity and rigor over looseness and context dependent
rules.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Creation from the keyboard while minimizing on key-strokes.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Few meta characters. Zoem achieves this by having a single
special character and a reasonably restricted syntax.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Adding filtering capabilities so that multiple devices can be
addressed.</p>
</div>
</div>

<a name="features"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#features">Features</a></div><div class="sec_num"><a class="intern" href="#toc3"><span class="sec_num">3.1</span></a></div></div>
<p class="asd_par">
Listed below are some features of the zoem primitives. In practice there are
two kinds of zoem files. The first is a zoem macro file, which should
contain macros defined in terms of lower-level macros, with zoem primitives
at the lowest level. The second is a zoem document file, which should import
such a macro file and only use the high-level macros defined in that macro
file. Additionally, a document file can define some high-level macros of
its own, in terms of low-level macros, zoem primitives, or a mixture of
both.
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Macros with arguments, overloading of key names allowed (i.e. different
keys with the same name are distinguished by the number of arguments they
take). (<a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, and <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>).
Zoem primitives look like regular macros, but
usually they expand their arguments before use. User macros
can be equipped with this behaviour by wrapping them in <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Support for variable number of arguments - see the
<a class="intern" href="#vararg">vararg</a> section.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Easy file, <span class="smallcaps">STDIN</span>, <span class="smallcaps">STDOUT</span>, and <span class="smallcaps">STDERR</span> input/output,
nested file inclusion (<a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a>, <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a>, <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a>,
and <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Extensive support for arithmetic with the primitives <a class="intern" href="#let_1"><span class="zpr">\let#1</span></a>, <a class="intern" href="#f_2"><span class="zpr">\f#2</span></a>,
<a class="intern" href="#f_3"><span class="zpr">\f#3</span></a>, <a class="intern" href="#fv_2"><span class="zpr">\fv#2</span></a>, and <a class="intern" href="#eqt_3"><span class="zpr">\eqt#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Operators returning booleans (<a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a>, <a class="intern" href="#cmp_3"><span class="zpr">\cmp#3</span></a>, <a class="intern" href="#eqt_3"><span class="zpr">\eqt#3</span></a>),
control operators acting on those (<a class="intern" href="#while_2"><span class="zpr">\while#2</span></a>, <a class="intern" href="#if_3"><span class="zpr">\if#3</span></a>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The <i>for</i>-like primitives <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> and <a class="intern" href="#table_5"><span class="zpr">\table#5</span></a>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Match and substitution capabilities using <acronym class="ucase" title="Portable Operating System Interface [for Unix]">POSIX</acronym> regexes (<a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Register macros with <a class="intern" href="#register_2"><span class="zpr">\register#2</span></a> to be processed after regular
processing (e.g. to output counters or warnings).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The switch primitive <a class="intern" href="#switch_2"><span class="zpr">\switch#2</span></a>, employing the <a class="intern" href="#vararg">vararg
construct</a>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Localized expansions (<a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a>)
and meta-zoem (<a class="intern" href="#excl"><span class="zpr">\!</span></a> and <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A user dictionary stack that can be manipulated using <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and
<a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>. An environment environment for doing <tt>\begin{stuff}</tt> <tt>..</tt>
<tt>\end{stuff}</tt> stuff (see <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>). This environment creates name
scopes by pushing and popping to/from the <a class="intern" href="#dictionary">dollar
dictionary stack</a>. Environments may take arguments,
one particular useful application is that local variables (e.g. local
to an <i>itemize</i> environment) can thus be specified by the user.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Storage of data by multiple string indexing &mdash; arbitrary data can be stored
in a tree by indexing nodes with (arbitrary) strings.
Refer to the <a class="intern" href="#grape">Tree data</a> section.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The ability to nicely format macros (see <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<a class="intern" href="#xmlsugar">Syntactic sugar</a>
for writing <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>-style mark-up and having it checked.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Executing system commands, possibly sending data to <span class="smallcaps">STDIN</span> and
receiving data from <span class="smallcaps">STDOUT</span> &mdash; <a class="intern" href="#system_3"><span class="zpr">\system#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
And more.</p>
</div>
</div>

<a name="cline"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#cline">Invoking zoem from the command line</a></div><div class="sec_num"><a class="intern" href="#toc4"><span class="sec_num">4</span></a></div></div>
<p class="asd_par">
You use zoem by invoking it from the command line. The normal mode of
operation is that you specify a file for zoem to chew up and spit out. This
is called the <i>entry file</i>, and its name usually has the extension
<tt>.azm</tt>. A common invocation looks as follows:</p>
<div class="verbatim">zoem -i mcl.azm</div>
<p class="asd_car">
The <tt>-i</tt> flag specifies the entry file. It is not necessary to write the
<tt>.azm</tt> extension, zoem will append it for you. The preceding could also
have been entered as</p>
<div class="verbatim">zoem -i mcl</div>
<p class="asd_car">
In either case, zoem will set the session key <a class="intern" href="#session"><tt>\__fnbase__</tt></a> to the base
name of the entry file, i.e. the name stripped of its <tt>.azm</tt> suffix and
any leading path components. In this example, the key <a class="intern" href="#session"><tt>\__fnbase__</tt></a> will
get the value <tt>mcl</tt>. If you have an input file without the <tt>.azm</tt>
extension, you need to use the <tt>-I</tt> option.</p>
<p class="asd_par">
Zoem writes its output to a default output file which is named according to
three rules. The rules are:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
If the <tt>-o</tt> flag was given the value say <tt>somestr</tt>,
zoem will write to the file named <tt>somestr</tt>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
If <tt>-o</tt> was not supplied but the <tt>-d</tt> flag was used with argument say
<tt>zyx</tt>, zoem will write to the file named <a class="intern" href="#session"><tt>\__fnbase__.zyx</tt></a>.
The -d flag also results in the macro <a class="intern" href="#session"><tt>\__device__</tt></a> being set
to <tt>xyz</tt>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
If neither <tt>-d</tt> nor <tt>-o</tt> was given, zoem will write to the
file named <a class="intern" href="#session"><tt>\__fnbase__.ozm</tt></a>.</p>
</div>
</div>
<p class="asd_par">
It is possible to change the default output file from within the document;
this is achieved with the <a class="intern" href="#writeto_1"><span class="zpr">\writeto#1</span></a> primitive. Zoem can mingle default
output with output to other files, use the <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> primitive for that.</p>
<p class="asd_par">
Both the <tt>-i</tt> and <tt>-o</tt> flag accept a hyphen as argument,
meaning respectively that zoem will read from <span class="smallcaps">STDIN</span> and write
to <span class="smallcaps">STDOUT</span>.</p>
<p class="asd_par">
Specifying just zoem and entering a return will cause zoem
to enter interactive mode, in which it reads from <span class="smallcaps">STDIN</span> and writes to <span class="smallcaps">STDOUT</span>.
Interactive mode currently should catch any errors occurring,
so it is a good way of experimenting and testing.
By default, interactive mode reads chunks that are ended by a single
dot on a line by itself. This behaviour can be changed by setting
the session variable <a class="intern" href="#session"><tt>\__parmode__</tt></a> using the <tt>-s</tt> option.
Using <tt>zoem -l parmode</tt> shows the bits that can be set in this variable.
It is for example possible to make zoem read paragraphs (ended by two
or more consecutive newlines).</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
There is a difference between specifying <i>no</i> output stream
(i.e. not using the <tt>-o</tt> option) and explicitly specifying <tt>-o -</tt>.
In the latter case, zoem will never enter interactive mode. Should
you need to insert zoem into some pipe sequence, then you need to
use <tt>-o -</tt>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Tracing errors</span>
If your document contains erroneous input (e.g. using a macro that was never
defined), zoem will by default print the approximate corresponding line
number of the current input file and the last key it saw, and then exit. If
that does not suffice in tracking down the error, you have a choice of
options. One possibility is to use one of the various tracing modes
described below and in the zoem interpreter manual. Another possibility is
to specify the <tt>-x</tt> option which says to enter interactive mode should an
error occur. This enables you to inspect the values of keys defined or used
in the problematic area.
A selection of other options is given below. For the full story,
consult <a class="local sibling" href="zoem.html">the manual page of the zoem interpreter</a>.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-h</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
lists all flags accepted by zoem with a short description for each.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-s foo=bar</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Sets key <tt>\foo</tt> to <tt>bar</tt>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-e &lt;any&gt;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Zoem will evaluate <tt>&lt;any&gt;</tt>, writing any result text to <span class="smallcaps">STDOUT</span>,
and then exit.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-E &lt;any&gt;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Zoem will evaluate <tt>&lt;any&gt;</tt>, writing any result text to <span class="smallcaps">STDOUT</span>,
and then proceed.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-x</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
If an error occurs, zoem stops processing and enters interactive mode.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-l &lt;str&gt;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
lists all entities specified by <tt>&lt;str&gt;</tt>. It can be any of
<tt>all</tt>,
<tt>filter</tt>,
<tt>legend</tt>,
<tt>alias</tt>,
<tt>session</tt>,
<tt>trace</tt>, or
<tt>zoem</tt>.
Repeated use is allowed. In fact, zoem will only check whether
the target is present as a substring, so</p>
<div class="verbatim">zoem -l legendzoem</div>
<p class="asd_car">
will print the legend and the list of zoem primitives. </p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>--trace</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This traces (prints) all keys encountered, and prints
possibly truncated arguments.
Zoem has several other tracing flags, use the <tt>-h</tt> flag
or refer to the zoem manual page for more information.</p>
<p class="asd_par">
Tracing can be set from within the document using the
<a class="intern" href="#trace_1"><span class="zpr">\trace#1</span></a> primitive. Part or whole of the data tree
can be output from within the document using the <tt>\%dump</tt> primitive
(refer to the <a class="intern" href="#grape">Tree data</a> section).</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>--stats</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
When zoem is done, it prints statistics about the primitive name
table and about the user name table.</p>
</div>
</div>

<a name="syntax"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#syntax">Zoem syntax and parsing</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5</span></a></div></div>

<a name="nomenclature"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#nomenclature">Syntax and nomenclature</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.1</span></a></div></div>
<p class="asd_par">
Zoem parses text which may contain zoem <b>escape sequences</b>, these are
sequences that have special meaning and cause zoem to do special
processing. Each and every escape sequences starts with a backslash, no
exceptions. There are three kinds of sequences that are <i>macros</i>, which
may or may not take arguments. These are zoem primitives, user keys, and
dollar keys.</p>
<p class="asd_par">
There are currently about sixty zoem primitives, these are listed in the
<a class="intern" href="#language">The zoem language</a> section. Sixty is quite a lot; it includes
convenience sibling sets such as <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>, <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, and
<a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, and entries covering a variety of areas such as <span class="smallcaps">I/O</span>, arithmetic,
testing, control, string conversions, formatting, shadowing (scopes),
and all the other stuff listed in the <a class="intern" href="#topicindex">Topic index</a> section.</p>
<p class="asd_par">
Additionally there are a number of zoem built-ins that are defined
in terms of primitives. Built-ins live in the same dictionary as
primitives and behave the same in all aspects.
The next section has some further remarks on the differences
and resemblances between primitives/built-ins on the one hand
and user macros on the other hand.</p>
<p class="asd_par">
User keys and dollar keys are discussed in the
<a class="intern" href="#macro">Macro expansion</a> section. Arguments are shipped by delimiting them with curly
braces, as in</p>
<div class="verbatim"><tt>\thiskey{takes}{\bf{two}\it{arguments}}</tt>.</div>
<p class="asd_car">
No characters are allowed inbetween (the delimiting curlies of) two
arguments (but take note of the handy <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a> primitive). See the
<a class="intern" href="#macro">Macro expansion</a> section for more information.
Zoem is very strict in the syntax it accepts, but it <i>garantuees</i> to
accept a text in which each backslash <tt>\</tt> is escaped as <tt>\\</tt> (i.e. a
text in which all consecutive runs of backslashes have even length).</p>
<p class="asd_par">
An <b>active backslash</b> is any backslash that is not made inactive by an
active backslash immediately preceding it. The first backslash seen by zoem
(proceeding sequentially through the text) is active. This is one
incomprehensible way of stating the obvious, and I bet you know what I mean
anyway. An active backslash must always have a meaning known to zoem. If
zoem does not get it, it will complain and exit. The meaning (i.e. class)
of the escape sequence introduced by an active backslash is determined by
the character immediately following it. A list is given below.</p>
<p class="asd_par">
Within arguments, curlies not functioning as argument delimiters must also
be escaped if they are not balanced. It is best practice to escape all
non-argument-delimiting curlies, but I never do so myself unless they are
not balanced.
An <b>escaped curly</b> is a curly preceded by an active
backslash.
An <b>active curly</b> is a curly that is not escaped.
A pair of
<b>balanced curlies</b> consists of an active left curly that matches an active
right curly, where inbetween all escaped curlies are disregarded.
A <b>block</b> is anything delimited by balanced curlies.
The word <b>scope</b> is most often used to distinguish between <b>device
scope</b> and <b>plain scope</b>, these are the two kinds of <b>parse scopes</b>.
An <b>environment scope</b> refers to the stuff enclosed by instances of the
<a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> and <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a> primitives.
So called <b>name scopes</b> are entered and exited by <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>.</p>

<a name="namespaces"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#namespaces">Primitives, built-ins and user macros</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.2</span></a></div></div>
<p class="asd_par">
Zoem distinguishes between primitives and built-ins and user macros
on the other hand. Consider
the following slightly contrived example.</p>
<div class="verbatim">\def{fib#1}{
   \push{fibonacci}
   \set{a}{1}
   \set{b}{1}
   \set{c}{0}
   \while{\let{\a &lt;= \1}}{
      \setx{c}{\a}
      \setx{a}{\let{\a + \b}}
      \write{-}{txt}{\c\|}
      \setx{b}{\c}
   }
   \pop{fibonacci}
}</div>
<p class="asd_car">
The example is contrived in that zoem is not the most appropriate
language to compute Fibonacci numbers. The reason for using
it is that extracts from existing macro packages require more context
and are simply more boring.</p>
<p class="asd_par">
In the example, the following macros are primitives:
<b><a class="intern" href="#push_1"><span class="zpr">\push#1</span></a></b>, <b><a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a></b>,
<b><a class="intern" href="#def_2"><span class="zpr">\def#2</span></a></b>, <b><a class="intern" href="#set_2"><span class="zpr">\set#2</span></a></b>, <b><a class="intern" href="#while_2"><span class="zpr">\while#2</span></a></b>, <b><a class="intern" href="#let_1"><span class="zpr">\let#1</span></a></b>,
<b><a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a></b>, and <b><a class="intern" href="#write_3"><span class="zpr">\write#3</span></a></b>.
The example defines a user macro <b><tt>\fib#1</tt></b>, which can be
invoked e.g. as <tt>\fib{100}</tt>. Doing this either from a file
or from interactive mode should give the output below.</p>
<div class="verbatim">1
2
3
5
8
13
21
34
55
89</div>
<p class="asd_par">
From the above it can be seen that a macro (primitive or user-defined)
is in this text often referenced by its signature. The signature
contains both the name of the macro and the number of arguments it takes,
separated by the <tt>#</tt> (octothorpe) character. The octothorpe
and ensuing integer are omitted if a macro does not take
arguments. A new macro is defined
by specifying the required signature (without the leading backslash)
as the first argument of one of the definition macros.
In this text a signature is usually prefixed
with the backslash.</p>
<p class="asd_par">
The example above also defines user macros <tt>a</tt>, <tt>b</tt>, and <tt>c</tt>.
The <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> primitive will not warn when a previous definition
exists. The <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> acts similarly but will also first evaluate
the value assigned to the macro. Finally, <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>
temporarily create a new dictionary in which the definitions are stored.
This is one easy way to ensure that no other definitions are
overwritten. This level of care is generally not required though.</p>
<p class="asd_par">
The following are useful to know about primitives, built-ins
and user macros.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&bull;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Primitives and built-ins live in one namespace (or dictionary),
user macros live in another.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&bull;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A built-in is a special macro provided by zoem.
It is defined in terms of one or more primitives, but its definition
lives in the same dictionary as primitives do. It is called
a built-in because its definition is built into the zoem interpreter.
Example: <tt>begin#1</tt> is defined as <tt>\begin{\1}{}</tt> (cf <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>).
The full list can be obtained by issuing <tt>zoem -l alias</tt>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&bull;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Primitives and built-ins can be shadowed by user-macros, but a warning will
be issued. You can test this by issuing e.g.
<tt>\def{def#2}{\set{\1}{\2}}</tt>. This particular piece of code redefines
<a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> as <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> by shadowing the primitive <tt>\def#2</tt> as a user
macro, losing the property of <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> that it warns if a key already
exists.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&bull;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Primitives and built-ins can <i>always</i> be accessed by prefixing
the name with a right quote, as in <tt>\'def{foo}{bar}</tt>.
The prefixed primitive syntax also has the advantage that
it is slightly faster, although zoem speed is likely not something
one should worry about.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em">&bull;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
It is impossible to access a user macro with the quote prefix syntax.</p>
</div>
</div>
<p class="asd_par">
It is probably a good idea in macro packages that
export functionality to use the primitive quote prefix syntax.
This protects the package from user redefinitions. At the same
time, the ability to shadow zoem primitives implies that user
macros (also those exported by macro packages themselves)
are protected against potential clashes with zoem primitives
that may be introduced in later versions of the language.
The Fibonacci example looks as follows using the quote prefix syntax.</p>
<div class="verbatim">\'def{fib#1}{
   \'push{fibonacci}
   \'set{a}{1}
   \'set{b}{1}
   \'set{c}{0}
   \'while{\'let{\a &lt;= \1}}{
      \'setx{c}{\a}
      \'setx{a}{\'let{\a + \b}}
      \'write{-}{txt}{\c\|}
      \'setx{b}{\c}
   }
   \'pop{fibonacci}
}</div>
<p class="asd_par">
The quote mechanism only works for zoem primitives and built-ins that follow
the syntax of user macros. This includes names starting with a dollar <tt>$</tt>
or with a double quote <tt>"</tt>. The primitive <a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a> and the built-ins
<tt>\""</tt> and <tt>\""#1</tt> are the only examples in this category.
The quote mechanism does not work for special zoem primitives
such as data keys (<a class="intern" href="#grape">Tree data</a>), delay keys (<a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>),
or <abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntactic sugar (<a class="intern" href="#xmlsugar"><abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>/<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>/<abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntactic sugar cubes</a>).</p>

<a name="escape"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#escape">List of escape sequence classes</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.3</span></a></div></div>
<p class="asd_par">
This is a list of escape sequence classes recognized by zoem, indexed
by the (set of) character(s) triggering the class(es) &mdash; this assumes
that the character in question is preceded by an active backslash.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>$[_a-zA-Z]*</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[dollar key]
A sequence starting with a dollar sign possibly continued with
underscores and alphanumeric characters. Introduces a dollar key. No
dollar signs are allowed in the remainder, and the first non-alphanumeric
non-underscore character terminates the sequence. The primary use of dollar
keys is that they are set by <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> and <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a>. Dollar keys live
in the dollar dictionary stack, which is pushed and popped by <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>
and <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a>. Nested <tt>begin/end</tt> scopes can thus safely associate
different values with the same key name. Refer also to the <a class="intern" href="#macro">Macro expansion</a>
section, the <a class="intern" href="#language">The zoem language</a> section, and the <a class="intern" href="#dictionary">Dictionary stacks</a> section.</p>
<p class="asd_par">
Note: <a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a> is the only zoem primitive starting with a dollar.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>[_a-zA-Z][_a-zA-Z0-9]*</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[user key/zoem primitive]
A sequence starting with an underscore or an alphabetic character, with
only underscores and alphanumeric characters in the remainder. Introduces a
user key or a zoem primitive. The first non-alphanumeric non-underscore
character terminates the sequence. These keys live in the <i>user
dictionary stack</i>, which the user can control with the <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and
<a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a> primitives. Refer also to the <a class="intern" href="#macro">Macro expansion</a>, <a class="intern" href="#language">The zoem language</a>,
and <a class="intern" href="#dictionary">Dictionary stacks</a> sections.</p>
<p class="asd_par">
A sequence consisting of a single underscore (i.e. not followed
by an alphanumeric character) introduces an
<a class="intern" href="#anonymous">anonymous key</a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>"</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[user key or zoem built-in]
Starts a user key, which is only different from the user keys mentioned
above in that it looks different. The sequence is terminated by
a closing&nbsp;<tt>"</tt>. Inbetween, anything is allowed except
a backslash or curly. This is used for creating mnemonic names such as </p>
<div class="verbatim">   \"man::author"
   \"man::section"
   \"man::version"
   \"html::title"
   \"html::charset"</div>
<p class="asd_car">
These keys live in the <i>user dictionary stack</i>.
See the <a class="intern" href="#macro">Macro expansion</a> section and the <a class="intern" href="#dictionary">Dictionary stacks</a> section.</p>
<p class="asd_par">
There are two zoem built-ins that take this particular form. These are
<tt>\""</tt> and <tt>\""#1</tt>. Both expand to nothing. The first can be used to
temporarily separate two pieces of text, as they will be joined after
expansion. The second can be used to quickly outcomment sections of text.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>'</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[primitive quote prefix]
As seen above, primitives and user keys largely live in the
same syntactic namespace. It is possible to unambiguously
invoke a primitive by inserting a right quote to the left
of the primitive key or built-in.
Refer to section <a class="intern" href="#namespaces">Primitives, built-ins and user macros</a>.</p>
<p class="asd_par">
The user keys live in a stack of dictionaries. Dictionaries
can be pushed and popped using <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>.
The default user dictionary is always present and acts
as a global namespace. It is possible to retrieve a key <tt>\foo</tt>
directly from the global namespace using the syntax <tt>\''foo</tt>,
even if it is shadowed in stacked dictionaries. It is possible
to set a key in the global namespace using <a class="intern" href="#set_3"><span class="zpr">\set#3</span></a>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>%</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[data key]
A sequence starting with a percent sign. The percent sign is
followed by a number of scopes. This is used to access multi-dimensional
data storage. Such data is stored using the <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> primitive or one
of its siblings. Refer also to section&nbsp;<a class="intern" href="#grape">Tree data</a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>[1-9]</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[positional parameter]
A single (character encoding a) positive digit. The sequence
backslash followed by digit is called a <i>positional parameter</i>.
It is only interpreted in the second argument of <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>,
<a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, and <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>, and in the definition part of an
<a class="intern" href="#anonymous">anonymous key</a> (which can be an argument to <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>
and <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>). In all these instances, the sequence denotes a
positional parameter into which the corresponding argument will be
interpolated when a key with arguments is used. It is allowed in other
places though, as it is possible in zoem to create key definitions
dynamically (see e.g. the <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> primitive).
<b>Note</b> during interpolation, positional parameters that are enclosed by
the <i>delay scope</i> <tt>\!{..}</tt> will not be interpolated (see <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>).
The status of this feature is not entirely clear.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>&lt;newline&gt;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[strip newline] The newline will be stripped during the
interpretation stage. If you want the newline to be stripped during
the file-read preprocessing stage use the sequence <tt>\:{/}</tt>,
which is a special case of the comment sequence (see below).</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>:</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[preprocessing sequence]
There are a few preprocessing sequences, which are evaluated during file
read (cf the <a class="intern" href="#fileread">File read</a> section).
The most important preprocessing sequence is simply the sequence <tt>\:</tt>
followed by whitespace, an alphanumeric character, or a backslash. It
introduces a comment up till and excluding the next newline, which is
stripped.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>|</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[zoem glyph]
Comprises a special two-character sequence that can be given a
device-specific meaning. It is customarily used to encode a line break. To
zoem, this sequence is more or less the same as a 'normal' character. See
the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>~</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[zoem glyph]
It is customarily used to encode a non-breaking space. See the entry above.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>-</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[zoem glyph]
It is customarily used to encode a long dash. See two entries back.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>\</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[backslash] Denotes a literal backslash.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[left curly] Denotes a literal left curly.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[right curly] Denotes a literal right curly.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>*</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[glyph sequence] Starts a glyph sequence or constant sequence.
Refer to the <a class="intern" href="#dscope">Device scope</a> section and to the <a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a> primitive.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>&lt;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[syntactic sugar]
This introduces syntactic sugar for directly writing <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>-style mark-up,
such as <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> and <abbr class="ucase" title="Extensible Markup Language">XML</abbr> (e.g. DocBook).
Refer to the <a class="intern" href="#xmlsugar">anchor section</a> for that topic.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>@</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[at scope] <i>Typically seen in macro package files only</i>.
Starts a special instance of device scope called <i>at scope</i>. The
sequence&nbsp;<tt>\@</tt> <i>must</i> immediately be followed by a pair of balanced
curlies, so at scope always appears as <tt>\@{..}</tt>. Refer to the
<a class="intern" href="#dichotomy">Scope dichotomy</a> and <a class="intern" href="#dscope">Device scope</a> sections for more information.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>@e</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[at <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> entity]
<tt>\@e{ent}</tt> will expand to the <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> character entity &amp;ent; &mdash;
it is equivalent to, somewhat easier to type and minimally shorter than
<tt>\@{&amp;ent;}</tt>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>&amp;</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[and scope] <i>Typically seen in macro package files only</i>.
May only be used within device scope, and implements a limited
form of macro expansion within that scope.
The sequence&nbsp;<tt>\&amp;</tt> <i>must</i> immediately be followed by a pair of balanced
curlies. so and scope always appears as <tt>\&amp;{..}</tt>. Refer to the
<a class="intern" href="#dichotomy">Scope dichotomy</a> and <a class="intern" href="#dscope">Device scope</a> sections for more information.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>`</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[back quote - formatting escape]
<i>Typically seen in macro package files only</i>.
Must be followed by a pair of balanced curlies enclosing a formatting
sequence. This is only recognized within the <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a> primitive.
This primitive removes all literal whitespace it encounters in its argument;
the formatting sequences are transformed to the whitespace characters encoded
by them.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>,</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[comma - atomic separator] <i>Typically seen in macro package files only</i>.
This is interpreted during filter time, and is
always mapped to nothing. Use it for glueing things as in <tt>\foo\,1</tt>,
which will result in <tt>theresultoffoo1</tt>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>!</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[delay sequence] <i>Typically seen in macro package files only</i>.
Introduces a zoem meta sequence. Such a sequence consists of a maximal run
of consecutive backslashes, possibly followed by a single block. It can be
used to delay interpretation during any number of interpretation stages, and
is useful to delay interpretation, perhaps even in a nested fashion, for
arguments in keys such as <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> that expand one or more of their
arguments before use. The run of exclamation marks (or 'bangs' as they are
internally called) actually comprises an argument to the underlying
primitive, so the two primitives (one taking a single block argument)
internally have respective signatures <tt>!#1</tt> and <tt>!#2</tt>. Externally
though, they are just refered to as <a class="intern" href="#excl"><span class="zpr">\!</span></a> and <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>=</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[inline files] <i>Rarely used feature</i>.
Starts either a sequence of the form <tt>\={fname}</tt>, which begins a so called
inline file named <tt>fname</tt>, or a sequence of the form <tt>\==</tt>, which
ends such an inline file. Refer to the <a class="intern" href="#fileread">File read</a> section.</p>
</div>
</div>
<p class="asd_par">
This leaves <tt>0&gt;()[]?^#/.;</tt> for future use, hopefully
very few of these will ever acquire meaning.
If the sequence&nbsp;<tt>\#</tt> acquires meaning, it will probably be for encoding
Unicode scalar values.</p>

<a name="stages"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#stages">Parsing stages</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.4</span></a></div></div>
<p class="asd_par">
Parsing is separated into three stages, conceptually.
Zoem knows two different parse scopes, plain scope and device scope.
These are mentioned below, and explained in the <a class="intern" href="#dichotomy">Scope dichotomy</a>
section. The three stages are:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
File read
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
Macro expansion / file inclusion - only plain scope is seen.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
Filtering - both plain scope and device scope are filtered.
Device directives that lay hidden in device scope
are interpreted during output.
</div>
</div>
<p class="asd_par">
A file is read in chunks, if possible. The requirement is that chunks must
end on lines and be in the outermost scope. The default minimum chunk size
is approximately one megabyte. Chunks are processed by recursively
chunking them into smaller chunks as dictated by macro expansion. As soon
as a chunk is no longer subject to macro expansion it is immediately
filtered and output.</p>
<p class="asd_par">
Macro expansion is done recursively. Whenever a macro is encountered, it is
replaced by its expansion, and the result is again fed to the parser.
Evaluatation is not necessarily lazy, that is, during macro expansion the
expander may expand arguments before they are interpolated and substituted in
the macro definition. This inside-out evaluation can recurse if necessary.
Many zoem primitives evaluate one or more of their arguments before use. The
default behaviour for user macros is lazy evaluation. This can be changed
however by wrapping both the macro and its arguments in <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>.
Expansion can be delayed using <a class="intern" href="#excl"><span class="zpr">\!</span></a> and <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>, so different arguments
can be treated differently.</p>
<p class="asd_par">
Important is that the result from the second stage is still
valid zoem input.
If you re-feed it to zoem, file read and macro expansion are usually no-ops
(unless some interpretation delay-magic was used), and the syntax is
garantueed to be acceptable to zoem. This is because device scope is not
touched during the first two stages, and device specific text (which is most
likely not conforming to zoem syntax) lies always hidden in that scope. There
are three kinds of escape sequences introducing device scope; these are
described in the <a class="intern" href="#dscope">Device scope</a> section.</p>
<p class="asd_par">
This is used for example when creating a table of contents; you can write
expanded but unfiltered content to a file and read it in during the
following run. It is important that such content is fully expanded,
because you want things like index numbers and references as
they are at the time of macro invocation. It is equally important that what
you read back in is still valid zoem input; this is simply achieved by
witholding filtering. When the table of contents is read in, it can be
subjected to filtering, and this is the right way to do toc stuff in Zoem.</p>

<a name="fileread"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#fileread">File read</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.5</span></a></div></div>
<p class="asd_par">
File read - stripping comments, reading inline files.</p>
<p class="asd_par">
Zoem searches for files included via
<a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> or one of its built-in aliases in a number of places if
it cannot find the file in the current directory.
The precise way of searching is documented in section <a class="intern" href="#searchpath">File search path</a>.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style=""><tt>\:</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
In most cases, this sequence introduces a comment, namely
where it is followed by whitespace, an alphanumeric character, or a
backslash. It introduces a comment up until and excluding the next newline,
which is stripped.</p>
<p class="asd_par">
The sequence <tt>\:{/}</tt> introduces a comment up till and including
the newline. This feature can be
useful within the <a class="intern" href="#protect_1"><span class="zpr">\protect#1</span></a> primitive, as it is the only way to delete
actual newlines within the argument of that primitive.</p>
<p class="asd_par">
The sequence <tt>\:{!}</tt> is replaced by a backslash. The single
use currently known is to make it easy to quote zoem input containing
comment sequences. This</p>
<div class="verbatim">\protect{\foo
   \bar  
   \zut     \:{!}:  this will end up as a comment.
}</div>
<p class="asd_car">
will result in the following</p>
<div class="verbatim">\foo
   \bar  
   \zut     \:  this will end up as a comment.</div>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>\={fname}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
starts inline file named fname at the next line, removes remainder of line
after the <tt>\={fname}</tt> sequence. When using the <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> primitive or
one of its four built-in aliases, an inline file takes precedence over
regular files in the file system, whether it is present (as a regular file)
or not. See below. This feature can be used to ship zoem input in one piece
while putting the macro parts at the end. <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a> can address inline
files as well, but <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> cannot. The reason for this is that inline
files have to satisfy zoem syntax, whereas <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> can be used to
read arbitrary data.</p>
<p class="asd_par">
The future will probably bring a zoem option that creates
such a self-contained file automatically from the zoem
entry file.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style=""><tt>\==</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
ends inline file, removes remainder of line.</p>
</div>
</div>
<p class="asd_par">
The above applies to any file read at any stage. Inline files may occur in
any file included at any time, but they do not nest.</p>
<p class="asd_par">
The <i>zoem entry file</i> is the single file that is specified
on the command line. This is the main file, from which other
files can be included if desired.</p>
<p class="asd_par">
Zoem entry files usually have the extension <tt>.azm</tt>, which is memnonic
for <b>A ZoeM</b> file. This is required if the <tt>-i</tt> option is used.
Arbitrary entry file names can be specified using the <tt>-I</tt> option.
It is not uncommon to generate sibling files with
<tt>.roff</tt>, <tt>.html</tt>, <tt>.zmt</tt> (zoem table of contents), and
<tt>.zmr</tt> (zoem references) extensions &mdash; however, this is all configurable
in user space and not part of zoem itself. There are no restrictions on
names of files that are included from the entry file. Inclusion is done
recursively.</p>
<p class="asd_par">
The future will probably bring a second extension that is allowed,
namely <tt>.ezm</tt> for <b>Expanded ZoeM</b> file, which is a self-contained
file in which every included file is present as an inline file.</p>

<a name="searchpath"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#searchpath">File search path</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.6</span></a></div></div>
<p class="asd_par">
If zoem cannot find a file in the current directory, it attempts
to find the file in one of three different ways. These are,
in the order in which they are attempted:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The environment variable <tt>$ZOEMSEARCHPATH</tt> is checked. It may
contain a listing of paths separated by whitespace or colons.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The zoem variable <a class="intern" href="#session"><tt>\__searchpath__</tt></a> is checked. It must contain a listing
of paths stored as a vararg, i.e. a sequence of paths where each path is
delimited by curly brackets. <b>DO NOT</b> overwrite this variable, but
rather append or prepend to it. Most likely zoem was configured and compiled
locally on your system, in which case <a class="intern" href="#session"><tt>\__searchpath__</tt></a> contains the path
necessary to find the macro packages <tt>man.zmm</tt>, <tt>faq.zmm</tt>, and
<tt>ref.zmm</tt>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The path of the file currently being parsed is used.
Assume that file <tt>foo</tt> contains <tt>\import{/a/b/c/bar}</tt>.
If file <tt>bar</tt> wants to include file <tt>zut</tt>, which is in
the same <tt>/a/b/c/</tt> directory, it need not prepend a path
but can just issue <tt>\import{zut}</tt>. Should the
previous search mechanisms fail to find zut, then zoem will
as a last resort deduce the path from <tt>/a/b/c/bar</tt>.
This feature is probably rarely needed, if ever at all.</p>
</div>
</div>

<a name="macro"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#macro">Macro expansion</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.7</span></a></div></div>
<p class="asd_par">
Macro expansion consists of recursive file inclusion and macro expansion.
All zoem primitives and user keys are recursively expanded
until none remains. Zoem primitives and user keys take one
of the following forms:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>\abc_0123_</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A key with alphanumerics and underscores only. Ends with
any other character. All zoem primitives but one have this form.</p>
<p class="asd_par">
Note: <tt>\_</tt> denotes an anonymous key, see the <a class="intern" href="#anonymous">Anonymous keys</a> section.</p>
<p class="asd_par">
These keys live in the <i>user</i> dictionary stack. Initially, there is
only one dictionary. The stack can be manipulated using the <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a>
and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a> primitives.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>\"abc::def-ghi.jkl,mno+qrs"</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A quoted key. Almost anything inbetween quotes is allowed. Always
ends with a quote. No zoem primitive has this form.
These keys live in the same <i>user</i> dictionary stack
as the keys above.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>\$abc_0123_</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
A key introduced with a dollar sign. The name may further consist
of alphanumerics and underscores and it ends with any other character.
These keys live in the <i>dollar</i> dictionary stack.
A dictionary is pushed with every occurrence of
<a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>, and that dictionary is popped with the corresponding
occurrence of <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a>.</p>
<p class="asd_par">
Further note: <a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a> is a zoem primitive.</p>
</div>
</div>
<p class="asd_par">
All three types of keys may take arguments, and overloading is allowed:</p>
<div class="verbatim">   \foo                          \: signature foo
   \foo{bar}                     \: signature foo#1
   \foo{bar}{bop}                \: signature foo#2
   \$foo{bar}{baz}               \: signature $foo#2
   \"foo::oof"{zut}{zit}{zot}    \: signature "foo::oof"#3</div>
<p class="asd_car">
is an ensemble of valid and unique keys, which can be defined for
example by</p>
<div class="verbatim">\def{foo}{FOO}
\def{foo#1}{The FOO of \1}
\def{foo#2}{The FOO of \1 and \2}
\def{$foo#2}{The $FOO of \1 and \2}
\def{"foo::oof"#3}{\foo{\1}{\2}\foo{\2}{\3}}</div>
<p class="asd_car">
Additionally, zoem allows the definition of <i>constant keys</i> that map
directly into device space and are ignored during macro expansion. Usage of
such keys looks like <tt>\*{'e}</tt> or <tt>\*{(c)}</tt> and is detailed later on.</p>
<p class="asd_par">
A sequence&nbsp;<tt>\k</tt> where k is in 1-9 is allowed within anonymous keys (as
used for example in <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> and <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>) and in the definition
argument of the <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> primitive and its siblings <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>,
<a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, and <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>. It indicates the position(s) where arguments
should be interpolated.
<b>Note</b> during interpolation, positional parameters that are enclosed by
the <i>delay scope</i> <tt>\!{..}</tt> will not be interpolated (see <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>).
The status of this feature is not entirely clear.</p>
<p class="asd_par">
A feature that should only rarely be needed is that zoem allows
name scopes. Refer to the <a class="intern" href="#dictionary">Dictionary stacks</a> section.</p>

<a name="section_5_8"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#section_5_8">File inclusion</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.8</span></a></div></div>
<p class="asd_par">
There is one zoem primitive which has four different uses. For each
of those uses, a built-in alias exists.</p>
<div class="verbatim">\dofile#2 use      alias          meaning

\dofile{expr}{!+}  \input{expr}   require file, interpret and output
\dofile{expr}{!-}  \import{expr}  require file, interpret only
\dofile{expr}{?+}  \read{expr}    permit absence, interpret and output
\dofile{expr}{?-}  \load{expr}    permit absence, interpret only</div>
<p class="asd_car">
The <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> primitive and its four aliases are perhaps a little funny
interface-wise &mdash; better ideas are welcome. The <tt>expr</tt> argument is
<i>digested</i>, that is, expanded until no macro's remain. It is thus possible
to specify <a class="intern" href="#session"><tt>\__fnbase__.zmt</tt></a> and include a table of contents file that has
been written to in a previous run. <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> and its aliases have the
property that zoem really descends into the files, and on error will emit a
message containing the approximate line number where it occurred.</p>
<p class="asd_par">
Additionally, the contents of a file can be placed inline using
<a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> and <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>.</p>
<p class="asd_par">
Note: wherever <tt>key</tt> is written, it means that something
of the form <tt>\foo</tt>, <tt>\$foo</tt>, or <tt>\"foo"</tt> has to
be provided, so you would use <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> e.g. as
<tt>\setx{foo}{\finsert{\__fnbase__.zyx}}</tt>.</p>

<a name="protection"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#protection">Protection</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.9</span></a></div></div>
<p class="asd_par">
The <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> primitive requires that the files to be included
satisfy zoem syntax. It will descend into the files and proceed parsing
them.</p>
<p class="asd_par">
The <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> and <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a> primitives do not descend,
but rather act as if the contents of the file specified were pasted
into the place of macro invocation.</p>
<p class="asd_par">
<a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> will <i>protect</i> the contents of the inserted file,
that is, all backslashes and curlies are escaped by preprending
them with a backslash.
<a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a> will include the file unchanged, assuming that its
contents satisfy zoem syntax.</p>
<p class="asd_par">
The <a class="intern" href="#system_3"><span class="zpr">\system#3</span></a> primitive is able to pipe data to a system command's
<span class="smallcaps">STDIN</span> stream and retrieve data from the command's <span class="smallcaps">STDOUT</span> stream.
This primitive will <i>unprotect</i> the data it sends, and it will
protect the data it receives.
<b>Note</b> the security implications of this feature
as discussed at the <a class="intern" href="#system_3"><span class="zpr">\system#3</span></a> entry.</p>
<p class="asd_par">
Data can be explicitly protected using the <a class="intern" href="#protect_1"><span class="zpr">\protect#1</span></a> primitive.</p>
<p class="asd_par">
Protected data can (currently) never result in it being expanded
again. This is because escaped backslashes are only interpreted
at filter time, and never during expansion.
If you only need <i>temporary</i> delay of expansion, use
the <a class="intern" href="#excl"><span class="zpr">\!</span></a> primitive or the <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a> primitive.</p>

<a name="dichotomy"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#dichotomy">Scope dichotomy</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.10</span></a></div></div>
<p class="asd_par">
Zoem knows two parse scopes: <b>plain scope</b> and <b>device scope</b>. The
latter is also called 'at scope' because <tt>\@{..}</tt> is one (but not the only)
way of entering device scope. In plain scope, every character
represents itself as a glyph, i.e. as something that should show that way in
print/on screen (after the zoem output/device input is fed to the device
interpreter).</p>
<p class="asd_par">
For example, if you write the less than sign&nbsp;<tt>&lt;</tt> in plain scope,
it should show up as a readable less than glyph, like in
this very sentence. In order to make this happen, zoem provides
the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive, so that the less than sign can be
automatically mapped to the html entity sequence <tt>&amp;lt;</tt>.</p>
<p class="asd_par">
In device scope, nothing is mapped except for a double backslash should it
occur. If you enter this particular sequence of mixed scope:
<tt>\@{&lt;b&gt;}&lt;hello world&gt;\@{&lt;/b&gt;}</tt> as zoem input,
the zoem output/device input is (provided the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a>
primitive was correctly used for the html device):
<tt>&lt;b&gt;&amp;lt;hello world&amp;gt;&lt;/b&gt;</tt>
and what you finally see on screen is:
<b>&lt;hello world&gt;</b>.
In device scope, every character (except for the escape sequences available
in that scope) represents itself as the character that should be
present in the zoem output/device input. Device scope should normally only
be seen in macros and not in running zoem input.</p>
<p class="asd_par">
In plain space you type characters just as you want to see them eventually
&mdash; when you read the document after the zoem output was run through a device
interpreter (such as a browser or printer, or postscript previewer).
The only exceptions are the backslash and the two curlies, these should
be entered as&nbsp;<tt>\}</tt>, <tt>\{</tt>, and&nbsp;<tt>\}</tt>, respectively.
Those escape sequences are interpreted as the characters or glyphs
<tt>\</tt>, <tt>{</tt>, and&nbsp;<tt>}</tt>. For all characters, including these
three, it is checked whether they should be further mapped according to the
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive. If a mapping is found, it is retrieved
and interpreted by the device scope filter. Read on.</p>

<a name="dscope"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#dscope">Device scope</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.11</span></a></div></div>
<p class="asd_par">
There are three kind of strings which are interpreted by the
generic device filter, and which are said to live in device scope:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The strings embedded in <tt>\@{..}</tt> sequences.<br></p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The strings mapped to by the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive, including
mappings of the zoem glyphs&nbsp;<tt>\~</tt>, <tt>\|</tt>, and&nbsp;<tt>\-</tt>.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The strings mapped to by the <a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a> primitive.</p>
</div>
</div>
<p class="asd_par">
In a macro package that is meant to work for multiple devices, every use of
any of these constructs will typically be embedded in something that tests
the value of the active device. This can be done using either <a class="intern" href="#cmp_3"><span class="zpr">\cmp#3</span></a>
with <a class="intern" href="#if_3"><span class="zpr">\if#3</span></a>, <a class="intern" href="#switch_1"><span class="zpr">\switch#1</span></a>, or <a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a>, in conjuction with the
pre-defined zoem key <a class="intern" href="#session"><tt>\__device__</tt></a>, containing the name of the active
device (which can be specified on the command-line). The following are
equivalent:</p>
<div class="verbatim">   \if{\cmp{eq}{\__device__}{html}}{ \@{&lt;!-- (c) foo bar --&gt;} }{}

   \: is equivalent with

   \${html}{ \@{&lt;!-- (c) foo bar --&gt;} }</div>
<p class="asd_car">
The <a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a> primitive is used if something needs to be done for one
device only, and it may occasionally appear in documents. For example, the
<a target="_parent" class="extern" href="http://micans.org/pud/"><acronym class="ucase" title="Portable Unix Documentation">PUD</acronym></a>
man macros enable the creation of a table of contents (for both html
and troff). My own convention is to have a table of contents only in html,
and I specify this using the sequence</p>
<div class="verbatim"><tt>\${html}{\"man::maketoc"}</tt></div>
<p class="asd_car">
When zoem enters device scope, it
outputs all characters literally, except that the backslash still has
special meaning. It is used for encoding the backlash itself (as
<tt>\\</tt>), and for encoding the two curlies&nbsp;<tt>{</tt> and&nbsp;<tt>}</tt> (as
<tt>\{</tt> and&nbsp;<tt>\}</tt>). This is the same as in plain scope (except that
in plain scope the resulting character may again be mapped onto something
else, for example, in troff the backslash also needs encoding as
<tt>\\</tt>).</p>
<p class="asd_par">
In device scope the sequence&nbsp;<tt>\"</tt> maps to a double quote.
This is an additional feature to allow zoem input to be more susceptible to
some editors moving features. It is not <i>necessary</i> though; simply using
the double quote without escaping it is sufficient.</p>
<p class="asd_par">
Additionally, the backslash can be followed by a single letter from a
prescribed set listed below. Such a backslash+letter combination is called a
<i>device directive</i>. By default, zoem will never print consecutive
newlines, and it will never print consecutive spaces or spaces at the
beginning of a line. The device directives allow this to be altered.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">N</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">garantuee a newline</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">P</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">garantuee a paragraph skip (two consecutive newlines)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">S</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">garantuee a space (except if next char is newline)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">I</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">increase indent by one (indent is printed after each newline)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">J</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">decrease indent by one</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">C</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">set indent to zero</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">n</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">print newline</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">s</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">print space</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">t</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">print tab</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">w</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">stop managing white space (squashing spaces and newlines)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">W</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">start managing white space (use after&nbsp;<tt>w</tt>)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">&amp;</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">start <i>and</i> scope (see further below)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">+</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">set the special level (see further below)</p>
</div>
</div>
<p class="asd_par">
Note that the directives mainly affect the lay-out of the device text (which
is zoem output), not the look of the interpreted device text. The '<tt>N</tt>'
directive is rather important when constructing troff macros, as many
special troff commands are encoded by a dot as the first character on a
line, i.e. a newline followed by a dot. Since troff attaches special meaning
to two consecutive newlines as well (interpreting it as a paragraph break),
zoem needs to be able to specify <i>print a newline only if the previous
character was not a newline</i>. This is exactly what the <tt>N</tt>&nbsp;directive
means. The '<tt>W</tt>' and '<tt>w</tt>' directives are required for enabling
the construction of a verbatim environment.</p>
<p class="asd_par">
The sequence <tt>\&amp;{&lt;almost any&gt;}</tt> can be used to avoid
overly cumbersome constructions. It is for example illegal
to write</p>
<div class="verbatim">\@{&lt;table width="\width"&gt;}</div>
<p class="asd_car">
In the early days of zoem, you had to write</p>
<div class="verbatim">\@{&lt;table width="}\width\@{"&gt;}</div>
<p class="asd_car">
&mdash; ugly by most standards. Today you write</p>
<div class="verbatim">\@{&lt;table width="\&amp;{\width}"&gt;}</div>
<p class="asd_car">
Which is not any shorter, but more pleasant to read.
What happens is that the contents of <i>and</i> scope <tt>\&amp;{..}</tt> is first
fully expanded in plain scope, after which the result is passed back to
device scope. You have to be careful though. The content of <tt>\&amp;{..}</tt>
should never expand to something containing the <i>at</i> sequence <tt>\@{..}</tt>,
because device scope is not allowed to nest. It should also not expand to
something containing the <i>and</i> sequence <tt>\&amp;{..}</tt> either, as this
sequence is illegal in plain scope.</p>

<a name="special"></a><div class="sec_leader sec_lev3"><div class="sec_title"><a class="intern" href="#special">Device scope resulting from mapping special characters</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.11.1</span></a></div></div>
<p class="asd_par">
The first kind of zoem escape introducing device scope is <tt>\@{..}</tt>.
The second kind comprises the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> mappings, including the
three zoem glyphs&nbsp;<tt>\~</tt>, <tt>\|</tt>, and&nbsp;<tt>\-</tt>. Conventionally, these
are used to encode a non-breaking space (<tt>&amp;nbsp;</tt> in html), a line break
(<tt>&lt;br&gt;</tt> in html), and a long dash (emdash, not present in html).
You would for example put</p>
<div class="verbatim">\if{\cmp{eq}{\__device__}{html}}{
   \special{
      {38}  {&amp;amp;}           \: 38 is ascii character '&amp;'
      {60}  {&amp;lt;}            \: 60 -&gt; '&lt;'
      {62}  {&amp;gt;}            \: 62 -&gt; '&gt;'
      {-1}  {&amp;nbsp;}          \: the zoem escape \~
      {-2}  {&lt;br&gt;\!N}          \: the zoem escape \|
      {-3}  {-}               \: the zoem escape \-
   }
}{  
}</div>
<p class="asd_car">
All <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> definitions are interpreted in device scope. For every
character encountered in plain scope, it is checked whether a
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> definition exists, if so, the corresponding string is
retrieved and this is filtered through the device scope filter.
Note that the three zoem glyphs described here
may not be used in device scope, they can only be used in plain scope. In
device scope you will have to write the explicit, device-specific sequence
such as <tt>&lt;br&gt;</tt> (in html).</p>
<p class="asd_par">
The <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive allows different levels of mappings
to be defined simultaneously. Several definitions of the same
character are allowed; these are placed on a stack particular
to that character (cf. the
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> entry).
When zoem encounters a character for which
one or more mappings exist, it retrieves a mapping
using the <i>special level</i>. This is an integer that has by
default the value&nbsp;<tt>1</tt>. Each open output stream has a unique
special level associated with it. [Output streams exist
for the <i>default output file</i> (see e.g. <a class="intern" href="#writeto_1"><span class="zpr">\writeto#1</span></a>) and
for each file openend by <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a>].
A mapping is retrieved using this rule: <i>The deepest element
is fetched for which the depth does not exceed the level</i>.
The most visible element (which is the element first occurring
in the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> invocation) has depth&nbsp;<tt>1</tt>.</p>
<p class="asd_par">
The presence of different levels comes in handy e.g. when the troff
device is used. In some contexts, the double quote
is a special character in troff (and a printable quote is then
mysteriously represented by <i>two consecutive double quotes</i>),
in most contexts it is not.
This is combatted by including these two specifications in the
<tt>\special#1</tt> call preparing for troff output (note that 34 is
the <abbr class="ucase" title="American Standard Code for Information Interchange">ASCII</abbr> value representing the double quote):</p>
<div class="verbatim">\special{
   ...
   {34}{"}
   {34}{""}
   {92}{\\e}
   ...
}</div>
<p class="asd_car">
The first pair shown simply maps the double quote onto itself, and the second
pair maps it onto a double double quote. As long as the special level
is&nbsp;<tt>1</tt>, the second definition is not used. The backslash (with <abbr class="ucase" title="American Standard Code for Information Interchange">ASCII</abbr> value
<tt>92</tt>) needs only one definition as it is escaped in the same way in all
troff contexts.</p>
<p class="asd_par">
The special level can
be set using the <tt>\+</tt>&nbsp;directive, which must be followed
immediately by a digit in the range <tt>0-9</tt> enclosed by curly brackets,
e.g. <tt>\@{\+{2}}</tt> will set the special level to <tt>2</tt>.
The special level <i>can</i> be set to&nbsp;<tt>0</tt> (zero) and this means
that no character will be mapped.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span>
Double quotes need to be escaped in certain troff contexts.
This is achieved by the following.</p>
<div class="verbatim">\@{\+{2}"} ... funny quote context ... \@{"\+{1}}</div>
<p class="asd_car">
Such a context is typically encapsulated by a macro defined in a package; its
definition should never be visibile to the user of the package.
Note that the double quotes embedded in <i>at</i> scope in the example
above are not susceptible to special mapping &mdash; mapping is only
applied in plain scope.</p>

<a name="glyph"></a><div class="sec_leader sec_lev3"><div class="sec_title"><a class="intern" href="#glyph">Device scope resulting from glyph definitions</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.11.2</span></a></div></div>
<p class="asd_par">
The third kind of device scope strings are those mapped to by the
<a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a> primitive. An example of (toy) usage is this:</p>
<div class="verbatim">\constant{
   {'e}  {&amp;eacute;}     \: Use e.g. as \*{'e}l\*{`e}ve (&eacute;l&egrave;ve)
   {(c)} {&amp;copy;}       \: Use e.g. as \*{(c)} DEEDEE (&copy; DEEDEE)
   {+-}  {&amp;plusmn;}     \: Use e.g. as \*{+-} a few (&plusmn; a few)
}</div>
<p class="asd_car">
This is largely convenient syntactic sugar. These constants
could also have been defined as</p>
<div class="verbatim">   \def{"'e"}{\@{&amp;eacute;}}
   \def{"(c)"}{\@{&amp;copy;}}
   \def{"+-"}{\@{&amp;plusmn;}}</div>
<p class="asd_car">
The idea is that the <tt>\*{..}</tt> namespace is used for glyph-like
device-specific bindings, whereas the <tt>\".."</tt> namespace is used for
semantic purposes that are device-independent, but nothing prohibits you
from fiddling with this.</p>

<a name="xmlsugar"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#xmlsugar"><abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>/<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>/<abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntactic sugar cubes</a></div><div class="sec_num"><a class="intern" href="#toc5"><span class="sec_num">5.12</span></a></div></div>
<p class="asd_par">
Zoem provides a shorthand for entering <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>-style tags.
It is checked by zoem for well-formedness of the resulting <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr> code,
and it can be freely mixed with other modes of entering tags.
Normally you would
have to enter <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>-style tags in device scope,
or write a macro for doing that.
For example,
a macro <tt>x#2</tt> that expands <tt>\x{b}{be bold}</tt> to
<tt>\@{&lt;b&gt;}be bold\@{&lt;/b&gt;}</tt> is a likely candidate.
However, this would be inelegant for constructions that span
a long distance, and it does not provide for letting zoem expressions
expand within an xml tag.</p>
<p class="asd_par">
Zoem provides the <tt>\&lt;</tt> token. It can be used in several ways:</p>
<div class="verbatim">
   \&lt;foo&gt;            \: foo can be an expression.
      Some &lt;content&gt; \: of course, expressions may occur here as well.
      over here.
      \&lt;bar&gt;{zut}    \: bar can be an expression too;
                     \: this syntax will close itself.
      Some &lt;content&gt; \: again, expressions may occur here as well.
      over there.
   \&lt;&gt;               \: this is a closing tag for the first foo. \&lt;/foo&gt; works too.

   \&lt;tim x=y/&gt;       \: zoem knows this closes itself.
   \&lt;*br&gt;            \: zoem converts this to &lt;br&gt;
</div>
<p class="asd_car">
Suppose that foo, bar, and zut are zoem expressions expanding
to strings FOO, BAR, and ZUT respectively (FOO and BAR might be of the form
<tt>tag a="b" c="d"</tt>). Provided that the characters&nbsp;<tt>&lt;</tt>, <tt>&gt;</tt>,
and&nbsp;<tt>&amp;</tt> are automatically mapped in plain scope (as a result of correct
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> usage), the above will result in</p>
<div class="verbatim">   &lt;FOO&gt;
      Some &amp;lt;content&amp;gt;
      over here.
      &lt;BAR&gt;
         ZUT
      &lt;/BAR&gt;
      Some &amp;lt;content&amp;gt;
      over there.
   &lt;/FOO&gt;

   &lt;tim x=y/&gt;
   &lt;br&gt;</div>
<p class="asd_car">
The <tt>foo</tt> part inside the <tt>\&lt;foo&gt;</tt> syntax should never expand to
something containing a&nbsp;<tt>&gt;</tt>. This is entirely the responsibility of the
user or macro package author.</p>
<p class="asd_par">
Both kinds of syntax, <tt>\&lt;foo&gt;</tt> and <tt>\&lt;bar&gt;{zut}</tt>, are kept as they are
during the expansion stage, and they can be subjected to multiple levels of
expansion (which may be the case if such syntax is used inside e.g.
<a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> or <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>). It is only at the output stage that the
syntax is transformed to actual <abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr> code and that well-formedness is
checked. So, the two examples just seen will first transform to <tt>\&lt;FOO&gt;</tt>
and <tt>\&lt;BAR&gt;{ZUT}</tt> (please note that foo, bar, and zut all denote
expressions here). If they are at that point no longer subject to expansion
they enter the output stage where they are converted to <tt>&lt;FOO&gt;</tt> and
<tt>&lt;BAR&gt;ZUT&lt;/BAR&gt;</tt> (plus some additional formatting/indenting)
respectively.</p>
<p class="asd_par">
Zoem pushes on a stack of opening tags whenever it encounters <tt>\&lt;foo&gt;</tt>
syntax during the output stage. It naturally knows that a tag can be
followed by attributes. It also knows that a tag such as <tt>\&lt;tag a=b/&gt;</tt>
closes itself (<abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntax), and the applies for <abbr class="ucase" title="Document Type Definition">DTD</abbr> tags such as
<tt>\&lt;!ENTITY ...&gt;</tt>. As a special case, <tt>\&lt;*tag foo bar zut&gt;</tt> is converted
to <tt>&lt;tag foo bar zut&gt;</tt> to allow encoding of <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr> tags such as <tt>&lt;meta&gt;</tt>,
<tt>&lt;link&gt;</tt>, and <tt>&lt;hr&gt;</tt>. This syntax is mandatory for tags that will not be
closed. Note that you should only use <tt>\&lt;p&gt;</tt> if you are going to use
<tt>\&lt;/p&gt;</tt> or <tt>\&lt;&gt;</tt> as well (because zoem requires closing tags for opening
tags). That said, the syntax <tt>\&lt;p&gt;{ paragraph content }</tt> is preferable in
most cases.
</p>
<p class="asd_par">
Zoem does not know about other ways of entering tags, so
<tt>\@{&lt;body&gt;}</tt> would not affect the stack just mentioned.
<tt>\&lt;&gt;</tt> automatically closes
the top level opening tag from the stack. Again, syntax such as
<tt>\@{&lt;/body&gt;}</tt> does not interact with the stack.
</p>
<p class="asd_par">
It is possible to explicitly close a tag by simply using <tt>\&lt;/foo&gt;</tt>
syntax. Zoem will check whether the closing tag matches the top level
opening tag. As seen before, <tt>\&lt;&gt;</tt> does the same thing, but rather than
doing a check, zoem will use the top level opening tag to construct the
corresponding closing tag.</p>

<a name="section_6"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#section_6">Zoem miscellanea</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6</span></a></div></div>

<a name="signature"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#signature">Key signatures</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.1</span></a></div></div>
<p class="asd_par">
Several keys take another key as argument, e.g. they store a value in a
second key or check whether the second key exists. The full list of these
meta keys is <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>, <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>,
<a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a>, <a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a>, <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>, and <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>. In all
cases, the argument key is passed as the first argument, by means of the
<b>key signature</b>.</p>
<p class="asd_par">
For a key <tt>\key</tt> taking <tt>k</tt>&nbsp;(<tt>k</tt>&gt;0) arguments its signature is
<tt>key#k</tt>. The signature of a key <tt>\key</tt> taking no arguments is simply
<tt>key</tt>. The rule is: Key usage always includes a single
leading backslash (this activates the key). When a key is subject
of inspection, it is always referred to by its signature.</p>
<p class="asd_par">
Throughout this text, a key with signature <tt>key#k</tt> is mentioned
by means of its <b>key mention</b> <tt>\key#k</tt>, that is, for extra clarity
the backslash is prepended to the signature.</p>
<p class="asd_par">
As explained in <a class="intern" href="#namespaces">Primitives, built-ins and user macros</a>, almost all primitives
can be specified using quote syntax. The quote syntax is
integrated with signatures. This means that primitives that
expect a signature (such as <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, <a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a>, and <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>)
accept quoted signatures too when the signature refers to
a primitive.</p>

<a name="anonymous"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#anonymous">Anonymous keys</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.2</span></a></div></div>
<p class="asd_par">
A single underscore introduces an <b>anonymous key</b>. It is optionally
followed by a <tt>#k</tt> tag (for&nbsp;<tt>k</tt> in&nbsp;<tt>1..9</tt>), denoting the number of
arguments the anonymous key takes. An occurrence of the latter is called a
<b>tagged anonymous key</b>. The first argument to the key should be a key
definition, the other arguments are the arguments for that key definition.
If a tag is present, it is used for verifying that the anonymous key is used
properly.</p>
<div class="verbatim">   \_{\1 the \2}{row}{boat}
   \_#2{\1 the \2}{row}{boat}</div>
<p class="asd_car">
results in</p>
<div class="verbatim">   row the boat
   row the boat</div>
<p class="asd_car">
Anonymous keys may occur in the first argument of <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>, within the
first argument of <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>, and they may occur freely in running text.
The presence of a tag is required when an anonymous key is used
within either of <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> and <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>.
An example of usage in <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>:</p>
<div class="verbatim">\apply{_#2{\1 kisses \2\|}}{{bill}{max}{max}{bill}}
bill kisses max
max kisses bill</div>
<p class="asd_car">
or even</p>
<div class="verbatim">\set{%foo}{{{\1 hugs \2\|}}}
\apply{_#2\%{foo}}{{bill}{max}{max}{bill}}
bill hugs max
max hugs bill</div>
<p class="asd_car">
Note that in order to store a block with <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, an extra pair of
curlies has to be used, as blocks can only be passed as a sub-argument of a
single-element <a class="intern" href="#vararg">vararg</a>. Also note that in a vararg it is
allowed to put white space inbetween the constituting elements.</p>

<a name="grape"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#grape">Tree data</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.3</span></a></div></div>
<p class="asd_par">
Data can be organized in a global tree with a specialized use of
<a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> and its siblings, as shown further below.
The data is retrieved from the tree using so called data keys.
Such a key is started using a percent sign, immediately followed
by zero, one, or more blocks, e.g. <tt>\%</tt>, <tt>\%{..}</tt>, and
<tt>\%{...}{...}{...}</tt> would all be allowable invocations.
If more than one block follows the percent sign,
there must be no interleaving white space.</p>
<p class="asd_par">
The underlying primitive has signature <tt>%#1</tt>, as the trailing scopes are
congregated into a single argument before they are further processed. The
two sibling primitives <tt>%free#1</tt> and <tt>%dump#1</tt> serve for freeing and
dumping parts or whole of the tree, as described further below.</p>
<p class="asd_par">
When applied to data keys, <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> and its siblings set one or more
values in a global multi-dimensional associative array that we shall refer
to here as <tt>ROOT</tt>. Please note that <tt>ROOT</tt> is for explanatory purposes
only. This associative array is best viewed as a tree, in which every node
can have branches to higher nodes. A node may or may not contain a value.
Let us denote the value contained by a node <tt>some-node</tt> as
<tt>*(some-node)</tt>.
The fact that <tt>beta</tt> is a node one branch higher than <tt>alpha</tt>, which is
in turn one branch higher than <tt>ROOT</tt>, is denoted as
<tt>ROOT-&gt;"alpha"-&gt;"beta"</tt>.
In this <i>path</i> notation, strings indexing nodes in the trees are written
inbetween quotes. This has the advantage that the empty string, which is a
valid index string, has the representation <tt>""</tt>. Combining these
conventions, we write the value associated with <tt>beta</tt> as
<tt>*(ROOT-&gt;"alpha"-&gt;"beta")</tt>.
Consider these examples.</p>
<div class="verbatim">\set{%{foo}{bar}{zut}}{lez}
      \: now *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut") is "lez"

\set{%{foo}{bar}{zut}}{{a}{b}{x}{y}}
      \: now *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut"-&gt;"a") is "b"
      \: and *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut"-&gt;"x") is "y"
      \: and *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut") still is "lez"

   \: some special cases
\set{%{foo}{bar}{zut}}{{{c}}}
      \: now *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut") is "{c}"
\set{%{foo}{bar}{zut}}{{c}}
      \: now *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut") is "c"
\set{%{foo}{bar}{zut}}{c}
      \: now *(ROOT-&gt;"foo"-&gt;"bar"-&gt;"zut") is "c"

\set{{foo}{bar}{zut}}{{c}{d}{e}}
      \: This does nothing, because the second argument
      \: must either be an *even* vararg, a 1-element vararg,
      \: or a simple argument.

\set{%{{tiger}}}{in the woods}
      \: now *(ROOT-&gt;"{tiger}") is "in the woods"
\set{%{tiger}}{in the woods}
      \: now *(ROOT-&gt;"tiger") is "in the woods"
\set{%tiger}{on the loose}
      \: now *(ROOT-&gt;"tiger") is "on the loose"
      \: stripping curlies from a vararg with one argument
      \: does not make a difference with the exception of
      \: the case shown below.

\set{%{}}{empty}
      \: now *(ROOT-&gt;"") is "empty".
\set{%}{root}
      \: now *(ROOT) is "root".</div>
<p class="asd_car">
Take note of the rule governing the second argument. If the first
non-white space character is a left curly, <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> expects a
vararg. The vararg must either be even or it must contain exactly
<i>one</i> argument.</p>
<p class="asd_par">
An even vararg is interpreted as a sequence of key-value pairs.
Each key induces a new branch from the node specified in the first
argument, and each value is associated with the node at the end of
that branch.
If the vararg contains exactly one argument, that argument is simply used as
a value. This is the only way to specify a block as the value.
If the first non-white space character is not a curly, <tt>\set#2</tt> will
simply interpret the second argument as a value to append to the node
specified in the first argument.
It is possible to sidestep these issues by using <a class="intern" href="#set_3"><span class="zpr">\set#3</span></a> and
the directive <tt>u</tt> as argument to the <tt>modes</tt> key. This will cause
the value to be copied without further interpretation as a vararg
or block.
</p>
<p class="asd_par">
If you want the data to be stored to be expanded before it is bound,
use <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> or <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>.</p>
<p class="asd_par">
Data is retrieved simply by prefixing the path with the <tt>\%</tt> token.
Example:</p>
<div class="verbatim">\set{%{foo}{bar}{zut}}{{a}{b}{x}{y}}
\%{foo}{bar}{zut}{a}
\%{foo}{bar}{zut}{x}</div>
<p class="asd_car">
will print <tt>b</tt> and <tt>y</tt>.
If the path is not an existing path in the current tree it will simply
be ignored, although an error message will be emitted.</p>
<p class="asd_par">
Whole or part of the data tree can be freed using the <tt>\%free</tt> primitive.
Again, simply append the access sequence in which you are interested. For
freeing the entire tree, use <tt>\%free</tt> without trailing scopes. The
<tt>\%free</tt> primitive largely exists for testing purposes to ensure that zoem
gets its internal data manipulation right.</p>
<p class="asd_par">
Whole or part of the data tree can be output for debugging purposes using
the <tt>\%dump</tt> primitive. Simply append the access sequence in which you are
interested. For printing the entire tree, use <tt>\%dump</tt> without trailing
scopes. This can be used for debugging if your data manipulation does not
work out as expected. There is no result text as far as usual processing is
concerned. The underlying primitive dumps its findings to <span class="smallcaps">STDOUT</span> in a
line-based textual representation of the data-tree.</p>

<a name="vararg"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#vararg">Of blocks and varargs</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.4</span></a></div></div>
<p class="asd_par">
A <b>block</b> is a string beginning with a left curly and ending with a right
curly, the curlies being balanced. This is a convenient naming
convention. Blocks can be used in constructing anonymous keys; refer to the
<a class="intern" href="#anonymous">Anonymous keys</a> section.</p>
<p class="asd_par">
Some keys take a <i>vararg</i> argument, which is a single argument (enclosed
by curlies as are all arguments), which can contain any number of
sub-arguments, that is, a list consisting of blocks. Inbetween the blocks
white space may occur. The <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> and <a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a> keys both
take a single vararg argument, and the <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> and <a class="intern" href="#switch_2"><span class="zpr">\switch#2</span></a> keys
each take a vararg as their second argument. For <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> the first
argument is a key that is applied to subsequent batches of arguments from
that vararg. The <a class="intern" href="#table_5"><span class="zpr">\table#5</span></a> primitive takes a vararg as its last
argument. For examples, see the <a class="intern" href="#tour">A zoem tour</a> section and the <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>
entry.</p>
<p class="asd_par">
An <b>even vararg</b> is a vararg with an even number of elements,
An <b>odd vararg</b> is a vararg with an odd number of elements.</p>
<p class="asd_par">
User keys may check whether an argument is a vararg
by employing the <a class="intern" href="#nargs_1"><span class="zpr">\nargs#1</span></a> primitve. This can be used to
take different actions depending on the structure of the argument.</p>

<a name="session"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#session">Session keys</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.5</span></a></div></div>
<p class="asd_car">
This is a compact listing of session keys, created
by issuing <tt>zoem -l session</tt>.</p>
<div class="verbatim">
Predefined session variables
\$__args__       (local to env) key/value pairs given to \begin#2
\$__xargs__      (local to env) key/value pairs given to \begin#2, expanded
\__device__     name of device (given by -d)
\__fnbase__     base name of entry file (given by -i/-I)
\__fnentry__    name of entry file (given by -i/-I)
\__fnin__       name of current input file
\__fnout__      name of current output file
\__fnpath__     path component of entry file (given by -i/-I)
\__fnwrite__    arg1 to \write#3, accessible in arg3 scope
\__lc__         expands to a left curly (only for magic)
\__line__       index of current input line
\__parmode__    paragraph slurping mode for interactive sessions
\__rc__         expands to a right curly (only for magic)
\__searchpath__ search path for macro packages (e.g. man.zmm)
\__split__      user space toggle for chapter mode indicator
\__sysval__     exit status of last system command
\__version__    version of zoem, formatted as e.g. 2003, 2004-010
\__zoemput__    result text of last \try#1 key
\__zoemstat__   status of last \try#1 key</div>
<p class="asd_car">
This manual is littered with examples of the usage of <a class="intern" href="#session"><tt>\__device__</tt></a>. The
<a class="intern" href="#session"><tt>\__fnbase__</tt></a> key is useful for creating sibling files of the entry file,
i.e. a table of contents file or a file containing reference information. I
have the habit of naming those <a class="intern" href="#session"><tt>\__fnbase__.zmt</tt></a> and <a class="intern" href="#session"><tt>\__fnbase__.zmr</tt></a>,
respectively. The <a class="intern" href="#session"><tt>\__fnin__</tt></a> key is useful for emitting log, warning, or
error messages particular to the file currently being parsed. The
<a class="intern" href="#session"><tt>\__parmode__</tt></a> macro affects the way in which zoem reads chunks in
interactive mode (refer to Section&nbsp;<a class="intern" href="#cline">Invoking zoem from the command line</a>). The <a class="intern" href="#session"><tt>\__searchpath__</tt></a>
macro is one of the ways in which zoem can be instructed to search for files
in a set of locations, when confronted with <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> or one of its
built-in aliases. Section&nbsp;<a class="intern" href="#searchpath">File search path</a> has more information about
the mechanism of file location. See also <a class="local sibling" href="zoem.html#session">the zoem
manual</a>.</p>

<a name="builtin"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#builtin">Built-in macros</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.6</span></a></div></div>
<p class="asd_par">
This is the result from doing <tt>zoem -l builtin</tt>:</p>
<div class="verbatim">
Built-in aliases
done            maps to   \'throw{done}
ifdef#3         maps to   \'if{\defined{\1}{\2}}{\3}{}
ifdef#4         maps to   \'if{\defined{\1}{\2}}{\3}{\4}
input#1         maps to   \'dofile{\1}{!+}
import#1        maps to   \'dofile{\1}{!-}
read#1          maps to   \'dofile{\1}{?+}
load#1          maps to   \'dofile{\1}{?-}
begin#1         maps to   \'begin{\1}{}
env#3           maps to   \'env{\1}{}{\2}{\3}
system#2        maps to   \'system{\1}{\2}{}
system#1        maps to   \'system{\1}{}{}
throw#1         maps to   \'throw{\1}{}
inform#1        maps to   \'write{stderr}{device}{\1\@{\N}}
append#2        maps to   \'set{{modes}{a}}{\1}{\2}
appendx#2       maps to   \'set{{modes}{ax}}{\1}{\2}
seq#4           maps to   \'set{\1}{\2}\'while{\'let{\'get{''}{\1}&lt;\3}}{\4\'setx{\1}{\'let{\'get{''}{\1}+1}}}
update#2        maps to   \'set{{modes}{e}}{\1}{\2}
updatex#2       maps to   \'set{{modes}{ex}}{\1}{\2}
""              maps to      (nothing)
""#1            maps to      (nothing)
group#1         maps to   \1
PI              maps to   3.1415926536
E               maps to   2.71828182846
$#1             maps to   \'switch{\__device__}{\1}
$#3             maps to   \'switch{\__device__}{{\1}{\2}{\3}}</div>

<a name="dictionary"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#dictionary">Dictionary stacks</a></div><div class="sec_num"><a class="intern" href="#toc6"><span class="sec_num">6.7</span></a></div></div>
<p class="asd_par">
By default, when using <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> and <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, keys and their values are
put in a global user dictionary. It could be useful to shadow keys by
entering a new name scope. Zoem facilitates this by providing the
<a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a> keys. These push and pop a new dictionary onto/from
the user dictionary stack.</p>
<p class="asd_par">
A second dictionary stack is the <i>dollar dictionary stack</i>, which
contains all keys that start with a dollar sign.
The <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> primitive pushes a dollar dictionary each
time it is invoked, and that dictionary is popped by the corresponding
<a class="intern" href="#end_1"><span class="zpr">\end#1</span></a> invocation. This is typically useful for creating nested
environments that need access to the same type of information - by storing
such information in dollar keys, it can be shadowed and recovered. Refer to
the <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> entry.</p>
<p class="asd_par">
When a key is used its definition is searched in all dictionaries, starting
from the top-level dictionary. The key <a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a> has only access to the
top-level dictionary, and will never delete a key in any other dictionary.</p>

<a name="tour"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#tour">A zoem tour</a></div><div class="sec_num"><a class="intern" href="#toc7"><span class="sec_num">7</span></a></div></div>
<p class="asd_par">
What follows is an informal tour through zoem's offerings. The next
section contains a comprehensive overview of the zoem primitives.</p>
<p class="asd_par">
Let us start with how filtering in plain space is configured.
The following was obtained from the
<a target="_parent" class="extern" href="http://micans.org/pud/"><acronym class="ucase" title="Portable Unix Documentation">PUD</acronym></a> man macros.</p>
<div class="verbatim">\switch{\__device__}{
   {html}{
      \special{
         {38}  {&amp;amp;}
         {60}  {&amp;lt;}
         {62}  {&amp;gt;}
         {-1}  {&amp;nbsp;}          \: the zoem escape \~
         {-2}  {&lt;br&gt;\!N}          \: the zoem escape \|
         {-3}  {-}               \: the zoem escape \-
      }
   }
   {roff}{
      \special{
         {46}  {\\.}
         {96}  {\\`}
         {92}  {\\\\}            \: a single backslash
         {-1}  {\\ }             \: the zoem escape \~
         {-2}  {\!N.br\!N}         \: the zoem escape \|
         {-3}  {\\-}             \: the zoem escape \-
      }
   }
   {\write{stderr}{txt}{No such device: \__device__\|}
    \write{\__fnbase__.err}{txt}{No such device: \__device__\|}
    \exit
   }
}</div>
<p class="asd_car">
Take note of the number of backslashes. In order to print a backslash
in troff, the troff input must contain two consecutive backslashes.
In order to specify a backslash in zoem, we must also provide two,
thus we need four backslashes in all (in order to create this example
I needed eight backslashes in the zoem input).</p>
<p class="asd_par">
Also note the use of the <a class="intern" href="#switch_2"><span class="zpr">\switch#2</span></a> primitive, which takes
an expression in the first argument and an arbitrary number of pairs plus an
optional clause in the second argument. The optional clause was in this case
used as a failure test.</p>
<p class="asd_par">
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> is an example of a zoem key taking an argument that may
contain arbitrarily many sub-arguments
(i.e. a <a class="intern" href="#vararg">vararg</a>).
In this particular case the
sub-arguments must be paired, each pair defining how certain
characters that are special to the device must be represented.</p>
<p class="asd_par">
The <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> and <a class="intern" href="#exit"><span class="zpr">\exit</span></a> need little comment, they work as
expected. Zoem opens output files as needed, and closes them when it is
done. The file name <tt>-</tt>&nbsp;is equivalent to
either <span class="smallcaps">STDOUT</span> or <span class="smallcaps">STDIN</span> (depending on context),
the file name <tt>stderr</tt> denotes <span class="smallcaps">STDERR</span>.</p>
<p class="asd_par">
<a class="intern" href="#exit"><span class="zpr">\exit</span></a> is considered a failure (and will cause zoem to stop and
complain), but <tt>\throw{done}</tt> is not. <a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a> with argument <tt>done</tt> will
merely quit parsing the current stack, so if you specify it at top level in
a file &mdash; not nested in a key that does its own parsing such as <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>,
zoem will stop parsing the current file and transfer control back to the
file from which it was included.</p>
<p class="asd_par">
The previous example introduces the keys <a class="intern" href="#session"><tt>\__device__</tt></a> and
<a class="intern" href="#session"><tt>\__fnbase__</tt></a>. They are so called session variables
described in section <a class="intern" href="#session">Session keys</a>.</p>
<p class="asd_par">
A sibling primitive to <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> is <a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a>. The
following is an example of use.</p>
<div class="verbatim">\constant{
   {'e}  {&amp;eacute;}     \: Use e.g. as \*{'e}l\*{`e}ve (&eacute;l&egrave;ve)
   {(c)} {&amp;copy;}       \: Use e.g. as \*{(c)} DEEDEE (&copy; DEEDEE)
   {+-}  {&amp;plusmn;}     \: Use e.g. as \*{+-} a few (&plusmn; a few)
}</div>
<p class="asd_car">
The main thing to note here is that the target string (e.g. <tt>&amp;eacute;</tt>)
is <i>always interpreted in device space</i>. In the reference string (e.g.
<tt>'e</tt>, <tt>(c)</tt> and <tt>+-</tt> in the example above) almost anything is allowed,
including backslash-escaped characters and balanced curlies.
The latter are not recommended though.
</p>
<p class="asd_par">
There are three zoem tokens representing the characters that have meaning to
zoem syntax, the backslash and the two curlies. Those zoem tokens are just
like any other plain characters: they can be mapped in plain space, and they
are printed literally in device space.</p>
<div class="verbatim">   \\            \: A backslash; possibly mapped in plain space.
   \{            \: A curly; possibly mapped in plain space.
   \}            \: A curly; possibly mapped in plain space.
   \,            \: The atomic separator (vanishes).</div>
<p class="asd_car">
These tokens are mapped only during the (final) filter stage.
The atomic separator can be useful when you want to glue together
items some of which will be the result of macro expansion.</p>
<div class="verbatim">   \def{foo}{bar}
   \foo\,1                    \: \foo1 would be the key \foo1</div>
<p class="asd_car">
This will result in bar1. The tokens&nbsp;<tt>\\</tt>, <tt>\{</tt>, and&nbsp;<tt>\}</tt>
are really the corresponding ordinary characters.
They can be mapped in plain space via <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> using their
<abbr class="ucase" title="American Standard Code for Information Interchange">ASCII</abbr> values 92, 123, and 125 as was seen above for the backslash.
In device space, they will result in&nbsp;<tt>\</tt>, <tt>{</tt>, and&nbsp;<tt>}</tt>.</p>
<p class="asd_par">
Let us now continue with device scope by implementing a <tt>\bf#1</tt> key.
Below you find two possible definitions:</p>
<div class="verbatim">   \def{bf}{1}{\@{&lt;b&gt;} \1 \@{&lt;/b&gt;}}    \: OK
   \def{bf}{1}{\@{&lt;b&gt; \1 &lt;/b&gt;}}        \: Wrong! Wrong!</div>
<p class="asd_car">
The second is wrong because the contents of&nbsp;<tt>\1</tt> end up in device
space. If the expansion of&nbsp;<tt>\1</tt> still contains keys they will not be
expanded (and cause a fatal syntax error when device space is filtered),
and additionally any special characters in&nbsp;<tt>\1</tt> will not be
mapped.</p>

<a name="language"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#language">The zoem language</a></div><div class="sec_num"><a class="intern" href="#toc8"><span class="sec_num">8</span></a></div></div>

<a name="section_8_1"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#section_8_1">Alphabetic index</a></div><div class="sec_num"><a class="intern" href="#toc8"><span class="sec_num">8.1</span></a></div></div>
<a href="#excl">
<tt>\!</tt>
</a>
<a href="#excl_1">
<tt>\!#1</tt>
</a>
<a href="#dollar_2">
<tt>\$#2</tt>
</a>
<a href="#apply_2">
<tt>\apply#2</tt>
</a>
<a href="#begin_2">
<tt>\begin#2</tt>
</a>
<a href="#catch_2">
<tt>\catch#2</tt>
</a>
<a href="#cmp_3">
<tt>\cmp#3</tt>
</a>
<a href="#constant_1">
<tt>\constant#1</tt>
</a>
<a href="#def_2">
<tt>\def#2</tt>
</a>
<a href="#defx_2">
<tt>\defx#2</tt>
</a>
<a href="#defined_2">
<tt>\defined#2</tt>
</a>
<a href="#dofile_2">
<tt>\dofile#2</tt>
</a>
<a href="#dowhile_2">
<tt>\dowhile#2</tt>
</a>
<a href="#__env___1">
<tt>\__env__#1</tt>
</a>
<a href="#end_1">
<tt>\end#1</tt>
</a>
<a href="#env_4">
<tt>\env#4</tt>
</a>
<a href="#eqt_3">
<tt>\eqt#3</tt>
</a>
<a href="#branch_1">
<tt>\branch#1</tt>
</a>
<a href="#eval_1">
<tt>\eval#1</tt>
</a>
<a href="#exit">
<tt>\exit</tt>
</a>
<a href="#f_2">
<tt>\f#2</tt>
</a>
<a href="#f_3">
<tt>\f#3</tt>
</a>
<a href="#fv_2">
<tt>\fv#2</tt>
</a>
<a href="#finsert_1">
<tt>\finsert#1</tt>
</a>
<a href="#format_2">
<tt>\format#2</tt>
</a>
<a href="#formatted_1">
<tt>\formatted#1</tt>
</a>
<a href="#get_2">
<tt>\get#2</tt>
</a>
<a href="#if_3">
<tt>\if#3</tt>
</a>
<a href="#inspect_4">
<tt>\inspect#4</tt>
</a>
<a href="#length_1">
<tt>\length#1</tt>
</a>
<a href="#let_1">
<tt>\let#1</tt>
</a>
<a href="#nargs_1">
<tt>\nargs#1</tt>
</a>
<a href="#pop_1">
<tt>\pop#1</tt>
</a>
<a href="#protect_1">
<tt>\protect#1</tt>
</a>
<a href="#push_1">
<tt>\push#1</tt>
</a>
<a href="#register_2">
<tt>\register#2</tt>
</a>
<a href="#set_2">
<tt>\set#2</tt>
</a>
<a href="#setx_2">
<tt>\setx#2</tt>
</a>
<a href="#set_3">
<tt>\set#3</tt>
</a>
<a href="#special_1">
<tt>\special#1</tt>
</a>
<a href="#switch_2">
<tt>\switch#2</tt>
</a>
<a href="#system_3">
<tt>\system#3</tt>
</a>
<a href="#table_5">
<tt>\table#5</tt>
</a>
<a href="#textmap_2">
<tt>\textmap#2</tt>
</a>
<a href="#throw_2">
<tt>\throw#2</tt>
</a>
<a href="#tr_2">
<tt>\tr#2</tt>
</a>
<a href="#trace_1">
<tt>\trace#1</tt>
</a>
<a href="#try_1">
<tt>\try#1</tt>
</a>
<a href="#undef_1">
<tt>\undef#1</tt>
</a>
<a href="#vanish_1">
<tt>\vanish#1</tt>
</a>
<a href="#while_2">
<tt>\while#2</tt>
</a>
<a href="#whilst_2">
<tt>\whilst#2</tt>
</a>
<a href="#write_3">
<tt>\write#3</tt>
</a>
<a href="#writeto_1">
<tt>\writeto#1</tt>
</a>
<a href="#zinsert_1">
<tt>\zinsert#1</tt>
</a>

<a name="topicindex"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#topicindex">Topic index</a></div><div class="sec_num"><a class="intern" href="#toc8"><span class="sec_num">8.2</span></a></div></div>
<p class="asd_par">
This is an overlapping categorization in topics.
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Using and inspecting keys</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>
<a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a>
<a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>
<a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a>
<a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>
<a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>
<a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>
<a class="intern" href="#push_1"><span class="zpr">\push#1</span></a>
<a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>
<a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>
<a class="intern" href="#table_5"><span class="zpr">\table#5</span></a>
<a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a>
<p class="asd_par">
These primitives affect or use either <i>user keys</i> that are
stored in the user dictionary,
<i>dollar keys</i> that are stored in the dollar dictionary,
or <i>anonymous keys</i>. Dictionaries are discussed in
<a class="intern" href="#dictionary">Section&nbsp;6.7</a>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Control, booleans, testing and comparison</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#dollar_2"><span class="zpr">\$#2</span></a>
<a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>
<a class="intern" href="#branch_1"><span class="zpr">\branch#1</span></a>
<a class="intern" href="#cmp_3"><span class="zpr">\cmp#3</span></a>
<a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a>
<a class="intern" href="#dowhile_2"><span class="zpr">\dowhile#2</span></a>
<a class="intern" href="#eqt_3"><span class="zpr">\eqt#3</span></a>
<a class="intern" href="#if_3"><span class="zpr">\if#3</span></a>
<a class="intern" href="#length_1"><span class="zpr">\length#1</span></a>
<a class="intern" href="#register_2"><span class="zpr">\register#2</span></a>
<a class="intern" href="#switch_2"><span class="zpr">\switch#2</span></a>
<a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a>
<a class="intern" href="#while_2"><span class="zpr">\while#2</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Expansion, delay</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#excl"><span class="zpr">\!</span></a>
<a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>
<a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>
<a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>
<a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a>
<a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Meta-zoem, introspection, exceptions, errors</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#catch_2"><span class="zpr">\catch#2</span></a>
<a class="intern" href="#exit"><span class="zpr">\exit</span></a>
<a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a>
<a class="intern" href="#try_1"><span class="zpr">\try#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Execution, tracing</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#trace_1"><span class="zpr">\trace#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Input/output</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a>
<a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a>
<a class="intern" href="#format_1"><span class="zpr">\format#1</span></a>
<a class="intern" href="#register_2"><span class="zpr">\register#2</span></a>
<a class="intern" href="#vanish_1"><span class="zpr">\vanish#1</span></a>
<a class="intern" href="#write_3"><span class="zpr">\write#3</span></a>
<a class="intern" href="#writeto_1"><span class="zpr">\writeto#1</span></a>
<a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Filtering</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#special_1"><span class="zpr">\special#1</span></a>
<a class="intern" href="#vanish_1"><span class="zpr">\vanish#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Environment scopes</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>
<a class="intern" href="#end_1"><span class="zpr">\end#1</span></a>
<a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Name scopes</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a>
<a class="intern" href="#push_1"><span class="zpr">\push#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Data storage</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<tt>\%</tt>, <tt>\%free</tt>, and <tt>\%dump</tt> are primitives described elsewhere
&mdash; refer to the <a class="intern" href="#grape">Tree data</a> section.
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>String conversions</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#format_2"><span class="zpr">\format#2</span></a>
<a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>
<a class="intern" href="#length_1"><span class="zpr">\length#1</span></a>
<a class="intern" href="#textmap_2"><span class="zpr">\textmap#2</span></a>
<a class="intern" href="#tr_4"><span class="zpr">\tr#4</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Arithmetic</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#f_2"><span class="zpr">\f#2</span></a>
<a class="intern" href="#f_3"><span class="zpr">\f#3</span></a>
<a class="intern" href="#fv_2"><span class="zpr">\fv#2</span></a>
<a class="intern" href="#let_3"><span class="zpr">\let#3</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Glyphs</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#constant_1"><span class="zpr">\constant#1</span></a>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><b>Syntactic sugar</b></div></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a>
<a class="intern" href="#vanish_1"><span class="zpr">\vanish#1</span></a>
<a class="intern" href="#xmlpr1"><tt>\&lt;&gt;#1</tt></a>
<a class="intern" href="#xmlpr2"><tt>\&lt;&gt;#2</tt></a>
</div>
</div>

<a name="section_8_3"></a><div class="sec_leader sec_lev2"><div class="sec_title"><a class="intern" href="#section_8_3">Primitives</a></div><div class="sec_num"><a class="intern" href="#toc8"><span class="sec_num">8.3</span></a></div></div>
<p class="asd_par">
Zoem primitives may expand (which is the same as evaluate) one, several, or all
of their arguments before using them. Such arguments are enclosed by double
angle brackets in the listing below. The inside-out type evaluation is done
recursively and works for arbitrary levels of nesting. An argument which is
first expanded and is then interpreted as a label is thus written
<tt>&lt;label&gt;</tt> in the primary entry. In the definition text accompanying the
entry, the expanded argument is simply refered to as <tt>&lt;label&gt;</tt>, so the extra
pair of brackets is dropped.
</p>
<p class="asd_par">
Each primitive below has a little paragraph with the caption
<b>Result text</b>. It gives a summary of 'what comes out'.
Note that the result of macro expansion is always passed to the parser
again, so the result text is again subject to expansion.
</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div class="" style="margin-top:0em"><div class=" item_cascade item_leftalign nowrap" style=""><a name="xmlpr1"><tt>\&lt;&gt;#1</tt></a></div><div class=" item_cascade item_leftalign nowrap" style=""><a name="xmlpr2"><tt>\&lt;&gt;#2</tt></a></div></div>
<div class=" item_text " style="margin-left:2em">
These are special. Refer to section <a class="intern" href="#xmlsugar"><abbr class="ucase" title="Standard Generalized Markup Language">SGML</abbr>/<abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>/<abbr class="ucase" title="Extensible Markup Language">XML</abbr> syntactic sugar cubes</a>.
The angle brackets are part of the syntax, do not confuse them
with the angle brackets used below to enclose arguments.
These primitives are respectively used as <tt>\&lt;*any*&gt;</tt> and
<tt>\&lt;*any*&gt;{*any*}</tt>,
so the positioning of arguments is different from all other
zoem primitives.
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="excl">
</a>
<tt>\!</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
This primitive is triggered by an active backslash followed by a consecutive
run of exclamation marks, which is <i>not</i> followed by an opening curly.
The sequence is called a <i>delay sequence</i>, and its <i>arity</i> is the
count of backslashes. A single exclamation mark is stripped (i.e. the arity
is decremented) and the sequence is no longer subject to the current
expansion stage. It is used to construct valid zoem input, which is usually
redirected to file with the copy filter, stored using <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>, or used
in nested occurrences of <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>, <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>, and other primitives.
Other uses are possible, the main thing is that one should keep a clear view
of the meta-programming implied by&nbsp;<tt>\!</tt>.
Refer also to the <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a> primitive.
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span>
The primitive <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a> evaluates its argument a single time,
and passes it on for further evaluation.
The following are fully equivalent:
</p>
<div class="verbatim">\set{foo}{zut}
\eval{\!foo}
\foo</div>
<p class="asd_car">
whereas <tt>\!foo</tt> would pass the sequence <tt>\foo</tt> to the filtering stage,
where it will yield a (non-fatal) error message.
Similarly, <tt>\eval{\eval{\!!foo}}</tt> is equivalent to the above.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
A delay sequence of decremented arity.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="excl_1">
</a>
<tt>\!#1</tt>:&nbsp;&nbsp;<tt>\!{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This primitive is triggered by an active backslash followed by a consecutive
run of exclamation marks, which is in turn followed by a block. The block
is called a <i>delay</i> scope. The arity of the delay scope is the count of
backslashes found in the run. A single exclamation mark is stripped (i.e.
the arity is decremented); if no further exclamation marks remain (i.e. the
arity becomes zero) then the introducing backslash and the delimiting
curlies are stripped as well. The result (including the contents of the
block) is passed on and is no longer subject to the current expansion stage.
The same observations hold as those made for the previous entry.
Refer also to the <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a> primitive.
</p>
<p class="asd_par">
Additionally, blocks that are protected by the delay primitive will be
skipped during parameter interpolation.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
<tt>&lt;any&gt;</tt>, if the arity of the delay scope just found was equal to one,
otherwise, <tt>&lt;any&gt;</tt> put in a decremented delay scope. <tt>&lt;any&gt;</tt> will in
both case no longer be subject to the current expansion stage.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="dollar_2">
</a>
<tt>\$#2</tt>:&nbsp;&nbsp;<tt>\${&lt;str&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
This is a shortcut for activating output for a particular device.
If <a class="intern" href="#session"><tt>\__device__</tt></a> expands to <tt>&lt;str&gt;</tt>, <tt>&lt;any&gt;</tt>
is passed on for expansion, otherwise it is ignored.
The following two are equivalent:
<div class="verbatim">\${html}{Seen only in the html device}

\if{\cmp{eq}{\__device__}{html}}{Seen only in the html device}{}</div>
<p class="asd_ccar"><span class="asd_ccar_caption">Result text</span>
Either none or <tt>&lt;any&gt;</tt>.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="apply_2">
</a>
<tt>\apply#2</tt>:&nbsp;&nbsp;<tt>\apply{&lt;&lt;key-sig|anon-key&gt;&gt;}{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The first argument is expanded before use.
It should expand either to the signature of a user key, primitive or builtin
taking arguments, or to a <a class="intern" href="#anonymous">tagged anonymous key</a>. Examples
of the first are <tt>foo#k</tt> and <tt>"bar::baz"#k</tt>, the latter takes the form
<tt>_#k{..}</tt>. If you use an anonymous key containing macro sequences, be
sure to escape whole or part of the anonymous key, depending on your needs.
The expansion of <tt>_#2\!{{&lt;any&gt;}}</tt> for example, will result in
<tt>_#2{&lt;any&gt;}</tt>. Primitives can used in both quoted and regular syntax.</p>
<p class="asd_par">
The second argument should result in a vararg. <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> extracts
<tt>k</tt>&nbsp;elements at a time from <tt>&lt;vararg&gt;</tt>,
and applies the key resulting from
the first argument to each vector of <tt>k</tt>&nbsp;elements successively.
Any elements remaining in <tt>&lt;vararg&gt;</tt> are ignored.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Entirely depending on the key specified in the first argument.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="begin_2">
</a>
<tt>\begin#2</tt>:&nbsp;&nbsp;<tt>\begin{&lt;label&gt;}{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> pushes a new dictionary onto the dollar dictionary stack which
is popped by the matching <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a>.</p>
<p class="asd_par">
<tt>\begin#1</tt> is an alias which invokes <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> with an empty
<tt>&lt;vararg&gt;</tt> argument.</p>
<p class="asd_par">
<a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> pushes the begin expression associated with <tt>&lt;label&gt;</tt> via
<a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>. The <tt>&lt;label&gt;</tt> part is <i>not</i> expanded. The second argument
<tt>&lt;vararg&gt;</tt> consists of consecutive scopes denoting key-value pairs. It is
expanded before use and is allowed to be empty. The keys (which are the
odd-numbered scopes, starting with one) in <tt>&lt;vararg&gt;</tt> must be such that
prepending a dollar sign (<tt>$</tt>) to them yields a valid key signature. That
signature will be used to set a dollar key in the newly pushed dollar
dictionary that expands to the <tt>value</tt> part associated with the key
(specified as the consecutive even-numbered scope in <tt>&lt;vararg&gt;</tt>).
Alternatively, since the 07-333 release,
it is also possible to explicitly include the dollar sign in the keys rather
than having them prepended.
</p>
<p class="asd_par">
The <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a> invocation that defines the environment likely
sets defaults for the dollar keys (via the second argument
of <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>) that can be set as described above.</p>
<p class="asd_par">
The pushing of a dictionary provides a means for shadowing and localization
with nested <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> statements. By associating dollar keys with an
environment, these keys can be given different meanings in nested
environments - the previous meaning will be restored once an environment is
closed. The advantages are that the environment does not have to exercise
<a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> and <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a> itself, that the user dictionary stack is not
unnecessarily extended (saving look-up time), and that the 'dollar' look of
a key such as <tt>\$align</tt> signals that it will automagically work in nested
enviroments. Of course, the latter is still the responsibility of the
author of the environment.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The string associated with <tt>&lt;label&gt;</tt> via <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example I</span>
The zoem faq macros define a <tt>faqsec</tt> environment, for which
two additional arguments are required. It is used for example as</p>
<div class="verbatim">\begin{faqsec}{{ref}{misc}{cap}{Miscellaneous questions}}
 ...
\end{faqsec}</div>
<p class="asd_car">
The <tt>ref</tt> key introduces the label, the <tt>cap</tt> key introduces the
caption.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example II</span>
The itemize environment in the zoem <i>generic</i> package allows one
additional and optional argument. This argument, if present, must contain a
vararg, and is used to set options related to the itemize environment. It
is used for example as</p>
<div class="verbatim">\begin{itemize}{
   {interitem}{0}
   {flow}{compact}
   {mark}{\*{itembullet}}
   {align}{right}
}
 ...
\end{itemize}</div>
<p class="asd_car">
Internally, the itemize environment maps these options to dollar keys.
Because a unique dollar dictionary is associated with each environment, this
makes it possible for nested itemize instances to have separate namespaces.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The (unexpanded) string stored in the third argument of the corresponding
<a class="intern" href="#env_4"><span class="zpr">\env#4</span></a> invocation.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="catch_2">
</a>
<tt>\catch#2</tt>:&nbsp;&nbsp;<tt>\catch{&lt;type&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This will process <tt>&lt;any&gt;</tt>. Depending on <tt>&lt;type&gt;</tt> the
result is accepted as succesful.
If <tt>&lt;type&gt;</tt> is <tt>towel</tt>,
any occurrence of <tt>\throw{towel}</tt> in <tt>&lt;any&gt;</tt> is caught, and
the truncated result is further processed. For <tt>towel</tt>,
zoem <i>errors</i> are not caught but cascade/escalate further down/up.
If <tt>&lt;type&gt;</tt> is <tt>error</tt>,
any error in <tt>&lt;any&gt;</tt> is caught, and
the truncated result is further processed.
If <tt>&lt;type&gt;</tt> is <tt>done</tt>, no exception is accepted.
It is possible though to use <tt>throw{done{..}}</tt> which will stop processing
without generating an exception. See also <a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a>.</p>
<p class="asd_par">
Output will be truncated in case an error or exception was caught.
The status, currently one of <tt>done</tt>, <tt>towel</tt>, or <tt>error</tt>,
is written in the session macro <a class="intern" href="#session"><tt>\__zoemstat__</tt></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The possibly truncated result of expanding <tt>&lt;any&gt;</tt> in case
of a caught exception or error, else the full result.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="cmp_3">
</a>
<tt>\cmp#3</tt>:&nbsp;&nbsp;<tt>\cmp{&lt;str&gt;}{&lt;&lt;any&gt;&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The last two arguments are expanded. Their results are compared as
strings. The first argument must be one of the labels
<tt>lt|lq|eq|gq|gt|ne|cp</tt>. In case it equals one of the six labels
<tt>lt|lq|eq|gq|gt|ne</tt>, this primitive puts in place
the associated boolean as
a string (i.e. either&nbsp;<tt>0</tt> or&nbsp;<tt>1</tt>). In case the label equals <tt>cp</tt>,
it puts in place the result of the string compare (as a string),
namely one of&nbsp;<tt>-1</tt>, <tt>0</tt>, or&nbsp;<tt>1</tt>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Either the string enconding of a boolean (<tt>0</tt> or&nbsp;<tt>1</tt>)
or the string encoding of the ternary value resulting from a string compare
(<tt>-1</tt>&nbsp;or <tt>0</tt> or&nbsp;<tt>1</tt>).</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="constant_1">
</a>
<tt>\constant#1</tt>:&nbsp;&nbsp;<tt>\constant{&lt;vararg&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<tt>&lt;vararg&gt;</tt> must have an even number of arguments. These are interpreted
as pairs. The first of each pair must enclose a string that does not contain
any of the characters&nbsp;<tt>*</tt>, <tt>\</tt>, <tt>{</tt>, or&nbsp;<tt>}</tt>, say string
<tt>&lt;keystr&gt;</tt>. The second encloses a string that will be interpreted in
device space, say string <tt>&lt;valstr&gt;</tt>. When a sequence
<tt>\*</tt>{<tt>&lt;keystr&gt;</tt>} is encountered, it is interpreted as
<tt>\@{</tt><tt>&lt;valstr&gt;</tt><tt>}</tt>. This is done at filter time only, the sequence
is skipped during macro expansion. It is not allowed to use a sequence
<tt>\*</tt>{<tt>&lt;keystr&gt;</tt>} in device scope, e.g.
<tt>\@{\*</tt>{<tt>&lt;keystr&gt;</tt>} is illegal. For further information see
section <a class="intern" href="#dscope">Device scope</a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="def_2">
</a>
<tt>\def#2</tt>:&nbsp;&nbsp;<tt>\def{&lt;key-sig|data-seq&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Bind second argument to the key or access sequence in the first argument.
This primitive will complain if a binding exists already, but it will
overwrite the previous binding and continue anyway. Use <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> if you
do no want to be warned for overwriting. Examples of usage:</p>
<div class="verbatim">   \def{foo}{FOO}
   \def{foo#1}{The FOO of \1}
   \def{foo#2}{The FOO of \1 and \2}
   \def{$foo#2}{The $FOO of \1 and \2}
   \def{"foo::oof"#3}{\foo{\1}{\2}\foo{\2}{\3}}</div>
<p class="asd_car">
These examples are all of type <tt>key-sig</tt>.
See the <a class="intern" href="#grape">Tree data</a> section for examples of type <tt>data-seq</tt>
(this pertains to multi-dimensional data storage).
See the <a class="intern" href="#macro">Macro expansion</a> section for the forms that keys may take. A key
signature is the name of a key with appended to
it the number of argument that the key takes, if any. If the key takes no
arguments, than the key signature is identical to the key name.</p>
<p class="asd_par">
If you want the value to be bound to be expanded before binding it,
use either <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a> or <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>. This works the same for
data keys.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span><a class="intern" href="#set_3"><span class="zpr">\set#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="defx_2">
</a>
<tt>\defx#2</tt>:&nbsp;&nbsp;<tt>\defx{&lt;key-sig&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The second argument is expanded and stored in the key <tt>&lt;key-name&gt;</tt>. This
primitive will complain if a binding for that key exists already, but it
will overwrite the previous value anyway.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span><a class="intern" href="#set_3"><span class="zpr">\set#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="defined_2">
</a>
<tt>\defined#2</tt>:&nbsp;&nbsp;<tt>\defined{&lt;type&gt;}{&lt;&lt;access&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<tt>&lt;type&gt;</tt> is one string of <tt>key</tt>, <tt>lkey</tt>, <tt>data</tt>,
<tt>primitive</tt>, <tt>builtin</tt>, <tt>zoem</tt> or <tt>ENV</tt>. The
second argument is expanded before use.
For the type <tt>key</tt>, the <tt>&lt;access&gt;</tt> argument is looked up as a key
signature in either the user dictionary stack or the dollar dictionary
stack.
For the type <tt>lkey</tt>, it is looked up only in the top level dictionary.
For the type <tt>data</tt>, the <tt>&lt;access&gt;</tt> argument is interpreted as a data
access sequence.
For the type <tt>primitive</tt>, the <tt>&lt;access&gt;</tt> argument is looked up in
the zoem primitive table.
For the type <tt>builtin</tt>, the <tt>&lt;access&gt;</tt> argument is looked up in
the zoem builtin macro table.
The type <tt>zoem</tt> corresponds with the union of the types <tt>primitive</tt> and
<tt>alias</tt>.
For the type <tt>ENV</tt>, it is checked whether it exists as an environment
variable (which can be retrieved using the <a class="intern" href="#__env___1"><span class="zpr">\__env__#1</span></a> primitive).
This primitive pushes the string&nbsp;<tt>1</tt> if the result is
indeed a valid reference, it pushes the string&nbsp;<tt>0</tt> otherwise.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>The string encoding of a boolean (<tt>0</tt> or&nbsp;<tt>1</tt>).</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="dofile_2">
</a>
<tt>\dofile#2</tt>:&nbsp;&nbsp;<tt>\dofile{&lt;&lt;file name&gt;&gt;}{&lt;char[!?]&gt;&lt;char[+-]&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Open a file and process its contents while keeping track of line numbers.
Depending on the second argument, absence of the file is either allowed or
not, and its interpreted contents are output or not. The fact
that <tt>&lt;file name&gt;</tt> is first expanded allows you to specify
file names such as <a class="intern" href="#session"><tt>\__fnbase__.zyx</tt></a>.</p>
<p class="asd_par">
Zoem may search for a file in several locations until it is found.
The process of locating a file is described in section <a class="intern" href="#searchpath">File search path</a>.</p>
<p class="asd_par">
When found, the file is opened according to the specification in the second
argument. This argument must contain exactly two characters, the first one
of [<tt>!?</tt>], the second one of [<tt>+-</tt>]. The first character indicates
whether the file is allowed to be absent. A '<tt>!</tt>' implies that absence is
fatal, a '<tt>?</tt>' permits absence. The latter is useful e.g. when creating a
Table Of Contents file. The second character indicates whether the
interpreted file should be filtered and output or not ('<tt>+</tt>' for yes and
'<tt>-</tt>' for no). Macro packages typically need interpretation only, whereas
concatenation of document parts (c.q. chapters) stored in different files
requires that the interpreted content is also filtered and output. The
following aliases are available:</p>
<div class="verbatim">
\input{fname}        \dofile{fname}{!+}
\import{fname}       \dofile{fname}{!-}
\read{fname}         \dofile{fname}{?+}
\load{fname}         \dofile{fname}{?-}</div>
<p class="asd_car">
The contents of <tt>&lt;file name&gt;</tt> cannot be captured. If you need to
capture the contents of a file, use <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> or <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Technically none. Of course the processing of <tt>&lt;file name&gt;</tt>
may result in output, depending on the mode of opening.
However, this result text cannot be captured.
For example,</p>
<div class="verbatim">\setx{foo}{\dofile{bar}{!+}}</div>
<p class="asd_car">
will result in the file <tt>&lt;bar&gt;</tt> being processed and output via
the standard output mechanisms, while the key <tt>\foo</tt> will have
the empty string as value.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="dowhile_2">
</a>
<tt>\dowhile#2</tt>:&nbsp;&nbsp;<tt>\dowhile{&lt;any&gt;}{&lt;condition&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<tt>&lt;any&gt;</tt> is expanded and concatenated to the result text
until <tt>&lt;condition&gt;</tt> exands to something that is nonzero when interpreted
as an integer. <tt>&lt;any&gt;</tt> is expanded at least one time.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="__env___1">
</a>
<tt>\__env__#1</tt>:&nbsp;&nbsp;<tt>\__env__{&lt;name&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Looks up <tt>&lt;name&gt;</tt> in the environment.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The corresponding value if <tt>&lt;name&gt;</tt> exists in the environment, the
empty string otherwise.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
This primitive yields identical results for names not in the environment
and names in the environment for which the value is empty.
Use <a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a> to check whether <tt>&lt;name&gt;</tt> exist.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="end_1">
</a>
<tt>\end#1</tt>:&nbsp;&nbsp;<tt>\end{&lt;label&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Expands the end definition associated with <tt>&lt;label&gt;</tt> via <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The string associated with <tt>&lt;label&gt;</tt> via <a class="intern" href="#env_4"><span class="zpr">\env#4</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="env_4">
</a>
<tt>\env#4</tt>:&nbsp;&nbsp;<tt>\env{&lt;label&gt;}{&lt;&lt;any1&gt;&gt;}{&lt;any2&gt;}{&lt;any3&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Stores <i>expanded</i> <tt>&lt;any1&gt;</tt> and <i>unexpanded</i> <tt>&lt;any2&gt;</tt>
for later use with <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> (when
given argument <tt>&lt;label&gt;</tt>) and
unexpanded <tt>&lt;any3&gt;</tt> for later use with <a class="intern" href="#end_1"><span class="zpr">\end#1</span></a> (when
given argument <tt>&lt;label&gt;</tt>).</p>
<p class="asd_par">
<tt>&lt;any1&gt;</tt> may contain a vararg denoting key-value pairs.
These will be set for each <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> invocation
in the corresponding dollar dictionary. It provides a convenient
mechanism to set default values for keys that can be passed
in the second argument of <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>.
Note that keys are passed as regular macro signatures, but
they are then transformed to dollar keys by prepending a dollar sign.
Environments are tighly linked to the dollar dictionary stack.
Read more about this in the description of <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a>.</p>
<p class="asd_par">
With each <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> invocation, after <tt>&lt;any1&gt;</tt> is
processed as indicated above,
<tt>&lt;any2&gt;</tt> will be pushed onto the input stream.
Before this, <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> defines the keys <tt>\$__args__</tt>
and <tt>\$__xargs__</tt>. These contain respectively the vararg
that was passed as the second argument of <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> and the
same vararg after it was expanded.
These keys can be used in <tt>&lt;any2&gt;</tt>. One possible usage is
to pass the key-values on to other environment invocations.
This is a likely scenario in case one environment is a thin customization
wrapper around a full-fledged base
environment.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="eqt_3">
</a>
<tt>\eqt#3</tt>:&nbsp;&nbsp;<tt>\eqt{&lt;str&gt;}{&lt;&lt;num1&gt;&gt;}{&lt;&lt;num2&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The last two arguments are expanded. Their results are compared as
numbers. The first argument must be one of the labels
<tt>lt|lq|eq|gq|gt|ne|cp</tt>. In case it equals one of the six labels
<tt>lt|lq|eq|gq|gt|ne</tt>, this primitive pushes the associated boolean as a
string (i.e. either&nbsp;<tt>0</tt> or&nbsp;<tt>1</tt>). In case the label equals&nbsp;<tt>cp</tt>,
this primitive pushes the result of the integer compare,
namely one of <tt>-1</tt> (if the result of <tt>&lt;any1&gt;</tt> is
smaller than the result of <tt>&lt;any2&gt;</tt>),
<tt>0</tt> (equal to), or&nbsp;<tt>1</tt> (greater than).</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Either the string enconding of a boolean (<tt>0</tt> or&nbsp;<tt>1</tt>)
or the string encoding of the ternary value resulting from
a numeric compare, (<tt>-1</tt> or&nbsp;<tt>0</tt> or&nbsp;<tt>1</tt>).</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="branch_1">
</a>
<tt>\branch#1</tt>:&nbsp;&nbsp;<tt>\branch{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Two arguments are successively taken from <tt>&lt;vararg&gt;</tt>. The first is
expanded and then evaluated as an integer. If the integer is nonzero, the
second argument is expanded and everything else is ignored. Otherwise the
procedure is repeated. If no (odd) argument matches, and the <tt>&lt;vararg&gt;</tt>
has an odd number of arguments, the last argument is put in place. It can
be considered a default, else, or failure clause.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="eval_1">
</a>
<tt>\eval#1</tt>:&nbsp;&nbsp;<tt>\eval{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Expands <tt>&lt;any&gt;</tt> and passes it on for further evaluation.
This can come in handy when complicated requirements demand
zoem acrobatics. This primitive used to be implemented as a macro;
it is fully equivalent to</p>
<div class="verbatim">\set{eval#1}{\apply{_#1{\!1}}{\1}}</div>
<p class="asd_car">
The above macro works as follows. First, <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> expands both of its
arguments. The second argument is the data it received from <tt>\eval</tt>, i.e.
the latter's single argument. At this stage, the data is thus expanded for
the first time. <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> also expands its first argument. The sequence
<tt>\!1</tt> is contracted to the sequence&nbsp;<tt>\1</tt>. The&nbsp;<tt>\1</tt> needed by
<a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a> needs to be protected by the interpolation that occurs when
<tt>eval#1</tt>'s argument is interpolated. Expansion of <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>'s first
argument thus yields the anonymous key <tt>_#1{\1}</tt> &mdash; a key that simply
copies it argument and passes it on for further expansion.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span>
<tt>\foo</tt> and <tt>\eval{\!foo}</tt> are fully equivalent.
<tt>\!foo</tt> on the other hand, expands to <tt>\foo</tt> and is then
passed to the filter stage.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span>
<a class="intern" href="#excl"><span class="zpr">\!</span></a>, <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
<tt>&lt;any&gt;</tt> gone through <i>two</i> stages of interpretation.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="exit">
</a>
<tt>\exit</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
goodbye world. This is a disgraceful exit for use when some error test
presumably yields true. See also <a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="f_2">
</a>
<tt>\f#2</tt>:&nbsp;&nbsp;<tt>\f{&lt;fun&gt;}{&lt;&lt;num1&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Expand the last argument, interprets the result as a number,
applies the operand specified by <tt>&lt;fun&gt;</tt>, and puts the
result in place.
<tt>&lt;fun&gt;</tt> can be one of</p>
<p class="asd_par">
<tt>floor</tt>, <tt>ceil</tt>, <tt>round</tt>, <tt>abs</tt>, <tt>sign</tt>, <tt>inc</tt>, <tt>dec</tt>, <tt>not</tt>, <tt>drand</tt>, <tt>irand</tt>,
and that's about it. Mode <tt>\f{drand}{&lt;num&gt;}</tt> yields a floating point
number in the range <tt>[0-&lt;num&gt;]</tt>, and mode <tt>\f{irand}{&lt;int&gt;}</tt>
yields an integer in the range <tt>[0-&lt;int&gt;)</tt>, that is, the argument
<tt>&lt;int&gt;</tt> itself is excluded from the range.
</p>
<p class="asd_par">
For a wider range of mathematical functions, refer to
the <a class="intern" href="#let_1"><span class="zpr">\let#1</span></a> primitive.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The string encoding of a number.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="f_3">
</a>
<tt>\f#3</tt>:&nbsp;&nbsp;<tt>\f{&lt;fun&gt;}{&lt;&lt;num1&gt;&gt;}{&lt;&lt;num2&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Expands the last two arguments, interprets the results as
numbers, applies the operand specified by <tt>&lt;fun&gt;</tt>, and puts the
result in place.</p>
<p class="asd_par">
Most arithmetic is done using floating point arithmetic (with the C double
type). Integers are preserved if possible. Since nearly everything is
treated as a string in zoem, this simply means that no decimal fraction is
printed when the number is output. A number is considered integer if the
difference with the integer nearest by is less than the precision (1e-8)
<i>and</i> if it can be represented as an integer using the C long type.
Otherwise it is output in decimal representation of the underlying floating
point representation.</p>
<p class="asd_par">
<tt>&lt;fun&gt;</tt> can be one of</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">*</div></div></div>
<div class=" item_text " style="margin-left:2em">
Multiplication.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">+</div></div></div>
<div class=" item_text " style="margin-left:2em">
Addition.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">-</div></div></div>
<div class=" item_text " style="margin-left:2em">
Subtraction.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">/</div></div></div>
<div class=" item_text " style="margin-left:2em">
Does true division, returns real.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">%</div></div></div>
<div class=" item_text " style="margin-left:2em">
Modulus.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">and</div></div></div>
<div class=" item_text " style="margin-left:2em">
Boolean <i>and</i>, results in&nbsp;<tt>0</tt> or&nbsp;<tt>1</tt>.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">or</div></div></div>
<div class=" item_text " style="margin-left:2em">
Boolean <i>or</i>, results in&nbsp;<tt>0</tt> or&nbsp;<tt>1</tt>.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">div</div></div></div>
<div class=" item_text " style="margin-left:2em">
Does integer division.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">mod</div></div></div>
<div class=" item_text " style="margin-left:2em">
Same as&nbsp;<tt>%</tt>.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">pow</div></div></div>
<div class=" item_text " style="margin-left:2em">
Power.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">max</div></div></div>
<div class=" item_text " style="margin-left:2em">
Maximum.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">min</div></div></div>
<div class=" item_text " style="margin-left:2em">
Minimum.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">ceil</div></div></div>
<div class=" item_text " style="margin-left:2em">
Nearest by higher multiple, e.g. <tt>\f{ceil}{12}{5}=15</tt>.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">floor</div></div></div>
<div class=" item_text " style="margin-left:2em">
Nearest by lower multiple, e.g. <tt>\f{floor}{12}{5}=10</tt>.
</div>
</div>
<p class="asd_par">
For a wider range of mathematical functions, refer to
the <a class="intern" href="#let_1"><span class="zpr">\let#1</span></a> primitive.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
<tt>and</tt> and <tt>or</tt> short-circuit.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The string encoding of a number.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="fv_2">
</a>
<tt>\fv#2</tt>:&nbsp;&nbsp;<tt>\fv{&lt;fun&gt;}{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Expands the second argument and interprets it as vararg,
and applies the operator specified by <tt>&lt;fun&gt;</tt> to the elements of vararg.</p>
<p class="asd_par">
<tt>&lt;fun&gt;</tt> can be one of</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">*</div></div></div>
<div class=" item_text " style="margin-left:2em">
Multiplication.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">+</div></div></div>
<div class=" item_text " style="margin-left:2em">
Addition.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">and</div></div></div>
<div class=" item_text " style="margin-left:2em">
Boolean and.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">or</div></div></div>
<div class=" item_text " style="margin-left:2em">
Boolean or.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">max</div></div></div>
<div class=" item_text " style="margin-left:2em">
Maximum.
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">min</div></div></div>
<div class=" item_text " style="margin-left:2em">
Minimum.
</div>
</div>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
<tt>and</tt> and <tt>or</tt> short-circuit.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The string encoding of a number.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="finsert_1">
</a>
<tt>\finsert#1</tt>:&nbsp;&nbsp;<tt>\finsert{&lt;file name&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The argument is expanded and interpreted as file name. The file is read,
and every&nbsp;<tt>\</tt>, <tt>{</tt>, and&nbsp;<tt>}</tt> is escaped (resulting in one of
<tt>\\</tt>, <tt>\{</tt>, and&nbsp;<tt>\}</tt>) The altered contents are then put in
place. See also <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>.
If file can not be opened, the empty string results.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
This primitive cannot be used to read
<a class="intern" href="#fileread">inline files</a> whereas <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a> can.
The reason is that inline files have to satisfy zoem syntax.
<tt>\finsert#1</tt> can be used to read arbitrary data.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The escaped contents of <tt>&lt;file name&gt;</tt> or the empty string if
file can not be opened.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="format_2">
</a>
<tt>\format#2</tt>:&nbsp;&nbsp;<tt>\format{&lt;&lt;fmt&gt;&gt;}{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_ccar"><span class="asd_ccar_caption">NOTE</span>
This primitive was changed in an incompatible way in the 07-333 release.
The special case specification syntax was discarded and replaced by the more
robust and extensible key-value based syntax described below.
</p>
<p class="asd_par">
The primitive formats elements from <tt>&lt;vararg&gt;</tt> according to the format
specification in <tt>&lt;fmt&gt;</tt>. A format string may contain normal characters
that will be output, and meta sequences. A meta sequence is started with the
percent character <tt>%</tt> and either followed by a block or by another percent
sign. A meta sequence consisting of two consecutive percent signs (<tt>%%</tt>)
will be skipped and result in the output of a single percent sign.
Otherwise, the meta sequence will format the next argument from <tt>&lt;arg&gt;</tt>
according to the specification in the block. A specification consists of a
series of key-value pairs that may occur in any order. The key is called the
<i>directive</i> and the supported directives are:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{padding}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The literal string <tt>padding</tt> is the directive and indicates that the value
specifies the padding. The <tt>&lt;any&gt;</tt> content of the
value block is used as the padding string. By default spaces are used
for padding (and incidentally runs of spaces will be squashed unless
<tt>\@{\w}</tt> is issued).
Padding is applied if the width of the field exceeds the width of
<tt>&lt;arg&gt;</tt> plus the width of the optional delimiter(s) described below.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{delimit}{&lt;delimiter&gt;}[{&lt;delimiter&gt;}]</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The content of the first block is inserted inbetween the padding and
<tt>&lt;arg&gt;</tt>. If centered alignment is used, this will be done on both sides.
By default no such delimiter is used.
It is possible to specify two <tt>&lt;delimiter&gt;</tt> arguments. In that
case the first specifies the left delimiter and the second specifies
the right delimiter.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{align}{left|center|right}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The directive is <tt>align</tt>, the value is one of <tt>left</tt>, <tt>center</tt>, or <tt>right</tt>
and specifies how the argument taken from <tt>&lt;vararg&gt;</tt> is to be aligned.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{width}{&lt;num&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The directive is <tt>width</tt>, the value should be a positive integer number denoting
the desired width of the field on which <tt>&lt;arg&gt;</tt> is to be printed.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{length}{{key}[{args}*]}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The directive is <tt>length</tt>, the value consists of one or more blocks.
The first value block should contain the name of a macro.
This is for when you want to customize the way in
which the length of strings is computed.
The macro will be used to compute the lenght of strings under
consideration, using entries in the <i>double</i> directive as appropriate (see below).
This allows you for example to do alignment in <tt>&lt;pre&gt;</tt> formatted blocks in html,
while keeping the
possibility to insert elements that do not take up any width (e.g. links).
The first value block should contain the name of a macro.
A likely candidate is
<a class="intern" href="#length_1"><span class="zpr">\length#1</span></a>, which should be specified simply as <tt>length</tt>.
The first argument that is given to this macro will be the string
under consideration. The rest of the value blocks, if any, will be given
as additional arguments.
</p>
<p class="asd_par">
Currently, this custom length computation is only applied to the
argument that is being formatted and the two delimiters if present.
All three of these can be replaced, for the purpose of length
computation, by placeholders using the <i>double</i> directive.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{double}{{[{key}{value}]*}}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The directive is <tt>double</tt>, the value consists of a single block containing
a vararg. This is used to specify placeholders when computing the length of
elements. The vararg contains placeholder types as keys and the
corresponding placeholder values. It is currently possible to specify three
different types of placeholders. These are the argument to be typeset,
specified with the placeholder key <i>arg</i>, the left delimiter, specified
with <i>delimit-left</i>, and the right delimiter, specified with
<i>delimit-right</i>.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">NOTE</span>
The value is enclosed in a block, as part of the key-value specification
employed by the <i>double</i> specification. The value itself is
a block containing key-value pairs (again specified as curly-delimited
blocks). So be sure to supply the correct number and nesting of blocks.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{alignat}{{&lt;pivot&gt;}{&lt;width&gt;}}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The directive is <tt>alignat</tt>, the value consists of two blocks. This is used to
specify alignment. The content of the first value block is used as the
string on which to align. The content of the second block is used as the
width on which the first part of <tt>&lt;arg&gt;</tt> (up to and including the
alignment substring) will be right-aligned. If the <tt>length</tt> specification
is used as well, the length macro specified therein will be used to compute
the width of the string specified in the first block.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{reuse}{&lt;num&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This instructs zoem to reuse the current specification for another <tt>&lt;num&gt;</tt>
arguments taken from <tt>&lt;vararg&gt;</tt>.
Instead of <tt>&lt;num&gt;</tt> it is possible to specify <tt>{reuse}{*}</tt>. This
will reuse the current specification until all arguments have been exhausted.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style=""><tt>{border}{{&lt;left&gt;}{&lt;right&gt;}}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This borders the result of the current specification with <tt>&lt;left&gt;</tt>
and <tt>&lt;right&gt;</tt>.
This is useful in conjunction with the <tt>reuse</tt> specifier, for example
for adding device line-breaks to each formatted item.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span></p>
<div class="verbatim">\format{%{{align}{right}{width}{10}{reuse}{*}{padding}{{'}{}}}}{
   {beauty}{lies}{in}{the}{eye}{of}{the}{beholder}
}</div>
<p class="asd_car">results in</p>
<div class="verbatim">''''beauty''''''lies''''''''in'''''''the'''''''eye''''''''of'''''''the''beholder</div>
</div>
</div>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The formatted string.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="formatted_1">
</a>
<tt>\formatted#1</tt>:&nbsp;&nbsp;<tt>\formatted{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This removes and adds white space from its arguments
via the following rules:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
It skips any <tt>\@{..}</tt> enclosed sequence.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
It skips any <tt>\&lt;..&gt;</tt> enclosed sequence - note that the contents
eventually will end up in <tt>\@{..}</tt> (at) scope.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
It removes all spaces, tabs, and newlines it encounters otherwise.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
It inspects and (after inspection) removes all <tt>\`{..}</tt> enclosed
sequences it encounters. During inspection, <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a> maps
'<tt>s</tt>' to a space, '<tt>t</tt>' to a tab, and '<tt>n</tt>' to a newline.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
If the sequence <tt>\`{&lt;}</tt> is encountered (not in at scope),
<tt>\formatted#1</tt> starts copying literally without munging
whitespace; it resumes its normal mode of operation
after encountering the sequence <tt>\`{&gt;}</tt>.</p>
</div>
</div>
<p class="asd_par">
This is useful for writing legible macro files while exercising full control
over whitespace (modulo Zoem's white space munging rules).</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The argument in its unformatted form.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="get_2">
</a>
<tt>\get#2</tt>:&nbsp;&nbsp;<tt>\get{&lt;dict-label&gt;}{&lt;key-sig&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The user stack is searched from top to bottom for dictionaries
with label <tt>&lt;dict-label&gt;</tt>, and those dictionaries
are searched in order for a key with signature <tt>&lt;key-sig&gt;</tt>.
The first succesful match is retrieved and its definition
is pushed onto the interpretation stack.
It is an error if no such definition is found.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
The label of the default user dictionary is <tt>''</tt>. This ties
in with the syntax <tt>\''keysig</tt>, used to specify the user
dictionary stack. So the following:</p>
<div class="verbatim">      \set{user}{Jill}
      \push{foo}
      \set{user}{Phil}
      \push{bar}
      \set{user}{Bill}
      \get{''}{user} \get{foo}{user} \get{bar}{user}</div>
<p class="asd_car">
yields output <tt>Jill Phill Bill</tt>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
It is currently not possible to access keys that take arguments.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The result of processing the retrieved definition.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="if_3">
</a>
<tt>\if#3</tt>:&nbsp;&nbsp;<tt>\if{&lt;&lt;int-expr&gt;&gt;}{&lt;any1&gt;}{&lt;any2&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The first argument is expanded and interpreted as an integer.
If it is nonzero, <tt>&lt;any1&gt;</tt> is pushed on the interpretation stack
and <tt>&lt;any2&gt;</tt> is ignored, vice versa if it is zero.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Either <tt>&lt;any1&gt;</tt> or <tt>&lt;any2&gt;</tt>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="inspect_4">
</a>
<tt>\inspect#4</tt>:&nbsp;&nbsp;<tt>\inspect{&lt;&lt;vararg&gt;&gt;}{&lt;&lt;reg&gt;&gt;}{&lt;&lt;any|anon key&gt;&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_ccar"><span class="asd_ccar_caption">status</span>Experimental</p>
<p class="asd_par">
All arguments are expanded before use. <tt>&lt;vararg&gt;</tt> currently
recognizes a single key <i>mods</i>. The value of <i>mods</i> may contain a
comma-separated list of the following directives. Repeated use
of <i>mods</i> is allowed.</p>
<div class="verbatim">
   posix
   icase
   dotall
   iter-lines
   iter-args
   match-once
   discard-nmp
   discard-nil-out
   discard-miss
   count-matches</div>
<p class="asd_par">
The <tt>posix</tt> directive is currently required, specifying that <acronym class="ucase" title="Portable Operating System Interface [for Unix]">POSIX</acronym>
regular expressions are used. The future might bring other regex syntaxes.</p>
<p class="asd_par">
Argument <tt>&lt;reg&gt;</tt> specifies a (<acronym class="ucase" title="Portable Operating System Interface [for Unix]">POSIX</acronym>) regular expression. Before being
passed to the match engine, it undergoes <span class="smallcaps">UNIX</span> and <span class="smallcaps">TILDE</span> tilde replacement
as described in <a class="local sibling" href="zoem.html#tildexp">the zoem manual</a>.</p>
<p class="asd_par">
Consult the <acronym class="ucase" title="Portable Operating System Interface [for Unix]">POSIX</acronym> documentation or the regex(7) manual page for a description
of posix regexp syntax.</p>
<p class="asd_par">
The expansion of <tt>&lt;any|anon key&gt;</tt> can either result in plain data or in an
anonymous key. The expansion of the last argument results in data to which
the regex <tt>&lt;reg&gt;</tt> is successively applied.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Interpolation</span>
If the second expansion starts with the pattern <tt>_#k{</tt> it is assumed
to be an anonymous key. The subpatterns from the matched pattern are
interpolated by the key, and the entire matched pattern is substituted by the
interpolation. Else, the matched pattern is simply replaced by the expansion.</p>
<p class="asd_par">
<tt>icase</tt> induces case insensitive matching.
<tt>dotall</tt> makes the dot&nbsp;<tt>.</tt> match any character, including the newline.
<tt>iter-lines</tt> causes matching to be applied to lines shifted from the data (i.e.
data is split on newlines).
<tt>iter-args</tt> causes matching to be applied to blocks shifted from the data (which
should obviously be a vararg).
<tt>match-once</tt> inspects each element under consideration only once.
<tt>count-matches</tt> replaces the data by the count of matches. In conjunction
with <tt>iter-lines</tt> or <tt>iter-args</tt> it yields the counts on separate lines
and in separate blocks, respectively.
<tt>discard-nmp</tt> discards non-matching parts.
<tt>discard-miss</tt> removes any lines or blocks which are empty after inspect
is done with it.
<tt>discard-nil-out</tt> discards any strings or lines or blocks that are empty
after matching and optionally interpolation has been applied.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Bugs</span>
The <acronym class="ucase" title="GNU's Not Unix">GNU</acronym> implementation of <acronym class="ucase" title="Portable Operating System Interface [for Unix]">POSIX</acronym> regexes was at some point known to be buggy
for long strings and/or long matches.</p>
<p class="asd_par">
A search pattern consisting of a single word boundary or the start-of-string
token (<tt>^</tt>) will match at each position, because after a succesful match
<a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a> simply resumes searching for a new match by skipping to the
end of the previous match (and adding a single position if the match had
width zero and offset zero). Similar but not yet noticed bugs may exist.</p>
<p class="asd_par">
Nevertheless, this can be a very useful primitive for the occasional
odd job, and it should always work except for the cases just mentioned.
If you have a complicated instance of <a class="intern" href="#inspect_4"><span class="zpr">\inspect#4</span></a>, test it first
in isolation. Consider sending a bug report in case you find one (a bug,
or a bug report).</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Depending on the presence of a match and the modifiers given.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="length_1">
</a>
<tt>\length#1</tt>:&nbsp;&nbsp;<tt>\length{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Computes the length of <tt>&lt;any&gt;</tt> and puts this in place.
It takes into account the zoem escape sequences <tt>\\</tt>, <tt>\{</tt>,
and <tt>\}</tt>. The future may bring a generalized <tt>\length#2</tt> primitive
that provides different ways of measuring string length.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>The length of any <tt>&lt;any&gt;</tt>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="let_1">
</a>
<tt>\let#1</tt>:&nbsp;&nbsp;<tt>\let{&lt;&lt;let expression&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The <a class="intern" href="#let_1"><span class="zpr">\let#1</span></a> primitive puts zoem in arithmetic mode and the contents are
parsed accordingly. All of C's operators are supported including the
logical, bitwise, and comparison operators as well as the ternary operator.
The operators <tt>**</tt> and <tt>//</tt> are added, which respectively denote
exponentiation and integer division.
Operations or functions resulting in integers are tracked, and
the result will be stored in the integer type used (typically
long) if possible. Thus one may find that</p>
<div class="verbatim">\let{2**42}
\let{2**22}
</div>
<p class="asd_car">
respectively result in <tt>4398046511104.0</tt> and <tt>2097152</tt>.</p>
<p class="asd_par">
The precedence rules used by Zoem are simpler than C's. The respective groups
of logical, bitwise, and comparison operators all have identical precedence
internally, and associate from left to right.</p>
<p class="asd_par">
Most of the <abbr class="ucase" title="American National Standards Institute">ANSI</abbr> C math functions are supported, with in addition
<tt>max</tt> and <tt>min</tt>. The functions <tt>round</tt>, <tt>sign</tt>, and <tt>abs</tt> behave
slightly different from their C counterparts, as they result in integer
results if no overflow occurs.</p>
<p class="asd_par">
At any place where an atomic type is expected one is allowed to insert
a zoem macro invocation. It will be evaluated and the result will be
interpreted as a number. Evaluation will take place in the order
as dictated by the precedence rules governing the expression.</p>
<p class="asd_par">
The logical operators shortcircuit and the ternary operator evaluates
only one of its branches. This can be used to create side effects, such
as in</p>
<div class="verbatim">
   \let{\bar &amp;&amp; \group{\set{foo}{zut}1}}
</div>
<p class="asd_car">
This sets <tt>foo</tt> only if <tt>bar</tt> evaluates to a non-zero number.
The trailing&nbsp;<tt>1</tt> in the <tt>group</tt> macro is good practice because
<a class="intern" href="#let_1"><span class="zpr">\let#1</span></a> expects a number to be the result of any macro it encounters.
It could have been any other number, or a macro or sequence of macros
evaluating to a number.
The <tt>group</tt> macro is a predefined macro that does nothing except
passing its arguments. It is necessary in this concocted example
because any occurrence of
a macro within <a class="intern" href="#let_1"><span class="zpr">\let#1</span></a> is interpreted as a number by itself.
The sequence <tt>\bar \bar</tt> would for example be syntactically
identical to <tt>1 1</tt>, which is incorrect.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>A number.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="nargs_1">
</a>
<tt>\nargs#1</tt>:&nbsp;&nbsp;<tt>\nargs{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The argument is not expanded. It puts in place a number that indicates
whether this argument could be parsed as a number of scopes or whether it is
a regular argument. The following list of examples illustrates
the rules according to which the number is created.</p>
<div class="verbatim">
   \nargs{{abc}def}     : -2      \: neither fish nor fowl
   \nargs{abc}          : -1      \: regular argument
   \nargs{abc{def}}     : -1      \: regular argument too
   \nargs{}             :  0      \: empty vararg (not empty regular arg)
   \nargs{   }          :  0      \: empty vararg again
   \nargs{{abc}}        :  1      \: vararg with 1 argument
   \nargs{{abc}{def}}   :  2      \: vararg with 2 arguments
   \nargs{   {abc}
             {def}
   }                    :  2      \: vararg with 2 arguments
   \: etc.
</div>
<p class="asd_par">
From this it is seen that if the first non-whitespace character
is an opening curly the primitive expects to find a number of scopes
with nothing inbetween or trailing.
If it does not succeed the result text is set to the special value -2.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>integer</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="pop_1">
</a>
<tt>\pop#1</tt>:&nbsp;&nbsp;<tt>\pop{&lt;label&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Pops a dictionary from the user dictionary stack pushed earlier
by <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a>. The tag <tt>&lt;label&gt;</tt> must be same as the one
supplied by that specific <a class="intern" href="#push_1"><span class="zpr">\push#1</span></a> invocation.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="protect_1">
</a>
<tt>\protect#1</tt>:&nbsp;&nbsp;<tt>\protect{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The argument is expanded. Subsequently, all backslashes and curlies
are escaped. The resulting text is put in place.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
<tt>&lt;any&gt;</tt> with backslashes and curlies escaped.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="push_1">
</a>
<tt>\push#1</tt>:&nbsp;&nbsp;<tt>\push{&lt;label&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Pushes a new dictionary onto the user dictionary stack with tag
<tt>&lt;label&gt;</tt>. The corresponding <a class="intern" href="#pop_1"><span class="zpr">\pop#1</span></a> should use the same tag. Note
that <a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a> with the <tt>lkey</tt> directive checks only the top-level
dictionary, whereas <a class="intern" href="#defined_2"><span class="zpr">\defined#2</span></a> with the <tt>key</tt> directive checks the
whole stack of dictionaries. Also, <a class="intern" href="#undef_1"><span class="zpr">\undef#1</span></a> only removes a key from the
top-level dictionary. There is currently not a way to access keys based on
dictionary label.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_par">
Example of usage:</p>
<div class="verbatim">\def{num}{1}
\push{foo}
   \def{num}{2}
   \push{bar}
      \def{num}{3}
      \push{tim}
         \def{num}{4}
      \pop{tim}
      num is \num
   \pop{bar}
   num is \num
\pop{foo}
num is \num</div>
<p class="asd_car">
results in
</p>
<div class="verbatim">num is 3
num is 2
num is 1</div>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="register_2">
</a>
<tt>\register#2</tt>:&nbsp;&nbsp;<tt>\register{&lt;tag&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Register <tt>&lt;any&gt;</tt> to be processed at the occassion specified by
<tt>&lt;tag&gt;</tt>. The only <tt>&lt;tag&gt;</tt> currently supported is <tt>END</tt>.
<tt>END</tt> registrees are processed only after all regular input has been
processed. Multiple <a class="intern" href="#register_2"><span class="zpr">\register#2</span></a> invocations are allowed. Registrees are
processed in the order of registration.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None at time of registering, the result of <tt>&lt;any&gt;</tt> at time of
processing.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="set_2">
</a>
<tt>\set#2</tt>:&nbsp;&nbsp;<tt>\set{&lt;key-sig&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
As <a class="intern" href="#def_2"><span class="zpr">\def#2</span></a> above, except that <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a> will not complain
if the key labeled by <tt>&lt;key-sig&gt;</tt> already exists.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span><a class="intern" href="#set_3"><span class="zpr">\set#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="setx_2">
</a>
<tt>\setx#2</tt>:&nbsp;&nbsp;<tt>\setx{&lt;key-sig&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The second argument is expanded and stored in the key <tt>&lt;key-name&gt;</tt>.
Besides simply storing the expansion of an expression, it can
also be used to do trickier things as</p>
<div class="verbatim">   \def{bar}{klaas}
   \setx{foo#2}{\bar says \1 and \2}
   \foo{x}{y}
   klaas says x and y</div>
<p class="asd_car">
If you need lambda-like capabilities, take note that you can use <tt>\!k</tt> or
<tt>\!{\k}</tt> to construct a positional parameter&nbsp;<tt>\k</tt>, if you want to
interpolate arguments into a key that will later take other arguments. Like
this:</p>
<div class="verbatim">   \: is there any use for this wacky stuff?
   \def{lambda#2}{\setx{\1#1}{\2 says \!1}}
   \lambda{foo}{bar}
   \foo{moo}
   bar says moo</div>
<p class="asd_car">
Take care: the <a class="intern" href="#dofile_2"><span class="zpr">\dofile#2</span></a> key outputs
to the default output file. If you need to include the contents of
a file within a <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> call, you need to use <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a> or <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>
in conjunction with <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span><a class="intern" href="#set_3"><span class="zpr">\set#3</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="set_3">
</a>
<tt>\set#3</tt>:&nbsp;&nbsp;<tt>\set{&lt;{modes}{..}{if}{..}{unless}{..}{dict}{..}{start}{..}{width}{..}&gt;}{&lt;key-sig&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This primitive encompasses all of the previous four as well as providing
additional modes of operation.
The first argument
is a vararg storing key-value pairs. The possible keys are <tt>modes</tt>,
<tt>if</tt>, <tt>unless</tt>, <tt>dict</tt>, <tt>start</tt> and <tt>width</tt>. All of these
are optional.
</p>
<p class="asd_par">
The <tt>&lt;modes&gt;</tt>
value, if present must be a string over the following characters.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">a</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">append to the key, do not overwrite, create if not existing.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">c</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">conditionally; only set if not already defined.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">e</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">existing; update existing key, possibly in lower dictionary.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">g</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">global; set in the global (bottom) user dictionary.</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">u</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">unary; do not interpret vararg in <tt>&lt;any&gt;</tt> as key-value list (data keys only)</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">v</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">vararg; interpret vararg in <tt>&lt;any&gt;</tt> as key-value list (regular keys only).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">w</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">warn if key exists (like <tt>\def#2</tt> and <tt>\defx#2</tt>).</p>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_leftalign nowrap "
style="">x</div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">expand argument (like <tt>\setx#2</tt> and <tt>\defx#2</tt>).</p>
</div>
</div>
<p class="asd_par">
The <tt>u</tt> directive applies when setting <a class="intern" href="#grape">data</a>.
The <tt>v</tt> directive applies when setting regular keys.
In this case, <tt>&lt;key-sig&gt;</tt> must be empty, and <tt>&lt;any&gt;</tt>
is treated as a vararg of repeated key-value pairs.
Directives can be combined as needed.
</p>
<p class="asd_par">
Note that keys in the global user dictionary can be accessed
even if other dictionaries are pushed using the syntax <tt>\''foo</tt>.</p>
<p class="asd_par">
The <i>if</i> and <i>unless</i> directives can be used to trigger action (i.e.
definition of keys) only if the corresponding clause evaluates to non-zero
or zero, respectively.
</p>
<p class="asd_par">
The <i>dict</i> directive must be followed by a dictionary name in the subsequent
block. The dictionary stack will be searched for a dictionary with
this name. The type of dictionary is derived from the key signature.
This is either the dollar dictonary used for the dictionary stack
associated with <a class="intern" href="#begin_2"><span class="zpr">\begin#2</span></a> (if the key starts with a dollar sign <tt>$</tt>),
or the default user dictionary.
</p>
<p class="asd_par">
The <i>start</i> and <i>width</i> directives only work if a single key is set.
Their values should evaluate to integers <tt>&lt;start&gt;</tt> and <tt>&lt;width&gt;</tt>.
The key will be set to its old value with a segment of length
<tt>&lt;width&gt;</tt> starting at offest <tt>&lt;start&gt;</tt> replaced by <tt>&lt;any&gt;</tt>.
Offsets are zero-based and units are in bytes.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">See also</span><a class="intern" href="#def_2"><span class="zpr">\def#2</span></a>, <a class="intern" href="#defx_2"><span class="zpr">\defx#2</span></a>, <a class="intern" href="#set_2"><span class="zpr">\set#2</span></a>, <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="special_1">
</a>
<tt>\special#1</tt>:&nbsp;&nbsp;<tt>\special{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<tt>&lt;vararg&gt;</tt> is expanded before use.
It must have an even number of arguments. These are
interpreted as pairs. The first of each pair must enclose an integer in
the range 0-255 or one of the special token identifiers <tt>-1</tt>,
<tt>-2</tt> or <tt>-3</tt>. The integers in the range 0-255 are interpreted as
character indices The characters indexed <tt>-1</tt>, <tt>-2</tt>
and <tt>-3</tt> correspond with the zoem glyphs&nbsp;<tt>\~</tt>, <tt>\|</tt>, and&nbsp;<tt>\-</tt>
respectively. The second element in each pair defines the string to
which the character specified by the first element must be mapped. This
string is interpreted in device scope. See the
<a class="intern" href="#dscope">Device scope</a> section for simple uses.</p>
<p class="asd_par">
A key may occur multiple times. The corresponding definitions
are stacked away and will be accessed according to the current
<i>special level</i>
(cf. the section on <a class="intern" href="#special">mapped characters in device scope</a>).</p>
<p class="asd_par">
Repeated use of <tt>\special#1</tt> does not cause the removal of previous
definitions, with one exception: If <tt>\special#1</tt> is invoked
with no arguments at all then all definitions are removed.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
Be sure to use delay sequences as appropriate, noting that vararg is expanded.
Below is how <a target="_parent" class="extern" href="http://micans.org/pud/">Portable Unix Documentation</a>
encodes a line break in troff:</p>
<div class="verbatim">{-2} {\!N.br\!N}</div>
<p class="asd_car">
Zoem interprets the value and accordingly associates
the device scope sequence <tt>\N.br\N</tt> with the token <tt>\|</tt>.
The escape sequence <tt>\N</tt> will thus be processed during
the filter stage as is appropriate.
Without the delay sequence zoem would try to expand <tt>\N</tt> during
processing of the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a> primitive.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="switch_2">
</a>
<tt>\switch#2</tt>:&nbsp;&nbsp;<tt>\switch{&lt;&lt;pivot&gt;&gt;}{&lt;vararg&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The first argument is expanded. Subsequently, two arguments are successively
taken from <tt>&lt;vararg&gt;</tt>. The first is expanded and string compared with
<tt>&lt;pivot&gt;</tt>. If they match, the second argument is expanded and everything
else is ignored. If they do not match, the procedure is repeated. If no
(odd) argument matches, and the <tt>&lt;vararg&gt;</tt> has an odd number of
arguments, the last argument is put in place. It can be considered a
failure clause. This primitive does not have fall-through behaviour; at
most one branch will be handed to the parser.</p>
<p class="asd_car">
Different cases can be grouped in a vararg. If <a class="intern" href="#switch_2"><span class="zpr">\switch#2</span></a> recognizes
that the test argument can be parsed as a vararg it will exctract all
the corresponding sub-arguments. If the pivot matches any of these
the branch corresponding to the test argument will be taken.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Either the first block associated with a matching case of <tt>&lt;pivot&gt;</tt>,
the failure clause, or nothing at all.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="system_3">
</a>
<tt>\system#3</tt>:&nbsp;&nbsp;<tt>\system{&lt;cmd&gt;}{&lt;&lt;args&gt;&gt;}{&lt;&lt;data&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<i>By default this primitive is disallowed.</i>
The first argument is the name of a system command. The environment variable
PATH is used in tracing the location of the command. If <tt>&lt;data&gt;</tt> is
non-empty, it is first <i>unprotected</i>, that is, escaped backslashes and
curlies are unescaped. The resulting text is then fed to command <tt>&lt;cmd&gt;</tt>
with arguments <tt>&lt;args&gt;</tt>. The latter, if non-empty, must be
specified as a vararg, even if only a single argument is present.
Should execution of the command (be it with or
without data) result in output on <span class="smallcaps">STDOUT</span> then the latter is captured,
backslashes and curlies are escaped (i.e. the output is protected), and the
result is put in place. <span class="smallcaps">STDERR</span> is the same as it is for the parent (zoem).</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
The security implications of this feature. By default
zoem will <i>ignore</i> <tt>\system</tt>. The
command line option <tt>--unsafe</tt> will cause zoem to prompt for user
confirmation (if prompting is not possible it will ignore again) for
each encountered <tt>\system</tt> invocation. The option <tt>--unsafe-silent</tt>
will silently allow all <tt>\system</tt> invocations. The option
<tt>--allow=cmd[:cmd]*</tt> explicitly specifies which commands to allow silently.
It is also possible to use this option repeatedly rather than separate
different commands by colons.</p>
<p class="asd_par">
If the zoem command line option <tt>--system-honor</tt> is used, zoem will
exit if a system command fails or is ignored.</p>
<p class="asd_par">
A simple exit status is written in the variable <a class="intern" href="#session"><tt>\__sysval__</tt></a>:
it is zero (<tt>0</tt>) on success, and one (<tt>1</tt>) on failure.</p>
<p class="asd_par">
Refer to <a class="local sibling" href="zoem.html">the manual page of the zoem interpreter</a> for
more information on <tt>--unsafe</tt>, <tt>--unsafe-silent</tt>,
<tt>--allow=</tt>, and <tt>--system-honor</tt>.</p>
<p class="asd_par">
Built-in macros <tt>\system#2</tt> and <tt>system#1</tt> exist. The former
drops the <tt>&lt;data&gt;</tt> argument, the latter also drops the <tt>&lt;args&gt;</tt>
argument.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span></p>
<div class="verbatim">\system{sort}{{-n}}{\finsert{foo}}
\system{ls}{{-l}{-a}}
\system{date}</div>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The output captured (and then protected) from <tt>&lt;cmd&gt;</tt>'s <span class="smallcaps">STDOUT</span>, if any.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="table_5">
</a>
<tt>\table#5</tt>:&nbsp;&nbsp;<tt>\table{&lt;&lt;row length&gt;&gt;}{&lt;any1&gt;}{&lt;any2&gt;}{&lt;any3&gt;}{&lt;&lt;vararg&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The first argument is expanded and interpreted as an integer, say&nbsp;<tt>k</tt>.
Successively, vectors of <tt>k</tt>&nbsp;elements are shifted from
<tt>&lt;vararg&gt;</tt>. Each vector is bordered on the left with
<tt>&lt;any1&gt;</tt>, bordered on the right with <tt>&lt;any3&gt;</tt>, and
all elements in the vector are separated with <tt>&lt;any2&gt;</tt>.</p>
<p class="asd_par">
This primitive is perhaps not really needed as its functionality
is largely covered by <a class="intern" href="#apply_2"><span class="zpr">\apply#2</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The blocks from <tt>&lt;vararg&gt;</tt> interspersed in a table-like
manner with <tt>&lt;any1&gt;</tt>, <tt>&lt;any2&gt;</tt>, and <tt>&lt;any3&gt;</tt>.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="textmap_2">
</a>
<tt>\textmap#2</tt>:&nbsp;&nbsp;<tt>\textmap{&lt;vararg&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Apply one or more transformations to <tt>&lt;any&gt;</tt> and
put the result in place.
<tt>&lt;vararg&gt;</tt> takes a succession of key-value pairs.
The associated transformation are applied in order. The
supported transformations are:</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{word}{ucase}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Uppercase <tt>&lt;any&gt;</tt>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{word}{lcase}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Lowercase <tt>&lt;any&gt;</tt>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{number}{roman}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Convert number to Roman
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{number}{alpha}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Convert number to letters
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{repeat}{&lt;num&gt;}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Concatenate &lt;num&gt; copies of <tt>&lt;any&gt;</tt>
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{caesar}{&lt;num&gt;}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Apply caesar encryption
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{vigenere}{&lt;key&gt;}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Apply vigenere encryption
</div>
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign nowrap "
style="right:-5em">{vigenerex}{&lt;key&gt;}</div></div></div>
<div class=" item_text " style="margin-left:6em">
Apply vigenere encryption and include space
</div>
</div>
<p class="asd_par">
The roman transformation can e.g. used to equip the Aephea itemize
environment with roman numbering. To get uppercase roman,
do this:</p>
<div class="verbatim">   \textmap{{number}{roman}{word}{ucase}}{\your_nice_counter}</div>
<p class="asd_car">
The alpha transformation maps its argument to a string over the alphabet <tt>_a-z</tt>, i.e.
all the set of all lowercase letters with the underscore added.
This set is simply used for counting in base&nbsp;27, with the underscore
playing the role of zero.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The transformed text.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="throw_2">
</a>
<tt>\throw#2</tt>:&nbsp;&nbsp;<tt>\throw{&lt;towel|error|done&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Quit parsing, unwind stack until some occurrence of
<a class="intern" href="#catch_2"><span class="zpr">\catch#2</span></a>, <a class="intern" href="#try_1"><span class="zpr">\try#1</span></a> captures this throw.
</p>
<p class="asd_par">
The throw <tt>\throw{done}</tt> is also unconditionally caught by
<a class="intern" href="#while_2"><span class="zpr">\while#2</span></a> and <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a>.
If <tt>\throw{done}</tt> is encapsulated by neither of these four
primitives it means that processing of the current file
is stopped, and processing at the including file, if applicable,
is resumed.
</p>
<p class="asd_par">
<tt>&lt;any&gt;</tt> is digested; if it has positive length the result
is issued as a diagnostic.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
Many primitives evaluate one or more of their arguments before use,
as indicated in this manual.
An occurrence of <tt>\throw{done}</tt> in such an argument, if not caught, will be
treated like an error. It is possible to use <tt>\throw{done}</tt> in such
an instance by encapsulating the argument in <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a>.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None, affects the result text of the embedding scopes.
</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="tr_2">
</a>
<tt>\tr#2</tt>:&nbsp;&nbsp;<tt>\tr{&lt;vararg&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<tt>&lt;vararg&gt;</tt> 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 <tt>&lt;any&gt;</tt> by successively applying
translation, deletion and squashing in that order. Only the
transformations that are needed need be specified.</p>
<p class="asd_par">
The syntax accepted as translation specification 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. Finally, character specifications can be
complemented by preceding them with the caret <tt>^</tt>. See further below for
examples where these features are used.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Preprocessing</span>
The values (not the data <tt>&lt;any&gt;</tt>) are subjected to <span class="smallcaps">UNIX</span> tilde expansion
as described in the <a class="local sibling" href="zoem.html#tildexp">the zoem manual</a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Syntax</span>
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>
<div class="verbatim">   [:alnum:]
   [:alpha:]
   [:cntrl:]
   [:digit:]
   [:graph:]
   [:lower:]
   [:print:]
   [:punct:]
   [:space:]
   [:upper:]
   [:xdigit:]</div>
<p class="asd_par">
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="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The expanded <tt>&lt;any&gt;</tt> subjected to the <tt>tr</tt> operator as specified.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span>
The following was entered in interactive mode.</p>
<div class="verbatim">\tr{
   {from}{[:lower:][:upper:][:digit:][:space:][:punct:]}
   {to}{[*L#][*U#][*D#][*S#][*P#]}}{
 !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@
ABCDEFGHIJKLMNOPQRSTUVWXYZ
[\\]^_`
abcdefghijklmnopqrstuvwxyz
\{|\}~]}
.
----------------------------------------
SSPPPPPPPPPPPPPPPDDDDDDDDDDPPPPPPPSUUUUUUUUUUUUUUUUUUUUUUUUUUSPPPPPPSLLLLLLLLLLLLLLLLLLLLLLLLLLSPPPPP
----------------------------------------
\tr{
   {squash}{^}
   {from}{[:lower:][:upper:][:digit:][:space:][:punct:]}
   {to}{[*L#][*U#][*D#][*S#][*P#]}}{
 !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@
ABCDEFGHIJKLMNOPQRSTUVWXYZ
[\\]^_`
abcdefghijklmnopqrstuvwxyz
\{|\}~]}
.
----------------------------------------
SPDPSUSPSLSP</div>
<p class="asd_car">Note how the magic repeat operator <tt>[*#]</tt> stops on class boundaries.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="trace_1">
</a>
<tt>\trace#1</tt>:&nbsp;&nbsp;<tt>\trace{&lt;&lt;int&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The argument is expanded and interpreted as an integer. This integer
encodes an ensemble of flags controlling the trace output. The different
modes are exactly the same as those that can be set from the command line.
Refer to the <a class="intern" href="#cline">corresponding section</a> for more information.
Special values are&nbsp;<tt>0</tt> (switch off all tracing),
<tt>-1</tt> (switch on all tracing modes in short mode),
<tt>-2</tt> (switch on all tracing modes in long mode),
<tt>-3</tt> (switch to the previous tracing value),
and <tt>-4</tt> emit a listing of tracing bits.
The third can be useful to switch tracing on for a short while and then off
again if you need to debug your document.
Additionally and redundantly, <tt>\trace#1</tt> puts the previous tracing
value in place.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The previous tracing value.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="try_1">
</a>
<tt>\try#1</tt>:&nbsp;&nbsp;<tt>\try{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This will process the content and
output is written in the macro <a class="intern" href="#session"><tt>\__zoemput__</tt></a>. Output will
be truncated in case <a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a> was used or an error occurred.
The status, currently one of <tt>done</tt>, <tt>towel</tt>, or <tt>error</tt>,
is written in the session macro <a class="intern" href="#session"><tt>\__zoemstat__</tt></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="undef_1">
</a>
<tt>\undef#1</tt>:&nbsp;&nbsp;<tt>\undef{&lt;key-sig&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Deletes the key with signature <tt>&lt;key-sig&gt;</tt> from the
top level dictionary. Complains (but does not fail) if the key
does not exist in that dictionary.
It is possible to specify that a regular key (i.e. not a dollar key)
must be looked up in the global dictionary by prefixing its
signature with two single quotes.
</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="vanish_1">
</a>
<tt>\vanish#1</tt>:&nbsp;&nbsp;<tt>\vanish{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
This will only process the content for its side effects. Any result text is
disregarded. This allows easy free-style commenting of sequences of
definitions. By comparison, <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a> provides the means to give a
formatted presentation of the definitions themselves.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="while_2">
</a>
<tt>\while#2</tt>:&nbsp;&nbsp;<tt>\while{&lt;condition&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
While <tt>&lt;condition&gt;</tt> exands to something that is nonzero when interpreted
as an integer, <tt>&lt;any&gt;</tt> is expanded and concatenated to the result text.
The following piece of zoem asks the user for an integer and writes all
Fibonacci numbers smaller than that integer plus one extra to <span class="smallcaps">STDOUT</span>.</p>
<div class="verbatim">\import{ctr.zmm}     \: import ctr macros.
\def{fib#1}{
   \ctrset{a}{1}
   \ctrset{b}{1}
   \ctrset{c}{0}
   \while{\eqt{lq}{\ctrput{c}}{\1}}{
      \ctrset{c}{\ctrput{a}}
      \ctrset{a}{\let{\ctrput{a}+\ctrput{b}}}
      \write{-}{txt}{\ctrput{c}\|}
      \ctrset{b}{\ctrset{c}}
   }
}

\write{-}{txt}{Enter a number please, }
\write{-}{txt}{then press &lt;cr&gt; and &lt;ctl-d&gt;\|}
\setx{num}{\finsert{-}}    \:  this reads from <span class="smallcaps">STDIN</span>.
\fib{\num}</div>
<p class="asd_ccar"><span class="asd_ccar_caption">Note</span>
The strings built up by <a class="intern" href="#while_2"><span class="zpr">\while#2</span></a> are internally concatenated
until it is done, so the result from <a class="intern" href="#while_2"><span class="zpr">\while#2</span></a> <i>can</i> be captured.
This will make <a class="intern" href="#while_2"><span class="zpr">\while#2</span></a> work for <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a>. If you want to output
100M worth of lines or paragraphs in a while loop, either embed the stuff to
be output in a <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> call and make sure that no whitespace results
from the loop (for example by using <a class="intern" href="#formatted_1"><span class="zpr">\formatted#1</span></a>), or simply use
<a class="intern" href="#whilst_2"><span class="zpr">\whilst#2</span></a>. With <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> you can specify a file name to which
results should be output (use <a class="intern" href="#session"><tt>\__fnout__</tt></a> for the current default output
file) whereas <a class="intern" href="#whilst_2"><span class="zpr">\whilst#2</span></a> simply outputs to the current default stream.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="whilst_2">
</a>
<tt>\whilst#2</tt>:&nbsp;&nbsp;<tt>\whilst{&lt;condition&gt;}{&lt;any&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
While <tt>&lt;condition&gt;</tt> exands to something that is nonzero when interpreted
as an integer, <tt>&lt;any&gt;</tt> is expanded and <i>immediately output</i> to
the current default output stream.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None &mdash; everything is sent to the default output stream right away.
Output from <a class="intern" href="#while_2"><span class="zpr">\while#2</span></a> <i>can</i> be captured, i.e. it can be that what
is assigned by a <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> invocation.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="write_3">
</a>
<tt>\write#3</tt>:&nbsp;&nbsp;<tt>\write{&lt;&lt;file name&gt;&gt;}{&lt;str&gt;}{&lt;&lt;any&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The first argument is expanded and used as a file name. It is a fatal error
if the file has either not been opened by a previous <tt>\write#3</tt> call or
cannot be opened for writing. Two special file names or 'streams' are
recognized, namely <tt>-</tt> and <tt>stderr</tt>. They map to <span class="smallcaps">STDOUT</span>
and <span class="smallcaps">STDERR</span>.
The third argument is expanded, filtered, and written to file. The second
argument indicates the filter to be used. It must be one of the (literal)
strings <tt>copy</tt>, <tt>device</tt>, or <tt>txt</tt>.</p>
<p class="asd_par">
The <tt>copy</tt> filter does not filter anything at all (neither plain scope
nor device scope) and does not touch any of the zoem escape sequences
remaining after expansion.</p>
<p class="asd_par">
The <tt>device</tt> filter does a full-fledged filtering of both parse scopes.
It respects the settings according to the <a class="intern" href="#special_1"><span class="zpr">\special#1</span></a>
primitive. The write primitive associates unique metadata with each
file it opens, so <i>at directives</i> such as&nbsp;<tt>\N</tt>, <tt>\W</tt>, and <tt>\+</tt>
for different output files do not interfere with one another.
Refer to the <a class="intern" href="#dscope">Device scope</a> section for more information on
at directives.</p>
<p class="asd_par">
The <tt>txt</tt> filter maps <tt>\\</tt> to <tt>\</tt> (i.e. a single
backslash), <tt>\~</tt>&nbsp;to a single space, <tt>\-</tt>&nbsp;to a single hyphen,
<tt>\,</tt> (the atomic separator) to nil, <tt>\|</tt>&nbsp;to a newline,
<tt>\{</tt>&nbsp;to&nbsp;<tt>{</tt>, and&nbsp;<tt>\}</tt> to&nbsp;<tt>}</tt>. It copies everything
else verbatim.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
Technically none, as the output of <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> cannot be captured.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="writeto_1">
</a>
<tt>\writeto#1</tt>:&nbsp;&nbsp;<tt>\writeto{&lt;&lt;file-name&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
Closes the current default output stream, and changes it to point to file
<tt>&lt;file name&gt;</tt>. Useful when splitting a document into chapters, or god
forbid, nodes.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Notes</span>
If the file name contains a path separator, zoem will refuse to carry
on, because this may pose a risk that sensitive files are overwritten -
in case someone has written a malicious zoem input file to do just that.
If the option <tt>--unsafe</tt> is used, zoem will query the user
what to do. If the option <tt>--unsafe-silent</tt> is used, zoem will
merrily buzz on without querying.
The path separator is entirely <span class="smallcaps">UNIX</span>-centric, i.e. a forward slash.</p>
<p class="asd_par">
Zoem will recognize if <tt>\writeto#1</tt> is issued more than once for the same
file <tt>&lt;file-name&gt;</tt>. On the first occassion, it will simply open the file
and truncate any previous contents. On the second occasion and onwards, it
will append to the file. There is currently no option to vary this
behaviour. Zoem will not recognize the fact that different strings might
refer to the same file (e.g. <tt>foo</tt> and <tt>./foo</tt>). Whenever it encounters
a file name not seen before, it will try to open the file in write mode.</p>
<p class="asd_par">
In interactive mode, <tt>\writeto#1</tt> has no effect for text entered
in plain mode. It <i>does</i> have effect in case <a class="intern" href="#write_3"><span class="zpr">\write#3</span></a> is issued
with <a class="intern" href="#session"><tt>\__fnout__</tt></a> as the file name argument, since <tt>\writeto#3</tt>
resets the <a class="intern" href="#session"><tt>\__fnout__</tt></a> macro.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
None.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_cascade"><div class=" item_leftalign nowrap "
style="">
<a name="zinsert_1">
</a>
<tt>\zinsert#1</tt>:&nbsp;&nbsp;<tt>\zinsert{&lt;&lt;file name&gt;&gt;}</tt></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
The contents of file <tt>&lt;file name&gt;</tt> are put in place unaltered
enclosed by the <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a> delay primitive. The contents must necessarily
satisfy zoem syntax. If the file can not be opened, the empty
string results.
See also <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Example</span></p>
<div class="verbatim">\setx{foo}{\zinsert{mydata}}
\setx{foo}{\eval{\zinsert{mydata}}}</div>
<p class="asd_par">
In the first case, <tt>\foo</tt> will contain the exact contents
of file <tt>mydata</tt>. Those contents are first
enclosed within the <a class="intern" href="#excl_1"><span class="zpr">\!#1</span></a> primitive by <a class="intern" href="#zinsert_1"><span class="zpr">\zinsert#1</span></a>.
The resulting text is evaluated by <a class="intern" href="#setx_2"><span class="zpr">\setx#2</span></a> - the only
thing this does is strip the enclosing <tt>\!{}</tt> scope.</p>
<p class="asd_par">
In the second case, <tt>\foo</tt> will contain the <i>evaluated</i>
contents of file <tt>mydata</tt>, as <a class="intern" href="#eval_1"><span class="zpr">\eval#1</span></a> adds an additional
layer of evaluation.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Note</span>
This primitive is able to read
<a class="intern" href="#fileread">inline files</a>, unlike <a class="intern" href="#finsert_1"><span class="zpr">\finsert#1</span></a>.</p>
<p class="asd_cpar"><span class="asd_cpar_caption">Result text</span>
The contents of file <tt>file name</tt> or the empty string if
file can not be opened.</p>
</div>
</div>

<a name="pitfalls"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#pitfalls">Pitfalls</a></div><div class="sec_num"><a class="intern" href="#toc9"><span class="sec_num">9</span></a></div></div>
<p class="asd_par">
This is a young section, with only few entries yet.</p>
<div class=" itemize " style="margin-top:1em; margin-left:0em; font-size:100%">
<div style="position:relative; margin-top:0em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[<a class="intern" href="#system_3"><span class="zpr">\system#3</span></a>] Beware that the argument/option list (the second
argument of <tt>\system#3</tt>) is encoded
as a vararg. If you have a single argument, it is easy to
forget the enclosing curlies. In that case, zoem ignores the
argument altogether.</p>
<p class="asd_par">
Zoem protects the data returned by <tt>\system#3</tt>. So you may
e.g. think (as I once did) that</p>
<div class="verbatim">\system{date}{{%e}{%B}{%Y}}</div>
<p class="asd_car">
Is a neat way to create a vararg, but you will end up with
something like</p>
<div class="verbatim">\{24\}\{April\}\{2004\}</div>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
[Package authors] Beware of using <i>and</i> scope within <i>at</i> scope
within a <tt>\write#3</tt> invocation that uses the copy filter.</p>
<div class="verbatim">\write{file}{copy}{ foo \@{ zut \&amp;{ bar }}}</div>
<p class="asd_car">
The <tt>bar</tt> part will not be evaluated as the copy filter does not apply the
filtering stage. If the stuff written is read back in from some other part
of the document, or from another document altogether, the <tt>bar</tt> part will
be evaluated in a different context than the one in which it was created.</p>
</div>
<div style="position:relative; margin-top:1em"><div class=" item_compact"><div class=" item_rightalign "
style="right:-1em"><span class="itembullet">&bull;</span></div></div></div>
<div class=" item_text " style="margin-left:2em">
<p class="asd_car">
<a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a> with argument <tt>done</tt> can be used to halt processing of the
current file. Refer to the <a class="intern" href="#throw_2"><span class="zpr">\throw#2</span></a> description for the associated
requirements.</p>
</div>
</div>

<a name="glossary"></a><div class="sec_leader sec_lev1"><div class="sec_title"><a class="intern" href="#glossary">Glossary</a></div><div class="sec_num"><a class="intern" href="#toc10"><span class="sec_num">10</span></a></div></div>
<p class="asd_par">
For <b>user keys</b>, <b>dollar keys</b>, and <b>dictionary stacks</b>,
refer to the <a class="intern" href="#dictionary">Dictionary stacks</a> section and the <a class="intern" href="#macro">Macro expansion</a> section.
For <b>data keys</b>, refer to the <a class="intern" href="#grape">Tree data</a> section.</p>
<p class="asd_par">
For <b>key signatures</b> and <b>key mention</b>, refer to the <a class="intern" href="#signature">Key signatures</a>
section. For <b>anonymous keys</b>: the <a class="intern" href="#anonymous">Anonymous keys</a> section.</p>
<p class="asd_par">
<b>Session variables</b> are described in the <a class="intern" href="#session">Session keys</a> section.</p>
<p class="asd_par">
For <b>varargs</b>, arguments in which a variable number of sub-arguments
can be stored, and for <b>blocks</b>: the <a class="intern" href="#vararg">Of blocks and varargs</a> section.</p>
<p class="asd_par">
For <b>plain scope</b>, <b>device scope</b>, <b>at scope</b>, and <b>glyph
sequences</b>: The <a class="intern" href="#dichotomy">Scope dichotomy</a> and <a class="intern" href="#dscope">Device scope</a> sections.</p>
<p class="asd_par">
For file read and <b>inline files</b>: the <a class="intern" href="#fileread">File read</a> section.</p>
<p class="asd_par">
Sometimes zoem <i>protects</i> or <i>unprotects</i> data. Refer to the
<a class="intern" href="#protection">Protection</a> section.</p>
<a name="asd_body_end"></a>
</div></div>
</body>
</html>