Subversion Repositories tendra.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 7u83 1 
<!-- Crown Copyright (c) 1998 -->
2 
<HTML>
3 
<!-- Generated by ramify version 1.1 -->
4 
<HEAD>
5 
<TITLE>
6 
TDF Notation Compiler
7 
</TITLE>
8 
</HEAD>
9 
 
10 
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
11 
<H1>TDF Notation Compiler</H1>
12 
<H3>January 1998</H3>
13 
<IMG SRC="../images/no_next.gif" ALT="next section">
14 
<IMG SRC="../images/no_prev.gif" ALT="previous section">
15 
<IMG SRC="../images/no_top.gif" ALT="current document">
16 
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
17 
</A>
18 
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
19 
<HR>
20 
<DL>
21 
<DT><A HREF="#S1"><B>1</B> - Introduction</A><DD>
22 
<DT><A HREF="#S2"><B>2</B> - Input classes</A><DD>
23 
<DL>
24 
<DT><A HREF="#S21"><B>2.1</B> - Delimiters</A><DD>
25 
<DT><A HREF="#S22"><B>2.2</B> - White space</A><DD>
26 
<DT><A HREF="#S23"><B>2.3</B> - Comments</A><DD>
27 
<DT><A HREF="#S24"><B>2.4</B> - Identifiers</A><DD>
28 
<DT><A HREF="#S25"><B>2.5</B> - Numbers</A><DD>
29 
<DT><A HREF="#S26"><B>2.6</B> - Strings</A><DD>
30 
<DT><A HREF="#S27"><B>2.7</B> - Blanks</A><DD>
31 
<DT><A HREF="#S28"><B>2.8</B> - Bars</A><DD>
32 
</DL>
33 
<DT><A HREF="#S3"><B>3</B> - Input syntax</A><DD>
34 
<DL>
35 
<DT><A HREF="#S31"><B>3.1</B> - Basic syntax</A><DD>
36 
<DT><A HREF="#S32"><B>3.2</B> - Sorts</A><DD>
37 
<DT><A HREF="#S33"><B>3.3</B> - Numbers and strings</A><DD>
38 
<DT><A HREF="#S34"><B>3.4</B> - Tokens, tags, alignment tags and labels</A><DD>
39 
<DT><A HREF="#S35"><B>3.5</B> - Outer level syntax</A><DD>
40 
<DT><A HREF="#S36"><B>3.6</B> - Included files</A><DD>
41 
<DT><A HREF="#S37"><B>3.7</B> - Internal and external names</A><DD>
42 
<DT><A HREF="#S38"><B>3.8</B> - Token declarations</A><DD>
43 
<DT><A HREF="#S39"><B>3.9</B> - Token definitions</A><DD>
44 
<DT><A HREF="#S310"><B>3.10</B> - Alignment tag declarations</A><DD>
45 
<DT><A HREF="#S311"><B>3.11</B> - Alignment tag definitions</A><DD>
46 
<DT><A HREF="#S312"><B>3.12</B> - Tag declarations</A><DD>
47 
<DT><A HREF="#S313"><B>3.13</B> - Tag definitions</A><DD>
48 
</DL>
49 
<DT><A HREF="#S4"><B>4</B> - Shape checking</A><DD>
50 
<DT><A HREF="#S5"><B>5</B> - Remarks</A><DD>
51 
<DT><A HREF="#S6"><B>6</B> - Limitations</A><DD>
52 
<DT><A HREF="#S7"><B>7</B> - Manual Page for tnc</A><DD>
53 
</DL>
54 
<HR>
55 
 
