File: manual.html

package info (click to toggle)
cost 2.2p1-3
links: PTS
area: main
in suites: woody
size: 1,032 kB
ctags: 1,728
sloc: ansic: 12,123; tcl: 2,702; sh: 209; makefile: 161
file content (1104 lines) | stat: -rw-r--r-- 48,736 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- This file was automatically generated.  DO NOT EDIT BY HAND. -->
<HTML>
<HEAD>
<TITLE>Cost 2 Reference Manual</TITLE>
<META NAME=Creator CONTENT="Cost 2.1a1">
<LINK REV=MADE HREF="mailto:joe@flightlab.com">
<LINK REL=STYLESHEET HREF="manual.css">
</HEAD>
<BODY>
<DIV CLASS=header><H1 CLASS=title>Cost 2 Reference Manual</H1>
<P>Joe English<BR><I>Last updated: Sunday 27 June 1999, 15:31 PDT</I></DIV><HR>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#INTRO">1 Introduction</A>
<LI CLASS=TOCENTRY><A HREF="#SECT1">2 Running Cost</A>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#SECT2">2.1 Environment Variables</A>
<LI CLASS=TOCENTRY><A HREF="#SECT3">2.2 Loading documents</A>
<LI CLASS=TOCENTRY><A HREF="#SECT4">2.3 Running costsh</A>
</UL>
<LI CLASS=TOCENTRY><A HREF="#ESIS">3 Element Structure</A>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#PROP-QUERY">3.1 General properties</A>
<LI CLASS=TOCENTRY><A HREF="#SECT5">3.2 Element nodes</A>
<LI CLASS=TOCENTRY><A HREF="#SECT6">3.3 Data nodes</A>
<LI CLASS=TOCENTRY><A HREF="#ENTITY-PROPS">3.4 Entities</A>
<LI CLASS=TOCENTRY><A HREF="#SECT7">3.5 Attributes</A>
</UL>
<LI CLASS=TOCENTRY><A HREF="#QUERY">4 Queries</A>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#SECT8">4.1 Syntax</A>
<LI CLASS=TOCENTRY><A HREF="#SECT9">4.2 Examples</A>
<LI CLASS=TOCENTRY><A HREF="#SECT10">4.3 Query commands</A>
<LI CLASS=TOCENTRY><A HREF="#NAV-QUERY">4.4 Navigational clauses</A>
<LI CLASS=TOCENTRY><A HREF="#SECT11">4.5 Addressing</A>
<LI CLASS=TOCENTRY><A HREF="#SECT12">4.6 Miscellaneous clauses</A>
</UL>
<LI CLASS=TOCENTRY><A HREF="#SPECS">5 Specifications</A>
<LI CLASS=TOCENTRY><A HREF="#PROPERTIES">6 Application Properties</A>
<LI CLASS=TOCENTRY><A HREF="#HANDLERS">7 Event handlers</A>
<LI CLASS=TOCENTRY><A HREF="#RELATIONS">8 Links and relations</A>
<LI CLASS=TOCENTRY><A HREF="#UTILS">9 Miscellaneous utilities</A>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#ENVIRONMENTS">9.1 Environments</A>
<LI CLASS=TOCENTRY><A HREF="#SUBST">9.2 Substitutions</A>
<LI CLASS=TOCENTRY><A HREF="#SECT13">9.3 Numerals</A>
<LI CLASS=TOCENTRY><A HREF="#SECT14">9.4 Miscellaneous Miscellaneous</A>
<LI CLASS=TOCENTRY><A HREF="#REQUIRE-CMD">9.5 Script management</A>
</UL>
</UL><HR>
<H2><A NAME=INTRO>1 Introduction</A></H2>
<P>Cost is a structure-controlled SGML application programming tool.  
It is implemented as a Tcl extension, and works in conjunction 
with James Clark's nsgmls and/or sgmls parsers.
<P>Cost provides a flexible set of 
low-level primitives upon which 
sophisticated applications can be built.
These include
<UL><LI>A powerful <EM>query language</EM> for navigating the document tree
and extracting ESIS information; </LI><LI>An <EM>event-driven</EM> programming interface;</LI><LI>A <EM>specification</EM> mechanism which binds
properties to nodes based on queries;</LI></UL>
<P>Cost can be dynamically <B>load</B>ed
into a Tcl application with the usual <B>package</B> mechanism,
or it can be statically linked into a custom Tcl interpreter.
There is also a command-line interface, <B>costsh</B>,
which can be used interactively or as part of a command pipeline.
A windowing interface, <B>costwish</B>, is also available for
building GUI applications with Cost and Tk.
<P>Cost provides a relatively low-level interface:
it's a toolkit for building SGML applications rather
than an SGML application itself.  One application,
<TT>Simple.tcl</TT>, is provided as an example and as
a starting point.  

<H2><A NAME=SECT1>2 Running Cost</A></H2>
<HR>

<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#SECT2">2.1 Environment Variables</A>
<LI CLASS=TOCENTRY><A HREF="#SECT3">2.2 Loading documents</A>
<LI CLASS=TOCENTRY><A HREF="#SECT4">2.3 Running costsh</A>
</UL><HR>
<P>Cost can be included in a Tcl shell in the usual way,
by calling <SAMP>Cost_Init(interp);</SAMP> from
<TT>Tcl_AppInit</TT> and linking the executable with
the Cost library (<TT>libcost2.2.a</TT> under Unix).
It can also be dynamically loaded into an existing Tcl shell
with the Tcl command:
<PRE>
package require Cost
</PRE>

<H3><A NAME=SECT2>2.1 Environment Variables</A></H3>
<P>Cost uses the following environment variables,
all of which are optional:
<DL><DT><TT>$COSTLIB</TT></DT><DD>Points to the directory containing <TT>costinit.tcl</TT>
and other library scripts.</DD><DT><TT>$COSTPATH</TT></DT><DD>A colon-separated list of directories to be
searched by the <B>cost:require</B> command;
see <A HREF="#REQUIRE-CMD">9.5. ``Script management''</A>.</DD><DT>TCL_LIBRARY</DT><DT>TCLLIBPATH</DT><DD>Used by Tcl to find its script libraries; see the
Tcl documentation for details.</DD><DT>SGML_DECLARATION</DT><DD>If set, the <B>loaddoc</B> command
passes its value on the command line
when running a subprocess to parse SGML documents.  
It should point to a file containing the
default SGML declaration for your site.
(This is primarily useful if you're using <B>sgmls</B>,
which uses the Reference Concrete Syntax by default.
Most document types won't work with this SGML declaration,
so you usually have to provide a different one.
<B>nsgmls</B> uses a more sensible set of defaults.)</DD><DT>SGML_CATALOG_FILES</DT><DD>Used by <B>nsgmls</B> and later versions of <B>sgmls</B>
to find catalog files to resolve <SAMP>PUBLIC</SAMP> identifiers.</DD></DL>

