File: lib_1.html

package info (click to toggle)
eli-doc 4.4.0-4
links: PTS
area: main
in suites: sarge
size: 13,256 kB
ctags: 4,583
sloc: makefile: 42
file content (1479 lines) | stat: -rw-r--r-- 65,338 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.29
     from ../tnf/lib.tnf on 12 Febuary 2003 -->

<TITLE>Library Reference - The Eli Library</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000" BACKGROUND="gifs/bg.gif">
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0" VALIGN=BOTTOM>
<TR VALIGN=BOTTOM>
<TD WIDTH="160" VALIGN=BOTTOM><IMG SRC="gifs/elilogo.gif" BORDER=0>&nbsp;</TD>
<TD WIDTH="25" VALIGN=BOTTOM><img src="gifs/empty.gif" WIDTH=25 HEIGHT=25></TD>
<TD ALIGN=LEFT WIDTH="600" VALIGN=BOTTOM><IMG SRC="gifs/title.gif"></TD>
</TR>
</TABLE>

<HR size=1 noshade width=785 align=left>
<TABLE BORDER=0 CELLSPACING=2 CELLPADDING=0>
<TR>
<TD VALIGN=TOP WIDTH="160">
<h4>General Information</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="index.html">Eli: Translator Construction Made Easy</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gindex_toc.html">Global Index</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="faq_toc.html" >Frequently Asked Questions</a> </td></tr>
</table>

<h4>Tutorials</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="EliRefCard_toc.html">Quick Reference Card</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="novice_toc.html">Guide For new Eli Users</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="news_toc.html">Release Notes of Eli</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="nametutorial_toc.html">Tutorial on Name Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="typetutorial_toc.html">Tutorial on Type Analysis</a></td></tr>
</table>

<h4>Reference Manuals</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ui_toc.html">User Interface</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="pp_toc.html">Eli products and parameters</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lidoref_toc.html">LIDO Reference Manual</a></td></tr>
</table>

<h4>Libraries</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lib_toc.html">Eli library routines</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="modlib_toc.html">Specification Module Library</a></td></tr>
</table>

<h4>Translation Tasks</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lex_toc.html">Lexical analysis specification</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="syntax_toc.html">Syntactic Analysis Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="comptrees_toc.html">Computation in Trees</a></td></tr>
</table>

<h4>Tools</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lcl_toc.html">LIGA Control Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="show_toc.html">Debugging Information for LIDO</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gorto_toc.html">Graphical ORder TOol</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="fw_toc.html">FunnelWeb User's Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ptg_toc.html">Pattern-based Text Generator</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="deftbl_toc.html">Property Definition Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="oil_toc.html">Operator Identification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="tp_toc.html">Tree Grammar Specification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="clp_toc.html">Command Line Processing</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="cola_toc.html">COLA Options Reference Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="idem_toc.html">Generating Unparsing Code</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="mon_toc.html">Monitoring a Processor's Execution</a> </td></tr>
</table>

<h4>Administration</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="sysadmin_toc.html">System Administration Guide</a> </td></tr>
</table>

<HR WIDTH="100%">
<CENTER>&nbsp;<A HREF="mailto:elibugs@cs.colorado.edu"><IMG SRC="gifs/button_mail.gif" NOSAVE BORDER=0 HEIGHT=32 WIDTH=32></A><A HREF="mailto:elibugs@cs.colorado.edu">Questions, Comments, ....</A></CENTER>

</TD>
<TD VALIGN=TOP WIDTH="25"><img src="gifs/empty.gif" WIDTH=25 HEIGHT=25></TD>

<TD VALIGN=TOP WIDTH="600">
<H1>Library Reference</H1>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="lib_2.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="lib_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
<H1><A NAME="SEC1" HREF="lib_toc.html#SEC1">The Eli Library</A></H1>
<P>
The Eli library contains a collection of solutions to common problems in
language implementation.
If one of these problems is identified in the design of an application
specification, the library's solution can be easily applied.
<P>
This manual describes Eli's frame modules.
<A NAME="IDX1"></A>
They provide basic operations
that are not normally varied.
Some of the operations are quite general, while others carry out specific
translator-related tasks.
In each case, however, the task performed by the module is largely
independent of the overall problem being solved by the specification.
<P>
Frame modules are all code modules, and the facilities they export
are made available via the associated header file.  They can be used
directly by C programs, and do not involve any other Eli facilities.
<P>
Another class of modules provided by Eli contain a mixture of code
and specifications, of which some can be instantiated.  These modules
solve tasks such as name analysis according to Pascal scope rules.
Descriptions of these modules are in the specification module
library manual.
See  <A HREF="modlib_toc.html">Specification Module Library of modlib</A>.
<P>
<H2><A NAME="SEC2" HREF="lib_toc.html#SEC2">Using Frame Modules</A></H2>
<P>
The library modules described in this manual are implemented directly in C.
These modules may export constants, variables and routines to their
clients.
To reduce overhead, these modules have been pre-compiled and stored in the
<DFN>frame</DFN>.
Frame modules need not be instantiated, although it is allowable to do so.
A frame module will be incorporated into a specification whenever anything
exported by that module is used in the specification.
If a frame module is instantiated by a specification, however, it will be
included regardless of whether any exported facilities are used.
In either case, source code for the module is included in the <CODE>source</CODE>
product. See  <A HREF="pp_1.html#SEC3">Source Version of the Processor of pp</A>.
<P>
Each module is associated with a header file that specifies the
interface it presents to its clients.
Any module requiring access to the exports of another module must include
the header file associated with the exporting module.
<P>
Library header files are written according to certain conventions.
We recommend strongly that you follow the same conventions when defining
code modules to carry out tasks specific to your problem.
Your header files will be included in generated modules, and Eli will make
the same assumptions about them that it does about header files from the
library.
Failure to follow these conventions may result in errors when the generated
programs are compiled.
Since you will not recognize the generated programs, such errors may be
difficult to diagnose.
<P>
By convention, every header file is <DFN>complete</DFN>:
Including a module's header file in a C program provides all of the
information needed to use that module.
For example, the environment module exports operations that deliver
definition table keys as their results.
In order to use the environment module, therefore, a client must have
access to the interface of the definition table module.
Our convention therefore requires that the header file for the environment
module include the header file for the definition table module.
If the environment module header file did not include the definition table
module header file, a C program that included that included the environment
module header file would not necessarily have all of the information needed
to use the environment module.
<P>
This convention greatly simplifies decisions about which header files to
include, and avoids all questions of the order in which header files should
be included.
It does, however, require that each header file be protected against
multiple inclusion.
Protection is provided by defining a symbol in each header file and
skipping the entire contents if that symbol is already defined.
The symbol is the name of the header file, given as upper-case characters
with any periods replaced by underscores.
<P>
Here is an excerpt from <TT>`envmod.h'</TT>,
the header file for the environment module:
<P>
<PRE>
#ifndef ENVMOD_H
#define ENVMOD_H

#include "deftbl.h"

typedef struct EnvImpl *Environment;    /* Set of Identifier/Definition pairs */

...

/***/
#if defined(__cplusplus) || defined(__STDC__)
extern DefTableKey DefineIdn(Environment env, int idn);
#else
extern DefTableKey DefineIdn();
#endif
/* Define an identifier in a scope
 *    If idn is defined in env then on exit-
 *       DefineIdn=key for idn in env
 *    Else let n be a previously-unused definition table key
 *    Then on exit-
 *       DefineIdn=n
 *       idn is defined in env with the key n
 ***/

...

#endif
</PRE>
<P>
Protection against multiple inclusion is provided by the test of
<CODE>ENVMOD_H</CODE>.
<CODE>DefineIdn</CODE> returns a definition table key, so the completeness
convention requires that <TT>`deftbl.h'</TT> (the definition table module
interface) be included.
<CODE>Environment</CODE> is a type exported by the environment module, and it is
defined in this interface.
<P>
<H2><A NAME="SEC3" HREF="lib_toc.html#SEC3">Text Input</A></H2>
<P>
<A NAME="IDX2"></A>
<A NAME="IDX3"></A>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<A NAME="IDX7"></A>
<A NAME="IDX8"></A>
<A NAME="IDX9"></A>
<PRE>
#include "source.h"