56 
<H2><A NAME=S1>1. Introduction</A></H2>
57 
<P>
58 
The TDF notation compiler, <CODE>tnc</CODE>, is a tool for translating
59 
TDF capsules to and from text. This paper gives a brief introduction
60 
to how to use this utility and the syntax of the textual form of TDF.
61 
The version here described is that supporting version 3.1 of the TDF
62 
specification.
63 
<P>
64 
<CODE>tnc</CODE> has four modes, two input modes and two output modes.
65 
These are as follows:
66 
<UL>
67 
<LI><B>decode</B> - translate an input TDF capsule into the <CODE>tnc</CODE>
68 
internal representation,
69 
<LI><B>read</B> - translate an input text file into the internal representation,
70 
<LI><B>encode</B> - translate the internal representation into an
71 
output TDF capsule,
72 
<LI><B>write</B> - translate the internal representation into an output
73 
text file.
74 
</UL>
75 
<P>
76 
Due to the modular nature of the program it is possible to form versions
77 
of <CODE>tnc</CODE> in which not all the modes are available. Passing
78 
the <B>-version</B> flag to <CODE>tnc</CODE> causes it to report which
79 
modes it has implemented.
80 
<P>
81 
Any application of <CODE>tnc</CODE> consists of the composite of an
82 
input mode and an output mode. The default action is <B>read</B>-<B>encode</B>,
83 
i.e. translate an input test file into an output TDF capsule. Other
84 
modes may be specified by passing the following command line options
85 
to <CODE>tnc</CODE>:
86 
<UL>
87 
<LI><B>-decode</B> or <B>-d</B>,
88 
<LI><B>-read</B> or <B>-r</B>,
89 
<LI><B>-encode</B> or <B>-e</B>,
90 
<LI><B>-write</B> or <B>-w</B>.
91 
</UL>
92 
<P>
93 
The only other really useful action is <B>decode</B>-<B>write</B>,
94 
i.e. translate an input TDF capsule into an output text file. This
95 
may also be specified by the <B>-print</B> or <B>-p</B> option. The
96 
actions <B>decode</B>-<B>encode</B> and <B>read</B>-<B>write</B> are
97 
not precise identities, they do however give equivalent input and
98 
output files.
99 
<P>
100 
In addition, the <B>decode</B> mode may be modified to accept a TDF
101 
library as input rather than a TDF capsule by passing the addition
102 
flag:
103 
<UL>
104 
<LI><B>-lib</B> or <B>-l</B>,
105 
</UL>
106 
<P>
107 
to <CODE>tnc</CODE>.
108 
<P>
109 
The overall syntax for <CODE>tnc</CODE> is as follows:
110 
<PRE>
111 
	tnc [ options ... ] input_file [ output_file ]
112 
</PRE>
113 
If the output file is not specified, the standard output is used.
114 
<P>
115 
<HR>
116 
 
117 
<H2><A NAME=S2>2. Input classes</A></H2>
118 
<P>
119 
The rest of this paper is concerned with the form required of the
120 
input text file. The input can be divided into eight classes.
121 
<H3><A NAME=S21>2.1. Delimiters</A></H3>
122 
<P>
123 
The characters <CODE>(</CODE> and <CODE>)</CODE> are used as delimiters
124 
to impose a syntactic structure on the input.
125 
<H3><A NAME=S22>2.2. White space</A></H3>
126 
<P>
127 
White space comprises sequences of space, tab and newline characters,
128 
together with comments (see below). It is not significant to the output
129 
(TDF notation is completely free-form), and serves only to separate
130 
syntactic units. Every identifier, number etc. must be terminated
131 
by a white space or a delimiter.
132 
<H3><A NAME=S23>2.3. Comments</A></H3>
133 
<P>
134 
Comments may be inserted in the input at any point. They begin with
135 
a <CODE>#</CODE> character and run to the end of the line.
136 
<H3><A NAME=S24>2.4. Identifiers</A></H3>
137 
<P>
138 
An identifier consists of any sequence of characters drawn from the
139 
following set: upper case letters, lower case letters, decimal digits,
140 
underscore (<CODE>_</CODE>), dot (<CODE>.</CODE>), and tilde (<CODE>~</CODE>),
141 
which does not begin with a decimal digit. <CODE>tnc</CODE> generates
142 
names beginning with double tilde (<CODE>~~</CODE>) for unnamed objects
143 
when in <B>decode</B> mode, so the use of such identifiers is not
144 
recommended.
145 
<H3><A NAME=S25>2.5. Numbers</A></H3>
146 
<P>
147 
Numbers can be given in octal (prefixed by <CODE>0</CODE>), decimal,
148 
or hexadecimal (prefixed by <CODE>0x</CODE> or <CODE>0X</CODE>). Both
149 
upper and lower case letters can be used for hex digits. A number
150 
can be preceded by any number of <CODE>+</CODE> or <CODE>-</CODE>
151 
signs.
152 
<H3><A NAME=S26>2.6. Strings</A></H3>
153 
<P>
154 
A string consists of a sequence of characters enclosed in double quotes
155 
(<CODE>&quot;</CODE>). The following escape sequences are recognised:
156 
<UL>
157 
<LI><CODE>\n</CODE> represents a newline character,
158 
<LI><CODE>\t</CODE> represents a tab character,
159 
<LI><CODE>\xxx</CODE>, where <CODE>xxx</CODE> consists of three octal
160 
digits, represents the character with ASCII code <CODE>xxx</CODE>.
161 
</UL>
162 
<P>
163 
Newlines are not allowed in strings unless they are escaped. For all
164 
other escaped characters, <CODE>\x</CODE> represents <CODE>x</CODE>.
165 
 