<H3><A NAME=SECT3>2.2 Loading documents</A></H3>
<P>The Cost command <B>loadsgmls</B> reads a document into memory:<PRE>
<B>loadsgmls</B> <I>filehandle</I>
</PRE><P>Reads an ESIS event stream in <B>sgmls</B> format from  <I>filehandle</I>
and constructs the internal document tree.
The current node is set to the root of the document.
<I>filehandle</I> must be a Tcl file handle
such as <SAMP>stdin</SAMP> or the return value of <B>open</B>.
Returns the <EM>document handle</EM> of the new document.<P>Cost provides two convenience functions as wrappers
around <B>loadsgmls</B>.
<SAMP><B>loadfile</B> <I>file</I></SAMP>
reads a pre-parsed ESIS stream from a file and is
essentially the same as<PRE>
set fp [open "<I>filename</I>" r]
loadsgmls $fp
close $fp
</PRE><P><B>loaddoc</B> invokes <B>sgmls</B> as a subprocess:<PRE>
<B>loaddoc</B> <I>args...</I>
</PRE><P>Invokes <B>sgmls</B> with the arguments <I>args...</I>
and reads the ESIS output stream.
If the <TT>$SGML_DECLARATION</TT> environment variable
is set, passes that as the first argument to <B>sgmls</B>.<P><B>loadxml</B> parses and loads an XML document:<PRE>
loadxml <I>filehandle</I>
</PRE><P>Reads an XML document from <I>filehandle</I> and
constructs the internal document tree,
where <I>filehandle</I> is a Tcl file handle.
Sets the current node is set to the root of the document,
and returns a new <EM>document handle</EM>.<P>All of the above commands return a <EM>document handle</EM>,
which may be passed to <B>selectDocument</B> or <B>withDocument</B>
to change the current document:
<PRE>
selectDocument <I>documentHandle</I>
</PRE><P>Sets the current document to the document referred to by 
<I>documentHandle</I>, and sets the current node to 
the root node of that document.<PRE>
withDocument <I>documentHandle</I> { <I>script</I> }
</PRE><P>Sets the current document to the document referred to by 
<I>documentHandle</I>, sets the current node to 
the root node of that document, then evaluates
<I>script</I> as a Tcl script.
When the script returns -- either normally or with an error,
<B>return</B>, <B>break</B>, or <B>continue</B> statement --
restores the previous current document and current node.
Returns: whatever <I>script</I> does (including Tcl result codes).<PRE>
currentDocument
</PRE><P>Returns the document handle of the currently active document.
<H3><A NAME=SECT4>2.3 Running <B>costsh</B></A></H3>
<P>Normally <B>costsh</B> is used
in a pipeline with <B>[n]sgmls</B>:<PRE>
<B>sgmls</B> [ <I>options</I> ] <I>sgml-document</I> ...
    | <B>costsh</B> <B>-S</B> <I>specfile</I> [ <I>script-options ...</I> ]
</PRE><P>The <B>-S</B> flag specifies that <B>costsh</B>
is to operate as a filter:
it reads a parsed document instance in sgmls format from standard input,
then evaluates the Tcl script <I>specfile</I>.
The remaining <I>script-options ...</I> are
available in the global list <SAMP>argv</SAMP>.
Finally, <B>costsh</B> calls the Tcl procedure <B>main</B>
if one was defined in <I>specfile</I>, then exits.
<B>main</B> should take zero arguments.<P>Calling <B>costsh</B> with no arguments
starts an interactive shell:<PRE>
<B>costsh</B>
</PRE>
<H2><A NAME=ESIS>3 Element Structure</A></H2>
<HR>

<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#PROP-QUERY">3.1 General properties</A>
<LI CLASS=TOCENTRY><A HREF="#SECT5">3.2 Element nodes</A>
<LI CLASS=TOCENTRY><A HREF="#SECT6">3.3 Data nodes</A>
<LI CLASS=TOCENTRY><A HREF="#ENTITY-PROPS">3.4 Entities</A>
<LI CLASS=TOCENTRY><A HREF="#SECT7">3.5 Attributes</A>
</UL><HR>
<P>An SGML document is represented in Cost
as a hierarchical collection of <EM>nodes</EM>.
Each node has an ordered list of <EM>children</EM>,
and an unordered collection of named <EM>attributes</EM>.
Every node except the root node
has a unique <EM>parent</EM>.
<P>There are several types of nodes, each with
a different set of characteristics:
<DL><DT><B>SD</B></DT><DD>An SGML document or subdocument</DD><DT><B>EL</B></DT><DD>An element</DD><DT><B>PEL</B></DT><DD>A ``pseudo-element'' or data container</DD><DT><B>CDATA</B></DT><DD>A sequence of data characters (excluding record-ends)</DD><DT><B>RE</B></DT><DD>A record-end character</DD><DT><B>SDATA</B></DT><DD>System data, from an <SAMP>SDATA</SAMP> entity reference</DD><DT><B>ENTREF</B></DT><DD>A data entity reference</DD><DT><B>PI</B></DT><DD>A processing instruction</DD><DT><B>ENTITY</B></DT><DD>An entity</DD><DT><B>AT</B></DT><DD>An attribute or data attribute</DD><DT><B>ILINK</B></DT><DD>A multi-ended link between nodes.
(ILINK nodes do not come from the source document:
they are created by application code.  See <A HREF="#RELATIONS">8. ``Links and relations''</A>)</DD></DL>
<P>The root node of a document is always
an <B>SD</B> node.
Elements are represented by <B>EL</B> nodes.
Data content matched by a <SAMP>#PCDATA</SAMP> content model token
is represented by a <B>PEL</B> node.
Collectively, these three node types are called <EM>tree nodes</EM>.
<P>Sequences of characters other than record-ends
are represented by <B>CDATA</B> nodes, and
record-end characters appear as <B>RE</B> nodes.
(Technically, record-ends <EM>are</EM> character data,
but it is often useful to handle them separately
so Cost creates distinguished nodes for them.)
<P><B>PI</B> nodes
represent processing instructions and references to <SAMP>PI</SAMP> entities.
<P><B>SDATA</B> nodes represent
internal system data entity references,
and <B>ENTREF</B> nodes
represent external data entity references.
References to SGML text entities are expanded by the parser
and are not directly represented as tree nodes.
<P><B>CDATA</B>, <B>RE</B>, <B>SDATA</B>, and <B>ENTREF</B>
nodes always appear as children of <B>PEL</B> nodes.
<B>PI</B> nodes may appear anywhere in the tree.
<P><B>AT</B> and <B>ENTITY</B> nodes
do not appear as children of any node in the tree;
instead, they are accessed by name.

<P>Node properties are accessed with the <B>query</B> and <B>query*</B>
commands; see <A HREF="#QUERY">4. ``Queries''</A> for full details.