SrcBufPtr SrcBuffer;

char *SRCFILE;
char *TEXTSTART;

void initBuf(char *name, int f);

void refillBuf(char *p);

int finlBuf();
</PRE>
<P>
The source module has been designed to allow rapid access to the
characters of a text file.
A text file is a sequence of <DFN>lines</DFN>,
each terminated by a newline character.
<A NAME="IDX10"></A>
There is no limit on the length of a line.
<A NAME="IDX11"></A>
The source module guarantees that if the first character of a line is in
memory then all of the characters of that line, including the terminating
newline character, are in contiguous memory locations.
The newline terminating the last line in memory is followed by an ASCII NUL
<A NAME="IDX12"></A>
character, and thus the sequence of lines constitutes a C string.
NUL characters are not allowed within the text file.
<P>
To use the module, first call <CODE>initBuf</CODE>, with a file name and descriptor.
The file must be opened for reading (by <CODE>open(2)</CODE> prior to the call.
Upon return,
<CODE>SrcBuffer</CODE> points to a new text buffer,
<CODE>SRCFILE</CODE> is the symbolic name of the input file,
and <CODE>TEXTSTART</CODE> points to the first character of the first line of the
input file.
(If the input file is empty then <CODE>TEXTSTART</CODE> points to an ASCII NUL
character.)
<P>
<CODE>SRCFILE</CODE> and <CODE>TEXTSTART</CODE> are components of the text buffer;
<CODE>TEXTSTART</CODE> may be arbitrarily altered by any client of the source
module.
Normally, <CODE>TEXTSTART</CODE> is used to describe the position reached by the
client in processing the buffer's text.
Because it is a component of the text buffer, there is no need to save and
restore it when another text buffer is created by a subsequent invocation
of <CODE>initBuf</CODE>.
<P>
All source module operations take place on the text buffer pointed to by
<CODE>SrcBuffer</CODE>, and both <CODE>SRCFILE</CODE> and <CODE>TEXTSTART</CODE> use
<CODE>SrcBuffer</CODE> to access the text buffer.
A client of the source module may manage a number of text buffers
simultaneously by saving and restoring <CODE>SrcBuffer</CODE>.
<P>
When a client has processed all of the information in a text buffer,
additional information can be obtained from the file by invoking
<CODE>refillBuf</CODE> with a pointer to the text in the buffer.
At least one line of text will be added to the text pointed to by the
argument of <CODE>refillBuf</CODE>, and upon return <CODE>TEXTSTART</CODE> points to
the first character of the augmented text.
The content of the memory pointed to by the argument of <CODE>refillBuf</CODE>
is undefined.
(If there is no more information in the file then the string pointed
to by the argument of <CODE>refillBuf</CODE> is not augmented.
Upon return <CODE>TEXTSTART</CODE> points to the first character of that string
and the content of the memory pointed to by the argument of
<CODE>refillBuf</CODE> is undefined.)
<P>
Invocation of <CODE>finlBuf</CODE> frees all storage for the text buffer pointed
to by <CODE>SrcBuffer</CODE>.
Upon return, <CODE>SrcBuffer</CODE> contains a null pointer and the value of
<CODE>finlBuf</CODE> is the descriptor of the file associated with the buffer.
The file itself has not been closed.
<P>
<H2><A NAME="SEC4" HREF="lib_toc.html#SEC4">Source Text Coordinates and Error Reporting</A></H2>
<P>
<A NAME="IDX13"></A>
<A NAME="IDX14"></A>
<A NAME="IDX15"></A>
<A NAME="IDX16"></A>
<A NAME="IDX17"></A>
<A NAME="IDX18"></A>
<A NAME="IDX19"></A>
<A NAME="IDX20"></A>
<A NAME="IDX21"></A>
<A NAME="IDX22"></A>
<A NAME="IDX23"></A>
<A NAME="IDX24"></A>
<PRE>
#include "err.h"

typedef POSITION *CoordPtr;

POSITION NoCoord;
CoordPtr NoPosition;

int LineOf(POSITION);
int ColOf(POSITION);

int LineNum;
POSITION curpos;

int ErrorCount[ ];

ErrorInit(int ImmOut, int AGout, int ErrLimit)

message(int severity, char *text, int grammar, CoordPtr source)

lisedit(char *name; FILE *stream; int cutoff, erronly)
</PRE>
<P>
This module implements the concept of a source text coordinate system
and a set of errors of various levels of severity.  Error reports are
tied to particular positions in the source text coordinate system, and
may be combined with the source text in a separate pass.
<P>
The coordinate of a source text position is a pair (line index, column
index), and is defined by a structure of type <CODE>POSITION</CODE>.
<CODE>LineOf</CODE> and <CODE>ColOf</CODE> are access functions for the elements of the
pair; they may be used either to read or to set these elements.
<P>
<CODE>LineNum</CODE> and <CODE>curpos</CODE> are variables provided by the error
reporting module for the use of its clients.
<CODE>LineNum</CODE> initially has the value 1.
It is neither read nor set by the error module.
The initial value of <CODE>curpos</CODE> is undefined, and it is also neither
read nor set by the error module.
<P>
<CODE>ErrorInit</CODE> may be called in order to change the default behavior
of the error module.  By default, all error messages are written to
<CODE>stderr</CODE> as they occur, however, if <CODE>ErrorInit</CODE> has been
called with a value of <CODE>0</CODE> for <CODE>ImmOut</CODE>, errors will not be
reported until <CODE>lisedit</CODE> is used.
Buffering is prevented by calling <CODE>fflush</CODE> after each output.
The error message format is illustrated by the following:
<PRE>
"filename", line 24:3 ERROR: boolean type required AG=124
</PRE>
The information shown is: the file name of the input file, the line and
column in that file where the error occurred, the severity (see below)
and the error message iself.  The integer value following <CODE>AG</CODE>
can be used to provide additional information when a particular report
may originate from many places.  This integer value is not reported if
<CODE>ErrorInit</CODE> has been called with a value of <CODE>0</CODE> for
<CODE>AGout</CODE>.
<P>
The format is designed so that it can be used as input to a special
mechanism, such as an intelligent editor, for making the reports known
to the user.
<P>
After printing to <CODE>stderr</CODE>, the errors are also queued for possible
printing later with <CODE>lisedit</CODE>.  <CODE>lisedit</CODE> prints to
<CODE>stdout</CODE> the source line containing the error, with an arrow
pointing at the corresponding column.  Then the body of the error
message is printed.
Only messages whose severity is larger than <CODE>cutoff</CODE> will be printed.
If <CODE>erronly</CODE> is nonzero, only lines with associated error reports will
be printed.
<P>
<CODE>Message</CODE>
is used to make an error report to the error module.
Both source program and compiler errors are reported via
<CODE>message</CODE>.
Six error severities are defined by constants exported by the module:
<P>
<DL COMPACT>
<A NAME="IDX25"></A>
<DT><CODE>NOTE</CODE>
<DD>The message is intended to convey additional information to the user,
not to report an error.
<A NAME="IDX26"></A>
<DT><CODE>WARNING</CODE>
<DD>The message reports an anomaly that may be indicative of an error.
<A NAME="IDX27"></A>
<DT><CODE>ERROR</CODE>
<DD>The message reports a definite error.
<A NAME="IDX28"></A>
<DT><CODE>DEADLY</CODE>
<DD>The message reports a violation of an assertion within the compiler.
</DL>
<P>
A compiler should be able to carry on after detecting any errors less
severe than deadly errors.  It may be necessary to repair some internal
data structures in order to guarantee their consistency, but the repairs
are usually not difficult to provide; see any standard compiler
construction text.  <CODE>Message</CODE> returns normally after accepting a
report of an error that is less severe than a deadly error.
<P>
Violations of compiler assertions signal programming errors within the
compiler itself.  Attempts to continue under such circumstances are
likely to result in further corruption and eventual catastrophic
failure.  <CODE>Message</CODE> therefore does <EM>not</EM> return after
accepting a report of a deadly error.
Instead, it outputs any queued reports and terminates the program
with <CODE>exit(1)</CODE>.
<P>
The <CODE>text</CODE> argument to <CODE>message</CODE> points to a character string
describing the error.  This character string must remain unchanged until
the reports are output at the end of the compilation; <CODE>message</CODE>
does not copy it.
<P>
<CODE>grammar</CODE> and <CODE>source</CODE> serve to locate the error in both the
compiler and the source text.  The former is most useful in the case of
violations of compiler assertions and limits.  It specifies the
particular assertion or, in the case of a generated compiler, the
specification rule that led to the violated assertion.  The latter gives
the source text coordinates of the construct the compiler was processing
at the time the report was issued.  Some errors are not associated with
a particular source language construct.  Reports of these errors should
use <CODE>NoPosition</CODE> in lieu of coordinates.
<P>
At any time during the compilation, <CODE>ErrorCount[<VAR>severity</VAR>]</CODE>
contains the number of reports of class <VAR>severity</VAR> that have been
issued so far.
<P>
If an error is reported with an invalid severity code, <CODE>message</CODE>
sets its severity to <CODE>DEADLY</CODE> after printing the message and its
severity code on <CODE>stderr</CODE>.
<P>
If the number of errors at severity level <CODE>ERROR</CODE> plus the number
at severity level <CODE>FATAL</CODE> is greater than 10 added to the current
line number divided by 20 then compilation is aborted with a
<CODE>DEADLY</CODE> message.  When the number of lines of source is reasonably
large this effectively amounts to a limit of one of these errors for
every 20 lines of source code (ie. a 5% error rate).  This error limit
is not checked if <CODE>ErrorInit</CODE> has been called with a value of
<CODE>0</CODE> for the argument <CODE>ErrLimit</CODE>.
<P>
<H2><A NAME="SEC5" HREF="lib_toc.html#SEC5">Memory Object Management</A></H2>
<P>
This module provides high-speed memory allocation that supports "growing"
objects -- objects whose size is not known a priori.
Any number of regions can be defined, and storage managed independently by
region.
Within one region the storage is allocated and freed in a last-in,
first-out manner that allows freeing of a large number of objects with a
single operation.
<P>
<A NAME="IDX29"></A>
<PRE>
#include "obstack.h"

void obstack_init(ObstackP obstack);
void obstack_begin(ObstackP obstack, int size, int alignment);
int obstack_chunk_size(ObstackP obstack);
int obstack_alignment_mask(ObstackP obstack);
<A NAME="IDX31"></A>
<A NAME="IDX32"></A>
<A NAME="IDX33"></A>
<A NAME="IDX30"></A>
void *obstack_alloc(ObstackP obstack, int size);
void *obstack_copy(ObstackP obstack, void *data, int size);
void *obstack_copy0(ObstackP obstack, void *data, int size);
void *obstack_strcpy(ObstackP obstack, char *data);
<A NAME="IDX35"></A>
<A NAME="IDX36"></A>
<A NAME="IDX37"></A>
<A NAME="IDX34"></A>
void obstack_blank(ObstackP obstack, int size);
void obstack_grow(ObstackP obstack, void *data, int size);
void obstack_grow0(ObstackP obstack, void *data, int size);
void obstack_strgrow(ObstackP obstack, char *data);
void obstack_1grow(ObstackP obstack, int data_char);
void obstack_ptr_grow(ObstackP obstack, void *data);
void obstack_int_grow(ObstackP obstack, int data);
<A NAME="IDX39"></A>
<A NAME="IDX40"></A>
<A NAME="IDX41"></A>
<A NAME="IDX42"></A>
<A NAME="IDX43"></A>
<A NAME="IDX44"></A>
<A NAME="IDX38"></A>
void obstack_blank_fast(ObstackP obstack, int size);
void obstack_1grow_fast(ObstackP obstack, int data_char);
void obstack_ptr_grow_fast(ObstackP obstack, void *data);
void obstack_int_grow_fast(ObstackP obstack, int data);
<A NAME="IDX46"></A>
<A NAME="IDX47"></A>
<A NAME="IDX48"></A>
<A NAME="IDX45"></A>
void *obstack_finish(ObstackP obstack);
<A NAME="IDX49"></A>
void obstack_free(ObstackP obstack, void *block);
<A NAME="IDX50"></A>
void *obstack_base(ObstackP obstack);
void *obstack_next_free(ObstackP obstack);
int obstack_object_size(ObstackP obstack);
int obstack_room(ObstackP obstack);
<A NAME="IDX52"></A>
<A NAME="IDX53"></A>
<A NAME="IDX54"></A>
<A NAME="IDX51"></A></PRE>
<P>
Each region is represented by a data structure of type <CODE>Obstack</CODE>.
A pointer of type <CODE>ObstackP</CODE>, which addresses this data structure, is
used to specify the region.
Here is an example showing how a region might be declared and initialized:
<P>
<PRE>
Obstack obstk;

obstack_init(&#38;obstk);
</PRE>
<P>
All the apparent functions operating on regions are macros.
Each takes a pointer of type <CODE>ObstackP</CODE> as its first argument.
This pointer may be evaluated many times, so you should not use
an expression as the first argument of any of these macros.
(Any arguments other than the first are evaluated exactly once.)
If you need to compute the appropriate <CODE>ObstackP</CODE>,
use the following strategy:
<P>
<PRE>
_obstack = (address expression); obstack_xxx(_obstack, ...);
<A NAME="IDX55"></A></PRE>
<P>
The variable <CODE>_obstack</CODE> is of type <CODE>ObstackP</CODE>, and is
exported by the module for use by clients.
Its value is never inspected or changed by the module itself or any of the
macros.
<P>
A region is a collection of objects managed in a last-in,
first-out manner.
Each region is independent of the others, and is
characterized by a <DFN>chunk size</DFN>
<A NAME="IDX56"></A>
and an <DFN>alignment</DFN>.
<A NAME="IDX57"></A>
As objects are added to the collection, blocks of memory of the given chunk
size are allocated to hold them.
The address of each object in the collection is guaranteed to be divisible
by the alignment, which must be a power of 2.
<P>
When the storage already available for a collection is insufficient for an
object being added to the collection, then a new chunk is allocated.
The size of the new chunk is the minimum of the chunk size parameter and
twice the size of the object to be added.
Thus the chunk size parameter does <EM>not</EM> limit the size of an object
that can be stored in the collection, but it does affect the number of
system requests for storage.
If it is not specified when the collection is initialized, a default value
equivalent to one virtual memory page is used.
Chunks are normally allocated by <CODE>malloc</CODE>
<A NAME="IDX58"></A>
or <CODE>realloc</CODE>,
<A NAME="IDX59"></A>
but you can substitute a
different storage allocator by re-defining the macros
<CODE>obstack_chunk_alloc</CODE>
<A NAME="IDX60"></A>
and <CODE>obstack_chunk_realloc</CODE>
<A NAME="IDX61"></A>
to be the names of your allocator functions.
Be certain that your allocator copes with memory exhaustion.
<A NAME="IDX62"></A>
Give the macro definition before including the module interface
specification:
<P>
<PRE>
#define obstack_chunk_alloc MyMalloc
#include "obstack.h"
</PRE>
<P>
After an object is added to a collection, the next available address is
adjusted to be divisible by the alignment parameter of the collection.
If <EM>any</EM> address is suitable as an object address
then the alignment should be 1 (the zeroth power of 2).
The default alignment value is that suitable for an object of the primitive
type <CODE>double</CODE>, normally the type that is most stringently aligned.
<P>
The first macro applied to a region must be either
<CODE>obstack_init</CODE>
<A NAME="IDX63"></A>
or <CODE>obstack_begin</CODE>,
<A NAME="IDX64"></A>
both of which create an empty collection of objects.
A collection initialized by <CODE>obstack_init</CODE> will have the default
values for its chunk size and alignment parameters, while
<CODE>obstack_begin</CODE> allows the user to set those values.
If either the <CODE>size</CODE> or <CODE>alignment</CODE> argument of the
<CODE>obstack_begin</CODE> call is <CODE>0</CODE> then the corresponding default value
is used.
Either of these values may be inspected or changed at any time via the
operations <CODE>obstack_chunk_size</CODE>
<A NAME="IDX65"></A>
and <CODE>obstack_alignment_mask</CODE>
<A NAME="IDX66"></A>
respectively.
These macros may be called either on the left side of an assignment (to
change the value) or within an expression (to inspect the value).
If the chunk size is changed, it can be returned to its default value by
assigning the value 0 to <CODE>obstack_chunk_size</CODE>:
<P>
<PRE>
obstack_chunk_size(&#38;obstk) = 0;
</PRE>
<P>
The alignment mask is an integer one less than the power of 2 that must
divide each object address.
To make a change in the alignment mask effective, you must create an empty
object.
For example, the following code guarantees that the addresses of
objects subsequently created in the collection <CODE>obstk</CODE>
will be divisible by 4:
<P>
<PRE>
obstack_alignment_mask(&#38;obstk) = 3; (void)obstack_alloc(&#38;obstk, 0);
</PRE>
<P>
Once a region has been initialized, there are two basic
strategies for creating objects: <DFN>allocation</DFN> and <DFN>growth</DFN>.
Objects are allocated when their size is known a priori;
they are grown when their size is not known a priori.
<P>
Allocation
<A NAME="IDX67"></A>
is the simplest strategy.
Suppose that it was necessary to create an object capable of storing
an array of five integers.
The call <CODE>(int *)obstack_alloc(&#38;MyStack, 5 * sizeof(int))</CODE>
<A NAME="IDX68"></A>
would create such an object in the collection <CODE>MyStack</CODE>,
and yield a pointer to that object.
The contents of the created object are undefined.
If an array of five integers was already stored in the variable
<CODE>ArrayValue</CODE>, and this array was to be the initial contents of the
created object, then the call
<CODE>(int *)obstack_copy(&#38;MyStack, ArrayValue, 5 * sizeof(int))</CODE>
<A NAME="IDX69"></A>
would create and initialize an appropriate object.
The operation <CODE>obstack_copy0</CODE>
<A NAME="IDX70"></A>
is identical to <CODE>obstack_copy</CODE>,
except that it adds a single zero byte after the value that was copied.
An object whose initial contents are to be the characters of an existing
null-terminated string should be created by the operation
<CODE>obstack_strcpy</CODE>.
<A NAME="IDX71"></A>
This operation does not require a length specification; it determines the
length from the given string.
<P>
With the growth
<A NAME="IDX72"></A>
strategy, a single object is created by a sequence of macro calls
rather than a single call.
Each call causes the object to grow in size, and possibly establishes some
of the initial contents of the object.
An object can be moved by the module while that object is growing.
The last call in the sequence is to either <CODE>obstack_finish</CODE>
<A NAME="IDX73"></A>
or some allocation operation,
which terminates the object's growth and fixes its address.
<P>
An obstack can only accomodate a single growing object at any time.
While that object is growing, no allocation operations may be issued for
the obstack.
After <CODE>obstack_finish</CODE> has been called, completing the growth of the
object, the obstack is again able to accept any operation.
Thus the legal sequence of operations on an obstack can be described by the
following regular expression (<CODE>A</CODE> stands for an allocation operation
and <CODE>G</CODE> stands for a growth operation):
<P>
<PRE>
obstack_init ( A | G+ ( obstack_finish | A ) )*
</PRE>
<P>
Macros implementing the growth strategy parallel, for the most part, the
macros implementing the allocation strategy.
They have the same pattern of arguments as their allocation counterparts,
but do not return a pointer to an object because no object exists until the
call of <CODE>obstack_finish</CODE>.
To grow an object by a given amount without specifying the initial contents
of that part of the object, use <CODE>obstack_blank</CODE>.
<A NAME="IDX74"></A>
If an initial contents is known, grow the object with one of the
operations <CODE>obstack_grow</CODE>,
<A NAME="IDX75"></A>
<CODE>obstack_grow0</CODE>
<A NAME="IDX76"></A>
or <CODE>obstack_strgrow</CODE>
<A NAME="IDX77"></A>
as appropriate.
<P>
The special operation <CODE>obstack_1grow</CODE>
<A NAME="IDX78"></A>
is used for placing characters
into a growing object.
It's argument is the actual value that is the initial content,
rather than the address of that value
as in the other growth and allocation macros.
Here is an example of how <CODE>obstack_strcpy</CODE> could be implemented using
<CODE>obstack_1grow</CODE>:
<P>
<PRE>
char *
obstack_strcpy(obstk, data)
ObstackP obstk; char *data;
{ register char c, *p = data;
  if (p) while (c = *p++) obstack_1grow(obstk, c);
  obstack_1grow(obstk, '\0');
  return (char *)obstack_finish(obstk);
}
</PRE>
<P>
The growth macros check that the current chunk has enough space in it for
the growth increment.
If the check fails, a new chunk is allocated and the growing object is
copied into the new chunk.
Two additional operations,
<CODE>obstack_blank_fast</CODE>
<A NAME="IDX79"></A>
and <CODE>obstack_1grow_fast</CODE>,
<A NAME="IDX80"></A>
can be used when sufficient space in the current chunk can be guaranteed.
These macros are identical to their normal counterparts
<CODE>obstack_blank</CODE> and <CODE>obstack_1grow</CODE>,
except that they do not check the space remaining in the current chunk.
The operation <CODE>obstack_room</CODE>
<A NAME="IDX81"></A>
returns the amount of free space in the current chunk.
<P>
The collection of objects in a region is managed in a last-in,
first-out manner.
This means that there is an operation, <CODE>obstack_free</CODE>,
<A NAME="IDX82"></A>
to remove objects from the collection.
A call of <CODE>obstack_free</CODE> specifies a region and an
object in that region.
This call removes the specified object <EM>and all objects added to the
collection after the specified object was added</EM>.
<P>
If an <CODE>obstack_free</CODE> operation frees all of the objects in a chunk,
that chunk is returned to the underlying storage allocator.
Chunks are normally returned by <CODE>free</CODE>,
<A NAME="IDX83"></A>
but you can specify a different routine by re-defining the macro
<CODE>obstack_chunk_free</CODE>
<A NAME="IDX84"></A>
to be the name of that routine.
(The macros <CODE>obstack_chunk_alloc</CODE>,
<A NAME="IDX85"></A>
<CODE>obstack_chunk_realloc</CODE>
<A NAME="IDX86"></A>
and <CODE>obstack_chunk_free</CODE> must be defined consistently.)
<P>
While an object is being grown, its current base address can be obtained
by calling the macro <CODE>obstack_base</CODE>,
<A NAME="IDX87"></A>
its current size by calling <CODE>obstack_object_size</CODE>,
<A NAME="IDX88"></A>
and the address of the first location above it by calling
<CODE>obstack_next_free</CODE>.
<A NAME="IDX89"></A>
This allows one to build a module that will give clients access to the
contents of an immature object while it is still growing.
Don't forget that the base address will change during the growth period
if the object outgrows the current chunk.
Also, <CODE>obstack_next_free</CODE> can be used on the left-hand side of an
assignment, thereby providing a way to "shrink" a growing object.
Its value should never be increased, nor should it be decreased beyond the
value yielded by <CODE>obstack_base</CODE>.
<P>
<H2><A NAME="SEC6" HREF="lib_toc.html#SEC6">Character String Storage</A></H2>
<P>
This module provides both temporary and persistent storage for
arbitrary-length character strings.
Strings stored by the module can be identified by either a pointer or an
integer.
The set of persistent strings can be written at any time to a text file
as either a sequence of lines, one string per line in the form of a C
string denotation, or as the C definition of an initialized data structure.
<P>
<A NAME="IDX90"></A>
<PRE>
#include "csm.h"

int stostr(char *c, int l)
<A NAME="IDX91"></A>char *StringTable(int i);
<A NAME="IDX92"></A>char *NoStr
<A NAME="IDX93"></A>int NoStrIndex;
<A NAME="IDX94"></A>int numstr;
<A NAME="IDX95"></A>
ObstackP Csm_obstk;
<A NAME="IDX96"></A>char *CsmStrPtr;
<A NAME="IDX97"></A>
char *prtstcon(FILE *d, char *p)
<A NAME="IDX98"></A>
savestr(FILE *d)
<A NAME="IDX99"></A>
dmpstr(FILE *d)
<A NAME="IDX100"></A></PRE>
<P>
<CODE>Stostr</CODE> stores a character string <CODE>c</CODE> of length <CODE>l</CODE> in the
memory, returning the index of the string.
<CODE>StringTable</CODE> is a macro that delivers a pointer to a null-terminated
string, given the index of that string established by <CODE>stostr</CODE>.
The number of strings currently stored is
given by <CODE>numstr</CODE> (initially 0); thus <CODE>numstr-1</CODE> is
the largest index that can be used as an argument to <CODE>StringTable</CODE>.
<P>
<TT>`csm.h'</TT> defines the constant <CODE>NoStr</CODE>
<A NAME="IDX101"></A>
to be a unique character pointer that represents no string.  It also
defines <CODE>NoStrIndex</CODE>
<A NAME="IDX102"></A>
to be a unique string index that will never be used to represent a
string.  The string indexed by <CODE>NoStrIndex</CODE> contains no
characters.
<P>
<CODE>Csm_obstk</CODE> is a region that can hold sets of strings.
It can be managed by the operations of the memory object allocator
(see  <A HREF="lib_1.html#SEC5">Memory Object Management</A>).
The actual characters of the strings stored by <CODE>stostr</CODE> are stored
in <CODE>Csm_obstk</CODE>.
<CODE>CsmStrPtr</CODE> is a pointer that can be set by a client of the character
storage module to point to a string in <CODE>Csm_obstk</CODE>.
When this pointer is passed to <CODE>stostr</CODE>, <CODE>stostr</CODE> assumes that
another copy of the string need not be stored.
<P>
<CODE>Prtstcon</CODE> prints the string pointed to by <CODE>p</CODE> on the current
line of file <CODE>d</CODE>.  The string is printed as a C string constant with
the quotes omitted.  This function can be omitted from the module by
compiling with the C flag <CODE>-DNOPRINT</CODE>.
<CODE>Dmpstr</CODE> prints the set of strings <CODE>StringTable(0)</CODE> through
<CODE>StringTable(numstr-1)</CODE> on file <CODE>d</CODE> as a sequence of lines.
This function can also be omitted from the module by compiling with the
C flag <CODE>-DNOPRINT</CODE>.
<P>
<CODE>Savestr</CODE> writes the current state of the module on file <CODE>d</CODE>,
in the form of C initialized variables.
Only the strings stored by <CODE>stostr</CODE> will be written to <CODE>d</CODE>.
This file can be used to create a copy of the module
initialized to the current state by naming it <TT>`csmtbl.h'</TT>
and recompiling the module.
The save
function is available only if the module was compiled with the C flag
<CODE>-DSAVE</CODE>, and if the printing routines were not omitted.
<P>
<H2><A NAME="SEC7" HREF="lib_toc.html#SEC7">Character String Arithmetic</A></H2>
<P>
<A NAME="IDX103"></A>
<A NAME="IDX104"></A>
<A NAME="IDX105"></A>
<A NAME="IDX106"></A>
<A NAME="IDX107"></A>
<A NAME="IDX108"></A>
<A NAME="IDX109"></A>
<A NAME="IDX110"></A>
<A NAME="IDX111"></A>
<A NAME="IDX112"></A>
<A NAME="IDX113"></A>
<PRE>
#include "strmath.h"

char *stradd(char *a, char *b, int base);
char *strsub(char *a, char *b, int base);
char *strmult(char *a, char *b, int base);
char *strdivf(char *a, char *b, int base);
char *strdivi(char *a, char *b, int base);
char *strrem(char *a, char *b, int base);
char *strpow(char *a, char *b, int base);
char *strsqrt(char *a, int base);

char *strnorm(char *a, int oldbase, int newbase, char *symbols);

char *strnumb(char *a, int *flag, int base);

int strmath(int select, ...);
</PRE>
<P>
This package is made available by adding the following line to a 
type-<CODE>specs</CODE> file:
<P>
<PRE>
$/Tech/strmath.specs
</PRE>
<P>
The strings accepted by this package are essentially those of most higher
level languages:
<P>
<PRE>
[+/-][d*][.][d*][e[+/-]d*]
</PRE>
<P>
Here <CODE>[]</CODE> indicate optional parts,
<CODE>+/-</CODE> indicates that a sign may be present,
<CODE>d</CODE> indicates digits in the chosen base,
<CODE>*</CODE> indicates repetition,
<CODE>.</CODE> is a period representing the separation between
the integer and fractional parts of the number, and
<CODE>e</CODE> stands for any one of the exponent symbols given in
the control string EXP_SYMBOL.
Strings generated by the package have the same formats.
The actual characters used to represent digits, signs,
fractional separators and exponent symbols are determined by
default or by settings established by the <CODE>strmath</CODE> operation.
<P>
In general (with the exception of <CODE>strnumb</CODE>) the operations
return a NULL pointer when an error is found in the input values
or occurs during computation (e.g., overflow).
When a null value is returned, the global <CODE>errno</CODE> is set to
indicate the type of error.
If multiple errors occur, only the first is reported.
<P>
When operations are cascaded, with the result of one being used as an
operand of another, there is no need to check each operation individually.
If an error occurs in an early operation, the resulting NULL pointer will
be an invalid input to the next operation, thus guaranteeing that it will
yield a NULL pointer.
The NULL pointer will therefore propagate, and appear as the final value.
Since only the first error is reported, the global <CODE>errno</CODE> will
not be changed when any of the subsequent invalid inputs are detected.
<P>
The error codes used are defined in &#60;errno.h&#62;:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>An error in the format of an input value made it invalid.
(The function <CODE>strnumb</CODE> can be used to assist in diagnosing
these problems.)
<DT><CODE>EDOM</CODE>
<DD>The given value falls outside the domain of the operation
(e.g. it is too large, or negative when a positive value is required).
<DT><CODE>ERANGE</CODE>
<DD>The result of the computation cannot be adequately
represented (e.g., divide by zero, overflow).
</DL>
<P>
The usual rules for the use of <CODE>errno</CODE> apply:
It is not explicitly cleared.
If desired, this must be done before calling the desired function.
It is set by these functions only if an error occurs.
<P>
Most of the operations exported by the strmath module return pointer
values.
These pointers address the result string, which occupies space in a static
array.
All operations use the same static array for their results.
Thus the pointer returned by an operation will be valid only until another
operation of the module completes.
It is therefore the responsibility of each client of the module to make a
copy of any result string whose value must be preserved beyond the
completion of the next strmath operation.
<P>
The operations
<CODE>stradd</CODE>,
<CODE>strsub</CODE>,
<CODE>strmult</CODE>,
<CODE>strdivf</CODE> (full divide, possibly yielding a fractional part),
<CODE>strdivi</CODE> (integer quotient),
<CODE>strrem</CODE> (integer remainder) and
<CODE>strpow</CODE>
perform the indicated operation on two string operands.
In each case the operation is performed in the radix given by <CODE>base</CODE>,
and the result is delivered as a string or <CODE>NULL</CODE>.
The unary operation
<CODE>strsqrt</CODE>
takes the square root of its string operand in the radix given by
<CODE>base</CODE>, and the result is delivered as a string or <CODE>NULL</CODE>.
<P>
The <CODE>strnorm</CODE> operation converts <CODE>a</CODE> from radix <CODE>oldbase</CODE> to
radix <CODE>newbase</CODE>, normalizing it in the process, and the result is
delivered as a string.
The format of that string depends on the <CODE>symbols</CODE> argument:
<P>
<DL COMPACT>
<DT><CODE>symbols</CODE>=<CODE>NULL</CODE>
<DD>Whole number and fraction parts separated by the defined fractional
separator unless the result can be expressed as an integral value,
exponent marker and exponent if the length would exceed <CODE>integer_size</CODE>
digits.
<DT><CODE>symbols</CODE> is an empty string
<DD>Sequence of digits if the length does not exceed <CODE>integer_size</CODE>
digits, otherwise <CODE>NULL</CODE>.
<DT><CODE>symbols</CODE> is a non-empty string
<DD>A fractional separator is guaranteed to appear in the result.
The first character of <CODE>symbols</CODE> is taken as the exponent marker.
If there are additional character in the string then they will be taken as
the fractional separator, the minus sign, and the plus sign respectively.
(The normally defined for these purposes will be used if they do not appear
in <CODE>symbols</CODE>.)
</DL>
<P>
If the intent of the operation is simply to perform radix conversion, use
<CODE>symbols</CODE>=<CODE>NULL</CODE>.
The resulting string will be in the normal format delivered by other
operations of this module.
Using an empty string for <CODE>symbols</CODE> guarantees that the result is in
integer form.
(If this is not possible, the result will be <CODE>NULL</CODE>.)
This guarantee is important when the number is being output in a position
where an integer is required.
Using a non-empty string for <CODE>symbols</CODE> guarantees that the result is
in floating-point format.
It also allows one to easily vary the characters used for the exponent
marker, fractional separator, and signs.
This is important when the number is being output where a real is
required.
<P>
The <CODE>strnumb</CODE> operation is intended for input of numbers,
particularly in cases where there may be a radix marker at the end
of the number string.
It scans the string <CODE>a</CODE> and interprets it as a value in the radix
given by <CODE>base</CODE>.
If an error is found, the appropriate error value is returned in the
variable <CODE>flag</CODE>.
Otherwise <CODE>flag</CODE> will be set to zero.
The operation returns a pointer to the last character scanned.
This character will be the character at which the error was detected if
<CODE>flag</CODE> is nonzero, otherwise it is the first character that does not
belong to the number.
Termination of the scan is controlled by the setting of
<CODE>STRM_CHECK_DIGITS</CODE>.
<P>
The <CODE>strmath</CODE> operation is used to vary some characteristic of the
module.
It is called with a selection symbol given in the following table, and
one additional argument which is the value of the characteristic being set.
It returns the value 1 if the requested setting succeeded.
Otherwise 0 is returned and no selected value has been changed.
The caller is responsible for ensuring that the contents of the
string arguments are disjoint sets as described below.
<P>
<DL COMPACT>
<DT><CODE>strmath(STRM_DIGITS,<SAMP>`string'</SAMP>)</CODE>
<DD>Change the string defining the set of valid digits.
For example, "0123456789ABCDEF" is a string that defines a set of digits for
bases 2-16.
Output strings are built by indexing this string to obtain the
representation of each computed digit.
The matching of alphabetic characters in input strings depends upon the
setting of <CODE>STRM_IGNORE_CASE</CODE>.
Unpredictable results will be obtained if any character is repeated.
<P>
The default value is the string consisting of the digits '0'-'9',
the upper case alphabetic characters,
the lower case alphabetic characters, and
the characters '%' and '$'.
This string provides 64 distinct characters, thus supporting any radix not
greater than 64.
<P>
<DT><CODE>strmath(STRM_EXP_SYMBOLS,<SAMP>`string'</SAMP>)</CODE>
<DD>Change the string defining the set of characters to be accepted as
representations of the exponent symbol.
Any character in the string is acceptable in input strings;
in output strings the first member of the set is used.
Unpredictable results will be obtained if any character is repeated
or is used as a digit.
<P>
The default value of this string is "^".
<P>
<DT><CODE>strmath(STRM_SIGNS,<SAMP>`string'</SAMP>)</CODE>
<DD>Change the string defining the set of characters to be accepted as
representations of negative and positive signs.
The first element of the string is the character representing a negation,
and the remainder are all taken as representations of a positive
value.
In output strings the first element is used to show negation,
and the second value to represent a positive sign (if one is requested).
Unpredictable results will be obtained if any character is repeated
or is used as an exponent symbol or digit.
<P>
The default value of this string is "-+".
<P>
<DT><CODE>strmath(STRM_SEPARATORS,<SAMP>`string'</SAMP>)</CODE>
<DD>Change the string defining the set of characters to be accepted as
representations of the fractional separator.
Any are acceptable in input strings; in output strings the first element
of the set is used.
Unpredictable results will be obtained if any character is repeated
or is used as a sign, exponent symbol or digit.
<P>
The default value of this string is ".".
<P>
<DT><CODE>strmath(STRM_EXP_BASE,<SAMP>`integer'</SAMP>)</CODE>
<DD>Define the radix assumed for the exponents of numbers.
If this value is zero, the exponent radix is taken to be the same as
the number radix, which is supplied on each call to the strmath functions.
Otherwise the specified value is used as the exponent radix,
independent of the number radix.
<P>
<DT><CODE>strmath(STRM_INTEGER_SIZE,<SAMP>`integer'</SAMP>)</CODE>
<DD>Set the maximum number of digits that a representation of an integer may have.
This value, plus <CODE>STRM_ROUND_SIZE</CODE>, may be no greater than
<CODE>ARITH_SIZE</CODE>.
Values with more than <CODE>STRM_INTEGER_SIZE</CODE> significant digits
will be represented as values with exponents, even if integral in value.
<P>
The default value is <CODE>ARITH_SIZE-2</CODE>.
<P>
<DT><CODE>strmath(STRM_ROUND_SIZE,<SAMP>`integer'</SAMP>)</CODE>
<DD>Set the number of additional digits a value may have a value may have
if not represented as an integer.
This value, plus <CODE>STRM_INTEGER_SIZE</CODE>,
may be no greater than <CODE>ARITH_SIZE</CODE>.
Values with more than <CODE>STRM_INTEGER_SIZE+STRM_ROUND_SIZE</CODE>
significant digits will be rounded on output to values with no
more than that <CODE>STRM_INTEGER_SIZE+STRM_ROUND_SIZE</CODE> digits.
<P>
The default value is 2.
<P>
<DT><CODE>strmath(STRM_ROUNDING,<SAMP>`mode'</SAMP>)</CODE>
<DD>Select the rounding mode to be applied to output values.
The following modes are recognized:
<P>
<DL COMPACT>
<DT><CODE>STRM_EVEN_ROUND</CODE>
<DD>The output value is rounded to the nearest value
representable in the given number of digits.
If two values are equally near,
the one with an even last digit will be returned.
This the default setting.
<DT><CODE>STRM_ZERO_ROUND</CODE>
<DD>The output value is rounded to the value
representable in the given number of digits
that is closest to and no greater in magnitude.
<DT><CODE>STRM_UP_ROUND</CODE>
<DD>The output value is rounded to the value
representable in the given number of digits
that is closest to but no less.
<DT><CODE>STRM_DOWN_ROUND</CODE>
<DD>The output value is rounded to the value
representable in the given number of digits
that is closest to but no greater.
<DT><CODE>STRM_HAND_ROUND</CODE>
<DD>The output value is rounded to the nearest value
representable in the given number of digits.
If two values are equally near,
the one with the greater magnitude will be returned
(as is normally done when computing by hand).
</DL>
<P>
<LI><CODE>strmath(STRM_DENORMALIZE,<SAMP>`Flag'</SAMP>)</CODE>
Select the treatment of values with exponent -1.
<SAMP>`Flag'</SAMP>=1 allows values with exponents that would normally be -1
to be represented with a 0-valued digit before the fractional separator
on output.
If <SAMP>`Flag'</SAMP>=0, then the initial digit of an output value will
always be nonzero.
<P>
The default setting is 1.
<P>
<LI><CODE>strmath(STRM_INEXACT,<SAMP>`Flag'</SAMP>)</CODE>
Select the treatment of inexact values.
(An inexact value is one that has lost digits in the course of computation,
or whose value was derived from an inexact value.)
<SAMP>`Flag'</SAMP>=1 indicates that input values containing a fractional separator
should be regarded as inexact, and that
a fractional separator and fractional part should be included on
output of any inexact value.
<SAMP>`Flag'</SAMP>=0 indicates that all input values should be regarded as exact,
and that no fractional separator should be included on output
if the fractional part of the value being output is zero.
<P>
The default setting is 1.
<P>
<LI><CODE>strmath(STRM_CHECK_DIGITS,<SAMP>`Flag'</SAMP>)</CODE>
Select the treatment of non-digit characters on input.
<SAMP>`Flag'</SAMP>=1 indicates that all characters of a string be checked on input
to ensure that they are valid digits and
are legitimate in the specified number radix.
If this is not so, an error is reported by the operation reading the number.
<SAMP>`Flag'</SAMP>=0 indicates that the scan should end with the first
character that is not legitimately part of the number,
and no error is to be reported signalled.
<P>
The default setting is 1.
<P>
<LI><CODE>strmath(STRM_IGNORE_CASE,<SAMP>`Flag'</SAMP>)</CODE>
Select the treatment of the case of letters representing digits on input.
<SAMP>`Flag'</SAMP>=1 indicates that the case of letters in input values,
and the case of letters in the STRM_DIGITS string,
is to be ignored when matching and defining
the value of elements of an input number.
<SAMP>`Flag'</SAMP>=0 indicates that case is significant.
<P>
The default setting is 1.
</DL>
<P>
<H2><A NAME="SEC8" HREF="lib_toc.html#SEC8">Unique Identifier Management</A></H2>
<P>
<A NAME="IDX114"></A>
<A NAME="IDX115"></A>
<A NAME="IDX116"></A>
<A NAME="IDX117"></A>
<A NAME="IDX118"></A>
<A NAME="IDX119"></A>
<A NAME="IDX120"></A>
<PRE>
#include "idn.h"

int dofold;

prtidnv(FILE *d, int i)

saveidn(FILE *d)

dmpidn(FILE *d)

mkidn(char *c, int l, int *t, int *s)
</PRE>
<P>
These functions implement the concept of unique identifiers.  The
representation is an integer, the index of the identifier's string in
the character string memory (see  <A HREF="lib_1.html#SEC6">Character String Storage</A>).  
<P>
<TT>`idn.h'</TT> defines the constant <CODE>NoIdn</CODE>
<A NAME="IDX121"></A>
to be a unique integer that is never used to represent an identifier.
The identifier string represented by <CODE>NoIdn</CODE> contains no
characters.
<P>
<CODE>Prtidnv</CODE> prints the string for identifier <CODE>i</CODE> on the current
line of file <CODE>d</CODE>.  This function can be omitted from the module by
compiling with the C flag <CODE>-DNOPRINT</CODE>.  <CODE>Dmpidn</CODE> prints the
current state of the lookup mechanism on file <CODE>d</CODE> as a sequence of
lines.  This function can also be omitted from the module by compiling
with the C flag <CODE>-DNOPRINT</CODE>.
<P>
<CODE>Saveidn</CODE> writes the current state of the module on file <CODE>d</CODE>,
in the form of C initialized variables.  This file can be used to create
a copy of the module initialized to the current state by naming it
<TT>`idntbl.h'</TT> and recompiling with the C flag <CODE>-DINIT</CODE>.  The save
function is available only if the module was compiled with the C flag
<CODE>-DSAVE</CODE>, and if the printing routines were not omitted.  An
initial state is usually created by <CODE>adtinit</CODE>.
<P>
<CODE>Mkidn</CODE> determines the unique identifier for a string <CODE>c</CODE> of
length <CODE>l</CODE>.  If the string has not been previously passed to
<CODE>mkidn</CODE> then it is assigned the first available location in the
character string memory, and the index of that position is stored in the
location pointed to by <CODE>s</CODE> .  The value pointed to by <CODE>t</CODE> is
noted but not changed.  If the string has previously been passed to
<CODE>mkidn</CODE> then the character string memory index assigned when it was
first passed to <CODE>mkidn</CODE> is stored in the location pointed to by
<CODE>s</CODE>, and the value of <CODE>t</CODE> noted at that time is stored in the
location pointed to by <CODE>t</CODE>.  <CODE>Mkidn</CODE> can be used as a
processor by the lexical analysis portion of an Eli-generated program
(see  <A HREF="lex_1.html#SEC10">Token Processors of Lexical Analysis</A>.)
<P>
The variable <CODE>dofold</CODE> controls the interpretation of upper and lower
case alphabetic characters by <CODE>mkidn</CODE>: If <CODE>dofold</CODE> contains 0
then upper and lower case versions of the same letter are considered to
be distinct; otherwise no distinction is made between upper and lower
case versions of the same letter.  This variable is initially 0, and
must be explicitly set nonzero if desired.  If it is known that upper
and lower case letters must <EM>always</EM> be distinct, the variable and
associated folding code can be removed from the module by compiling it
with the C flag <CODE>-DNOFOLD</CODE>.
<P>
<H2><A NAME="SEC9" HREF="lib_toc.html#SEC9">Contour-Model Environment</A></H2>
<P>
This module implements a standard contour model for name analysis.  The
data structure is a tree of <DFN>scopes</DFN>, each of which can contain an
arbitrary number of <DFN>definitions</DFN>.  A definition is a binding of an
identifier to an object in the definition table (see  <A HREF="deftbl_toc.html">PDL Reference Manual</A>);
the definition does not carry any other
information itself.  The environment module provides operations for
building scope trees, adding definitions to specific scopes, and
searching individual scopes or sequences of scopes for the definition of
a particular identifier.
<P>
The module is capable of building multiple trees of scopes, and it
places no constraints on the sequence of construction, definition and
lookup operations.
<P>
<A NAME="IDX122"></A>
<A NAME="IDX123"></A>
<A NAME="IDX124"></A>
<A NAME="IDX125"></A>
<A NAME="IDX126"></A>
<A NAME="IDX127"></A>
<A NAME="IDX128"></A>
<PRE>
#include "envmod.h"

Environment NewEnv ();
Environment NewScope (/* Environment e */);

int AddIdn (/* Environment e, int i, DefTableKey k */);
DefTableKey DefineIdn (/* Environment e, int i */);

DefTableKey KeyInScope (/* Environment e, int i */);
DefTableKey KeyInEnv (/* Environment e; int i */);
</PRE>
<P>
The type Environment is a pointer to the data structure representing the
tree of scopes.  Identifiers are represented by integers.
The bindings contained in a scope are between integers and arbitrary
pointers.
These arbitrary pointers are all obtained via two operations external to
the environment module:
<P>
<DL COMPACT>
<DT><CODE>DefTableKey NoKey</CODE>
<DD>Returns the same value on every invocation.
<P>
<DT><CODE>DefTableKey NewKey()</CODE>
<DD>Returns a different value on each invocation.
The value returned by <CODE>NoKey</CODE> is never returned by <CODE>NewKey</CODE>.
</DL>
<P>
<CODE>NoKey</CODE> and <CODE>NewKey</CODE> may be supplied by the user of Eli, or they
may be exported by a generated definition table module
(see  <A HREF="deftbl_1.html#SEC2">Keys of PDL Reference Manual</A>).
<P>
<CODE>NewEnv</CODE> creates a new tree consisting of a single, empty scope and
returns a reference to that empty scope.  <CODE>NewScope</CODE> creates a new
empty scope as a child of the scope referenced by its argument and
returns a reference to that empty scope.
<P>
<CODE>AddIdn</CODE> checks the scope referenced by its <CODE>e</CODE> argument for a
definition of the identifier specified by its <CODE>i</CODE> argument.  If no
such definition is found, a definition binding the identifier <CODE>i</CODE>
to the definition table object specified by <CODE>k</CODE> is added to scope
<CODE>e</CODE>.  <CODE>AddIdn</CODE> returns the value <CODE>0</CODE> if a definition
for <CODE>i</CODE> already exists, and returns <CODE>1</CODE> otherwise.
<P>
<CODE>DefineIdn</CODE> behaves exactly like <CODE>AddIdn</CODE>, except that if the
referenced scope contains no definition of <CODE>i</CODE> then <CODE>DefineIdn</CODE>
obtains a value from <CODE>NewKey</CODE> and binds <CODE>i</CODE> to that value
in scope <CODE>e</CODE>.  In addition, <CODE>DefineIdn</CODE> always returns the
definition table key associated with <CODE>i</CODE>.
<P>
<CODE>KeyInScope</CODE> checks the scope referenced by its <CODE>e</CODE> argument
for a definition of the identifier specified by its <CODE>i</CODE> argument.
If no such definition is found, <CODE>NoKey</CODE> is returned.  If a
definition is found, the definition table object bound to <CODE>i</CODE> is
returned.
<P>
<CODE>KeyInEnv</CODE> behaves the same way as <CODE>KeyInScope</CODE> except that
if no definition for <CODE>i</CODE> is found in scope <CODE>e</CODE> then the search
continues through successive ancestors of <CODE>e</CODE>.
If no definition for <CODE>i</CODE> is found in <CODE>e</CODE> or any of its ancestors,
<CODE>NoKey</CODE> is returned.  Otherwise the definition table object bound
to <CODE>i</CODE> is returned.
<P>
If any function is invoked with an invalid environment argument
<CODE>((ENVIRONMENT *) 0)</CODE>, a deadly error (<CODE>"CurrEnv: no
environment"</CODE>) is reported (see  <A HREF="lib_1.html#SEC4">Source Text Coordinates and Error Reporting</A> for a discussion of deadly errors).
<P>
<H2><A NAME="SEC10" HREF="lib_toc.html#SEC10">Storage Layout</A></H2>
<P>
This module provides operations that determine the storage requirement
of a composition of two objects, each of which has its own storage
requirement.  The storage requirement of an object is determined by the
number of memory units it occupies, the number by which its address
should be divisible, and whether its address is the address of its first
memory unit or the address of the first memory unit above it.  Two
distinct composition strategies, concatenation and overlaying, are
supported by this module.  (When two objects are concatenated they are
allocated adjacent areas of memory; when they are overlaid they share
memory.)
<P>
<A NAME="IDX129"></A>
<A NAME="IDX130"></A>
<A NAME="IDX131"></A>
<A NAME="IDX132"></A>
<A NAME="IDX133"></A>
<A NAME="IDX134"></A>
<A NAME="IDX135"></A>
<A NAME="IDX136"></A>
<A NAME="IDX137"></A>
<A NAME="IDX138"></A>
<PRE>
#include "Storage.h"

StorageRequired NewStorage(/* int size, align, top; */);
StorageRequired CopyStorage(/* StorageRequired a; */);
StorageRequired ArrayStorage(/* int n; StorageRequired a; */);

int StorageSize(/* StorageRequired a; */);
int StorageAlignment(/* StorageRequired a; */);

int Concatenate(/* StorageRequired a, b; */);
int Overlay(/* StorageRequired a, b; */);
</PRE>
<P>
The type <CODE>StorageRequired</CODE> is a pointer to the data structure
representing a storage requirement.
There is one predefined value, <CODE>NoStorage</CODE>, of type
<CODE>StorageRequired</CODE>.
<CODE>NoStorage</CODE> is a null pointer, and represents "no storage requirement".
<P>
<CODE>NewStorage</CODE> creates a new description of a storage area requiring
<CODE>size</CODE> memory units, whose address must be divisible by
<CODE>align</CODE>, and returns a reference to that description.  If
<CODE>top</CODE> is <CODE>TRUE</CODE> then the address of the storage area is the
address of the first memory unit above the area; otherwise the address
is the address of the first memory unit of the area itself.
<CODE>CopyStorage</CODE> creates a new description of a storage area whose
requirements are identical to those of <CODE>a</CODE> and returns a reference
to that description.
<CODE>ArrayStorage</CODE> creates a new description of a storage area for an
array of <CODE>n</CODE> elements, each described by <CODE>a</CODE> and returns a
reference to that description.
<P>
<CODE>StorageSize</CODE> returns the number of memory units required by
storage area <CODE>a</CODE>.  The function <CODE>StorageAlignment</CODE> returns the
number by which the address of storage area <CODE>a</CODE> must be divisible.
<P>
<CODE>Concatenate</CODE> determines the requirements of the storage area
resulting when storage area <CODE>b</CODE> is concatenated to storage area
<CODE>a</CODE>.  Area <CODE>b</CODE> is placed above area <CODE>a</CODE> if the address of
area <CODE>a</CODE> is the address of its first memory unit.  If the address
of area <CODE>a</CODE> is the address of the first memory unit above that
area, then area <CODE>b</CODE> is placed below area <CODE>a</CODE>.  In either case,
area <CODE>b</CODE> is placed as close to area <CODE>a</CODE> as possible, without
overlapping it.  The description referenced by <CODE>a</CODE> is changed to
describe the result of the concatenation, and <CODE>Concatenate</CODE> returns
the relative address of area <CODE>b</CODE> within that resultant area.
<P>
<CODE>Overlay</CODE> determines the requirements of the storage area resulting
when storage area <CODE>b</CODE> is overlaid onto storage area <CODE>a</CODE>.  The
description referenced by <CODE>a</CODE> is changed to describe the result of
the overlay, and <CODE>Overlay</CODE> returns the relative address of area
<CODE>b</CODE> within that resultant area.
<P>
This module should be made available to the Eli specification by including
the following line in a type-<CODE>specs</CODE> file:
<P>
<PRE>
$/Tech/Storage.specs
</PRE>
<P>
<HR size=1 noshade width=600 align=left>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="lib_2.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="lib_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
</TD>
</TR>
</TABLE>

</BODY></HTML>