166 
<H3><A NAME=S27>2.7. Blanks</A></H3>
167 
<P>
168 
A single minus character (<CODE>-</CODE>) has a special meaning. It
169 
may be used to indicate the absence of an optional argument or optional
170 
group of arguments.
171 
<H3><A NAME=S28>2.8. Bars</A></H3>
172 
<P>
173 
A single vertical bar (<CODE>|</CODE>) has a special meaning. It may
174 
be used to indicate the end of a sequence of repeated arguments.
175 
<P>
176 
<HR>
177 
 
178 
<H2><A NAME=S3>3. Input syntax</A></H2>
179 
 
180 
<H3><A NAME=S31>3.1. Basic syntax</A></H3>
181 
<P>
182 
The basic input syntax is very simple. A construct consists of an
183 
identifier followed by a list of arguments, all enclosed in brackets
184 
in a Lisp-like fashion. Each argument can be an identifier, a number,
185 
a string, a blank, a bar, or another construct. There are further
186 
restrictions on this basic syntax, described below.
187 
<PRE>
188 
	construct	: ( identifier arglist )
189 
 
190 
	argument	: construct
191 
			| identifier
192 
			| number
193 
			| string
194 
			| blank
195 
			| bar
196 
 
197 
	arglist		: (empty)
198 
			| argument arglist
199 
</PRE>
200 
<P>
201 
The construct <CODE>( identifier )</CODE>, with an empty argument
202 
list, is equivalent to the identifier argument <CODE>identifier</CODE>.
203 
The two may be used interchangeably.
204 
<H3><A NAME=S32>3.2. Sorts</A></H3>
205 
<P>
206 
Except at the outermost level, which forms a special case discussed
207 
below, every construct and argument has an associated sort. This is
208 
one of the basic TDF sorts: <CODE>access</CODE>, <CODE>al_tag</CODE>,
209 
<CODE>alignment</CODE>, <CODE>bitfield_variety</CODE>, <CODE>bool</CODE>,
210 
<CODE>callees</CODE>, <CODE>error_code</CODE>, <CODE>error_treatment</CODE>,
211 
<CODE>exp</CODE>, <CODE>floating_variety</CODE>, <CODE>label</CODE>,
212 
<CODE>nat</CODE>, <CODE>ntest</CODE>, <CODE>procprops</CODE>, <CODE>rounding_mode
213 
</CODE>, <CODE>shape</CODE>, <CODE>signed_nat</CODE>, <CODE>string</CODE>,
214 
<CODE>tag</CODE>, <CODE>transfer_mode</CODE>, <CODE>variety</CODE>,
215 
<CODE>tdfint</CODE> or <CODE>tdfstring</CODE>.
216 
<P>
217 
Ignoring for the moment the shorthands discussed below, the ways of
218 
creating constructs of sort <CODE>exp</CODE> say, correspond to the
219 
TDF constructs delivering an <CODE>exp</CODE>. For example, <CODE>contents
220 
</CODE> takes a <CODE>shape</CODE> and an <CODE>exp</CODE> and delivers
221 
an <CODE>exp</CODE>. Thus:
222 
<PRE>
223 
	( contents arg1 arg2 )
224 
</PRE>
225 
where <CODE>arg1</CODE> is an argument of sort <CODE>shape</CODE>
226 
and <CODE>arg2</CODE> is an argument of sort <CODE>exp</CODE>, is
227 
a sort-correct construct. Only constructs which are sort correct in
228 
this sense are allowed.
229 
<P>
230 
As another example, because of the rule concerning constructs with
231 
no arguments, both
232 
<PRE>
233 
	( true )
234 
</PRE>
235 
and
236 
<PRE>
237 
	false
238 
</PRE>
239 
are valid constructs of sort <CODE>bool</CODE>.
240 
<P>
241 
TDF constructs which take lists of arguments are easily dealt with.
242 
For example:
243 
<PRE>
244 
	( make_nof arg1 ... argn )