<H3><A NAME="PROP-QUERY">3.1 General properties</A></H3>
<PRE>
query <B>nodetype</B>
</PRE><P>Returns the <A HREF="#ESIS">node type</A> of the current node
(<SAMP>SD</SAMP>, <SAMP>EL</SAMP>, <SAMP>PEL</SAMP>, et cetera).<P>Specific node types may be selected with the
<B>sd</B>, <B>el</B>,
<B>pel</B>,
<B>cdata</B>, <B>sdata</B>, <B>re</B>, and <B>pi</B>
query clauses.
These test the type of the current node, and fail if it does not match.

<H3><A NAME=SECT5>3.2 Element nodes</A></H3>
<PRE>
query? <B>el</B>
</PRE><P>Tests if the current node is an <B>EL</B> node.<PRE>
query <B>gi</B>
</PRE><P>Returns the generic identifier (element type name) of the current node.
Fails if the current node is not an <B>EL</B> node.<PRE>
query? <B>withgi</B> <I>gi</I>
</PRE><P>Tests if the current node is an <B>EL</B> node
with generic identifier <I>gi</I>.
Matching is case-insensitive.<PRE>
query? <B>element</B> <I>gi</I>
</PRE><P>Synonym for <SAMP>query <B>withgi</B> <I>gi</I></SAMP><PRE>
query? <B>elements</B> "<I>gi...</I>"
</PRE><P>The argument <I>gi...</I> is a space-separated list of name tokens.
Succeeds if the current node's generic identifier is any one
of the listed tokens.  Matching is case-insensitive.<P><B>EL</B> nodes may also have a
<B>dcn</B> (<EM>data content notation</EM>) property.
The DCN of an element is the value of the attribute,
if any, with declared value <SAMP>NOTATION</SAMP>.

<H3><A NAME=SECT6>3.3 Data nodes</A></H3>
<P><EM>Data nodes</EM> are those which directly contain data.
This includes
<B>CDATA</B>, <B>SDATA</B>, <B>RE</B>, <B>PI</B>,
and <B>AT</B> nodes
(but not <B>PEL</B> nodes, which are <EM>containers</EM>
for data nodes).

<PRE>
query <B>content</B>
</PRE><P>Returns the character data content of the current node.
For <B>RE</B> nodes, this is always a newline character (<SAMP>\n</SAMP>).
For <B>SDATA</B> nodes it is the <EM>system data</EM> of the referenced entity.
For <B>PI</B> nodes it is the <EM>system data</EM>
    of the processing instruction.
For <B>AT</B> nodes it is the <EM>attribute value</EM>.
Fails for all other node types.<P>The <B>content</B> query clause only returns the content of data nodes.
The <B>content</B> <EM>command</EM> returns the
character data content of any node:
<PRE>
<B>content</B>
</PRE><P>If the current node is a data node,
equivalent to <SAMP>query content</SAMP>.
Otherwise, equivalent to
<SAMP>join [query* subtree textnode content] ""</SAMP>,
i.e., returns the text content of the current node.<P>The <B>textnode</B> clause filters out data nodes
which are not part of the document's ``primary content''
(e.g., processing instructions).
<PRE>
query? <B>textnode</B>
</PRE><P>Tests if the current node is a
<B>CDATA</B> (character data),
<B>RE</B> (record end), or
<B>SDATA</B> (system data) node.
<H3><A NAME="ENTITY-PROPS">3.4 Entities</A></H3>
<PRE>
query? <B>dataent</B>
</PRE><P>Tests if the current node is an
<B>ENTITY</B> (data entity)
or <B>ENTREF</B> (entity reference) node.<P><B>ENTREF</B> nodes appear in the document tree
at the point of a data entity reference.
<B>ENTITY</B> nodes represent the entity itself
and do not appear as children of any tree node.
All properties of <B>ENTITY</B> nodes,
including their content and data attributes,
are accessible from <B>ENTREF</B> nodes which reference them.

<P>The <B>entity</B> query clause navigates directly to
an <B>ENTITY</B> node:
<PRE>
query <B>entity</B> <I>ename</I>
</PRE><P>Selects the <B>ENTITY</B> node corresponding to
the entity named <I>ename</I> in the current subdocument, if any.
The entity name is case-sensitive.<P><B>ENTITY</B> nodes will only be present
for external data entities which are referenced in the document,
and data entities named in an attribute with declared value <SAMP>ENTITY</SAMP>
or <SAMP>ENTITIES</SAMP>.
<PRE>
query <B>ename</B>
</PRE><P>Returns the entity name of the current node
if it is a <B>ENTITY</B> or <B>ENTREF</B> node;
fails otherwise.<P>Note that the entity name is not available
for <B>SDATA</B> nodes.
<P>The <B>content</B> command returns
the replacement text of internal data entity nodes.
<P>External entities have a <EM>system identifier</EM>,
a <EM>public identifier</EM>, or both.
<PRE>
query <B>sysid</B>
</PRE><P>Returns the <EM>system identifier</EM> of the entity
referenced by the current node
if one was declared; fails otherwise.<PRE>
query <B>pubid</B>
</PRE><P>Like <B>sysid</B> but returns
the <EM>public identifier</EM> of the entity
referenced by the current node.<P>External data entities have an associated <EM>data content notation</EM>.

<P CLASS=NOTE>NOTE -- Elements (<B>EL</B> nodes) may also
have a data content notation.
This is determined by the value of an attribute
with declared value <SAMP>NOTATION</SAMP>
if one is specified for the element.<PRE>
query <B>dcn</B>
</PRE><P>Returns the name of the
current node's <EM>data content notation</EM>, if any.<PRE>
query? <B>withdcn</B> <I>name</I>
</PRE><P>Tests if the current node's data content notation is defined
and is equal to <I>name</I>.  Comparison is case-insensitive.<P>External data entities may also have <EM>data attributes</EM>
if any are declared for the entity's associated data content notation.
Data attributes are accessed in the same way as regular attributes.