245 
</PRE>
246 
where <CODE>arg1</CODE>, ..., <CODE>argn</CODE> are all arguments
247 
of sort <CODE>exp</CODE>, is valid. A vertical bar may be used to
248 
indicate the end of a sequence of repeated arguments.
249 
<P>
250 
Optional arguments should be entered normally if they are present.
251 
Their absence may be indicated by means of a blank (minus sign), or
252 
by simply omitting the argument.
253 
<P>
254 
The vertical bar and blank should be used whenever the input is potentially
255 
ambiguous. Particular care should be taken with <CODE>apply_proc</CODE>
256 
(which is genuinely ambiguous) and <CODE>labelled</CODE>.
257 
<P>
258 
The TDF specification should be consulted for a full list of valid
259 
TDF constructs and their argument sorts. Alternatively the <CODE>tnc</CODE>
260 
help facility may be used. The command:
261 
<PRE>
262 
	tnc -help cmd1 ... cmdn
263 
</PRE>
264 
prints sort information on the constructs or sorts <CODE>cmd1</CODE>,
265 
..., <CODE>cmdn</CODE>. Alternatively:
266 
<PRE>
267 
	tnc -help
268 
</PRE>
269 
prints this information for all constructs. (To obtain help on the
270 
sort <CODE>alignment</CODE> as opposed to the construct <CODE>alignment</CODE>
271 
use <CODE>alignment_sort</CODE>. This confusion cannot occur elsewhere.)
272 
 
273 
<H3><A NAME=S33>3.3. Numbers and strings</A></H3>
274 
<P>
275 
Numbers can occur in two contexts, as the argument to the TDF constructs
276 
<CODE>make_nat</CODE> and <CODE>make_signed_nat</CODE>. In the former
277 
case the number must be positive. The following shorthands are understood
278 
by <CODE>tnc</CODE>:
279 
<PRE>
280 
	number <I>for</I> ( make_nat number )
281 
	number <I>for</I> ( make_signed_nat number )
282 
</PRE>
283 
depending on whether a construct of sort <CODE>nat</CODE> or <CODE>signed_nat
284 
</CODE> is expected.
285 
<P>
286 
Strings are nominally of sort <CODE>tdfstring</CODE>. They are taken
287 
to be simple strings (8 bits per character). Multibyte strings (those
288 
with other than 8 bits per character) may be represented by means
289 
of the <CODE>multi_string</CODE> construct. This takes the form:
290 
<PRE>
291 
	( multi_string b c1 ... cn )
292 
</PRE>
293 
where <CODE>b</CODE> is the number of bits per character and <CODE>c1</CODE>,
294 
...,<CODE>cn</CODE> are the codes of the characters comprising the
295 
string. These multibyte strings cannot be used as external names.
296 
<P>
297 
In addition, a simple (8 bit) string can be used as a shorthand for
298 
a TDF construct of sort <CODE>string</CODE>, as follows:
299 
<PRE>
300 
	string <I>for</I> ( make_string string )
301 
</PRE>
302 
 
303 
<H3><A NAME=S34>3.4. Tokens, tags, alignment tags and labels</A></H3>
304 
<P>
305 
In TDF simple tokens, tags, alignment tags and labels are represented
306 
by numbers which may, or may not, be associated with external names.
307 
In <CODE>tnc</CODE> however they are represented by identifiers. This
308 
brings the problem of scoping which does not occur in TDF. The rules
309 
are that all tokens, tags, alignment tags and labels must be declared
310 
before they are used. Externally defined objects have global scope,
311 
and the scope of a formal argument in a token definition is the definition
312 
body. For those constructs which introduce a local tag or label -
313 
for example, <CODE>identify</CODE>, <CODE>make_proc</CODE>, <CODE>make_general_proc
314 
</CODE> and <CODE>variable</CODE> for tags and <CODE>conditional</CODE>,
315 
<CODE>labelled</CODE> and <CODE>repeat</CODE> for labels - the scope
316 
of the object is as set out in the TDF specification.
317 
<P>
318 
The following shorthands are understood by <CODE>tnc</CODE>, according
319 
to the argument sort expected:
320 
<PRE>
321 
	tag_id <I>for</I> ( make_tag tag_id )
322 
	al_tag_id <I>for</I> ( make_al_tag al_tag_id )
323 
	label_id <I>for</I> ( make_label label_id )
324 
</PRE>
325 
<P>
326 
The syntax for token applications is as follows:
327 
<PRE>
328 
	( apply_construct ( token_id arg1 ... argn ) )