<H3><A NAME=SECT7>3.5 Attributes</A></H3>
<P><B>AT</B> nodes do not appear in the tree directly;
instead, they are accessed by name from their parent node.<P>Only <B>EL</B> nodes and <B>ENTITY</B> nodes
have attributes.
<PRE>
query <B>attval</B> <I>attname</I>
</PRE><P>Returns the value of attribute <I>attname</I> on the current node.
If the attribute has an implied value, returns the empty string.
Fails if <I>attname</I> is not a declared attribute
of the current node.<PRE>
query? <B>hasatt</B> <I>attname</I>
</PRE><P>Tests if the current node has an attribute named
<I>attname</I> with a non-implied value
(i.e., the attribute was specified in the start-tag or
a default value appeared in the <SAMP>&lt;!ATTLIST&gt;</SAMP> declaration).<PRE>
query? <B>withattval</B> <I>attname</I> <I>value</I>
</PRE><P>Tests if the value of the attribute <I>attname</I> on the
current node has the value <I>value</I>.
Comparison is case-insensitive.<P>The <B>attribute</B> and <B>attlist</B> clauses
navigate to <B>AT</B> nodes.
<PRE>
query <B>attribute</B> <I>attname</I>
</PRE><P>Selects the attribute named <I>attname</I> of the current node.
Fails if no such attribute is present.<P>Note: the <B>attribute</B> clause navigates to the attribute
node; it does not return anything.  To return an attribute value,
use <SAMP>query attval <VAR>attribute-name</VAR></SAMP> or
<SAMP>query attribute <VAR>attribute-name</VAR> content</SAMP>.
<PRE>
query* <B>attlist</B>
</PRE><P>Selects each attribute (<SAMP>AT</SAMP> node) of the current node,
in an unspecified order.<P>Note: the <B>attlist</B> clause navigates to attribute nodes;
it does not return anything.  To return a list of attribute
names, use <SAMP>query* attlist attname</SAMP>.
<PRE>
query <B>attname</B>
</PRE><P>Returns the <EM>attribute name</EM> of the current node,
if it is an <B>AT</B> node.<P>The <B>content</B> query clause
returns the attribute value of the current node
if it is an <B>AT</B> node.
<P>The <B>attlist</B> clause selects all attributes declared for
an element, even those which have an <SAMP>#IMPLIED</SAMP> value.
To select only those attributes for which a value is specified,
you can use
<PRE>
foreach attname [query* attlist attname] {
	if {[query? hasatt $attname]} {
	    ... process attribute here
	}
}
</PRE>

<H2><A NAME=QUERY>4 Queries</A></H2>
<HR>

<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#SECT8">4.1 Syntax</A>
<LI CLASS=TOCENTRY><A HREF="#SECT9">4.2 Examples</A>
<LI CLASS=TOCENTRY><A HREF="#SECT10">4.3 Query commands</A>
<LI CLASS=TOCENTRY><A HREF="#NAV-QUERY">4.4 Navigational clauses</A>
<LI CLASS=TOCENTRY><A HREF="#SECT11">4.5 Addressing</A>
<LI CLASS=TOCENTRY><A HREF="#SECT12">4.6 Miscellaneous clauses</A>
</UL><HR>
<P>The Cost query language is used in several places:
<UL><LI>Accessing and testing node properties
    with the <B>query</B>, <B>query*</B>, and <B>query?</B> commands;</LI><LI>Locating nodes for processing 
    with the <B>withNode</B> and <B>foreachNode</B> commands;</LI><LI>In the ``match'' part of <EM>specification</EM> clauses;</LI></UL>
<P>Cost queries are similar to Prolog statements
or ``generators'' in the Icon programming language.

<H3><A NAME=SECT8>4.1 Syntax</A></H3>
<P>A query consists of a sequence of <EM>clauses</EM>.
Each <I>clause</I> begins with an identifying keyword,
and may contain further arguments.
Clause keywords are case-insensitive.
Arguments may or may not be case-sensitive depending on
the clause.
<PRE>
query ::= clause [ clause ... ] ;
clause ::= keyword [ arg ...] ;
</PRE><P>Note that there is no ``punctuation'':
clauses and arguments are delimited by spaces
as per the usual Tcl parsing rules.
Since each clause takes a fixed number of arguments,
there is no ambiguity.
<P>Some clauses are <EM>predicates</EM>, which test some
property of the current node and either succeed or fail
based on the outcome of the test.
Other clauses are <EM>navigational</EM>;
these traverse the document tree.  
Some navigational clauses select a single node (e.g., <B>parent</B>)
and others generate a list of nodes (e.g., <B>ancestor</B>).
Finally, <EM>value</EM> clauses are used to return
information about the current node (e.g., <B>gi</B>, 
<B>attval</B>, <B>content</B>).
<P>Queries are evaluated from left to right,
evaluating each clause in turn.
Each clause may take one of four actions:
<UL><LI><EM>succeed</EM>, possibly selecting a new current node</LI><LI><EM>fail</EM>, causing the query to backtrack</LI><LI><EM>return</EM> a value to the caller</LI><LI><EM>abort</EM>, signalling an error</LI></UL>
<P>If a clause succeeds, 
evaluation continues with the next clause.
If it fails, evaluation <EM>backtracks</EM> to the previous clause,
which will in turn either fail or 
select a new current node and continue again.
<P>When the query is complete, the original current node is restored.
It is not an error if the overall query fails;
the <B>query</B> command just returns
an empty string in this case.

<H3><A NAME=SECT9>4.2 Examples</A></H3>
<P>For example, the command
<PRE>
query ancestor attval "ID"
</PRE>
is evaluated as follows:
<UL><LI>the current node becomes the <EM>source node</EM> 
    for the <SAMP>ancestor</SAMP> clause;</LI><LI>the <SAMP>ancestor</SAMP> clause passes the source node to the
  <SAMP>attval ID</SAMP> clause;</LI><LI>if the current node has an <SAMP>ID</SAMP> attribute,
    <B>attval</B> returns that to the <B>query</B> command;</LI><LI>otherwise, the clause fails and evaluation backtracks to the
   <B>ancestor</B> clause, and</LI><LI><B>ancestor</B> sets the current node to the source node's
   parent and continues again; then its parent's parent,
   and so on until the rest of the query succeeds or 
   the root node is reached.</LI><LI>If <B>ancestor</B> reaches the root node, then the whole query fails.</LI></UL>
<P>Here is a simple query which returns 
a list of all of the hyperlinks (<TT>HREF</TT> attribute values)
in an HTML document:

<PRE>
query* doctree element A attval HREF
</PRE>
<P>The next example demonstrates a multi-step navigational query.
(Each query clause is listed on a separate line for clarity.)
(This could be used to generate cross-reference text from an ID reference,
for example.)

<PRE>
proc xreftext {refid} {
    return [join [query* \
	doctree \
	element SECT \
	withattval ID $refid \
	child \
	element TITLE \
	subtree \
	textnode \
	content]]
}
</PRE>
<P>The 
<SAMP>doctree</SAMP> clause selects every node in the document.
<SAMP>element SECT</SAMP> is a predicate which selects all the <TT>SECT</TT> elements.
<SAMP>withattval ID $refid</SAMP> tests if the source node has the 
desired ID.
<SAMP>child</SAMP> selects all the children of the selected
<TT>SECT</TT> element.
<SAMP>element TITLE</SAMP> selects the <TT>TITLE</TT> subelement of
the selected <TT>SECT</TT>.
<SAMP>subtree</SAMP> selects all the descendant nodes 
of the <TT>TITLE</TT> (i.e., <B>PEL</B> nodes and 
possibly subelements and all of their descendants).
<SAMP>textnode</SAMP> selects all the data nodes, and
finally <SAMP>content</SAMP> returns the data content.

<P>The <B>join</B> command is necessary in case the <TT>TITLE</TT>
element contains subelements or <B>SDATA</B> nodes,
in which case <SAMP>query* ... subtree textnode content</SAMP> 
returns a list with more than one member.


<H3><A NAME=SECT10>4.3 Query commands</A></H3>
<PRE>
<B>query</B> <I>clause...</I>
</PRE><P>Evaluates the query <I>clause...</I>, and returns the
first successful result.
If the query fails or does not return a value, returns the empty string.
<B>q</B> is a synonym for <B>query</B>.<PRE>
<B>query?</B> <I>clause...</I>
</PRE><P>Evaluates the query <I>clause...</I>,
and returns <SAMP>1</SAMP> if the query succeeds, <SAMP>0</SAMP> otherwise.
<B>q?</B> is a synonym for <B>query?</B>.<PRE>
<B>query*</B> <I>clause...</I>
</PRE><P>Returns a Tcl list of all values produced by the query <I>clause...</I>.
<B>q*</B> is a synonym for <B>query*</B>.<PRE>
<B>query#</B> <I>clause...</I>
</PRE><P>Returns the number of nodes selected or results returned 
by the query <I>clause...</I>.
<B>q#</B> and <B>countq</B> are synonyms for <B>query#</B>.<PRE>
<B>withNode</B> <I>clause...</I>  { <I>stmts</I> }
</PRE><P>Evaluates <I>stmts</I> as a Tcl script
with the current node set to the first node
produced by the query <I>clause...</I>.
If the query fails, does nothing.<PRE>
<B>foreachNode</B> <I>clause...</I>  { <I>stmts</I> }
</PRE><P>Evaluates <I>stmts</I> 
with the current node set to 
every node produced by the query <I>clause...</I> in order.
The Tcl <B>break</B> and <B>continue</B> commands exit the loop
and continue with the next selected node, respectively.<P><B>withNode</B> and <B>foreachNode</B> both restore
the original current node when evaluation is complete.
The <B>selectNode</B> command sets the current node
in the calling context:
<PRE>
<B>selectNode</B> <I>clause...</I>
</PRE><P>Sets the current node to the first node produced
by evaluating the query <I>clause...</I>.
<H3><A NAME="NAV-QUERY">4.4 Navigational clauses</A></H3>
<H4>Ancestors</H4><PRE>
query <B>parent</B>
</PRE><P>Selects the source node's parent.<PRE>
query* <B>ancestor</B>
</PRE><P>Selects all ancestors of the source node,
beginning with the source node 
and ending with the root node.<PRE>
query* <B>rootpath</B>
</PRE><P>Selects all ancestors of the source node,
beginning with the root node
and ending with the source node.<P>Note that a node is considered to be an ancestor of itself.
<H4>Siblings</H4><PRE>
query <B>left</B>
</PRE><P>Selects the source node's immediate left (preceding) sibling.
Fails if the source node is the first child of its parent.<PRE>
query <B>right</B>
</PRE><P>Selects the source node's immediate right (following) sibling.
Fails if the source node is the last child of its parent.<P><B>left</B> and <B>right</B> only select a single node.
<B>prev</B> and <B>next</B> select multiple siblings:
<PRE>
query* <B>prev</B>
</PRE><P>Selects all earlier siblings of the source node,
starting with the immediate left sibling
and continuing backwards to the first child.<PRE>
query* <B>next</B>
</PRE><P>Selects all later siblings of the source node. <P>The <B>prev</B> query clause selects nodes in ``reverse order'';
the <B>esib</B> (``elder siblings'') clause selects them in 
the same order as they 
appear in the document:
<PRE>
query* <B>esib</B>
</PRE><P>Selects all earlier siblings of the source node,
starting with the first child node and ending with
the immediate left sibling.<P>The <B>ysib</B> (``younger siblings'') clause 
is a synonym for <B>next</B>;
it is present for symmetry with <B>esib</B>.  
<PRE>
query* <B>ysib</B>
</PRE><P>Selects all later siblings of the source node. <P>To select <EM>all</EM> of a node's siblings (including the node itself),
use <SAMP>query parent child</SAMP>.
<P>The <B>forward</B>, <B>backward</B>, <B>later</B>, and <B>earlier</B>
clauses select all nodes in the subtrees before and after the current
element.  <B>backward</B> and <B>earlier</B> select the same set of
nodes, but in a different order (<B>earlier</B> traverses nodes
in the same order as <B>subtree</B>; <B>backwards</B> tracerses them
in the reverse order).  
<B>forward</B> and <B>later</B> are synonyms;
both names are included for symmetry
with <B>backward</B> and <B>earlier</B>.
<PRE>
query* <B>forward</B>
</PRE><P>Selects all nodes in the tree which appear after the source node.<PRE>
query* <B>backward</B>
</PRE><P>Selects all nodes in the tree which appear before the source node.
Nodes are selected in the reverse order, beginning with 
the source node's immediate predecessor and ending with
the root node.<PRE>
query* <B>later</B>
</PRE><P>Synonym for <B>forward</B>.<PRE>
query* <B>earlier</B>
</PRE><P>Selects all nodes in the tree which appear before the source node.
Nodes are selected in the same order as a preorder traversal,
beginning with the root node
and ending with the node's immediate predecessor.<H4>Descendants</H4><PRE>
query* <B>child</B>
</PRE><P>Selects all children of the source node in order.<PRE>
query* <B>subtree</B>
</PRE><P>Selects all descendants of the source node
in preorder traversal (document) order.
Note that a node is considered to be a member of its subtree.<PRE>
query* <B>descendant</B>
</PRE><P>Preorder traversal.  This is like <B>subtree</B>, but
does not include the source node. 
<H3><A NAME=SECT11>4.5 Addressing</A></H3>
<P>Every tree node (<B>EL</B> and <B>PEL</B> nodes)
has a unique <EM>node address</EM>.
This is an opaque string by which the node may be referenced.
<PRE>
query <B>address</B>
</PRE><P>Returns the node address of the current node.
Fails if the current node is not a tree node.<PRE>
query <B>node</B> <I>addr</I>
</PRE><P>Selects the node whose address is <I>addr</I>.<PRE>
query* <B>nodes</B> <I>addrlist</I>
</PRE><P><I>addrlist</I> is a space-separated list of node addresses
as returned by <B>address</B>.  
Selects each node in <I>addrlist</I>,
in the order they appear in the list.
<H3><A NAME=SECT12>4.6 Miscellaneous clauses</A></H3>
<PRE>
query <B>docroot</B>
</PRE><P>Selects the root node of the document.<P>The root node of a document is always an <B>SD</B> node.
The top-level <EM>document element</EM> may be selected
with <SAMP>query docroot child el</SAMP>.
<PRE>
query* <B>doctree</B>
</PRE><P>Selects every node in the document.
Equivalent to <SAMP>query docroot subtree</SAMP>.<PRE>
query <B>in</B> <I>gi</I>
</PRE><P>Selects the parent node if it is an <B>EL</B> node
with generic identifier <I>gi</I>, fails otherwise.
Shorthand for <SAMP>parent withGI <I>gi</I></SAMP>.<PRE>
query <B>within</B> <I>gi</I>
</PRE><P>Selects all ancestor <B>EL</B> nodes
with generic identifier <I>gi</I>.
Equivalent to <SAMP>ancestor withGI <I>gi</I></SAMP>.
<H2><A NAME=SPECS>5 Specifications</A></H2>
<P><EM>Specifications</EM> assign
parameters to document nodes based on queries.
<PRE>
<B>specification</B> <I>specName</I> {
    { <I>query</I> }  { <I>name</I> <I>value</I> <I>name</I> <I>value</I> ... }
    { <I>query</I> }  { <I>name</I> <I>value</I> ... }
    ...
}
</PRE><P>Defines a new specification associating
each <I>query</I> to the matching list of <I>name</I>-<I>value</I> pairs.
Creates a Tcl access command named <I>specName</I>.<P>Evaluating a specification tests each <I>query</I> in sequence,
and looks for a matching <I>name</I> in the parameter list associated
with every query that succeeds.  
Comparison is case-sensitive.
All the <I>name</I>s in a single parameter list must be unique.
<PRE>
<I>specName</I> <B>has</B> <I>name</I>
</PRE><P>Tests if there is a binding for <I>name</I>
associated with the current node
in <I>specName</I>.
Returns <SAMP>0</SAMP> if no such binding exists,
<SAMP>1</SAMP> otherwise.<PRE>
<I>specName</I> <B>get</B> <I>name</I> [ <I>default</I> ]
</PRE><P>Returns the <I>value</I> paired with <I>name</I>
associated with the current node 
in <I>specName</I>.
If there is no such binding,
then if a <I>default</I> argument was supplied,
returns <I>default</I>; otherwise signals an error.<P>Parameter bindings may also be Tcl scripts.
The <B>do</B> subcommand is a convenient way
to define ``methods'' for document nodes.
<PRE>
<I>specName</I> <B>do</B> <I>name</I>
</PRE><P>Equivalent to <SAMP>eval [<I>specName</I> get <I>name</I> ""]</SAMP> --
retrieves the binding (if any) of <I>name</I> in <I>specName</I>
associated with the current node
and evaluates it as a Tcl expression.
If no match is found, does nothing.<P>As a special case,
<SAMP><I>specName</I> <I>event</I></SAMP> is equivalent
to <SAMP><I>specName</I> <B>do</B> <I>event</I></SAMP>
for each <EM>event type</EM> 
(<SAMP>START</SAMP>, <SAMP>END</SAMP>, <SAMP>CDATA</SAMP>, etc.).
This allows specification commands to be used as
<A HREF="#HANDLERS">event handlers</A> 
by the <B>process</B> command.
<P>The order of entries in a specification is significant.
More specific queries should appear before more general ones.
For example, <SAMP>{element P withattval SECURITY TOP} {hide=1}</SAMP> 
must appear before <SAMP>{element P} {hide=0}</SAMP>
or else the <SAMP>{hide=0}</SAMP> binding will always take precedence.
<P>Tcl-style comments -- 
beginning with a <SAMP>#</SAMP> and extending to the end of the line --
may appear in specifications, but only at the <EM>beginning</EM>
of the name-value pairs, and at the very beginning of
the specification. 
For example:
<PRE>
specification foo {
    #
    # This comment is legal
    #
    {element P} {
	# LEGAL
	name1 	value1
	# ILLEGAL
	name2 	value2
    }
    # ILLEGAL
    {element Q} {
	# LEGAL
	name1 value1
    }
}
</PRE>