329 
</PRE>
330 
where <CODE>apply_construct</CODE> is the appropriate TDF token application
331 
construct, for example, <CODE>exp_apply_token</CODE> for tokens declared
332 
to deliver <CODE>exp</CODE>'s. The token arguments <CODE>arg1</CODE>,
333 
..., <CODE>argn</CODE> must be of the sorts indicated in the token
334 
declaration or definition. For tokens without any arguments the alternative
335 
form:
336 
<PRE>
337 
	( apply_construct token_id )
338 
</PRE>
339 
is allowed.
340 
<P>
341 
The token application above may be abbreviated to:
342 
<PRE>
343 
	( token_id arg1 ... argn )
344 
</PRE>
345 
the result sort being known from the token declaration. This in turn
346 
may be abbreviated to:
347 
<PRE>
348 
	token_id
349 
</PRE>
350 
when there are no token arguments.
351 
<P>
352 
Care needs to be taken with these shorthands, as they can lead to
353 
confusion, particularly when, due to optional arguments or lists of
354 
arguments, <CODE>tnc</CODE> is not sure what sort is coming next.
355 
The five categories of objects represented by identifiers - TDF constructs,
356 
tokens, tags, alignment tags and labels - occupy separate name spaces,
357 
but it is a good idea to try to avoid duplication of names.
358 
<P>
359 
By default all these shorthands are used by <CODE>tnc</CODE> in <B>write</B>
360 
mode. If this causes problems, the <B>-V</B> flag should be passed
361 
to <CODE>tnc</CODE>.
362 
<P>
363 
<HR>
364 
 
365 
<H2><A NAME=S35>3.5. Outer level syntax</A></H2>
366 
<P>
367 
At the outer level <CODE>tnc</CODE> is expecting a sequence of constructs
368 
of the following forms:
369 
<UL>
370 
<LI>an included file,
371 
<LI>a token declaration,
372 
<LI>a token definition,
373 
<LI>an alignment tag declaration,
374 
<LI>an alignment tag definition,
375 
<LI>a tag declaration,
376 
<LI>a tag definition.
377 
</UL>
378 
 
379 
<H3><A NAME=S36>3.6. Included files</A></H3>
380 
<P>
381 
Included files may be of three types - text, TDF capsule or TDF library.
382 
For TDF capsules and libraries there are two include modes. The first
383 
just decodes the given capsule or set of capsules. The second scans
384 
through them to extract token declaration information. These declarations
385 
appear in the output file only if they are used elsewhere.
386 
<P>
387 
The syntax for an included text file is:
388 
<PRE>
389 
	( include string )
390 
</PRE>
391 
where <CODE>string</CODE> is a string giving the pathname of the file
392 
to be included. <CODE>tnc</CODE> applies <B>read</B> to this sub-file
393 
before continuing with the present file.
394 
<P>
395 
Similarly, the syntaxes for included TDF capsules and libraries are:
396 
<PRE>
397 
	( code string )
398 
	( lib string )
399 
</PRE>
400 
respectively. <CODE>tnc</CODE> applies <B>decode</B> to this capsule
401 
or set of capsules (provided this mode is available) before continuing
402 
with the present file.
403 
<P>
404 
The syntaxes for extracting the token declaration information from
405 
a TDF capsule or library are:
406 
<PRE>
407 
	( use_code string )
408 
	( use_lib string )
409 
</PRE>
410 
Again, these rely on the <B>decode</B> mode being available.
411 
<H3><A NAME=S37>3.7. Internal and external names</A></H3>
412 
<P>
413 
All tokens, tags and alignment tags have an internal name, namely
414 
the associated identifier, but this name does not necessarily appear
415 
in the corresponding TDF capsule. There must firstly be an associated
416 
declaration or definition at the outer level - tags internal to a
417 
piece of TDF do not have external names. Even then we may not wish
418 
this name to appear at the outer level, because it is local to this
419 
file and is not required for linking purposes. Alternatively we may
420 
wish a different external name to be associated with it in the TDF
421 
capsule.
422 
<P>
423 
As an example of how <CODE>tnc</CODE> allows for this, consider token
424 
declarations (although similar remarks apply to token definitions,
425 
alignment tag definitions etc.). The basic form of the token declaration
426 
is:
427 
<PRE>
428 
	( make_tokdec token_id ... )
429 
</PRE>
430 
This creates a token with both internal and external names equal to
431 
<CODE>token_id</CODE>. Alternatively:
432 
<PRE>
433 
	( local make_tokdec token_id ... )
434 
</PRE>
435 
creates a token with internal name <CODE>token_id</CODE> but no external
436 
name. This allows the creation of tokens local to the current file.
437 
Again:
438 
<PRE>
439 
	( make_tokdec ( string_extern string ) token_id ... )