<H2><A NAME=PROPERTIES>6 Application Properties</A></H2>
<P>Document nodes may be annotated with
application-defined <EM>properties</EM>.   
Property values are strings (like everything in Tcl),
and are accessed by name.
<PRE>
<B>setprop</B> <I>propname</I> <I>propval</I>
</PRE><P>Assigns <I>propval</I> to the property <I>propname</I> on the current node.<PRE>
<B>unsetprop</B> <I>propname</I> [ <I>propname ...</I> ]
</PRE><P>Removes the properties <I>propname...</I> on the current node.
It is not an error if any of the <I>propname</I>s are not currently set.<P>Property values are retrieved with queries:
<PRE>
query <B>propval</B> <I>propname</I>
</PRE><P>Returns the value of the property <I>propname</I> on the current
node; fails if no such property has been assigned.<PRE>
query? <B>hasprop</B> <I>propname</I>
</PRE><P>Succeeds if the current node has been assigned a 
property named <I>propname</I>,
fails otherwise.<PRE>
query? <B>withpropval</B> <I>propname</I> <I>propval</I>
</PRE><P>Succeeds if the current node has a <I>propname</I> property
with value <I>propval</I>.  The value comparison is case sensitive. <P>Property names are case-sensitive.
<P>Property names beginning with a hash sign
(<SAMP>#</SAMP>, the SGML RNI delimiter)
are reserved for internal use by Cost.


<H2><A NAME=HANDLERS>7 Event handlers</A></H2>
<P>Cost supports an <EM>event-driven</EM> processing model.
This essentially reconstructs the
source ESIS event stream for a particular subtree.
<P>Tree traversal procedures are defined with the <B>eventHandler</B> command.
<PRE>
<B>eventHandler</B> <B>-global</B> <I>name</I> {
    <I>event</I> { <I>script</I> }
    <I>event</I> { <I>script</I> }
    ...
}
</PRE><P>Defines a new <EM>traversal procedure</EM> named <I>name</I>
which, when invoked,
traverses the subtree rooted at the current node
and evaluates the specified <I>script</I> for each ESIS event <I>event</I>.
Ignores events for which no <I>script</I> is defined.
If <B>-global</B> is specified, the <I>script</I>s are
evaluated in the top-level Tcl environment; 
otherwise they are evaluated in the calling context.
If any <I>script</I> calls the Tcl <B>break</B> command,
stops the traversal.<P>The following events are generated:

<DL><DT><B>START</B></DT><DD>Invoked when entering an <B>EL</B> (element) node.
The current node is set to the <B>EL</B> node.</DD><DT><B>END</B></DT><DD>Invoked when leaving an <B>EL</B> node.
The current node is set to the <B>EL</B> node.</DD><DT><B>CDATA</B></DT><DD>Invoked for each <B>CDATA</B> (character data) node.</DD><DT><B>RE</B></DT><DD>Invoked for each <B>RE</B> (record end or ``newline'') node.</DD><DT><B>SDATA</B></DT><DD>Invoked for each <B>SDATA</B> (system data entity reference) node.</DD><DT><B>PI</B></DT><DD>Invoked for each <B>PI</B> (processing instruction) node.</DD><DT><B>DATAENT</B></DT><DD>Invoked for each <B>ENTREF</B> (data entity reference)
or <B>ENTITY</B> (data entity) node.</DD></DL>
<P>Most event types correspond directly to data node types.
Two events are generated for each <B>EL</B> node,
one at the start of the element and one at the end.
No events are generated for <B>PEL</B> nodes
(events are generated for each data node child, however).


<PRE>
<B>process</B> <I>cmd</I>
</PRE><P>Performs a preorder traversal of the subtree
rooted at the current node,
calling <I>cmd</I> for each ESIS event.
<I>cmd</I> is invoked with one argument, the name of the event,
with the <EM>current node</EM> set to the active node.<P>The <B>process</B> command traverses the tree and
calls a user-specified event handler procedure at each event.
The event handler may be any Tcl command,
including an [incr tcl] object or 
a <A HREF="#SPECS">specification</A> command.
The handler is called with one argument,
which is the name of the event. 
<P>[incr tcl] classes which are to be used as event handlers
should inherit from the <B>EventHandler</B> base class,
which defines a do-nothing method for each event type.
<H4>Example</H4>
<PRE>
# File: printtree.spec
# Sample event handler
# Prints an indented listing of the tree structure

global level; set level 0

proc main {} { printtree }

eventHandler printtree -global {
    START {
	indent $level;
	puts "&lt;[query gi]&gt;";
	incr level;
    }
    END {
	incr level -1;
	indent $level;
	puts "&lt;/[query gi]&gt;";
    }
    CDATA   { indent $level; puts "\"[query content]\"" }
    SDATA   { indent $level; puts "|[query content]|" }
    RE      { #indent $level; puts "RE" }
    DATAENT { indent $level; puts "&amp;[query ename];" }
}

proc indent {n} { 
    while {$n &gt; 0} { puts stdout "   " nonewline; incr n -1 }
}
</PRE>

<H2><A NAME=RELATIONS>8 Links and relations</A></H2>

<P CLASS=NOTE>NOTE -- This facility is still experimental and subject to change.<P>Links and relations provide a way to correlate arbitrary tree nodes.
<P>A  <EM>relation</EM> is a named collection of <EM>ilink</EM>s.
An <EM>ilink</EM> is a collection of one or more named <EM>anchors</EM>.
Each <EM>anchor</EM> is a reference to a node in the tree;
the referenced node is the <EM>endpoint</EM> of the anchor.
Ilinks also have an <EM>origin</EM> node; this is 
the node which was current when the ilink was created.
All ilinks in the same relation typically have the same 
structure (number and names of anchors).
It is possible to traverse to an ilink from any of
its endpoints, and to any endpoint from an ilink.
Cost ilinks are similar to HyTime ilinks and XML
<EM>XLINK</EM>s; the chief difference is that in Cost
an anchor may only reference a single node:
aggregate anchors and character data spans are not (yet)
supported.
<P>Ilinks are stored as nodes in the document tree.
They are accessed by queries and may be assigned properties
just like other nodes.
<P>The <B>relation</B> and <B>addlink</B> commands
create a relations and ilinks.
Relations must be created before ilinks are added to them.
<PRE>
<B>relation</B> <I>relname</I>  \
	[ <I>anchname1</I> <I>anchname2</I> ... <I>anchnameN</I> ]
</PRE><P>Creates a new relation named <I>relname</I>.
The <I>anchname1</I> ... <I>anchnameN</I> parameters
are currently ignored; they may be used to
document the intended structure of the relation.<PRE>
<B>addlink</B> <I>relname</I> [ <I>anchname</I> "<I>query</I>" ... ]
</PRE><P>Adds a new <B>ILINK</B> node to the relation <I>relname</I>.
The ilink's origin is set to the current node.
A <I>query</I> must be specified for each anchor name <I>anchname</I> 
in the relation.
The anchor's endpoint is set to the first node produced by the query.
If the query fails, then the anchor is not created.
Each <I>query</I> is evaluated with the newly created <B>ILINK</B>
node as the source node.  <P>Anchors are created in the order specified.
The queries defining each anchor may refer to previously
created anchors or to the ilink's <B>origin</B>.
<P>For example,

<PRE>
# create a new relation with three anchors:
relation crossref source target targetsection

# create links:
foreachNode doctree element XREF {
    set refid [query attval REFID]
    addlink crossref \
	    source "origin" \
	    target "doctree el withattval ID $refid" \
	    targetsection "anchor target ancestor element SECT"
}
</PRE>
<P>Once ilinks are created, they may not be removed or changed.
<P>The  <B>ilink</B> and <B>anchor</B> query clauses navigate
to and from <B>ILINK</B> nodes:<PRE>
query* <B>ilink</B> <I>relname</I> <I>srcanch</I>
</PRE><P>Selects each <B>ILINK</B> in the relation <I>relname</I>
in which the anchor named by <I>srcanch</I> refers to
the current node.<PRE>
query <B>anchor</B> <I>dstanch</I>
</PRE><P>The current node must be an <B>ILINK</B> node.
Selects the node referenced by the <I>dstanch</I> anchor.<PRE>
query <B>origin</B>
</PRE><P>The current node must be an <B>ILINK</B> node.
Selects the ilink node's origin node.<P>For example,
<PRE>
foreachNode doctree element XREF {
    puts [query ilink CROSSREF SOURCE \
		anchor TARGET \
		propval TITLE]
}
</PRE>
<P>The clause <SAMP>ilink CROSSREF SOURCE</SAMP> selects the <B>ILINK</B>
nodes in the <SAMP>crossref</SAMP> relation having the current 
node as their <SAMP>source</SAMP> anchor.
The clause <SAMP>anchor TARGET</SAMP> traverses to the <SAMP>target</SAMP>
anchor, and the last clause returns the value of that node's
<SAMP>TITLE</SAMP> property.  In other words, the above example
prints the <SAMP>TITLE</SAMP> of the node referenced by 
each <SAMP>XREF</SAMP> element in the document.
<P>The <B>anchtrav</B> query clause navigates across ilinks;
it combines the <B>ilink</B> and <B>anchor</B> clauses into one step.
Thus the above example can be expressed more concisely as:
<PRE>
foreachNode doctree element XREF {
    puts [query anchtrav CROSSREF SOURCE TARGET  propval title]
}
</PRE>
<PRE>
query* <B>anchtrav</B> <I>relname</I> <I>srcanch</I> <I>dstanch</I>
</PRE><P>Selects the target node of the <I>dstanch</I> anchor 
in every ilink in the relation <I>relname</I> 
for which the current node is the <I>srcanch</I> anchor.
In other words: traverses a link.<P>Ilinks may be accessed independently of any of their anchors:<PRE>
query* <B>relation</B> <I>relname</I>
</PRE><P>Selects each <B>ILINK</B> node in the relation <I>relname</I>.<P>For example,
<PRE>
foreachNode relation CROSSREF {
    withNode anchor SOURCE { puts "[content]: " }
    withNode anchor TARGET { puts "[query propval title]" }
}
</PRE>

<H2><A NAME=UTILS>9 Miscellaneous utilities</A></H2>
<HR>

<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#ENVIRONMENTS">9.1 Environments</A>
<LI CLASS=TOCENTRY><A HREF="#SUBST">9.2 Substitutions</A>
<LI CLASS=TOCENTRY><A HREF="#SECT13">9.3 Numerals</A>
<LI CLASS=TOCENTRY><A HREF="#SECT14">9.4 Miscellaneous Miscellaneous</A>
<LI CLASS=TOCENTRY><A HREF="#REQUIRE-CMD">9.5 Script management</A>
</UL><HR>
<P>Cost provides some extra utilities which are useful
for text processing.

<H3><A NAME=ENVIRONMENTS>9.1 Environments</A></H3>
<P>An <EM>environment</EM> is a set of name-value bindings,
much like an associative array.
Bindings may be saved and restored dynamically,
similar to TeX's grouping mechanism.
It is possible to create multiple independent environments.
<PRE>
<B>environment</B> <I>envname</I> [ <I>name</I> <I>value</I> ...]
</PRE><P>Creates a new environment
and a Tcl access command named <I>envname</I>.
The optional <I>name</I> and <I>value</I> argument pairs
define initial bindings in the environment.<PRE>
<I>envname</I> <B>set</B> <I>name</I> <I>value</I> [ <I>name</I> <I>value</I>... ]
</PRE><P>Adds the <I>name</I>-<I>value</I> pairs to the environment
<I>envname</I>,
overwriting the current binding of each <I>name</I>
if it is already present.<PRE>
<I>envname</I> <B>get</B> <I>name</I> [ <I>default</I> ]
</PRE><P>Returns the value currently bound to <I>name</I>
in the environment <I>envname</I>.
If no binding for <I>name</I> currently exists in <I>envname</I>
and the <I>default</I> argument is present, returns that instead;
otherwise signals an error.<PRE>
<I>envname</I> <B>save</B> [ <I>name</I> <I>value</I> ... ]
</PRE><P>Saves the current set of name-value bindings in <I>envname</I>.
If <I>name</I> and <I>value</I> argument pairs are supplied,
adds new bindings to the environment after saving the current bindings.<PRE>
<I>envname</I> <B>restore</B>
</PRE><P>Restores the bindings in <I>envname</I> to their settings
at the time of the last call to <SAMP><I>envname</I> <B>save</B></SAMP>.<P>If the <B>set</B> and <B>save</B> subcommands
are passed one extra argument, it is treated as a list of name-value
bindings.  


<H3><A NAME=SUBST>9.2 Substitutions</A></H3>
<P>When translating SGML documents to other formats
(including other SGML document types),
it is often necessary to ``escape'' or ``protect''
character data that might be interpreted as markup
in the result language.
For example, HTML requires all 
occurrences of 
<SAMP>&lt;</SAMP>, <SAMP>&gt;</SAMP> and <SAMP>&amp;</SAMP>
to be entered as entity references 
<SAMP>&amp;lt;</SAMP>, <SAMP>&amp;gt;</SAMP> and <SAMP>&amp;amp;</SAMP>.
TeX and LaTeX have <EM>many</EM> special characters which
must be entered as control sequences.
<P>The <B>substitution</B> command provides an easy and 
efficient way to apply fixed-string substitutions.
<PRE>
<B>substitution</B> <I>substName</I> { 
    <I>string</I> <I>replacement</I> 
    <I>string</I> <I>replacement</I> 
    ...
}
</PRE><P>Defines a new Tcl command <I>substName</I> 
which takes a single argument
and returns a copy of the input
with each occurrence of any <I>string</I> 
replaced with the corresponding <I>replacement</I>.
If multiple <I>string</I>s match,
the earliest and longest match takes precedence.<H4>Example</H4><PRE>
substitution entify {
	{&lt;} {&amp;lt;}
	{&gt;} {&amp;gt;}
	{&amp;} {&amp;amp;}
	{&lt;=} {&amp;le;}
	{&gt;=} {&amp;ge;}
}
entify "a &lt; b &amp;&amp; b &gt;= c"
# returns "a &amp;lt; b &amp;amp;&amp;amp; b &amp;ge; c"
</PRE>
<H3><A NAME=SECT13>9.3 Numerals</A></H3>
<P><PRE>
require Numerals.tcl
<B>arabic</B>	<VAR>number</VAR>
<B>lcroman</B>	<VAR>number</VAR>
<B>ucroman</B>	<VAR>number</VAR>
<B>lcalpha</B>	<VAR>number</VAR>
<B>ucalpha</B>	<VAR>number</VAR>
</PRE><P>The file <TT>$COSTLIB/Numerals.tcl</TT>
provides a set of routines for converting integers to different styles.
These are useful for generating numbered lists, 
section and appendix numbers, etc.
<B>lcroman</B> and <B>ucroman</B> return lower-case
and upper-case Roman numerals, respectively.
<B>lcalpha</B> (<B>ucalpha</B>) converts the numbers 1 ... 26
to the letters 'a' ... 'z' ('A' ... 'Z').
<B>arabic</B> returns its argument unchanged; it is
provided for symmetry.
<H4>Example:</H4><PRE>
set counter 0
foreachNode child element LI {
    incr counter
    puts "[lcroman $counter]. " nonewline
    ... process content
}
</PRE>
<H3><A NAME=SECT14>9.4 Miscellaneous Miscellaneous</A></H3>
<PRE>
<B>cost:undefined</B> <VAR>class</VAR> <VAR>value</VAR>
</PRE><P>The command <B>cost:undefined</B> is a debugging and maintenance aid.
The first time it is called with a particular <VAR>class</VAR>-<VAR>value</VAR>
pair, it prints a warning message on <SAMP>stderr</SAMP>.
Subsequent calls with the same arguments are ignored.
<P>It useful to have a default rule in each translation script
that simply calls <B>cost:undefined</B>; for example:
<PRE>
specification mySpec {
    element FOO	{ ... }
    element BAR { ... }
    ...
    el { 
	startAction { cost:undefined GI [query gi] }
    }
}
</PRE>
<P>This will print a warning if the specification fails 
to account for any element types encountered in the document --
for example, if new element types are added to the DTD.
<P>The purpose of the <VAR>class</VAR> argument is to keep track of
different namespaces, e.g., <SAMP>cost:undefined NOTATION [query dcn]</SAMP>,
etc.

<H3><A NAME="REQUIRE-CMD">9.5 Script management</A></H3>
<PRE>
cost:require <VAR>filename</VAR>
</PRE><P>The <B>cost:require</B> command looks in the 
Cost search path (defined by the environment variable <TT>$COSTPATH</TT>)
for <VAR>filename</VAR> and sources it as a Tcl script.
It keeps track of which files have been loaded,
and will only read a file once.
Multiple calls to <SAMP>cost:require <VAR>filename</VAR></SAMP>
are therefore safe.
<P>The shell command <SAMP>costsh -S <VAR>specfile</VAR></SAMP>
uses <B>cost:require</B> to find <VAR>specfile</VAR>.
<P><B>require</B> is an alias for <B>cost:require</B>,
for backwards-compatibility with previous releases of Cost.
</BODY></HTML>