440 
</PRE>
441 
creates a token with internal name <CODE>token_id</CODE> and external
442 
name given by the string <CODE>string</CODE>. For example, to create
443 
a token whose external name is not a valid identifier, it would be
444 
necessary to use this construct. Finally:
445 
<PRE>
446 
	( make_tokdec ( unique_extern string1 ... stringn ) token_id ... )
447 
</PRE>
448 
creates a token with internal name <CODE>token_id</CODE> and external
449 
name given by the unique name consisting of the strings <CODE>string1</CODE>,
450 
..., <CODE>stringn</CODE>.
451 
<P>
452 
The <CODE>local</CODE> quantifier should be used consistently on all
453 
declarations and definitions of the token, tag or alignment tag. The
454 
alternative external name should only be given on the first occasion
455 
however. Thereafter the object is identified by its internal name.
456 
 
457 
<H3><A NAME=S38>3.8. Token declarations</A></H3>
458 
<P>
459 
The basic form of a token declaration is:
460 
<PRE>
461 
	( make_tokdec token_id ( arg1 ... argn ) res )
462 
</PRE>
463 
where the token <CODE>token_id</CODE> is declared to take argument
464 
sorts <CODE>arg1</CODE>, ..., <CODE>argn</CODE> and deliver the result
465 
sort <CODE>res</CODE>. These sorts are given by their sort names,
466 
<CODE>al_tag</CODE>, <CODE>alignment</CODE>, <CODE>bitfield_variety</CODE>
467 
etc. For a token with no arguments the declaration may be given in
468 
the form:
469 
<PRE>
470 
	( make_tokdec token_id res )
471 
</PRE>
472 
A token may be declared any number of times, provided the declarations
473 
are consistent.
474 
<P>
475 
This basic declaration may be modified in the ways outlined above
476 
to specify the external token name.
477 
<H3><A NAME=S39>3.9. Token definitions</A></H3>
478 
<P>
479 
The basic form of a token definition is:
480 
<PRE>
481 
	( make_tokdef token_id ( arg1 id1 ... argn idn ) res def )
482 
</PRE>
483 
where the token <CODE>token_id</CODE> is defined to take formal arguments
484 
<CODE>id1</CODE>, ..., <CODE>idn</CODE> of sorts <CODE>arg1</CODE>,
485 
..., <CODE>argn</CODE> respectively and have the value <CODE>def</CODE>,
486 
which is a construct of sort <CODE>res</CODE>. The scope of the tokens
487 
<CODE>id1</CODE>, ..., <CODE>idn</CODE> is <CODE>def</CODE>.
488 
<P>
489 
For a token with no arguments the definition may be given in the form:
490 
<PRE>
491 
	( make_tokdef token_id res def )
492 
</PRE>
493 
A token may be defined more than once. All definitions must be consistent
494 
with any previous declarations and definitions (the renaming of formal
495 
arguments is allowed however).
496 
<P>
497 
This basic definition may be modified in the ways outlined above to
498 
specify the external token name.
499 
<H3><A NAME=S310>3.10. Alignment tag declarations</A></H3>
500 
<P>
501 
The basic form of an alignment tag declaration is:
502 
<PRE>
503 
	( make_al_tagdec al_tag_id )
504 
</PRE>
505 
where the alignment tag <CODE>al_tag_id</CODE> is declared to exist.
506 
<P>
507 
This basic declaration may be modified in the ways outlined above
508 
to specify the external alignment tag name.
509 
<H3><A NAME=S311>3.11. Alignment tag definitions</A></H3>
510 
<P>
511 
The basic form of an alignment tag definition is:
512 
<PRE>
513 
	( make_al_tagdef al_tag_id def )
514 
</PRE>
515 
where the alignment tag <CODE>al_tag_id</CODE> is defined to be <CODE>def</CODE>,
516 
which is a construct of sort <CODE>alignment</CODE>. An alignment
517 
tag may be declared or defined more than once, provided the definitions
518 
are consistent.
519 
<P>
520 
This basic definition may be modified in the ways outlined above to
521 
specify the external alignment tag name.
522 
<H3><A NAME=S312>3.12. Tag declarations</A></H3>
523 
<P>
524 
The basic forms of a tag declaration are:
525 
<PRE>
526 
	( make_id_tagdec tag_id info dec )
527 
	( make_var_tagdec tag_id info dec )
528 
	( common_tagdec tag_id info dec )
529 
</PRE>
530 
where the tag <CODE>tag_id</CODE> is declared to be an identity, variable
531 
or common tag with access information <CODE>info</CODE>, which is
532 
an optional construct of sort <CODE>access</CODE>, and shape <CODE>dec</CODE>,
533 
which is a construct of sort <CODE>shape</CODE>. A tag may be declared
534 
more than once, provided all declarations and definitions are consistent
535 
(including agreement of whether the tag is an identity, a variable
536 
or common).
537 
<P>
538 
These basic declarations may be modified in the ways outlined above
539 
to specify the external tag name.
540 
<H3><A NAME=S313>3.13. Tag definitions</A></H3>
541 
<P>
542 
The basic forms of a tag definition are:
543 
<PRE>
544 
	( make_id_tagdef tag_id def )
545 
	( make_var_tagdef tag_id info def )
546 
	( common_tagdef tag_id info def )
547 
</PRE>
548 
where the tag <CODE>tag_id</CODE> is defined to be an identity, variable
549 
or common tag with value <CODE>def</CODE>, which is a construct of
550 
sort <CODE>exp</CODE>. Non-identity tag definitions also have an optional
551 
<CODE>access</CODE> construct, <CODE>info</CODE>. A tag must have
552 
been declared before it is defined, but may be defined any number
553 
of times. All declarations and definitions must be consistent (except
554 
that common tags may be defined inconsistently) and agree on whether
555 
the tag is an identity, a variable, or common.
556 
<P>
557 
These basic definitions may be modified in the ways outlined above
558 
to specify the external tag name.
559 
<P>
560 
<HR>
561 
 
562 
<H2><A NAME=S4>4. Shape checking</A></H2>
563 
<P>
564 
The input in <B>read</B> (and to a lesser extent <B>decode</B>) mode
565 
is checked for shape correctness if the <B>-check</B> or <B>-c</B>
566 
flag is passed to <CODE>tnc</CODE>. This is not guaranteed to pick
567 
up all shape errors, but is better than nothing.
568 
<P>
569 
When in <B>write</B> mode the results of the shape checking may be
570 
viewed by passing the <B>-cv</B> flag to <CODE>tnc</CODE>. Each expression
571 
is associated with its shape by means of the:
572 
<PRE>
573 
	( exp_with_shape exp shape ) -&gt; exp
574 
</PRE>
575 
pseudo-construct. Unknown shapes are indicated by <CODE>....</CODE>
576 
<P>
577 
<HR>
578 
 
579 
<H2><A NAME=S5>5. Remarks</A></H2>
580 
<P>
581 
The target independent TDF capsules produced by the C -&gt; TDF compiler,
582 
<CODE>tcc</CODE>, do not contain declarations or definitions for all
583 
the tokens they use. Thus <CODE>tnc</CODE> cannot fully decode them
584 
as they stand. However the necessary token declaration information
585 
may be made available to <CODE>tnc</CODE> by using the <B>use_lib</B>
586 
construct. The commands:
587 
<PRE>
588 
	( use_lib library )
589 
	( code capsule )
590 
</PRE>
591 
will decode the TDF capsule <CODE>capsule</CODE> which uses tokens
592 
defined in the TDF library <CODE>library</CODE>.
593 
<P>
594 
<HR>
595 
 
596 
<H2><A NAME=S6>6. Limitations</A></H2>
597 
<P>
598 
The main limitations in the current version of <CODE>tnc</CODE> are
599 
as follows:
600 
<UL>
601 
<LI>There is no error recovery,
602 
<LI>There is no support for foreign sorts,
603 
<LI>The support for tokenised tokens is limited and undocumented.
604 
</UL>
605 
<P>
606 
In addition, far more of the checks (scopes, shape checking, checking
607 
of consistency of declarations and definitions etc.) are implemented
608 
for <B>read</B> mode rather than <B>decode</B> mode. To shape check
609 
a TDF capsule, it will almost certainly be more effective to translate
610 
it into text and check that.
611 
<P>
612 
Another limitation is that the scoping rules for local tags do not
613 
allow such tags to be accessed outside their scopes using <CODE>env_offset
614 
</CODE>.
615 
<P>
616 
<HR>
617 
 
618 
<H2><A NAME=S7>7. Manual Page for tnc</A></H2>
619 
<P>
620 
Here is the manual page for tnc.
621 
<P>
622 
<B>NAME</B>: <CODE>tnc</CODE> - TDF notation compiler
623 
<P>
624 
<B>SYNOPSIS</B>: <CODE>tnc [ options ] input-file [ output-file ]</CODE>
625 
<P>
626 
<B>DESCRIPTION</B>: <CODE>tnc</CODE> translates TDF capsules to and
627 
from text. It has two input modes, <B>read</B> and <B>decode</B>.
628 
In the first, which is default, <CODE>input-file</CODE> is a file
629 
containing TDF text. In the second <CODE>input-file</CODE> is a TDF
630 
capsule. There are also two output modes, <B>encode</B> and <B>write</B>.
631 
In the first, which is default, a TDF capsule is written to <CODE>output-file
632 
</CODE> (or the standard output if this argument is absent). In the
633 
second, TDF text is written to <CODE>output-file</CODE>.
634 
<P>
635 
Combination of these modes give four actions: text to TDF (which is
636 
default), TDF to text, text to text and TDF to TDF. The last two actions
637 
are not precise identities, but they do give equivalent files.
638 
<P>
639 
The form of the TDF text format and more information about <CODE>tnc</CODE>
640 
can be found in the document <I>The TDF Notation Compiler</I>.
641 
<P>
642 
<B>OPTIONS</B>:
643 
<P>
644 
<B>-c</B> or <B>-cv</B> or <B>-check</B>
645 
Specifies that <CODE>tnc</CODE> should apply extra checks to <CODE>input-file
646 
</CODE>. For example, simple shape checking is applied. These checks
647 
are more efficient in <B>read</B> mode than in <B>decode</B> mode.
648 
If the <B>-cv</B> option is used in <B>write</B> mode, all the information
649 
gleaned from the shape checking appears in <CODE>output-file</CODE>.
650 
<P>
651 
<B>-d</B> or <B>-decode</B>
652 
Specifies that <CODE>tnc</CODE> should be in <B>decode</B> mode. That
653 
is, that <CODE>input-file</CODE> is a TDF capsule.
654 
<P>
655 
<B>-e</B> or <B>-encode</B>
656 
Specifies that <CODE>tnc</CODE> should be in <B>encode</B> mode. That
657 
is, that <CODE>output-file</CODE> is a TDF capsule.
658 
<P>
659 
<B>-help</B> <CODE>subject</CODE> ... Makes <CODE>tnc</CODE> print
660 
its help message on the given subject(s). If no subject is given,
661 
all the help messages are printed.
662 
<P>
663 
<B>-I</B><CODE>dir</CODE>
664 
Adds the directory <CODE>dir</CODE> to the search path used by <CODE>tnc</CODE>
665 
to find included files in <B>read</B> mode.
666 
<P>
667 
<B>-l</B> or <B>-lib</B>
668 
In <B>decode</B> mode, specifies that <CODE>input-file</CODE> is not
669 
a TDF capsule, but a TDF library. All the capsules comprising the
670 
library are decoded.
671 
<P>
672 
<B>-o</B> <CODE>output-file</CODE>
673 
Gives an alternative method of specifying the output file.
674 
<P>
675 
<B>-p</B> or <B>-print</B>
676 
Specifies that <CODE>tnc</CODE> should be in <B>decode</B> and <B>write</B>
677 
modes. That is, that <CODE>input-file</CODE> is a TDF capsule and
678 
<CODE>output-file</CODE> should consist of TDF text. This option makes
679 
<CODE>tnc</CODE> into a TDF pretty-printer.
680 
<P>
681 
<B>-q</B>
682 
Specifies that <CODE>tnc</CODE> should not check duplicate tag declarations
683 
etc for consistency, but should use the first declaration given.
684 
<P>
685 
<B>-r</B> or <B>-read</B>
686 
Specifies that <CODE>tnc</CODE> should be in <B>read</B> mode. That
687 
is, that <CODE>input-file</CODE> should consist of TDF text.
688 
<P>
689 
<B>-V</B>
690 
In <B>write</B> mode, specifies that the output should be in the &quot;verbose&quot;
691 
form, with no shorthand forms.
692 
<P>
693 
<B>-version</B>
694 
Makes <CODE>tnc</CODE> print its version number.
695 
<P>
696 
<B>-w</B> or <B>-write</B>
697 
Specifies that <CODE>tnc</CODE> should be in <B>write</B> mode. That
698 
is, that <CODE>output-file</CODE> should consist of TDF text.
699 
<P>
700 
<B>SEE ALSO</B>: <I>tdf</I>(1tdf).
701 
<P>
702 
<HR>
703 
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
704 
Copyright &copy; 1998.</I></P>
705 
</BODY>
706 
</HTML>