|
996
|
1 \input texinfo @c -*- texinfo -*-
|
|
|
2 @c %**start of header
|
|
|
3 @setfilename ick.info
|
|
|
4 @set VERSION 0.29
|
|
|
5 @set VERSIONDASH 0-29
|
|
|
6 @settitle C-INTERCAL @value{VERSION} Revamped Instruction Manual
|
|
|
7 @paragraphindent 0
|
|
|
8 @documentlanguage en
|
|
|
9 @documentencoding ISO-8859-1
|
|
|
10
|
|
|
11 @c Command line option index.
|
|
|
12 @defcodeindex op
|
|
|
13 @c Error index
|
|
|
14 @defindex er
|
|
|
15 @c Commands and language features are in the predefined fnindex.
|
|
|
16 @c Things generally are in the predefined cpindex.
|
|
|
17
|
|
|
18 @c Combining indices.
|
|
|
19 @syncodeindex fn cp
|
|
|
20 @syncodeindex op cp
|
|
|
21 @synindex er cp
|
|
|
22
|
|
|
23 @c Adding to the main documentation tree.
|
|
|
24 @dircategory INTERCAL
|
|
|
25 @direntry
|
|
|
26 * C-INTERCAL: (ick). The C-INTERCAL language and compiler.
|
|
|
27 * ick: (ick) Invoking ick. Invoking the C-INTERCAL compiler.
|
|
|
28 * convickt: (ick) convickt. The command-line character set converter.
|
|
|
29 @end direntry
|
|
|
30
|
|
|
31 @c Some macros to ease writing and updating. (The VERSION is set above because
|
|
|
32 @c it's needed to set the title.)
|
|
|
33 @macro cic{}
|
|
|
34 @abbr{C-INTERCAL}
|
|
|
35 @end macro
|
|
|
36 @macro clcic{}
|
|
|
37 @abbr{CLC-INTERCAL}
|
|
|
38 @end macro
|
|
|
39 @macro icst{}
|
|
|
40 @abbr{INTERCAL-72}
|
|
|
41 @end macro
|
|
|
42 @macro jic{}
|
|
|
43 @abbr{J-INTERCAL}
|
|
|
44 @end macro
|
|
|
45 @macro ical{}
|
|
|
46 @acronym{INTERCAL}
|
|
|
47 @end macro
|
|
|
48
|
|
|
49 @c Part headings for unsplit output
|
|
|
50 @macro partheading{arg}
|
|
|
51 @html
|
|
|
52 <!--
|
|
|
53 @end html
|
|
|
54 @unnumbered \arg\
|
|
|
55 @html
|
|
|
56 --><h1>\arg\</h1>
|
|
|
57 @end html
|
|
|
58 @c
|
|
|
59 @end macro
|
|
|
60 @iftex
|
|
|
61 @set notsplit
|
|
|
62 @end iftex
|
|
|
63
|
|
|
64 @c 'Portability' boxes
|
|
|
65 @macro portability{st,c,clc,j}
|
|
|
66 @multitable @columnfractions .23 .23 .23 .23
|
|
|
67 @headitem @icst{} @tab @cic{} @tab @clcic{} @tab @jic{}
|
|
|
68 @item \st\ @tab \c\ @tab \clc\ @tab \j\
|
|
|
69 @end multitable
|
|
|
70 @c
|
|
|
71 @end macro
|
|
|
72
|
|
|
73 @c Generating items and anchors together is also helpful.
|
|
|
74 @macro ianchor{arg}
|
|
|
75 @item \arg\
|
|
|
76 @anchor{\arg\}
|
|
|
77 @c
|
|
|
78 @end macro
|
|
|
79 @macro ianchorc{arg}
|
|
|
80 @item \arg\
|
|
|
81 @anchor{\arg\+}
|
|
|
82 @c
|
|
|
83 @end macro
|
|
|
84 @macro ieanchor{arg}
|
|
|
85 @item \arg\
|
|
|
86 @anchor{\arg\}
|
|
|
87 @erindex \arg\
|
|
|
88 @c
|
|
|
89 @end macro
|
|
|
90 @macro ianchorpm{arg}
|
|
|
91 @item +\arg\
|
|
|
92 @itemx -\arg\
|
|
|
93 @anchor{+\arg\}
|
|
|
94 @anchor{-\arg\}
|
|
|
95 @c
|
|
|
96 @end macro
|
|
|
97
|
|
|
98 @c Some fixes for HTML.
|
|
|
99 @ifhtml
|
|
|
100 @c Examples are styled in CSS; don't do it with hardcoded whitespace!
|
|
|
101 @exampleindent 0
|
|
|
102 @end ifhtml
|
|
|
103 @c %**end of header
|
|
|
104
|
|
|
105 @copying
|
|
|
106 This manual is for @cic{} version @value{VERSION}. It does not replace
|
|
|
107 the old groff manual, nor is it designed to be read in conjunction with
|
|
|
108 it; instead, it serves a different purpose, of providing information
|
|
|
109 useful to users of @cic{} (unlike the other manual, it is not derived
|
|
|
110 from the original @icst{} manual).
|
|
|
111
|
|
|
112 Copyright @copyright{} 2007 Alex Smith.
|
|
|
113
|
|
|
114 @quotation
|
|
|
115 Permission is granted to copy, distribute and/or modify this document
|
|
|
116 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
|
117 any later version published by the Free Software Foundation; with no
|
|
|
118 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
|
119 Texts. A copy of the license is included in the section entitled
|
|
|
120 ``GNU Free Documentation License.''
|
|
|
121
|
|
|
122 @end quotation
|
|
|
123 @end copying
|
|
|
124
|
|
|
125 @titlepage
|
|
|
126 @ifset notsplit
|
|
|
127 @title C-INTERCAL Revamped Instruction Manual
|
|
|
128 @subtitle (this version distributed with version @value{VERSION} of C-INTERCAL)
|
|
|
129
|
|
|
130 @page
|
|
|
131 @vskip 0pt plus 1filll
|
|
|
132 @insertcopying
|
|
|
133
|
|
|
134 @end ifset
|
|
|
135 @end titlepage
|
|
|
136
|
|
|
137 @ifset notsplit
|
|
|
138 @contents
|
|
|
139 @end ifset
|
|
|
140
|
|
|
141 @ifnottex
|
|
|
142 @node Top
|
|
|
143 @top C-INTERCAL @value{VERSION}
|
|
|
144
|
|
|
145 @insertcopying
|
|
|
146
|
|
|
147 @menu
|
|
|
148 * About this manual:: What is covered in this manual
|
|
|
149
|
|
|
150 The @cic{} compiler
|
|
|
151 * Installation:: How to install @cic{}
|
|
|
152 * Invoking ick:: Options to give to the compiler ick
|
|
|
153 * Errors and Warnings:: Error messages, and what to do about them
|
|
|
154 * The yuk debugger:: How to use the runtime debugger
|
|
|
155
|
|
|
156 Basic @ical{} features
|
|
|
157 * Syntax:: Holding statements together
|
|
|
158 * Expressions:: Operators, operands, and grouping
|
|
|
159 * Statements:: What an @ical{} statement can do
|
|
|
160 * System Library:: Pre-existing @ical{} routines
|
|
|
161
|
|
|
162 @ical{} dialects and extensions
|
|
|
163 * TriINTERCAL:: @ical{} in non-binary bases
|
|
|
164 * Multithreading and Backtracking:: Running @ical{} programs in parallel
|
|
|
165 * Operand Overloading:: Where one expression stands for another
|
|
|
166 * PIC-INTERCAL:: @ical{} on embedded systems
|
|
|
167 * CREATE:: Creating new syntax at runtime
|
|
|
168 * External Calls:: Linking @ical{} with other languages
|
|
|
169 * Differences to Other Compilers:: @cic{} vs. @clcic{}
|
|
|
170
|
|
|
171 Appendices and indices
|
|
|
172 * Character Sets:: A list of character sets used by @ical{}
|
|
|
173 * convickt:: The command-line character set converter
|
|
|
174 * Optimizer Idiom Language:: The syntax to specify optimizer idioms
|
|
|
175 * Copying:: License information for the code and manual
|
|
|
176 * Main Index:: An index of all the pages in this manual
|
|
|
177
|
|
|
178 @end menu
|
|
|
179 @end ifnottex
|
|
|
180
|
|
|
181 @node About this manual
|
|
|
182 @unnumbered About this manual
|
|
|
183 @cindex About this manual
|
|
|
184
|
|
|
185 This is the Revamped Instruction Manual for @cic{} (this version is
|
|
|
186 distributed with @cic{} version @value{VERSION}). It is divided into
|
|
|
187 four parts.
|
|
|
188
|
|
|
189 The first part is about the @cic{} compiler @command{ick}, and how to
|
|
|
190 use it. It covers installing the compiler, using the compiler, what
|
|
|
191 error and warning messages are produced by the compiler, and some
|
|
|
192 information on how to use the debugger.
|
|
|
193
|
|
|
194 The second part is about the core @ical{} language, invented in 1972,
|
|
|
195 and some other commands since then which don't feel like they're
|
|
|
196 extensions. (This is a pretty arbitrary distinction, but people who
|
|
|
197 write the documentation are entitled to arbitrary distinctions. The
|
|
|
198 manual's licensed under a license that lets you change it
|
|
|
199 (@pxref{Copying}), so if you disagree you can move the commands from
|
|
|
200 section to section yourself.) Mostly only commands that are
|
|
|
201 implemented in @cic{} are covered here (if you're interested in the
|
|
|
202 other commands implemented in other compilers, read @clcic{}'s
|
|
|
203 documentation). However, a comprehensive guide to portability of
|
|
|
204 these commands between @cic{} and other @ical{} compilers is given.
|
|
|
205
|
|
|
206 The third part covers the @ical{} extensions and dialects that are
|
|
|
207 implemented by @cic{}, such as TriINTERCAL and Threaded @ical{}.
|
|
|
208 Again, extensions and dialects not implemented have been mostly left
|
|
|
209 out.
|
|
|
210
|
|
|
211 The final part contains appendices (which were known as `tonsils' in
|
|
|
212 the original @ical{} manual), such as character sets used by @ical{},
|
|
|
213 programs other than @command{ick} in the @cic{} distribution,
|
|
|
214 information on how to read and update the list of optimizer idioms
|
|
|
215 used by the compiler, and the copyright.
|
|
|
216
|
|
|
217 @ifset notsplit
|
|
|
218 @partheading{PART I: THE @cic{} COMPILER}
|
|
|
219 @end ifset
|
|
|
220 @node Installation
|
|
|
221 @chapter Installation
|
|
|
222 @cindex installation
|
|
|
223 @cindex @command{ick}, installing
|
|
|
224
|
|
|
225 The @cic{} distribution is distributed in source code form; this means
|
|
|
226 that before using it, you first have to compile it. Don't worry: if you
|
|
|
227 have the right software, it's not at all difficult. Most Linux-based
|
|
|
228 and UNIX-based computers are likely to have the software needed already;
|
|
|
229 the software needed to compile source-distributed packages is also
|
|
|
230 readily available for free for other operating systems. The following
|
|
|
231 instructions will help you install the distribution in a method
|
|
|
232 appropriate for your system.
|
|
|
233
|
|
|
234 (If you happen to be using Debian or Ubuntu, you can also obtain and
|
|
|
235 install binaries with the command @samp{sudo apt-get install
|
|
|
236 intercal}, making the rest of this chapter redundant. If you do this,
|
|
|
237 use Debian's bug tracker to report bugs, rather than reporting them
|
|
|
238 directly to the maintainers.)
|
|
|
239
|
|
|
240 @menu
|
|
|
241 * Obtaining:: How to get a @cic{} distribution to install
|
|
|
242 * Unpacking:: What to do with the distribution file
|
|
|
243 * Simple Installation:: How to install things the easy way
|
|
|
244 * Uninstalling:: If you don't want to use the software
|
|
|
245 * Reporting Bugs:: If it doesn't work or you know how to fix it
|
|
|
246 * Distributing:: How to make your own @cic{} distribution
|
|
|
247 @end menu
|
|
|
248
|
|
|
249 @node Obtaining
|
|
|
250 @section Obtaining
|
|
|
251 @cindex obtaining C-INTERCAL
|
|
|
252 @cindex C-INTERCAL, obtaining a copy
|
|
|
253
|
|
|
254 @cic{} distributions have been stored in many different places over
|
|
|
255 time; it can sometimes be hard to make sure that you are finding the
|
|
|
256 most recent version. In order to make sure that you have the most
|
|
|
257 recent version, the easiest way is to look at the
|
|
|
258 @uref{news:alt.lang.intercal,,alt.lang.intercal newsgroup}; all releases
|
|
|
259 of the @cic{} compiler ought to be announced there. (If you are
|
|
|
260 interested in what other @ical{} compilers are available, it may also be
|
|
|
261 worth looking there.) If you don't have access to a newsreader, your
|
|
|
262 newsreader doesn't cover that newsgroup, or the distance between
|
|
|
263 releases has been too large for your news server to keep the message,
|
|
|
264 it's likely that you can find the announcement in an archive on the
|
|
|
265 World Wide Web; at the time of writing (2007), the archives of the
|
|
|
266 newsgroup are stored by @uref{http://groups.google.com,Google Groups},
|
|
|
267 and a search for @samp{alt.lang.intercal} there should tell you where to
|
|
|
268 find a copy.
|
|
|
269
|
|
|
270 If you're looking for the latest version, note that the number after the
|
|
|
271 dot represents the major version number; you want to maximise this in
|
|
|
272 favour of the number before the dot, which is the bugfix level within a
|
|
|
273 major version. (Major versions are released as version 0.whatever; if a
|
|
|
274 new version comes out that fixes bugs but adds no new features, nowadays
|
|
|
275 its number will be of the form 1.whatever, with the same major number.
|
|
|
276 This has not always been the case, though.)
|
|
|
277
|
|
|
278 @node Unpacking
|
|
|
279 @section Unpacking
|
|
|
280 @cindex C-INTERCAL, unzipping
|
|
|
281 @cindex C-INTERCAL, unpacking
|
|
|
282 @cindex unzipping C-INTERCAL
|
|
|
283 @cindex unpacking C-INTERCAL
|
|
|
284 @cindex ick-@value{VERSIONDASH}.pax.*
|
|
|
285
|
|
|
286 @cic{} is distributed in compressed pax format; for instance, you may
|
|
|
287 find as a @samp{.pax.lzma} file if you have the @command{unlzma}
|
|
|
288 decompression program (this is advised, as it's the smallest);
|
|
|
289 @samp{.pax.bz2} is larger and @samp{.pax.gz} is larger still. Most
|
|
|
290 computers can decompress files in this format, even if they don't
|
|
|
291 realise it, because pax is forwards-compatible with tar; try renaming
|
|
|
292 the extension from @samp{.pax} to @samp{.tar} after decompressing to
|
|
|
293 see if you have a progam that can decompress it. (If you're wondering
|
|
|
294 why such an apparently non-standard format is being used, this is is
|
|
|
295 actually a case where @cic{} is being perfectly nonstandard by
|
|
|
296 conforming to the standards; tar is no longer specified by POSIX, and
|
|
|
297 pax is its replacement. It's just that pax never really caught on.)
|
|
|
298
|
|
|
299 It doesn't matter where you extract the distribution file to: it's best
|
|
|
300 if you don't put it anywhere special. If you aren't an administrator,
|
|
|
301 you should extract the file to somewhere in your home directory (Linux
|
|
|
302 or UNIX-like systems) or to your My Documents directory (recent versions
|
|
|
303 of Windows; if you're using an older version, then you @emph{are} an
|
|
|
304 administrator, or at least have the same privileges, and can extract it
|
|
|
305 anywhere). Some commands that you might use to extract it:
|
|
|
306
|
|
|
307 @table @asis
|
|
|
308
|
|
|
309 @item Generic UNIX/Linux
|
|
|
310
|
|
|
311 @example
|
|
|
312 unlzma ick-@value{VERSIONDASH}.pax.lzma
|
|
|
313 tar xvf ick-@value{VERSIONDASH}.pax
|
|
|
314 @end example
|
|
|
315 @i{or}
|
|
|
316 @example
|
|
|
317 bunzip2 ick-@value{VERSIONDASH}.pax.bz2
|
|
|
318 tar xvf ick-@value{VERSIONDASH}.pax
|
|
|
319 @end example
|
|
|
320 @i{or}
|
|
|
321 @example
|
|
|
322 gunzip ick-@value{VERSIONDASH}.pax.gz
|
|
|
323 tar xvf ick-@value{VERSIONDASH}.pax
|
|
|
324 @end example
|
|
|
325
|
|
|
326 On most UNIX-based and Linux-based systems, @command{tar} will be
|
|
|
327 available to unpack the installation files once they've been
|
|
|
328 uncompressed with @command{gunzip}. (I've heard that some BSD systems
|
|
|
329 have @command{pax} itself to decompress the files, although have not
|
|
|
330 been able to verify this; some Linux distributions also have
|
|
|
331 @command{pax} in their package managers. Both tar and pax should work
|
|
|
332 fine, though.) @command{gunzip} is also likely to be available (and
|
|
|
333 @command{bunzip2} and @command{unlzma} are less likely, but use those
|
|
|
334 versions if you have them to save on your bandwidth); if it isn't, you
|
|
|
335 will need to download a copy from the Internet.
|
|
|
336
|
|
|
337 @item Using GNU tar
|
|
|
338
|
|
|
339 @example
|
|
|
340 tar xzvf ick-@value{VERSIONDASH}.pax.gz
|
|
|
341 @end example
|
|
|
342 @i{or}
|
|
|
343 @example
|
|
|
344 tar xqvf ick-@value{VERSIONDASH}.pax.bz2
|
|
|
345 @end example
|
|
|
346
|
|
|
347 If you are using the GNU version of @command{tar} (which is very likely
|
|
|
348 on Linux), you can combine the two steps into one as shown here,
|
|
|
349 except when using the lzma-compressed version.
|
|
|
350
|
|
|
351 @item Using DJGPP
|
|
|
352
|
|
|
353 @example
|
|
|
354 djtar -x ick-@value{VERSIONDASH}.pax.gz
|
|
|
355 @end example
|
|
|
356
|
|
|
357 On a DOS system, you will have to install DJGPP anyway to be able to
|
|
|
358 compile the distribution, and once you've done that you will be able
|
|
|
359 to use DJGPP's decompressing and unpacking utility to extract the
|
|
|
360 files needed to install the distribution. (You will need to type this
|
|
|
361 at the command line; on Windows 95 and later, try choosing Run...@:
|
|
|
362 from the start menu then typing @command{cmd} (or @command{command} if
|
|
|
363 that fails) in the dialog box that opens to get a command prompt,
|
|
|
364 which you can exit by typing @command{exit}. After typing any command
|
|
|
365 at a command line, press @key{RET} to tell the shell to execute that
|
|
|
366 command.)
|
|
|
367
|
|
|
368 @item On Windows
|
|
|
369
|
|
|
370 If you're running a Windows system, you could always try
|
|
|
371 double-clicking on the ick-@value{VERSIONDASH}.pax.gz file; probably
|
|
|
372 renaming it to have the extension @samp{.tgz} is likely to give the
|
|
|
373 best results. It's quite possible that you'll have a program
|
|
|
374 installed that's capable of decompressing and unpacking it.
|
|
|
375 Unfortunately, I can't guess what program that might be, so I can't
|
|
|
376 give you any instructions for using it.
|
|
|
377
|
|
|
378 @end table
|
|
|
379
|
|
|
380 Whatever method you use, you should end up with a directory created
|
|
|
381 called @file{ick-@value{VERSION}}; this is your main installation
|
|
|
382 directory where all the processing done by the installation will be
|
|
|
383 carried out. You will need to have that directory as the current
|
|
|
384 directory during install (at the command prompt in all the operating
|
|
|
385 systems I know, you can set the current directory by typing @command{cd
|
|
|
386 ick-@value{VERSION}}).
|
|
|
387
|
|
|
388 @node Simple Installation
|
|
|
389 @section Simple Installation
|
|
|
390 @cindex installation, simple
|
|
|
391 @cindex simple installation
|
|
|
392 @findex config.sh
|
|
|
393 @findex make
|
|
|
394 @findex make install
|
|
|
395 @cindex compiling, @command{ick} itself
|
|
|
396 @cindex installation, via autoconf and make
|
|
|
397 @cindex configuring
|
|
|
398
|
|
|
399 There are scripts included in the distribution to automate the process
|
|
|
400 of installing, in various ways. The simplest method of installing is to
|
|
|
401 use the following routine:
|
|
|
402
|
|
|
403 @enumerate
|
|
|
404
|
|
|
405 @item
|
|
|
406 Configure @cic{}, by running @command{configure}. Although building
|
|
|
407 in the distribution directory works; it is recommended that you build
|
|
|
408 elsewhere; create a directory to build in (using @command{mkdir} on
|
|
|
409 most operating systems), then run @command{configure} from inside that
|
|
|
410 directory (for instance, you could do this from inside the main
|
|
|
411 installation directory:
|
|
|
412 @example
|
|
|
413 mkdir build
|
|
|
414 cd build
|
|
|
415 ../configure
|
|
|
416 @end example
|
|
|
417 to build in a subdirectory of the distribution called ``build''). You
|
|
|
418 also specify where you want the files to be installed at this stage;
|
|
|
419 the default of @samp{/usr/local} is good for many people, but you may
|
|
|
420 want to install elsewhere (in particular, if you want to test out
|
|
|
421 C-INTERCAL without installing it, create a new directory somewhere you
|
|
|
422 own and specify that as the place to install it, so the install will
|
|
|
423 actually just copy the files into the right structure for use instead
|
|
|
424 of installing them). To specify a location, give the option
|
|
|
425 @option{--prefix=@var{location}} to configure; for instance,
|
|
|
426 @command{configure --prefix=/usr} would install in /usr.
|
|
|
427
|
|
|
428 @item
|
|
|
429 Compile the source code, with the command @command{make}. The
|
|
|
430 Makefile will be set up for your version of @command{make}, and to
|
|
|
431 automatically recompile only what needs compiling (it will even
|
|
|
432 recompile the build system if you change that).
|
|
|
433
|
|
|
434 @item
|
|
|
435 Optionally, create libraries from third-party interpreters to add
|
|
|
436 support for more languages to the @cic{} external calls system; see
|
|
|
437 @ref{Creating the Funge-98 Library}. (This step can be skipped; you
|
|
|
438 can also do it later, but if you do so you need to run the next step
|
|
|
439 again.)
|
|
|
440
|
|
|
441 @item
|
|
|
442 Install the executables, help files, include files, and libraries,
|
|
|
443 using @command{make install}. (This is the only step that needs
|
|
|
444 root/administrator permissions; so on a system that uses sudo to
|
|
|
445 elevate permissions, for instance, write it as @command{sudo make
|
|
|
446 install} if you're installing into a directory that you can't write to
|
|
|
447 as a non-administrative user.)
|
|
|
448
|
|
|
449 @end enumerate
|
|
|
450
|
|
|
451 On all systems, it's worth just trying this to see if it works. This
|
|
|
452 requires a lot of software on your computer to work, but all of it is
|
|
|
453 standard on Linux and UNIX systems. The first command is a
|
|
|
454 shell-script which will analyse your system and set settings
|
|
|
455 accordingly; it will explain what it's doing and what settings it
|
|
|
456 detected, and create several files in the installation directory to
|
|
|
457 record its results. (This is a configure script produced by the GNU
|
|
|
458 autoconf (configure); its autoconf source code is available in the
|
|
|
459 file @file{configure.ac}.) The second command actually compiles the
|
|
|
460 source code to produce binaries; this takes the longest of any of the
|
|
|
461 steps. You will see all the commands that it's running as it runs
|
|
|
462 them. The third command will copy the files it's compiled to
|
|
|
463 appropriate shared locations on your system so that anyone on the
|
|
|
464 system can just use @command{ick}.
|
|
|
465
|
|
|
466 There may be various factors that prevent this simple installation
|
|
|
467 method working. On a system not based on UNIX or Linux, you may find
|
|
|
468 that you don't have some of the software required to run this (for
|
|
|
469 instance, you may be missing the shell @command{sh}, and don't have
|
|
|
470 the shell @command{bash} which can emulate it, and so can't run
|
|
|
471 @command{sh config.sh} that depends on one of those shells being
|
|
|
472 available) and so this method won't work for you. In such cases, one
|
|
|
473 solution may be to install all the software required; the GNU project
|
|
|
474 has a version of all the commands required, for instance, and there
|
|
|
475 may be ports available for your operating system. However, the only
|
|
|
476 software absolutely required is a C compiler (@cic{} was designed to
|
|
|
477 work with @command{gcc} and is tested mostly with that compiler, but
|
|
|
478 in theory it should work with other C compilers too, and this is
|
|
|
479 tested on occasion) and the associated software needed to compile C
|
|
|
480 files to object files and executables, combine object files into
|
|
|
481 libraries, etc.
|
|
|
482
|
|
|
483 Another possibility that might stop this process working is if your
|
|
|
484 version of the relevant software is incompatible with the GNU versions
|
|
|
485 that were used for testing. For instance, I have come across
|
|
|
486 proprietary versions of @command{lex} that need directives in the source
|
|
|
487 file to say in advance how much memory the lexer-generator needs to
|
|
|
488 allocate. In such cases, pay attention to the error messages you're
|
|
|
489 getting; normally they will suggest trivial modifications to the source
|
|
|
490 files that will cause the compilation to work again.
|
|
|
491
|
|
|
492 @cindex installation, Debian
|
|
|
493 @cindex installation, Ubuntu
|
|
|
494 @cindex Debian
|
|
|
495 @cindex Ubuntu
|
|
|
496 Some Linux and UNIX systems (notably Debian and Ubuntu) don't have the
|
|
|
497 required files for compilation installed by default. To install them,
|
|
|
498 just download and install the required packages: for Ubuntu at the
|
|
|
499 time of writing, they are @samp{binutils}, @samp{cpp}, @samp{gcc},
|
|
|
500 @samp{libc6-dev}, @samp{make} to compile @cic{}, and if you want to
|
|
|
501 modify it, you may also need @samp{autoconf}, @samp{automake},
|
|
|
502 @samp{bison}, and @samp{flex}. For debugging help, you may also want
|
|
|
503 @samp{gdb}, and to recompile the documentation, you may need
|
|
|
504 @samp{groff}, @samp{tetex-bin}, @samp{texinfo}, and @samp{tidy}. Of
|
|
|
505 course, if @ical{} ever (the author of this sentence was going to
|
|
|
506 write something like ``becomes popular, someone will probably package
|
|
|
507 up a compiler for Debian or Ubuntu anyway'', but at that point on a
|
|
|
508 whim did an Ubuntu package search for 'intercal' and actually came up
|
|
|
509 with two results, which look suspiciously like @cic{} and @clcic{},
|
|
|
510 later confirming this. The author was vaguely aware that there was a
|
|
|
511 @clcic{} package floating around, but was unaware of the @cic{}
|
|
|
512 package, and as a result was too surprised to finish the sentence.)
|
|
|
513
|
|
|
514 If you're trying to do something unusual, you probably want to set some
|
|
|
515 of the settings yourself rather than letting the compilation process
|
|
|
516 guess everything. In this case, use @command{configure --help} to
|
|
|
517 view the options that you can set on @command{configure}; there's a wide
|
|
|
518 range of settings that you can set available there, and one of them may
|
|
|
519 be what you want.
|
|
|
520
|
|
|
521 @node Uninstalling
|
|
|
522 @section Uninstalling
|
|
|
523 @cindex uninstalling
|
|
|
524 @cindex @command{ick}, uninstalling
|
|
|
525
|
|
|
526 It may happen that you decide to uninstall @cic{} after installing it;
|
|
|
527 this may be useful if you want to test the installation system, or
|
|
|
528 change the location you install programs, or for some reason you don't
|
|
|
529 want it on your computer. It's worth uninstalling just before you
|
|
|
530 install a new version of @cic{} because this will save some disk space;
|
|
|
531 you cannot install two versions of @cic{} at once (at least, not in
|
|
|
532 the same directory; but you can change the --prefix of one of the
|
|
|
533 installations to get two versions at once).
|
|
|
534
|
|
|
535 If you installed @cic{} using @command{make install}, you can
|
|
|
536 uninstall it by using @command{make uninstall} from the installation
|
|
|
537 directory, assuming that it still exists. If you can't use that
|
|
|
538 method for some reason, you can uninstall it by deleting the files
|
|
|
539 @file{ick} and @file{convickt} where your computer installs binaries
|
|
|
540 (with an extension like @samp{.exe} added if that's usual for binaries
|
|
|
541 on your operating system), @file{libick.a}, @file{libickmt.a},
|
|
|
542 @file{libickec.a}, and @file{libyuk.a} where your computer installs
|
|
|
543 libraries, and the subdirectories @file{ick-@value{VERSION}} in the
|
|
|
544 places where your computer installs data files and include files, and
|
|
|
545 their contents.
|
|
|
546
|
|
|
547 You can go further than uninstalling. Running @command{make clean}
|
|
|
548 will delete any files created by compilation; @command{make distclean}
|
|
|
549 will delete those files, and also any files created by configuring.
|
|
|
550 It's probably a wise idea to uninstall before doing a distclean,
|
|
|
551 though, as otherwise information needed to uninstall will be deleted,
|
|
|
552 as that information is generated by @command{configure}.
|
|
|
553
|
|
|
554 @node Reporting Bugs
|
|
|
555 @section Reporting Bugs
|
|
|
556 @cindex bugs, reporting
|
|
|
557 @cindex reporting bugs
|
|
|
558 @cindex patches, submitting
|
|
|
559 @cindex submitting patches
|
|
|
560
|
|
|
561 If you can't get @cic{} to install at all, or something goes wrong when
|
|
|
562 you're using it, reporting a bug is probably a good idea. (This is
|
|
|
563 still important even if you figure out how to fix it, and the
|
|
|
564 information isn't in the manual, because the fix can be added to the
|
|
|
565 source code if possible, or at least to the manual, to benefit future
|
|
|
566 users.) For general help, you may want to post to the
|
|
|
567 @uref{news:alt.lang.intercal,,alt.lang.intercal} news group; to report
|
|
|
568 a bug or submit a patch, email the person who released the most recent
|
|
|
569 @cic{} version (which you can determine by looking at that newsgroup).
|
|
|
570
|
|
|
571 If you do find a bug (either the compiler not behaving in the way you'd
|
|
|
572 expect, or if you find a way to cause E778 (@pxref{E778}) without
|
|
|
573 modifying the source code), it helps a lot if you can submit a bug
|
|
|
574 report explaining what causes it. If you're not sure, say that; it
|
|
|
575 helps if you give examples of input, command line options, etc.@: that
|
|
|
576 cause the bug. There are several debug options (@pxref{Debug Options})
|
|
|
577 that you can use to help pin down a bug if you're interested in trying
|
|
|
578 to solve the problem yourself; looking at the output C code can also
|
|
|
579 help pin down a bug if the compiler gets that far.
|
|
|
580
|
|
|
581 Information that should be given in a bug report is what you expect to
|
|
|
582 happen, what actually happens, what input and command line options you
|
|
|
583 gave to the compiler, what operating system you're using, any ideas you
|
|
|
584 might have as to what the problem is, and any appropriate debug traces
|
|
|
585 (for instance, @option{-H} (@pxref{-H+,,-H}) output if you think the bug
|
|
|
586 is in the optimizer). Core dumps aren't portable between systems, so
|
|
|
587 don't send those; however, if you're getting an internal error and can
|
|
|
588 dump core with @option{-U} (@pxref{-U+,,-U}), it helps if you can load a
|
|
|
589 debugger (such as @command{gdb}) on the core dump, use the debugger to
|
|
|
590 produce a backtrace, and send that backtrace.
|
|
|
591
|
|
|
592 If you figure out how to solve the bug yourself, and want to submit the
|
|
|
593 patches to help other users (this also carries the advantage that your
|
|
|
594 patches will then be maintained along with the rest of the distribution,
|
|
|
595 and that you won't have to reapply them every time you upgrade to a
|
|
|
596 newer version of @cic{}), you must first agree to license your code
|
|
|
597 under the same license as the code that surrounds it (normally, that's
|
|
|
598 the GNU General Public License, but if you submit a patch to a file with
|
|
|
599 a different license, like this manual (yes, documentation patches are
|
|
|
600 useful too), you must agree to that license). You will be credited for
|
|
|
601 the patch in the source code unless you specifically ask not to be or
|
|
|
602 you don't give your name (in both these cases, you must license the code
|
|
|
603 to the public domain so that it can be incorporated without the
|
|
|
604 attribution requirement). Preferably, patches should be submitted in
|
|
|
605 the format created by the command @command{diff -u}; this command is
|
|
|
606 likely to be available on UNIX and Linux systems and versions are also
|
|
|
607 available for DOS and Windows (including a DJGPP port of the GNU
|
|
|
608 version). If you can't manage that, just submit your new code with
|
|
|
609 enough lines of old code around it to show where it's meant to go, and a
|
|
|
610 description of approximately where in the file it was. Patches should
|
|
|
611 be submitted by email to the person who most recently released a version
|
|
|
612 of @cic{}.
|
|
|
613
|
|
|
614 If you have a suggestion for a new feature, it makes sense to first
|
|
|
615 discuss it on the @uref{news:alt.lang.intercal,,alt.lang.intercal} news
|
|
|
616 group; other @ical{} compiler maintainers may also want to implement
|
|
|
617 that feature. If you have developed code to implement that feature in
|
|
|
618 @cic{}, you can submit it the same way that you would submit a patch for
|
|
|
619 a bug.
|
|
|
620
|
|
|
621 @node Distributing
|
|
|
622 @section Distributing
|
|
|
623 @cindex C-INTERCAL, distributing
|
|
|
624 @cindex distributing C-INTERCAL
|
|
|
625 @cindex releasing C-INTERCAL
|
|
|
626
|
|
|
627 Due to the licensing conditions of @cic{}, you are allowed to release
|
|
|
628 your own version or distribution if you want to. In such cases, it's
|
|
|
629 recommended that you follow the following guidelines:
|
|
|
630
|
|
|
631 @enumerate
|
|
|
632
|
|
|
633 @item
|
|
|
634 Make sure the new version is based on the most recent existing version.
|
|
|
635 Looking at the @uref{news:alt.lang.intercal,,alt.lang.intercal}
|
|
|
636 newsgroup will normally let you know what version is most recent.
|
|
|
637
|
|
|
638 @item
|
|
|
639 Increment the version number; if you add any new features, increment the
|
|
|
640 major version number (after the decimal point) and drop the minor version
|
|
|
641 number (before the decimal point) to 0, and otherwise increment the minor
|
|
|
642 version number. You have to update the version number in the following
|
|
|
643 files: @file{configure.ac}, @file{configure}, and @file{doc/ick.txi}. You
|
|
|
644 also have to rename the installation directory to reflect the new version
|
|
|
645 number.
|
|
|
646
|
|
|
647 @item
|
|
|
648 Add an entry to the @file{NEWS} file explaining what's new in the
|
|
|
649 version that you're releasing, following the same format as the other
|
|
|
650 entries.
|
|
|
651
|
|
|
652 @item
|
|
|
653 Update the @file{README} with a description of any new files you may
|
|
|
654 have added.
|
|
|
655
|
|
|
656 @item
|
|
|
657 Remove any autosave or backup files that may be littering the
|
|
|
658 installation directory or its subdirectories.
|
|
|
659
|
|
|
660 @item
|
|
|
661 Run @command{make distcheck}, which will make the distribution
|
|
|
662 paxballs, and rename them to have the correct extensions (Automake
|
|
|
663 thinks they're tarballs, so will use @samp{.tar} rather than
|
|
|
664 @samp{.pax}, and you have to fix this by hand). @command{make
|
|
|
665 distcheck} will also perform some sanity checks on the build system of
|
|
|
666 the resulting paxball, which will help to ensure that nothing
|
|
|
667 important is missing from it.
|
|
|
668
|
|
|
669 @item
|
|
|
670 Place the new version somewhere on the Internet, and announce the
|
|
|
671 location and the fact that a new version has been released on
|
|
|
672 @uref{news:alt.lang.intercal,,alt.lang.intercal}.
|
|
|
673
|
|
|
674 @end enumerate
|
|
|
675
|
|
|
676 @node Invoking ick
|
|
|
677 @chapter Invoking ick
|
|
|
678 @cindex command line options
|
|
|
679 @cindex options, to @command{ick}
|
|
|
680 @cindex @command{ick}, command line options
|
|
|
681 @cindex @command{ick}, invoking
|
|
|
682 @cindex @command{ick}, options
|
|
|
683 @cindex compiling, @ical{} source code
|
|
|
684
|
|
|
685 All operations on @ical{} source code available in @cic{} are currently
|
|
|
686 carried out by the compiler @command{ick}.
|
|
|
687
|
|
|
688 The syntax is
|
|
|
689
|
|
|
690 @example
|
|
|
691 ick -options @var{inputfile}
|
|
|
692 @end example
|
|
|
693
|
|
|
694 @noindent
|
|
|
695 (Options can be given preceded by separate hyphens, or all in a row
|
|
|
696 after one hyphen, or a mixture; they're all single characters.) By
|
|
|
697 default, this compiles one @ical{} program given as the input file
|
|
|
698 directly to an executable without doing anything fancy; usually you will
|
|
|
699 want to give options, which are described below.
|
|
|
700
|
|
|
701 @menu
|
|
|
702 * Language-affecting Options:: Options that specify language dialect
|
|
|
703 * Debug Options:: Debug your code or ick itself
|
|
|
704 * Output Options:: Specifying output format and location
|
|
|
705 * Optimizer Options:: Yes, you can optimize @ical{}!
|
|
|
706 * Other Options:: Options not covered in other sections
|
|
|
707 * Options to Generated Programs:: Generated executables allow options too
|
|
|
708 * Environment Variables:: What environment variables affect ick
|
|
|
709 @end menu
|
|
|
710
|
|
|
711 @node Language-affecting Options
|
|
|
712 @section Language-affecting Options
|
|
|
713 @cindex options, language-affecting
|
|
|
714 @cindex language-affecting options
|
|
|
715 @cindex options, dialect
|
|
|
716 @cindex dialect options
|
|
|
717
|
|
|
718 The following command-line options to @command{ick} affect what dialect
|
|
|
719 of the @ical{} language is compiled by the compiler; you may need to set
|
|
|
720 one or more of these options if your input is not the default @cic{} but
|
|
|
721 instead some other language like @icst{} or @clcic{}, or just because
|
|
|
722 you like certainty or like being different with respect to your output.
|
|
|
723 Note that there is no command-line option corresponding to
|
|
|
724 @abbr{TriINTERCAL} (or the base 4-7 versions); instead, the numeric base
|
|
|
725 to use is determined by looking at the filename extension (@samp{.i} for
|
|
|
726 base 2, the default, or @samp{.3i} to @samp{.7i} for the base 3-7
|
|
|
727 versions.)
|
|
|
728
|
|
|
729 @table @option
|
|
|
730 @ianchor -b
|
|
|
731 @opindex -b
|
|
|
732 @cindex random bug
|
|
|
733 @cindex E774, disabling
|
|
|
734 If this option is @emph{not} given, there is a small chance that a
|
|
|
735 random bug appears in the compiler, which causes the programs it creates
|
|
|
736 to manifest a bug that causes error E774 (@pxref{E774}). Giving the
|
|
|
737 option means that this bug will not happen. (You may wonder why this
|
|
|
738 bug was preserved; it is in fact a bug that was carefully preserved
|
|
|
739 since the days of @icst{}, in this case, but the option to turn it off
|
|
|
740 is available as a workaround. (There are no plans to fix this or any of
|
|
|
741 the other carefully preserved bugs any time soon, because that would
|
|
|
742 kind of defeat the point of having preserved them.) Interestingly, the
|
|
|
743 @icst{} compiler documentation mentions a similar command-line option
|
|
|
744 that is a workaround for the same bug.)
|
|
|
745
|
|
|
746 @ianchor -m
|
|
|
747 @opindex -m
|
|
|
748 @cindex multithreading, enabling
|
|
|
749 @cindex backtracking, enabling
|
|
|
750 This option needs to be given to allow any multithreading or
|
|
|
751 backtracking commands or identifiers to be used. (Unlike with other
|
|
|
752 language features, this is not autodetected because it's legal to have a
|
|
|
753 program with multiple COME FROM (@pxref{COME FROM}) commands aiming at
|
|
|
754 the same line even when it isn't multithreaded, in which case the
|
|
|
755 commands cause error E555 (@pxref{E555}) when that line is encountered
|
|
|
756 (with the usual caveats about both commands having to be active at the
|
|
|
757 time).) Attempts to use non-COME FROM multithreading or backtracking
|
|
|
758 commands without this option produce error E405 (@pxref{E405}).
|
|
|
759
|
|
|
760 @ianchor -e
|
|
|
761 @opindex -e
|
|
|
762 @cindex external calls, enabling
|
|
|
763 This option makes it possible to link non-@ical{} programs with
|
|
|
764 @ical{} programs; instead of giving @ical{} programs only on the
|
|
|
765 command line, give one @ical{} program, followed by any number of
|
|
|
766 programs in other languages that have been written to be able to link
|
|
|
767 to @ical{} programs. It also allows expansion libraries to be
|
|
|
768 specified on the command line, after the @ical{} program (expansion
|
|
|
769 libraries are given with no extension). For more information, see
|
|
|
770 @ref{External Calls}. Also, both the @option{-a} and @option{-e}
|
|
|
771 options must be set to use CREATEd operators (regardless of whether
|
|
|
772 external calls are used or not).
|
|
|
773
|
|
|
774 @ianchorc -E
|
|
|
775 @opindex -E
|
|
|
776 @cindex system library, disabling
|
|
|
777 This option causes the system library to never be linked; this option
|
|
|
778 is only useful if your program references a line number in the range
|
|
|
779 1000 to 1999, contains no line numbers in that range, and yet still
|
|
|
780 doesn't want the system library to be linked in; therefore, it is
|
|
|
781 mostly useful with @option{-e} when adding in a custom replacement
|
|
|
782 system library written in a non-@ical{} language, especially the
|
|
|
783 expansion library @option{syslibc} (a system library replacement
|
|
|
784 written in C).
|
|
|
785
|
|
|
786 @ianchor -t
|
|
|
787 @opindex -t
|
|
|
788 @cindex INTERCAL-72 compatibility mode
|
|
|
789 @cindex compatibility, INTERCAL-72
|
|
|
790 This option tells the compiler to treat the source code as @icst{}; as a
|
|
|
791 result, any language constructs that are used but weren't available in
|
|
|
792 1972 will trigger error E111 (@pxref{E111}).
|
|
|
793
|
|
|
794 @ianchor -a
|
|
|
795 @opindex -a
|
|
|
796 @cindex CREATE, enabling
|
|
|
797 This option allows the CREATE statement (@pxref{CREATE}) to be used.
|
|
|
798 Note that enabling it carries a run-time penalty, as it means that
|
|
|
799 operand overloading code has to be generated for every variable in the
|
|
|
800 program. (This option is not necessarily needed for the external call
|
|
|
801 version of CREATE to work, but the external call version has fewer
|
|
|
802 features without it.) Note that @option{-e} (@pxref{-e}) also needs
|
|
|
803 to be set to be able to CREATE operators.
|
|
|
804
|
|
|
805 @ianchor -v
|
|
|
806 @opindex -v
|
|
|
807 @cindex constants, assigning to
|
|
|
808 @cindex assigning to constants
|
|
|
809 It is possible to write @ical{} code sufficiently tortuous that it ends
|
|
|
810 up assigning to a constant. Generally speaking, this isn't what you
|
|
|
811 wanted to do, so the compiler will kindly cause an error (E277;
|
|
|
812 @pxref{E277}) that stops the insanity at that point, but at the cost of a
|
|
|
813 significant amount of performance you can give this option to tell the
|
|
|
814 compiler to simply change the constant and keep on going anyway. (Note
|
|
|
815 that unlike @clcic{}, this only changes uses of the constant preceded by
|
|
|
816 @code{#} in your program, not things like line numbers; you want
|
|
|
817 @uref{http://esolangs.org/wiki/Forte,Forte} for that.) This option also
|
|
|
818 allows you to write arbitary expressions on the left of an assignment
|
|
|
819 statement if you wish.
|
|
|
820
|
|
|
821 @ianchorc -C
|
|
|
822 @opindex -C
|
|
|
823 @cindex clockface mode
|
|
|
824 When this option is given, the generated programs will write the number
|
|
|
825 4 as @samp{IIII} rather than @samp{IV}, in case you're writing a clock
|
|
|
826 program.
|
|
|
827
|
|
|
828 @ianchorc -P
|
|
|
829 @opindex -P
|
|
|
830 @cindex PIC-INTERCAL, command line option
|
|
|
831 @cindex E256, avoiding
|
|
|
832 @cindex E652, avoiding
|
|
|
833 This tells the compiler to treat the input as @abbr{PIC-INTERCAL}
|
|
|
834 (@pxref{PIC-INTERCAL}) rather than ordinary @cic{} input, and generate
|
|
|
835 PIC output code accordingly. There are a lot of options that are
|
|
|
836 incompatible with this, as well as many language features, due to the
|
|
|
837 limited memory available on a PIC. If you get error E256
|
|
|
838 (@pxref{E256}), you have this option given when it shouldn't be;
|
|
|
839 likewise, if you get error E652 (@pxref{E652}), you should be using this
|
|
|
840 option but aren't. (A few simple programs are
|
|
|
841 @cic{}/@abbr{PIC-INTERCAL} polyglots, but such programs are incapable of
|
|
|
842 doing input or output, meaning that they aren't particularly useful.)
|
|
|
843
|
|
|
844 @ianchorc -X
|
|
|
845 @opindex -X
|
|
|
846 @cindex Princeton syntax, option
|
|
|
847 @cindex syntax, Princeton
|
|
|
848 The @cic{} and @clcic{} compilers use different notation for various
|
|
|
849 things, sometimes to the extent where the same notation is legal in both
|
|
|
850 cases but has a different meaning. As this is the @cic{} compiler, it
|
|
|
851 rather guessably uses its own notation by default; however, the @clcic{}
|
|
|
852 notation can be used as the default instead using this option. (In most
|
|
|
853 situations where there isn't an ambiguity about what something means,
|
|
|
854 you can use the `wrong' syntax freely.) The option causes ambiguous
|
|
|
855 characters like @code{?} to be interpreted with Princeton rather than
|
|
|
856 Atari meanings.
|
|
|
857
|
|
|
858 @ianchor -x
|
|
|
859 @opindex -x
|
|
|
860 @cindex CLC-INTERCAL compatibility mode
|
|
|
861 @cindex compatibility, CLC-INTERCAL
|
|
|
862 This option causes some constructs with different meanings in @cic{}
|
|
|
863 and @clcic{} to use the @clcic{} meaning rather than the @cic{}
|
|
|
864 meaning. At present, it affects the abstention of a GIVE UP
|
|
|
865 (@pxref{GIVE UP}) command by line number, which is possible as long as
|
|
|
866 this switch isn't given; reading through the @icst{} manual, there are
|
|
|
867 a lot of things that imply that this probably wasn't intended to be
|
|
|
868 possible, but as far as I can tell that manual doesn't actually
|
|
|
869 @emph{say} anywhere that this particular case is disallowed, even
|
|
|
870 though it rules out all other similar cases. It also causes I/O on
|
|
|
871 array variables to be done in @clcic{}'s extended Baudot syntax,
|
|
|
872 rather than using the Turing Tape method.
|
|
|
873
|
|
|
874 @end table
|
|
|
875
|
|
|
876 @node Debug Options
|
|
|
877 @section Debug Options
|
|
|
878 @cindex options, debug
|
|
|
879 @cindex debug options
|
|
|
880
|
|
|
881 Sometimes things will go wrong with your program, or with the way
|
|
|
882 @command{ick} was installed. There may even be unknown bugs in
|
|
|
883 @command{ick} itself (if you find one of these, please report it). The
|
|
|
884 following options are used to debug the whole system on various levels.
|
|
|
885
|
|
|
886 @table @option
|
|
|
887
|
|
|
888 @ianchor -d
|
|
|
889 @opindex -d
|
|
|
890 @cindex debugging, parser
|
|
|
891 @cindex parser, debugging
|
|
|
892 @cindex debugging, lexical analyser
|
|
|
893 @cindex lexical analyser, debugging
|
|
|
894
|
|
|
895 If you think that something has gone wrong with the parser, or you want
|
|
|
896 to see how your program is being parsed, you can give this option on the
|
|
|
897 command line. All the debug output produced by the parser and lexical
|
|
|
898 analyser will be output.
|
|
|
899
|
|
|
900 @ianchor -g
|
|
|
901 @opindex -g
|
|
|
902 @cindex debugging, C code
|
|
|
903 @cindex C code, debugging
|
|
|
904 @cindex C code, leaving in place
|
|
|
905
|
|
|
906 This option allows debugging of the final executable at the C code
|
|
|
907 level. Any C code generated will be left in place, and the @option{-g}
|
|
|
908 option will be given to the C compiler that's used to compile the code,
|
|
|
909 so all the information needed for a C debugger to be used on the
|
|
|
910 executable will be present there.
|
|
|
911
|
|
|
912 @item -h
|
|
|
913 @itemx -H
|
|
|
914 @itemx -hH
|
|
|
915 @anchor{-h}
|
|
|
916 @anchor{-H+}
|
|
|
917 @anchor{-hH}
|
|
|
918 @opindex -h
|
|
|
919 @opindex -H
|
|
|
920 @opindex -hH
|
|
|
921 @cindex optimizer, debugging
|
|
|
922 @cindex debugging, optimizer
|
|
|
923 @cindex OIL, debugging
|
|
|
924 @cindex debugging, OIL
|
|
|
925
|
|
|
926 These options allow debugging of the optimiser, or produce output
|
|
|
927 helpful for understanding how your program has been summarised.
|
|
|
928 @option{-h} produces a summary of what optimiser rules were used, the
|
|
|
929 initial expression and what it was optimised to; @option{-H} produces a
|
|
|
930 more expanded view that shows each intermediate step of optimisation,
|
|
|
931 and @option{-hH} shows the same output as @option{-H}, but written
|
|
|
932 completely using C syntax (the other options output in a strange mix of
|
|
|
933 @ical{} and C).
|
|
|
934
|
|
|
935 @ianchor -l
|
|
|
936 @opindex -l
|
|
|
937 @cindex warnings, enabling
|
|
|
938
|
|
|
939 This option turns on generation of warnings (@pxref{Warnings}). To make
|
|
|
940 sure that they aren't actually useful, or are only marginally useful,
|
|
|
941 the warning generator is far too sensitive, and there is no way to
|
|
|
942 decide which warnings are given and which ones aren't; you either get
|
|
|
943 all of them or none.
|
|
|
944
|
|
|
945 @ianchor -p
|
|
|
946 @opindex -p
|
|
|
947 @cindex profiling
|
|
|
948 @cindex yuk, profiling
|
|
|
949
|
|
|
950 This option causes the program to run immediately after being compiled,
|
|
|
951 and profiles the resulting program to identify performance bottlenecks,
|
|
|
952 etc. The usefulness of this depends on the resolution of the timers on
|
|
|
953 the computer and operating system; DOS, in particular, is really bad
|
|
|
954 with timer resolution. The output will be saved in a file called
|
|
|
955 @file{yuk.out} when the program finishes running. It's legal to turn on
|
|
|
956 both the profiler and the interactive debugger at the same time, but if
|
|
|
957 you do this the profiler will also identify bottlenecks in the person
|
|
|
958 typing in commands to step through the program! The profiler will, in
|
|
|
959 fact, identify all the timings that particular commands in the program
|
|
|
960 take; so @code{WRITE IN} instructions will often show up as taking a
|
|
|
961 long time due to their need to wait for input.
|
|
|
962
|
|
|
963 @ianchor -w
|
|
|
964 @opindex -w
|
|
|
965 @cindex +printflow, enabling
|
|
|
966 @cindex printflow, enabling
|
|
|
967
|
|
|
968 This option causes the produced program to support the
|
|
|
969 @option{printflow} option fully; when this option is not given,
|
|
|
970 @option{printflow} will in most cases have partial or no support
|
|
|
971 (except in multithreaded programs, where this option is redundant),
|
|
|
972 because not all the code needed for it will be included in the program
|
|
|
973 to save space.
|
|
|
974
|
|
|
975 @ianchor -u
|
|
|
976 @opindex -u
|
|
|
977 @cindex skeleton file, directory problems
|
|
|
978 @cindex system library, directory problems
|
|
|
979 @cindex syslib, directory problems
|
|
|
980 @cindex directory problems
|
|
|
981 @cindex E999, debugging
|
|
|
982 @cindex E127, debugging
|
|
|
983
|
|
|
984 When you are getting problems with finding files -- for instance, the
|
|
|
985 compiler can't find the skeleton file (@pxref{E999}) or the system
|
|
|
986 library (@pxref{E127}) -- this option will let you know, on standard
|
|
|
987 error, where the compiler is looking for files. This may hopefully help
|
|
|
988 you pin down where the file-finding problems are coming from, and also
|
|
|
989 offers the option of simply placing copies of the files where the
|
|
|
990 compiler is looking as a last resort.
|
|
|
991
|
|
|
992 @ianchor -y
|
|
|
993 @opindex -y
|
|
|
994 @cindex yuk, command line option
|
|
|
995
|
|
|
996 This is the main debugging option: it loads yuk, an interactive @ical{}
|
|
|
997 debugger with ability to step through the program, set breakpoints, view
|
|
|
998 and modify variables, etc. @xref{yuk}.
|
|
|
999
|
|
|
1000 @ianchorc -Y
|
|
|
1001 @opindex -Y
|
|
|
1002 @cindex external calls, debugging
|
|
|
1003 @cindex command line, showing intermediates
|
|
|
1004
|
|
|
1005 This options causes the command line to be displayed for all calls to
|
|
|
1006 other programs that @command{ick} makes (mostly to @command{gcc}); it
|
|
|
1007 is therefore useful for debugging problems with the command lines used
|
|
|
1008 when using the external calls system (@pxref{External Calls}).
|
|
|
1009
|
|
|
1010 @ianchorc -U
|
|
|
1011 @opindex -U
|
|
|
1012 @cindex internal errors, debugging
|
|
|
1013 @cindex debugging, internal errors
|
|
|
1014 @cindex internal errors, dumping core
|
|
|
1015 @cindex dumping core on error
|
|
|
1016 @cindex E778, debugging
|
|
|
1017
|
|
|
1018 The internal error E778 (@pxref{E778}) should never happen. However,
|
|
|
1019 there are all sorts of potential problems that may come up, and if part
|
|
|
1020 of the code detects something impossible, or more usually when the
|
|
|
1021 operating system detects things have got too insane and segfaults,
|
|
|
1022 normally this error will just be generated and that's that. (I most
|
|
|
1023 often get this when I've been writing a new section of code and have
|
|
|
1024 made a mistake; hopefully, all or at least most of these errors are
|
|
|
1025 fixed before release, though.) If you want more information as to what's
|
|
|
1026 going on, you can give the @option{-U} option, which will cause the
|
|
|
1027 compiler to raise an abort signal when an internal error happens. This
|
|
|
1028 can generally be caught by a debugger that's being run on @command{ick}
|
|
|
1029 itself at the time; on many systems, it will also cause a core dump.
|
|
|
1030
|
|
|
1031 @end table
|
|
|
1032
|
|
|
1033 @node Output Options
|
|
|
1034 @section Output Options
|
|
|
1035 @cindex output options
|
|
|
1036 @cindex options, output
|
|
|
1037
|
|
|
1038 These options allow you to control how far to compile (all the way to an
|
|
|
1039 executable, or only to C, etc.@:), and where the output will be created.
|
|
|
1040 Note that the output options may change depending on the other options
|
|
|
1041 selected; for instance, many of the debug options will prevent the code
|
|
|
1042 being compiled all the way to an executable.
|
|
|
1043
|
|
|
1044 @table @option
|
|
|
1045
|
|
|
1046 @ianchor -c
|
|
|
1047 @opindex -c
|
|
|
1048 @cindex code generation, stopping at C code
|
|
|
1049 @cindex C, stopping after C is generated
|
|
|
1050 @cindex output, C only
|
|
|
1051
|
|
|
1052 By default, the original @ical{} code will be compiled all the way to an
|
|
|
1053 executable, and the intermediate C and object files produced will be
|
|
|
1054 deleted. Giving this option causes the compiler to stop when it has
|
|
|
1055 finished producing the C file, leaving the C file there as the final
|
|
|
1056 output of the compiler. (Its filename is the same as the source file,
|
|
|
1057 but with @samp{.c} as its extension/suffix rather than the source file's
|
|
|
1058 extension.) Without this option, an executable will be produced with the
|
|
|
1059 extension changed to whatever's appropriate for the system you are on
|
|
|
1060 (or omitted entirely if that's appropriate for the system).
|
|
|
1061
|
|
|
1062 This option also places verbose comments in the output C file.
|
|
|
1063
|
|
|
1064 @ianchor -o
|
|
|
1065 @opindex -o
|
|
|
1066 @cindex output, to standard output
|
|
|
1067 @cindex standard output
|
|
|
1068
|
|
|
1069 This option causes the compiler to progress no further than producing
|
|
|
1070 the C output file, but instead of writing it to a file writes it
|
|
|
1071 directly to standard output. This might occasionally be useful when
|
|
|
1072 using @command{ick} as part of a pipe; it can also be useful to see how
|
|
|
1073 far the compiler gets with compiling code before an error happens, when
|
|
|
1074 you're trying to track down an error.
|
|
|
1075
|
|
|
1076 @end table
|
|
|
1077
|
|
|
1078 @node Optimizer Options
|
|
|
1079 @section Optimizer Options
|
|
|
1080 @cindex optimizer options
|
|
|
1081 @cindex options, optimizer
|
|
|
1082 @cindex optimization
|
|
|
1083
|
|
|
1084 There are various command line options that can be used to tell
|
|
|
1085 @command{ick} whether and in what ways to optimize code.
|
|
|
1086
|
|
|
1087 @table @option
|
|
|
1088
|
|
|
1089 @ianchor -f
|
|
|
1090 @opindex -f
|
|
|
1091 @cindex flow optimization
|
|
|
1092 @cindex optimization, flow
|
|
|
1093 @cindex optimization, control flow
|
|
|
1094
|
|
|
1095 This option requests the compiler to attempt to analyse the flow of the
|
|
|
1096 program and optimize accordingly; for instance, it will detect which
|
|
|
1097 commands can't possibly be @code{ABSTAINED} from and refrain from
|
|
|
1098 generating code to check the abstention status of those commands.
|
|
|
1099
|
|
|
1100 @ianchorc -F
|
|
|
1101 @opindex -F
|
|
|
1102 @cindex optimization, extreme
|
|
|
1103 @cindex extreme optimization
|
|
|
1104
|
|
|
1105 This option tells the compiler to optimize the output for speed. This
|
|
|
1106 is done to crazy extremes; the compiler may take several hours/days
|
|
|
1107 analysing the program in some cases and still not come up with an
|
|
|
1108 improvement. It turns on all the other optimizer options. Note that
|
|
|
1109 not all systems accept this option, because it sometimes outputs a shell
|
|
|
1110 script disguised as an executable rather than an actual executable.
|
|
|
1111
|
|
|
1112 @ianchorc -O
|
|
|
1113 @opindex -O
|
|
|
1114 @cindex optimization, idioms
|
|
|
1115 @cindex idiom optimization
|
|
|
1116 @cindex optimization, OIL
|
|
|
1117 @cindex OIL, optimizing code
|
|
|
1118
|
|
|
1119 This option tells the compiler to apply optimizer idioms to the
|
|
|
1120 expressions in the code given, when appropriate. The list of idioms is
|
|
|
1121 stored in the file @file{src/idiotism.oil}; note that it is compiled
|
|
|
1122 into the compiler, though, so you will have to rebuild and reinstall the
|
|
|
1123 compiler if you change it. For more information about changing the list
|
|
|
1124 of idioms, see @ref{Optimizer Idiom Language}.
|
|
|
1125
|
|
|
1126 @end table
|
|
|
1127
|
|
|
1128 @node Other Options
|
|
|
1129 @section Other Options
|
|
|
1130 @cindex other options
|
|
|
1131 @cindex options, other
|
|
|
1132
|
|
|
1133 Some options just can't be classified.
|
|
|
1134
|
|
|
1135 @table @option
|
|
|
1136
|
|
|
1137 @item -@@
|
|
|
1138 @anchor{-at}
|
|
|
1139 @opindex -@@
|
|
|
1140 @cindex options, help
|
|
|
1141 @cindex help with options
|
|
|
1142 @cindex usage instructions, printing
|
|
|
1143
|
|
|
1144 If this option is given, the compiler doesn't run at all, but instead
|
|
|
1145 prints a set of instructions for using it, explaining which options are
|
|
|
1146 available on the system you're on and which options conflict with which
|
|
|
1147 other options.
|
|
|
1148
|
|
|
1149 @end table
|
|
|
1150
|
|
|
1151 @node Options to Generated Programs
|
|
|
1152 @section Options to Generated Programs
|
|
|
1153 @cindex generated programs, options
|
|
|
1154 @cindex options, to generated programs
|
|
|
1155
|
|
|
1156 Once the compiler runs and produces an output executable, that
|
|
|
1157 executable itself will accept a range of options that control the way it
|
|
|
1158 runs. None of these options have to be used; a default value will be
|
|
|
1159 assumed if they aren't.
|
|
|
1160
|
|
|
1161 @table @option
|
|
|
1162
|
|
|
1163 @ianchorpm help
|
|
|
1164 @opindex +help
|
|
|
1165 @opindex -help
|
|
|
1166
|
|
|
1167 Whether @samp{+} or @samp{-} is given at the start of this option, it
|
|
|
1168 will cause the program to print out what options are available and what
|
|
|
1169 state they are in. It will then cause the program to exit via an
|
|
|
1170 internal error.
|
|
|
1171
|
|
|
1172 @ianchorpm wimpmode
|
|
|
1173 @opindex +wimpmode
|
|
|
1174 @opindex -wimpmode
|
|
|
1175 @cindex wimpmode
|
|
|
1176 @cindex Roman numerals, disabling
|
|
|
1177 @cindex Arabic numberals, enabling
|
|
|
1178 @cindex input, in Arabic numerals
|
|
|
1179 @cindex output, in Arabic numerals
|
|
|
1180
|
|
|
1181 If the @samp{+} version of this is given (rather than the default
|
|
|
1182 @samp{-}), then the program will print a message explaining that you are
|
|
|
1183 a wimp (the mode itself is known as wimpmode), and for the rest of
|
|
|
1184 execution will input in Arabic numerals (@samp{123} rather than
|
|
|
1185 @samp{ONE TWO THREE}) and likewise will output in Arabic numerals rather
|
|
|
1186 than Roman numerals (such as @samp{CXXIII}). True @ical{} programmers
|
|
|
1187 should rarely have to use this mode.
|
|
|
1188
|
|
|
1189 @ianchorpm traditional
|
|
|
1190 @opindex +traditional
|
|
|
1191 @opindex -traditional
|
|
|
1192
|
|
|
1193 This option does not actually appear to do anything.
|
|
|
1194
|
|
|
1195 @ianchorpm instapipe
|
|
|
1196 @opindex +instapipe
|
|
|
1197 @opindex -instapipe
|
|
|
1198 @cindex output, flushing
|
|
|
1199 @cindex flushing
|
|
|
1200
|
|
|
1201 This option causes standard output to be flushed whenever any characters
|
|
|
1202 are output when the @samp{+} version is used, rather than on each newline
|
|
|
1203 (the default @samp{-} version). It is most useful for more responsive
|
|
|
1204 pipes when outputting binary data, and also useful for debugging very
|
|
|
1205 slow programs.
|
|
|
1206
|
|
|
1207 @ianchorpm printflow
|
|
|
1208 @opindex +printflow
|
|
|
1209 @opindex -printflow
|
|
|
1210 @cindex flow, printing
|
|
|
1211 @cindex debugging, flow
|
|
|
1212 @cindex debugging, multithreaded programs
|
|
|
1213 @cindex multithreading, debugging
|
|
|
1214 @cindex backtracking, debugging
|
|
|
1215
|
|
|
1216 The usual debugging methods don't work with multithreaded or
|
|
|
1217 backtracking programs. This option exists to give at least a slim
|
|
|
1218 chance of working out what is going on with them. It causes the
|
|
|
1219 program to print the line number of the command it thinks it may be
|
|
|
1220 executing next (i.e.@: the line number that would be printed if that
|
|
|
1221 line had an error) immediately after executing each command, and also
|
|
|
1222 an internal identifier for the thread that that command was in. It
|
|
|
1223 also prints a trace of what parts of the multithreader are being
|
|
|
1224 activated; so for instance, it will tell you when a thread is being
|
|
|
1225 forked into multiple threads or when a choicepoint has been deleted.
|
|
|
1226 Note that the @option{-w} option (@pxref{-w}) must be given to gain
|
|
|
1227 full support for flow printing in non-multithreaded non-backtracking
|
|
|
1228 programs, because otherwise the required code to print this
|
|
|
1229 information will not be generated.
|
|
|
1230
|
|
|
1231 @ianchorpm mystery
|
|
|
1232 @opindex +mystery
|
|
|
1233 @opindex -mystery
|
|
|
1234
|
|
|
1235 This option is occasionally capable of doing something, but is
|
|
|
1236 deliberately undocumented. Normally changing it will have no effect,
|
|
|
1237 but changing it is not recommended.
|
|
|
1238
|
|
|
1239 @end table
|
|
|
1240
|
|
|
1241 @node Environment Variables
|
|
|
1242 @section Environment Variables
|
|
|
1243 @cindex environment variables
|
|
|
1244
|
|
|
1245 Various environment variables can be set to affect the operation of
|
|
|
1246 @command{ick}.
|
|
|
1247
|
|
|
1248 @multitable @columnfractions .3 .7
|
|
|
1249 @headitem Variable @tab Meaning
|
|
|
1250 @item ICKINCLUDEDIR@*ICKLIBDIR@*ICKDATADIR
|
|
|
1251 @tab
|
|
|
1252 These three environment variables suggest locations in which
|
|
|
1253 @command{ick} should look to find various files that it needs: the
|
|
|
1254 skeleton file, system library, C header files and libraries that it
|
|
|
1255 needs, constant-output optimiser, and the GNU General Public License
|
|
|
1256 (which the debugger needs to be able to display on demand for legal
|
|
|
1257 reasons).
|
|
|
1258 @item CC
|
|
|
1259 @tab
|
|
|
1260 The name of a C compiler to use (defaults to gcc, which is the only
|
|
|
1261 compiler with which @cic{} has been tested recently). This option has
|
|
|
1262 no effect on DJGPP, where gcc is always used.
|
|
|
1263 @item ICKTEMP@*TMPDIR@*TEMP@*TMP
|
|
|
1264 @tab
|
|
|
1265 On DJGPP, @command{ick} creates temporary files to pass options to gcc
|
|
|
1266 as a method of getting around the limit on the length of a command line
|
|
|
1267 that can sometimes affect DOS programs. These four environment
|
|
|
1268 variables are tried (in this order) to determine a location for the
|
|
|
1269 temporary file; if none of them are set, the current directory is used.
|
|
|
1270 @end multitable
|
|
|
1271
|
|
|
1272 @node Errors and Warnings
|
|
|
1273 @chapter Errors and Warnings
|
|
|
1274 @cindex @command{ick}, errors and warnings
|
|
|
1275 @cindex errors and warnings
|
|
|
1276
|
|
|
1277 Things may go wrong, either during the compilation or the execution of
|
|
|
1278 your program. Note that some things that would be compile-time errors
|
|
|
1279 in many other languages -- such as syntax errors -- are in fact run-time
|
|
|
1280 errors in @ical{}.
|
|
|
1281
|
|
|
1282 Errors and warnings appear as an error code starting with @samp{ICL},
|
|
|
1283 followed by a three digit number, followed by @samp{I} for an error or
|
|
|
1284 @samp{W} for a warning. However, they will be notated here as
|
|
|
1285 @samp{E000}, etc.@:, to save space and because consistency was never a
|
|
|
1286 strong point of @ical{}. This is followed by a text description of the
|
|
|
1287 error, and a hint as to the location of the error. This is not the line
|
|
|
1288 on which the error occurred, but rather the line on which the next
|
|
|
1289 command to be executed is. To add to the fun, the calculation of the
|
|
|
1290 next command to be executed is done at compile-time rather than runtime,
|
|
|
1291 so it may be completely wrong due to things like abstention on
|
|
|
1292 @code{COME FROM}s or computed @code{COME FROM}s. The moral of this
|
|
|
1293 story is that, if you really want to know where the error is, use a
|
|
|
1294 debugger. Note also that if the error happens at compile-time, there is
|
|
|
1295 no guarantee that the line number given makes any sense at all. Some
|
|
|
1296 errors don't give next line numbers, mostly those for which it doesn't
|
|
|
1297 make logical sense, such as E633 (@pxref{E633}). After this is a
|
|
|
1298 suggestion to correct (or reconsider) the source code and to resubnit
|
|
|
1299 it. (This typo has been carefully preserved for over a decade.)
|
|
|
1300
|
|
|
1301 @menu
|
|
|
1302 * Errors:: Error messages that might be produced
|
|
|
1303 * Warnings:: Warnings produced by the @option{-l} option
|
|
|
1304 @end menu
|
|
|
1305
|
|
|
1306 @node Errors
|
|
|
1307 @section Errors
|
|
|
1308 @cindex errors
|
|
|
1309 @cindex @command{ick}, errors
|
|
|
1310
|
|
|
1311 This is a list of the error messages that might be produced during the
|
|
|
1312 compilation or execution of an @ical{} program.
|
|
|
1313
|
|
|
1314 @table @asis
|
|
|
1315
|
|
|
1316 @ieanchor E000
|
|
|
1317 @cindex syntax error
|
|
|
1318
|
|
|
1319 This is an unusual error; it's what's printed when a syntax error is
|
|
|
1320 encounted at runtime, in a situation in which it would be executed. (An
|
|
|
1321 @code{ABSTAIN}ed syntax error, for instance, would not be executed; this
|
|
|
1322 is one of the mechanisms available for writing comments.) The text of
|
|
|
1323 the error message is simply the statement that couldn't be decoded.
|
|
|
1324
|
|
|
1325 @ieanchor E017
|
|
|
1326 @cindex constant, twospot
|
|
|
1327 @cindex overflow, in constant
|
|
|
1328 @quotation
|
|
|
1329 DO YOU EXPECT ME TO FIGURE THIS OUT?
|
|
|
1330 @end quotation
|
|
|
1331
|
|
|
1332 This error occurs when there is an attempt to use a constant with a
|
|
|
1333 value outside the onespot range; it's a compile-time error.
|
|
|
1334
|
|
|
1335 @ieanchor E079
|
|
|
1336 @cindex politesse
|
|
|
1337 @cindex @code{PLEASE}, proportion required
|
|
|
1338 @quotation
|
|
|
1339 PROGRAMMER IS INSUFFICIENTLY POLITE
|
|
|
1340 @end quotation
|
|
|
1341
|
|
|
1342 The balance between various statement identifiers is important. If less
|
|
|
1343 than approximately one fifth of the statement identifiers used are the
|
|
|
1344 polite versions containing @code{PLEASE}, that causes this error at
|
|
|
1345 compile time.
|
|
|
1346
|
|
|
1347 @ieanchor E099
|
|
|
1348 @quotation
|
|
|
1349 PROGRAMMER IS OVERLY POLITE
|
|
|
1350 @end quotation
|
|
|
1351
|
|
|
1352 Of course, the same problem can happen in the other direction; this
|
|
|
1353 error is caused at compile time if over about one third of the statement
|
|
|
1354 identifiers are the polite form.
|
|
|
1355
|
|
|
1356 @ieanchor E111
|
|
|
1357 @quotation
|
|
|
1358 COMMUNIST PLOT DETECTED, COMPILER IS SUICIDING
|
|
|
1359 @end quotation
|
|
|
1360
|
|
|
1361 This error happens when you give the @option{-t} option (@pxref{-t}) but
|
|
|
1362 you use a language construct that wasn't available in @icst{}. If this
|
|
|
1363 happens, then either there's a mistake in the program that prevents it
|
|
|
1364 being @icst{} or you shouldn't be compiling it as @icst{} in the first
|
|
|
1365 place.
|
|
|
1366
|
|
|
1367 @ieanchor E123
|
|
|
1368 @cindex black lagoon
|
|
|
1369 @cindex @code{NEXT}, stack overflow
|
|
|
1370 @cindex stack overflow
|
|
|
1371 @quotation
|
|
|
1372 PROGRAM HAS DISAPPEARED INTO THE BLACK LAGOON
|
|
|
1373 @end quotation
|
|
|
1374
|
|
|
1375 There is a hard limit of 80 @command{NEXT}s at a time; this is to
|
|
|
1376 discourage excessive use of @command{NEXTING} for things like recursion.
|
|
|
1377 (Recursive programs are entirely legal; you simply have to figure out
|
|
|
1378 how to do it with computed @command{COME FROM} instead. (For the
|
|
|
1379 record, it is possible. (Using lots of nested brackets when talking
|
|
|
1380 about recursion is great (yay!@:).))) Another problem with writing the
|
|
|
1381 source code that can cause this error is a failure to properly
|
|
|
1382 @command{FORGET} the entry on the @command{NEXT} stack created when
|
|
|
1383 trying to simulate a goto.
|
|
|
1384
|
|
|
1385 @ieanchor E127
|
|
|
1386 @cindex system library, errors
|
|
|
1387 @cindex syslib, errors
|
|
|
1388 @quotation
|
|
|
1389 SAYING 'ABRACADABRA' WITHOUT A MAGIC WAND WON'T DO YOU ANY GOOD
|
|
|
1390 @end quotation
|
|
|
1391 Your program asked to include the system library (by specifying a line
|
|
|
1392 number from 1000 to 1999 inclusive without including a line with that
|
|
|
1393 number), but due to installation problems the compiler couldn't find the
|
|
|
1394 system library to include. You could try using the @option{-u}
|
|
|
1395 (@pxref{-u}) option to see where the compiler's looking; that may give
|
|
|
1396 you an idea of where you need to copy the system library so that the
|
|
|
1397 compilation will work. This error happens at compile time and doesn't
|
|
|
1398 give a next command line number.
|
|
|
1399
|
|
|
1400 @ieanchor E129
|
|
|
1401 @cindex @code{NEXT}, nonexistent target
|
|
|
1402 @quotation
|
|
|
1403 PROGRAM HAS GOTTEN LOST
|
|
|
1404 @end quotation
|
|
|
1405
|
|
|
1406 This error happens at compile time when the compiler can't figure out
|
|
|
1407 where a @code{NEXT} command is actually aiming (normally due to a typo
|
|
|
1408 in either the line label given or the line label on the line aimed
|
|
|
1409 for). The logic behind this error means that the next line to be
|
|
|
1410 executed is unknown (after all, that's the whole point of the error)
|
|
|
1411 and is therefore not given. The @option{-e} command-line option
|
|
|
1412 (@pxref{-e}) makes this error into a run-time error, because it allows
|
|
|
1413 @code{NEXT} commands to dynamically change targets at runtime, as well
|
|
|
1414 as line labels to dynamically change values, and thus the error is
|
|
|
1415 impossible to detect at compile time.
|
|
|
1416
|
|
|
1417 @ieanchor E139
|
|
|
1418 @cindex @code{ABSTAIN}, nonexistent target
|
|
|
1419 @cindex @code{REINTSTATE}, nonexistent target
|
|
|
1420 @quotation
|
|
|
1421 I WASN'T PLANNING TO GO THERE ANYWAY
|
|
|
1422 @end quotation
|
|
|
1423
|
|
|
1424 This error happens at compile time when an @code{ABSTAIN} or
|
|
|
1425 @code{REINSTATE} references a non-existent target line. This generally
|
|
|
1426 happens for much the same reasons as E129 (@pxref{E129}).
|
|
|
1427
|
|
|
1428 @ieanchor E182
|
|
|
1429 @cindex line label, duplicate
|
|
|
1430 @cindex duplicate line label
|
|
|
1431 @quotation
|
|
|
1432 YOU MUST LIKE THIS LABEL A LOT!
|
|
|
1433 @end quotation
|
|
|
1434
|
|
|
1435 At present, it's impossible to have more than one line with the same
|
|
|
1436 line number. That would make @code{NEXT} act too much like @code{COME
|
|
|
1437 FROM} in reverse to be interesting. This error happens at compile
|
|
|
1438 time. (For inconsistency, it @i{is} possible to have multiple lines
|
|
|
1439 with the same number as long as at most one of them is in an @ical{}
|
|
|
1440 program (the others have to be in programs in other languages included
|
|
|
1441 via the external calls system).)
|
|
|
1442
|
|
|
1443 @ieanchor E197
|
|
|
1444 @cindex line label, illegal value
|
|
|
1445 @cindex illegal line label value
|
|
|
1446 @cindex invalid line label value
|
|
|
1447 @quotation
|
|
|
1448 SO@! 65535 LABELS AREN'T ENOUGH FOR YOU?
|
|
|
1449 @end quotation
|
|
|
1450
|
|
|
1451 Legal values for line labels are 1 to 65535 (with values from 1000 to
|
|
|
1452 1999 reserved if you want to use the system library, and 1600 to 1699
|
|
|
1453 reserved if you're using other expansion libraries). This error comes
|
|
|
1454 up if you use nonpositive or twospot values for a line label.
|
|
|
1455
|
|
|
1456 @ieanchor E200
|
|
|
1457 @cindex variable, illegal number
|
|
|
1458 @cindex illegal variable number
|
|
|
1459 @cindex invalid variable number
|
|
|
1460 @quotation
|
|
|
1461 NOTHING VENTURED, NOTHING GAINED
|
|
|
1462 @end quotation
|
|
|
1463
|
|
|
1464 You used a variable that isn't actually in your program. Failing that
|
|
|
1465 (which would be quite impressive and is probably impossible, at least in
|
|
|
1466 the present version of @cic{}), you specified an illegal number for a
|
|
|
1467 variable (legal numbers are positive and onespot). This error happens
|
|
|
1468 at compile time, at least for illegal variable numbers.
|
|
|
1469
|
|
|
1470 @ieanchor E222
|
|
|
1471 @cindex out of memory, during @code{STASH}
|
|
|
1472 @quotation
|
|
|
1473 BUMMER, DUDE!
|
|
|
1474 @end quotation
|
|
|
1475
|
|
|
1476 In @ical{}, you're allowed to @code{STASH} as much as you like; this
|
|
|
1477 makes the language Turing-complete and allows for unlimited recursion
|
|
|
1478 when combined with computed @code{COME FROM} in the right way.
|
|
|
1479 Unfortunately, real computers aren't so idealised; if you manage to
|
|
|
1480 write a program so memory-intensive that the computer runs out of memory
|
|
|
1481 to store stashes, it causes this error at runtime. To fix this error,
|
|
|
1482 you either have to simplify the program or upgrade your computer's
|
|
|
1483 memory, and even then that will only help to some extent.
|
|
|
1484
|
|
|
1485 @ieanchor E240
|
|
|
1486 @cindex array, invalid dimension
|
|
|
1487 @cindex invalid array dimension
|
|
|
1488 @cindex illegal array dimension
|
|
|
1489 @quotation
|
|
|
1490 ERROR HANDLER PRINTED SNIDE REMARK
|
|
|
1491 @end quotation
|
|
|
1492
|
|
|
1493 Arrays have to be large enough to hold at least one element; you tried
|
|
|
1494 to dimension an array which isn't large enough to hold any data. This
|
|
|
1495 error happens at run time.
|
|
|
1496
|
|
|
1497 @ieanchor E241
|
|
|
1498 @cindex array, wrong dimension
|
|
|
1499 @cindex wrong array dimension
|
|
|
1500 @cindex array, out of bounds
|
|
|
1501 @cindex out of bounds
|
|
|
1502 @quotation
|
|
|
1503 VARIABLES MAY NOT BE STORED IN WEST HYPERSPACE
|
|
|
1504 @end quotation
|
|
|
1505
|
|
|
1506 This error happens at run time when the subscripts given to an array
|
|
|
1507 are inconsistent with the way the array was dimensioned, either
|
|
|
1508 because there were the wrong number of subscripts or because a
|
|
|
1509 subscript was too large to fit in the array. It can also happen when
|
|
|
1510 a multidimensional array is given to a command, such as @code{WRITE
|
|
|
1511 IN}, that expects it to be monodimensional.
|
|
|
1512
|
|
|
1513 @ieanchor E252
|
|
|
1514 @cindex I/O, out of memory
|
|
|
1515 @cindex out of memory, I/O
|
|
|
1516 @quotation
|
|
|
1517 I'VE FORGOTTEN WHAT I WAS ABOUT TO SAY
|
|
|
1518 @end quotation
|
|
|
1519
|
|
|
1520 This run-time error message is caused by the compiler running out of
|
|
|
1521 memory whilst trying to do I/O; at present, it can only happen during
|
|
|
1522 @clcic{}-style I/O.
|
|
|
1523
|
|
|
1524 @ieanchor E256
|
|
|
1525 @cindex PIC-INTERCAL, unsupported command
|
|
|
1526 @quotation
|
|
|
1527 THAT'S TOO HARD FOR MY TINY BRAIN
|
|
|
1528 @end quotation
|
|
|
1529
|
|
|
1530 Some commands simply aren't available in @abbr{PIC-INTERCAL}. I mean,
|
|
|
1531 @acronym{PIC}s generally have less than a kilobyte of memory; you're not
|
|
|
1532 going to be able to use some of the more confusing language features
|
|
|
1533 with that sort of resource limitation. The solution is to replace the
|
|
|
1534 affected command, or to not give the @option{-P} option
|
|
|
1535 (@pxref{-P+,,-P}) if you didn't mean to compile as @abbr{PIC-INTERCAL}
|
|
|
1536 in the first place.
|
|
|
1537
|
|
|
1538 @ieanchor E275
|
|
|
1539 @cindex overflow, over onespot
|
|
|
1540 @cindex overflow, over 16 bits
|
|
|
1541 @cindex onespot overflow
|
|
|
1542 @cindex 16 bit overflow
|
|
|
1543 @quotation
|
|
|
1544 DON'T BYTE OFF MORE THAN YOU CAN CHEW
|
|
|
1545 @end quotation
|
|
|
1546
|
|
|
1547 This error happens when there is an attempt to store a twospot value in
|
|
|
1548 a onespot variable. The actual size of the value is what matters when
|
|
|
1549 counting its spots; so you can store the output of a mingle in a onespot
|
|
|
1550 variable if it happens to be less than or equal to 65535, for instance.
|
|
|
1551 (This is not necessarily the case in versions of @ical{} other than
|
|
|
1552 @cic{}, though, so you have to be careful with portability when doing
|
|
|
1553 this.)
|
|
|
1554
|
|
|
1555 @ieanchor E277
|
|
|
1556 @cindex reverse assignment, impossible
|
|
|
1557 @cindex reverse assignment, error
|
|
|
1558 @cindex operand overloading, impossible
|
|
|
1559 @cindex impossible reverse assignment
|
|
|
1560 @quotation
|
|
|
1561 YOU CAN ONLY DISTORT THE LAWS OF MATHEMATICS SO FAR
|
|
|
1562 @end quotation
|
|
|
1563
|
|
|
1564 Reverse assignments are not always mathematically possible. Also,
|
|
|
1565 sometimes they require changing the value of a constant; this is only
|
|
|
1566 legal if you specifically specified that it was legal by using the
|
|
|
1567 @option{-v} option. In the case of an impossible reverse assignment
|
|
|
1568 (including a situation in which operand overloading causes a reverse
|
|
|
1569 assignment to happen), this error happens at runtime.
|
|
|
1570
|
|
|
1571 This error can also come up when a scalar variable is overloaded to an
|
|
|
1572 array (which doesn't make sense, but could happen if someone exploited
|
|
|
1573 bugs in the CREATE statement (@pxref{CREATE})), and an attempt is made
|
|
|
1574 to read or assign to that variable. (Subscripting a scalar variable
|
|
|
1575 is a syntax error, so there is no use for doing such an overload
|
|
|
1576 anyway.)
|
|
|
1577
|
|
|
1578 @ieanchor E281
|
|
|
1579 @cindex spark, nesting limit
|
|
|
1580 @cindex ears, nesting limit
|
|
|
1581 @cindex rabbit-ears, nesting limit
|
|
|
1582 @cindex nesting limit
|
|
|
1583 @findex SENESTMAX
|
|
|
1584 @quotation
|
|
|
1585 THAT MUCH QUOTATION AMOUNTS TO PLAGIARISM
|
|
|
1586 @end quotation
|
|
|
1587
|
|
|
1588 There is a limit of 256 on the number of nested spark/ears groups
|
|
|
1589 allowed. If you somehow manage to exceed that limit, that will cause
|
|
|
1590 this error. Try breaking the expression up into smaller expressions.
|
|
|
1591 (The limit is trivial to increase by changing @code{SENESTMAX} in
|
|
|
1592 @file{ick.h}; if you ever actually come across a program that hits the
|
|
|
1593 limit but wasn't designed to, just email the maintainer to request a
|
|
|
1594 higher limit.)
|
|
|
1595
|
|
|
1596 @ieanchor E333
|
|
|
1597 @cindex variables, limit
|
|
|
1598 @quotation
|
|
|
1599 YOU CAN'T HAVE EVERYTHING, WHERE WOULD YOU PUT IT?
|
|
|
1600 @end quotation
|
|
|
1601
|
|
|
1602 Your program references so many variables that the compiler couldn't
|
|
|
1603 cope. This error is unlikely to ever happen; if it does, try reducing
|
|
|
1604 the number of variables you use by combining some into arrays. This is
|
|
|
1605 a compile-time error.
|
|
|
1606
|
|
|
1607 @ieanchor E345
|
|
|
1608 @cindex out of memory
|
|
|
1609 @quotation
|
|
|
1610 THAT'S TOO COMPLEX FOR ME TO GRASP
|
|
|
1611 @end quotation
|
|
|
1612
|
|
|
1613 This is another compile-time error that's unlikely to ever happen;
|
|
|
1614 this one signifies the compiler itself running out of memory trying to
|
|
|
1615 compile your program. The only solutions to this are to simplify your
|
|
|
1616 program, or to make more memory available to the compiler.
|
|
|
1617
|
|
|
1618 @ieanchor E404
|
|
|
1619 @cindex @code{GO BACK}, no choicepoint
|
|
|
1620 @cindex @code{GO AHEAD}, no choicepoint
|
|
|
1621 @quotation
|
|
|
1622 I'M ALL OUT OF CHOICES!
|
|
|
1623 @end quotation
|
|
|
1624
|
|
|
1625 Your program asked that a choicepoint be backtracked to or removed, but
|
|
|
1626 there aren't any choicepoints at the moment. This runtime error usually
|
|
|
1627 indicates a logic mistake in your program. In backtracking programs
|
|
|
1628 translated from other backtracking languages, this indicates that the
|
|
|
1629 program has failed.
|
|
|
1630
|
|
|
1631 @ieanchor E405
|
|
|
1632 @cindex multithreading, not enabled
|
|
|
1633 @cindex backtracking, not enabled
|
|
|
1634 @cindex @code{WHILE}, not enabled
|
|
|
1635 @cindex @code{MAYBE}, not enabled
|
|
|
1636 @cindex @code{GO AHEAD}, not enabled
|
|
|
1637 @cindex @code{GO BACK}, not enabled
|
|
|
1638 @quotation
|
|
|
1639 PROGRAM REJECTED FOR MENTAL HEALTH REASONS
|
|
|
1640 @end quotation
|
|
|
1641
|
|
|
1642 Your program used a construct that only makes sense when multithreading
|
|
|
1643 or backtracking (@code{WHILE}, @code{MAYBE}, @code{GO BACK}, or @code{GO
|
|
|
1644 AHEAD}), but you didn't specify the @option{-m} option (@pxref{-m}). If
|
|
|
1645 you meant to write a multithreaded or backtracking program, just give
|
|
|
1646 that option; if you didn't, be careful what words you use in comments!
|
|
|
1647 This error happens at compile-time.
|
|
|
1648
|
|
|
1649 @ieanchor E436
|
|
|
1650 @cindex @code{RETRIEVE}, without stashing
|
|
|
1651 @cindex stash failure
|
|
|
1652 @quotation
|
|
|
1653 THROW STICK BEFORE RETRIEVING!
|
|
|
1654 @end quotation
|
|
|
1655
|
|
|
1656 In order to @code{RETRIEVE} a variable, it has to be @code{STASH}ed
|
|
|
1657 first; if it isn't, then this error happens at runtime.
|
|
|
1658
|
|
|
1659 @ieanchor E444
|
|
|
1660 @cindex @code{COME FROM}, no target
|
|
|
1661 @cindex @code{NEXT FROM}, no target
|
|
|
1662 @quotation
|
|
|
1663 IT CAME FROM BEYOND SPACE
|
|
|
1664 @end quotation
|
|
|
1665
|
|
|
1666 A @code{COME FROM} aiming at a line label --- as opposed to a computed
|
|
|
1667 @code{COME FROM}, which is allowed to be pointing at a nonexistent line
|
|
|
1668 --- must point to a valid line label. The same applies to @code{NEXT
|
|
|
1669 FROM}. This error happens at compile time if a nonexistent line label is
|
|
|
1670 found in one of these contexts.
|
|
|
1671
|
|
|
1672 @ieanchor E533
|
|
|
1673 @cindex overflow, over twospot
|
|
|
1674 @cindex overflow, over 32 bits
|
|
|
1675 @cindex twospot overflow
|
|
|
1676 @cindex 32 bit overflow
|
|
|
1677 @quotation
|
|
|
1678 YOU WANT MAYBE WE SHOULD IMPLEMENT 64-BIT VARIABLES?
|
|
|
1679 @end quotation
|
|
|
1680
|
|
|
1681 This error is like E275 (@pxref{E275}), but applies when an attempt is
|
|
|
1682 made at runtime to store a threespot value (or even a fourspot or
|
|
|
1683 morespot value) in a twospot variable, or a threespot or greater value
|
|
|
1684 is produced as an intermediate during a calculation (for instance by a
|
|
|
1685 mingle operation). No values above twospot are allowed at any point
|
|
|
1686 during an @ical{} program; if you want to process higher numbers, you
|
|
|
1687 have to figure out a different way of storing them.
|
|
|
1688
|
|
|
1689 @ieanchor E553
|
|
|
1690 @cindex buffer overflow
|
|
|
1691 @quotation
|
|
|
1692 BETTER LATE THAN NEVER
|
|
|
1693 @end quotation
|
|
|
1694 Oops! The compiler just noticed that it had a buffer overflow.
|
|
|
1695 (Normally programs catch buffer overflows before they happen;
|
|
|
1696 C-INTERCAL catches them just afterwards instead.) This only happens
|
|
|
1697 on systems which don't have a modern C standard library. Try using
|
|
|
1698 shorter or fewer filenames on the command line, to reduce the risk of
|
|
|
1699 such an overflow.
|
|
|
1700
|
|
|
1701 @ieanchor E555
|
|
|
1702 @cindex @code{COME FROM}, ambiguity
|
|
|
1703 @quotation
|
|
|
1704 FLOW DIAGRAM IS EXCESSIVELY CONNECTED
|
|
|
1705 @end quotation
|
|
|
1706
|
|
|
1707 Aiming two @code{COME FROM}s at the same line only makes sense in a
|
|
|
1708 multithreaded program. In a non-multithread program, doing that will
|
|
|
1709 cause this error at compile time (if neither @code{COME FROM} is
|
|
|
1710 computed) or at run time (if the command that has just finished running
|
|
|
1711 is simultaneously the target of two or more @code{COME FROM}s). This
|
|
|
1712 either indicates an error in your program or that you've forgotten to
|
|
|
1713 use the @option{-m} option (@pxref{-m}) if you are actually trying to
|
|
|
1714 split the program into two threads.
|
|
|
1715
|
|
|
1716 @ieanchor E562
|
|
|
1717 @cindex input, EOF
|
|
|
1718 @cindex EOF
|
|
|
1719 @cindex end of file
|
|
|
1720 @quotation
|
|
|
1721 I DO NOT COMPUTE
|
|
|
1722 @end quotation
|
|
|
1723
|
|
|
1724 The program asked for input, but for some reason it wasn't available.
|
|
|
1725 (This is a runtime error, obviously.) The error may happen because the
|
|
|
1726 input is being piped in from a command or file which has reached
|
|
|
1727 end-of-file, or because the user typed @kbd{@key{CTRL}-@key{D}}
|
|
|
1728 (UNIX/Linux) or @kbd{@key{CTRL}-@key{Z}} (DOS/Windows) while the program
|
|
|
1729 was trying to @code{WRITE IN} some data.
|
|
|
1730
|
|
|
1731 @ieanchor E579
|
|
|
1732 @cindex input, invalid
|
|
|
1733 @quotation
|
|
|
1734 WHAT BASE AND/OR LANGUAGE INCLUDES @var{string}?
|
|
|
1735 @end quotation
|
|
|
1736
|
|
|
1737 When reading spelt-out-digit input, the input didn't seem to be a valid
|
|
|
1738 digit in English, Sanskrit, Basque, Tagalog, Classical Nahuatl,
|
|
|
1739 Georgian, Kwakiutl, Volap@"uk, or Latin. This seems to have languages
|
|
|
1740 covered pretty well; what on earth were you using, or did you just make
|
|
|
1741 a spelling mistake?
|
|
|
1742
|
|
|
1743 @ieanchor E621
|
|
|
1744 @cindex @code{RESUME}, by 0
|
|
|
1745 @quotation
|
|
|
1746 ERROR TYPE 621 ENCOUNTERED
|
|
|
1747 @end quotation
|
|
|
1748
|
|
|
1749 The compiler encountered error E621 (@pxref{E621}). This happens at
|
|
|
1750 runtime when the program requests that no entries are removed from the
|
|
|
1751 @code{NEXT} stack (which is possible), but that the last entry removed
|
|
|
1752 should be jumped to (which given the circumstances isn't, because no
|
|
|
1753 entries were removed).
|
|
|
1754
|
|
|
1755 @ieanchor E632
|
|
|
1756 @quotation
|
|
|
1757 THE NEXT STACK RUPTURES. ALL DIE. OH, THE EMBARRASSMENT!
|
|
|
1758 @end quotation
|
|
|
1759
|
|
|
1760 When an attempt is made to @code{RESUME} past the end of the @code{NEXT}
|
|
|
1761 stack, the program ends; however, this cause the program to end in a
|
|
|
1762 manner other than via @code{GIVE UP} or @code{DON'T TRY AGAIN}, so an
|
|
|
1763 error message must be printed, and this is that error message.
|
|
|
1764
|
|
|
1765 @ieanchor E633
|
|
|
1766 @quotation
|
|
|
1767 PROGRAM FELL OFF THE EDGE
|
|
|
1768 @end quotation
|
|
|
1769
|
|
|
1770 You can't just let execution run off the end of the program. At least,
|
|
|
1771 that is, if it doesn't end with @code{TRY AGAIN}. An attempt to do that
|
|
|
1772 causes this error at runtime. Note that if your program references the
|
|
|
1773 system library, then it counts as being appended to your program and so
|
|
|
1774 the program will run into the first line of the system library rather
|
|
|
1775 than cause this error. As it happens, the first line of the system
|
|
|
1776 library is a syntax error, so doing this will cause E000 (@pxref{E000})
|
|
|
1777 with the error text @samp{PLEASE KNOCK BEFORE ENTERING}. There isn't a
|
|
|
1778 next statement to be executed with E633, so the next statement won't be
|
|
|
1779 given in the error message.
|
|
|
1780
|
|
|
1781 @ieanchor E652
|
|
|
1782 @cindex @code{PIN}, in a non-PIC program
|
|
|
1783 @quotation
|
|
|
1784 HOW DARE YOU INSULT ME!
|
|
|
1785 @end quotation
|
|
|
1786
|
|
|
1787 The @code{PIN} command doesn't make much sense for anything bigger than
|
|
|
1788 a @acronym{PIC}; using it in a non-@acronym{PIC} program causes this
|
|
|
1789 error at compile-time. Try using the normal input and output mechanisms
|
|
|
1790 instead. This error may also be a clue that you are trying to compile a
|
|
|
1791 @abbr{PIC-INTERCAL} program without giving the @option{-P} option
|
|
|
1792 (@pxref{-P+,,-P}).
|
|
|
1793
|
|
|
1794 @ieanchor E666
|
|
|
1795 @cindex out of memory, during compile
|
|
|
1796 @cindex too many input files
|
|
|
1797 @cindex line too long
|
|
|
1798 @quotation
|
|
|
1799 COMPILER HAS INDIGESTION
|
|
|
1800 @end quotation
|
|
|
1801
|
|
|
1802 There isn't a limit on the length of an input program other than your
|
|
|
1803 computer's memory; if your computer does run out of memory during
|
|
|
1804 compilation, it causes this error. This error can also be caused if
|
|
|
1805 too many input files are specified on the command line; if you suspect
|
|
|
1806 this is the problem, split the compilation into separate compilations
|
|
|
1807 if you can, or otherwise you may be able to concatenate together your
|
|
|
1808 input files into larger but fewer files. Yet another potential cause
|
|
|
1809 of this error is if a line in an input program is too long; sensible
|
|
|
1810 line-wrapping techniques are encouraged.
|
|
|
1811
|
|
|
1812 @ieanchor E774
|
|
|
1813 @cindex random bug, error message
|
|
|
1814 @quotation
|
|
|
1815 RANDOM COMPILER BUG
|
|
|
1816 @end quotation
|
|
|
1817
|
|
|
1818 No compiler is perfect; sometimes errors just happen at random. In this
|
|
|
1819 case, the random error is E774. If you don't like the idea that your
|
|
|
1820 program may be shot down by a random compiler bug, or you are doing
|
|
|
1821 something important, you can use the @option{-b} option (@pxref{-b}) to
|
|
|
1822 prevent this bug happening. (You may wonder why this bug is in there at
|
|
|
1823 all if it's so easily prevented. The answer is that such a bug was
|
|
|
1824 present in the original @icst{} compiler, which also had an option to
|
|
|
1825 turn the bug off. It's also a reward for people who actually read the
|
|
|
1826 manual.)
|
|
|
1827
|
|
|
1828 @ieanchor E777
|
|
|
1829 @cindex directory problems, source file
|
|
|
1830 @cindex no source file
|
|
|
1831 @quotation
|
|
|
1832 A SOURCE IS A SOURCE, OF COURSE, OF COURSE
|
|
|
1833 @end quotation
|
|
|
1834
|
|
|
1835 You specified a file to compile on the command line, but the compiler
|
|
|
1836 couldn't find or couldn't open it. This is almost certainly because you
|
|
|
1837 made a typo specifying the file.
|
|
|
1838
|
|
|
1839 @ieanchor E778
|
|
|
1840 @cindex internal errors
|
|
|
1841 @quotation
|
|
|
1842 UNEXPLANED COMPILER BUG
|
|
|
1843 @end quotation
|
|
|
1844
|
|
|
1845 This should never come up, either at compile time or at run time. It
|
|
|
1846 could come up at either when an internal check by the compiler or the
|
|
|
1847 runtime libraries realises that something has gone badly wrong; mistakes
|
|
|
1848 happen, and in such cases the mistake will have been detected. (If this
|
|
|
1849 happens at compile time you can use the @option{-U} option
|
|
|
1850 (@pxref{-U+,,-U}) to cause the compiler to send an abort signal -- which
|
|
|
1851 normally causes a core dump -- when the error happens, to help debug
|
|
|
1852 what's causing it.) More often, this error comes up when the operating
|
|
|
1853 system has noticed something impossible, like an attempt to free
|
|
|
1854 allocated memory twice or to write to a null pointer, and tells the
|
|
|
1855 compiler an error has occured, in which case the same response of
|
|
|
1856 putting up this error happens. The point is that in all cases this
|
|
|
1857 error indicates a bug in the compiler (even if it happens at run time);
|
|
|
1858 in such cases, it would be very helpful if you figure out what caused it
|
|
|
1859 and send a bug report (@pxref{Reporting Bugs}).
|
|
|
1860
|
|
|
1861 @ieanchor E810
|
|
|
1862 @cindex yuk, input overflow
|
|
|
1863 @quotation
|
|
|
1864 ARE ONE-CHARACTER COMMANDS TOO SHORT FOR YOU?
|
|
|
1865 @end quotation
|
|
|
1866
|
|
|
1867 This is a debug-time error caused when you give too much input to the
|
|
|
1868 debugger when all it wanted was to know what you wanted to do next.
|
|
|
1869
|
|
|
1870 @ieanchor E811
|
|
|
1871 @cindex yuk, breakpoint overflow
|
|
|
1872 @cindex yuk, too many breakpoints
|
|
|
1873 @cindex breakpoints, too many
|
|
|
1874 @quotation
|
|
|
1875 PROGRAM IS TOO BADLY BROKEN TO RUN
|
|
|
1876 @end quotation
|
|
|
1877
|
|
|
1878 There's a limit to how many breakpoints you can have in a program;
|
|
|
1879 you've broken the limit and therefore broken the debugger. This is a
|
|
|
1880 debug-time error.
|
|
|
1881
|
|
|
1882 @ieanchor E888
|
|
|
1883 @quotation
|
|
|
1884 I HAVE NO FILE AND I MUST SCREAM
|
|
|
1885 @end quotation
|
|
|
1886 @cindex output file, failure to write
|
|
|
1887
|
|
|
1888 The output file couldn't be written, maybe because the disk is full or
|
|
|
1889 because there's already a read-only file with the same name. This is a
|
|
|
1890 compile-time error.
|
|
|
1891
|
|
|
1892 @ieanchor E899
|
|
|
1893 @quotation
|
|
|
1894 HELLO?
|
|
|
1895 CAN ANYONE GIVE ME A HAND HERE?
|
|
|
1896 @end quotation
|
|
|
1897 @cindex Funge, no external library
|
|
|
1898 @cindex Befunge, no external library
|
|
|
1899 @cindex external libraries, unavailable
|
|
|
1900 @cindex .b98, no external library
|
|
|
1901
|
|
|
1902 This error occurs at compile-time if a file type was requested for
|
|
|
1903 which the required libraries are unavailable. (Support for Funge does
|
|
|
1904 not ship with the compiler; instead, you need to generate the library
|
|
|
1905 yourself from the cfunge sources. For more information, see
|
|
|
1906 @ref{Creating the Funge-98 Library}.)
|
|
|
1907
|
|
|
1908 @ieanchor E991
|
|
|
1909 @cindex out of memory, multithreading
|
|
|
1910 @cindex out of memory, backtracking
|
|
|
1911 @cindex multithreading, out of memory
|
|
|
1912 @cindex backtracking, out of memory
|
|
|
1913 @quotation
|
|
|
1914 YOU HAVE TOO MUCH ROPE TO HANG YOURSELF
|
|
|
1915 @end quotation
|
|
|
1916
|
|
|
1917 There is no limit on the number of threads or choicepoints that you can
|
|
|
1918 have in a multithreaded or backtracking program (in a program that isn't
|
|
|
1919 multithreaded or backtracking, these are obviously limited to 1 and 0
|
|
|
1920 respectively). However, your computer may not be able to cope; if it
|
|
|
1921 runs out of memory in the multithreader, it will cause this error at
|
|
|
1922 runtime.
|
|
|
1923
|
|
|
1924 @ieanchor E993
|
|
|
1925 @cindex @code{TRY AGAIN}, not last
|
|
|
1926 @quotation
|
|
|
1927 I GAVE UP LONG AGO
|
|
|
1928 @end quotation
|
|
|
1929
|
|
|
1930 @code{TRY AGAIN} has to be the last command in a program, if it's there
|
|
|
1931 at all; you can't even follow it by comments, not even if you know in
|
|
|
1932 advance that they won't be @code{REINSTATE}d. This error happens at
|
|
|
1933 compile time if a command is found after a @code{TRY AGAIN}.
|
|
|
1934
|
|
|
1935 @ieanchor E995
|
|
|
1936 @quotation
|
|
|
1937 DO YOU REALLY EXPECT ME TO HAVE IMPLEMENTED THAT?
|
|
|
1938 @end quotation
|
|
|
1939
|
|
|
1940 Some parts of the code haven't been written yet. There ought to be no
|
|
|
1941 way to cause those to actually run; however, if you do somehow find a
|
|
|
1942 way to cause them to run, they will cause this error at compile time.
|
|
|
1943
|
|
|
1944 @ieanchor E997
|
|
|
1945 @cindex whirlpool, in base 2
|
|
|
1946 @cindex sharkfin, in base 2
|
|
|
1947 @cindex TriINTERCAL, operators in base 2
|
|
|
1948 @quotation
|
|
|
1949 ILLEGAL POSSESSION OF A CONTROLLED UNARY OPERATOR
|
|
|
1950 @end quotation
|
|
|
1951
|
|
|
1952 Some operators (such as whirlpool (@code{@@}) and sharkfin (@code{^}))
|
|
|
1953 only make sense in @abbr{TriINTERCAL} programs, and some have a minimum
|
|
|
1954 base in which they make sense. This error happens at compile-time if
|
|
|
1955 you try to use an operator that conflicts with the base you're in (such
|
|
|
1956 as using @abbr{TriINTERCAL} operators in an @ical{} program in the
|
|
|
1957 default base 2).
|
|
|
1958
|
|
|
1959 @ieanchor E998
|
|
|
1960 @cindex unsupported file type
|
|
|
1961 @cindex file type, unsupported
|
|
|
1962 @quotation
|
|
|
1963 EXCUSE ME,
|
|
|
1964 YOU MUST HAVE ME CONFUSED WITH SOME OTHER COMPILER
|
|
|
1965 @end quotation
|
|
|
1966
|
|
|
1967 This error occurs just before compile-time if a file is encountered on
|
|
|
1968 the command line that C-INTERCAL doesn't recognise. (If this error
|
|
|
1969 occurs due to a @samp{.a}, @samp{.b98}, @samp{.c}, or @samp{.c99},
|
|
|
1970 then you forgot to enable the external calls system using @option{-e}
|
|
|
1971 (@pxref{-e}).)
|
|
|
1972
|
|
|
1973 @ieanchor E999
|
|
|
1974 @cindex skeleton file, errors
|
|
|
1975 @quotation
|
|
|
1976 NO SKELETON IN MY CLOSET, WOE IS ME!
|
|
|
1977 @end quotation
|
|
|
1978
|
|
|
1979 The skeleton file @file{ick-wrap.c} or @file{pickwrap.c} is needed to be
|
|
|
1980 able to compile @ical{} to C. If the compiler can't find it, it will
|
|
|
1981 give this error message. This indicates a problem with the way the
|
|
|
1982 compiler has been installed; try using the @option{-u} option
|
|
|
1983 (@pxref{-u}) to find out where it's looking (you may be able to place a
|
|
|
1984 copy of the skeleton file in one of those places).
|
|
|
1985
|
|
|
1986 @end table
|
|
|
1987
|
|
|
1988 @node Warnings
|
|
|
1989 @section Warnings
|
|
|
1990 @cindex warnings
|
|
|
1991 @cindex @command{ick}, warnings
|
|
|
1992
|
|
|
1993 This is a list of the warnings stored in the warning database.
|
|
|
1994 Warnings only come up when the @option{-l} option (@pxref{-l}) is
|
|
|
1995 given; even then, some of the warnings are not currently implemented
|
|
|
1996 and therefore will never come up.
|
|
|
1997
|
|
|
1998 @table @asis
|
|
|
1999
|
|
|
2000 @ieanchor W016
|
|
|
2001 @quotation
|
|
|
2002 DON'T TYPE THAT SO HASTILY
|
|
|
2003 @end quotation
|
|
|
2004
|
|
|
2005 The positional precedence rules for unary operators are somewhat
|
|
|
2006 complicated, and it's easy to make a mistake. This warning is meant to
|
|
|
2007 detect such mistakes, but is not currently implemented.
|
|
|
2008
|
|
|
2009 @ieanchor W018
|
|
|
2010 @quotation
|
|
|
2011 THAT WAS MEANT TO BE A JOKE
|
|
|
2012 @end quotation
|
|
|
2013
|
|
|
2014 If an @ical{} expression has been translated from another language such
|
|
|
2015 as C, the optimiser is generally capable of translating it back into
|
|
|
2016 something similar to the original, at least in base 2. When after
|
|
|
2017 optimisation there are still @ical{} operators left in an expression,
|
|
|
2018 then this warning is produced. (Therefore, it's likely to come up quite
|
|
|
2019 a lot if optimisation isn't used@!) The system library produces some of
|
|
|
2020 these warnings (you can tell if a warning has come up in the system
|
|
|
2021 library because you'll get a line number after the end of your program).
|
|
|
2022
|
|
|
2023 @ieanchor W112
|
|
|
2024 @cindex warnings, non-INTERCAL-72
|
|
|
2025 @cindex non-INTERCAL-72 warning
|
|
|
2026 @quotation
|
|
|
2027 THAT RELIES ON THE NEW WORLD ORDER
|
|
|
2028 @end quotation
|
|
|
2029
|
|
|
2030 This warning comes up whenever the compiler recognises that you've added
|
|
|
2031 some code that didn't exist in @icst{}. This allows you to check
|
|
|
2032 whether your code is valid @icst{} (although @option{-t} (@pxref{-t}) is
|
|
|
2033 more useful for that); it also warns you that code might not be portable
|
|
|
2034 (because @icst{} is implemented by most @ical{} compilers, but more
|
|
|
2035 recent language features may not be).
|
|
|
2036
|
|
|
2037 @ieanchor W128
|
|
|
2038 @quotation
|
|
|
2039 SYSLIB IS OPTIMIZED FOR OBUSCATION
|
|
|
2040 @end quotation
|
|
|
2041
|
|
|
2042 There is an idiom used in the system library that does a right-shift by
|
|
|
2043 selecting alternate bits from a twospot number and then mingling them
|
|
|
2044 the other way round. A rightshift can much more easily be done with a
|
|
|
2045 single rightshift, so this is a silly way to do it, and this warning
|
|
|
2046 warns that this idiom was used. However, the present optimizer is
|
|
|
2047 incapable of recognising whether this problem exists or not, so the
|
|
|
2048 warning is not currently implemented.
|
|
|
2049
|
|
|
2050 @ieanchor W276
|
|
|
2051 @cindex onespot, overflow warning
|
|
|
2052 @cindex overflow, warning
|
|
|
2053 @quotation
|
|
|
2054 YOU CAN'T EXPECT ME TO CHECK BACK THAT FAR
|
|
|
2055 @end quotation
|
|
|
2056
|
|
|
2057 It's an error to assign a twospot value (a value over 65535) to a
|
|
|
2058 onespot variable, or to use it as an argument to a mingle. If the
|
|
|
2059 optimizer can't guarantee at compile time that there won't be an
|
|
|
2060 overflow, it issues this warning. (Note that this doesn't necessarily
|
|
|
2061 mean there's a problem --- for instance, the system library generates
|
|
|
2062 some of these warnings --- only that the optimiser couldn't work out for
|
|
|
2063 sure that there wasn't a problem.)
|
|
|
2064
|
|
|
2065 @ieanchor W239
|
|
|
2066 @quotation
|
|
|
2067 WARNING HANDLER PRINTED SNIDE REMARK
|
|
|
2068 @end quotation
|
|
|
2069
|
|
|
2070 Your code looks like it's trying to assign 0 to an array, giving it no
|
|
|
2071 dimension; this is an error. This warning is produced at compile time
|
|
|
2072 if it looks like a line in your code will cause this error, but it isn't
|
|
|
2073 necessarily an error because that line of code might never be executed.
|
|
|
2074
|
|
|
2075 @ieanchor W278
|
|
|
2076 @quotation
|
|
|
2077 FROM A CONTRADICTION, ANYTHING FOLLOWS
|
|
|
2078 @end quotation
|
|
|
2079
|
|
|
2080 It's sometimes impossible to reverse an assignment (a reverse
|
|
|
2081 assignment can happen if the @option{-v} option (@pxref{-v}) is used
|
|
|
2082 and an expression is placed on the left of an assignment, or in
|
|
|
2083 operand overloading); if the compiler detects that a reversal failure
|
|
|
2084 is inevitable, it will cause this warning. Note that this doesn't
|
|
|
2085 always cause an error, because the relevant code might never be
|
|
|
2086 executed.
|
|
|
2087
|
|
|
2088 @ieanchor W450
|
|
|
2089 @quotation
|
|
|
2090 THE DOCUMENTOR IS NOT ALWAYS RIGHT
|
|
|
2091 @end quotation
|
|
|
2092
|
|
|
2093 There is no way to get this warning to come up; it isn't even written
|
|
|
2094 anywhere in @cic{}'s source code, is not implemented by anything, and
|
|
|
2095 there are no circumstances in which it is even meant to come up. It is
|
|
|
2096 therefore not at all obvious why it is documented.
|
|
|
2097
|
|
|
2098 @ieanchor W534
|
|
|
2099 @cindex unary operators, portability
|
|
|
2100 @cindex portability, unary operators
|
|
|
2101 @quotation
|
|
|
2102 KEEP LOOKING AT THE TOP BIT
|
|
|
2103 @end quotation
|
|
|
2104
|
|
|
2105 @cic{} uses a slightly different typing mechanism to some other @ical{}
|
|
|
2106 compilers; types are calculated at compile time rather than run time.
|
|
|
2107 This only makes a difference in some cases involving unary operators.
|
|
|
2108 It's impossible to detect at compile time for certain whether such a
|
|
|
2109 case has come up or not, but if the compiler or optimizer thinks that
|
|
|
2110 such a case might have come up, it will issue this warning.
|
|
|
2111
|
|
|
2112 @ieanchor W622
|
|
|
2113 @quotation
|
|
|
2114 WARNING TYPE 622 ENCOUNTERED
|
|
|
2115 @end quotation
|
|
|
2116
|
|
|
2117 Your code looks like it's trying to resume by 0; this is an error. This
|
|
|
2118 warning is produced at compile time if it looks like a line in your code
|
|
|
2119 will cause this error, but it isn't necessarily an error because that
|
|
|
2120 line of code might never be executed.
|
|
|
2121
|
|
|
2122 @end table
|
|
|
2123
|
|
|
2124 @node The yuk debugger
|
|
|
2125 @chapter The yuk debugger
|
|
|
2126 @cindex yuk
|
|
|
2127 @cindex debugging, yuk
|
|
|
2128 @cindex debugging, runtime
|
|
|
2129 @cindex runtime debugger
|
|
|
2130 @anchor{yuk}
|
|
|
2131
|
|
|
2132 The @cic{} distribution contains a runtime debugger called `yuk'.
|
|
|
2133 Unlike most other debuggers, it is stored as object code rather than as
|
|
|
2134 an executable, and it is compiled into the code rather than operating on
|
|
|
2135 it. To debug code, add @option{-y} (@pxref{-y}) to the command line of
|
|
|
2136 @command{ick} when invoking it; that tells it to compile the debugger
|
|
|
2137 into the code and then execute the resulting combination. (The
|
|
|
2138 resulting hybrid debugger/input executable is deleted afterwards; this
|
|
|
2139 is to prevent it being run by mistake, and to prevent spreading the
|
|
|
2140 debugger's licence onto the code it was compiled with.)
|
|
|
2141
|
|
|
2142 yuk can also be used as a profiler using the @option{-p} option
|
|
|
2143 (@pxref{-p}); this produces a file @file{yuk.out} containing information
|
|
|
2144 on how much time was spent running each command in your program, and
|
|
|
2145 does not prompt for debugger commands.
|
|
|
2146
|
|
|
2147 Note that some command line arguments are incompatible with the
|
|
|
2148 debugger, such as @option{-m} and @option{-f}. In particular, this
|
|
|
2149 means that multithreaded programs and programs that use backtracking
|
|
|
2150 cannot be debugged using this method; the @option{+printflow} option
|
|
|
2151 (@pxref{+printflow}) to a compiled program may or may not be useful for
|
|
|
2152 debugging multithreaded programs.
|
|
|
2153
|
|
|
2154 When the debugger starts, it will print a copyright message and a
|
|
|
2155 message on how to access online help; then you can enter commands to
|
|
|
2156 run/debug the program. The debugger will show a command prompt,
|
|
|
2157 @samp{yuk007 }, to let you know you can input a command.
|
|
|
2158
|
|
|
2159 @cindex yuk, commands
|
|
|
2160 Here are the commands available. Commands are single characters
|
|
|
2161 followed by newlines, or followed by a line number (in decimal) and a
|
|
|
2162 newline or a variable name (a @code{.}, @code{,}, @code{:} or @code{;}
|
|
|
2163 followed by a number in decimal; note that some commands only allow
|
|
|
2164 onespot and twospot variables as arguments).
|
|
|
2165
|
|
|
2166 @multitable @columnfractions .15 .85
|
|
|
2167 @headitem Command @tab Description
|
|
|
2168 @item a@var{LINE}
|
|
|
2169 @tab
|
|
|
2170 All non-abstained commands on line @var{LINE} become abstained from
|
|
|
2171 once.
|
|
|
2172 @item b@var{LINE}
|
|
|
2173 @tab
|
|
|
2174 A breakpoint is set on line @var{LINE}. The breakpoint causes execution
|
|
|
2175 with @samp{c} to stop when it is reached.
|
|
|
2176 @item c
|
|
|
2177 @tab
|
|
|
2178 The program is run until it ends (which also ends the debugger) or a
|
|
|
2179 breakpoint is reached.
|
|
|
2180 @item d@var{LINE}
|
|
|
2181 @tab
|
|
|
2182 Any breakpoint that may be on line @var{LINE} is removed.
|
|
|
2183 @item e@var{LINE}
|
|
|
2184 @tab
|
|
|
2185 An explanation of the main expression in each command on line @var{LINE}
|
|
|
2186 is printed to the screen. The explanation is in the same format as the
|
|
|
2187 format produced by @option{-h} (@pxref{-h}) and shows what the optimiser
|
|
|
2188 optimised the expression to (or the original expression if the optimiser
|
|
|
2189 wasn't used).
|
|
|
2190 @item f@var{LINE}
|
|
|
2191 @tab
|
|
|
2192 Removes the effect of the @samp{m} command on line @var{LINE}.
|
|
|
2193 @item g@var{LINE}
|
|
|
2194 @tab
|
|
|
2195 Causes the current command to be the first command on @var{LINE} (if not
|
|
|
2196 on that line already) or the next command on @var{LINE}, as if that line
|
|
|
2197 was @code{NEXT}ed to and then that @code{NEXT} stack item was forgotten.
|
|
|
2198 @item h
|
|
|
2199 @tab
|
|
|
2200 Lists 10 lines either side of the current line; if there aren't 10 lines
|
|
|
2201 to one or the other side of the current line, instead more lines will be
|
|
|
2202 shown on the other side to compensate, if available.
|
|
|
2203 @item i@var{VAR}
|
|
|
2204 @tab
|
|
|
2205 Causes variable @var{VAR} to become @code{IGNORE}d, making it read-only.
|
|
|
2206 @item j@var{VAR}
|
|
|
2207 @tab
|
|
|
2208 Causes variable @var{VAR} to become @code{REMEMBER}ed, making it no
|
|
|
2209 longer read-only.
|
|
|
2210 @item k
|
|
|
2211 @tab
|
|
|
2212 Continues executing commands until the @command{NEXT} stack is the same
|
|
|
2213 size or smaller than it was before. In other words, if the current
|
|
|
2214 command is not a @command{NEXT} and doesn't have a @command{NEXT FROM}
|
|
|
2215 aiming at it, one command is executed; but if a @command{NEXT} does
|
|
|
2216 happen, execution will continue until that @command{NEXT} returns or is
|
|
|
2217 forgotten. A breakpoint or the end of the program also end this.
|
|
|
2218 @item l@var{LINE}
|
|
|
2219 @tab
|
|
|
2220 Lists 10 lines of source code either side of line @var{LINE}, the same
|
|
|
2221 way as with @samp{h}, but using a line stated in the command rather than
|
|
|
2222 the current line.
|
|
|
2223 @item m@var{LINE}
|
|
|
2224 @tab
|
|
|
2225 Produces a message onscreen every time a command on line @var{LINE} is
|
|
|
2226 executed, but without interrupting the program.
|
|
|
2227 @item n
|
|
|
2228 @tab
|
|
|
2229 Show the @command{NEXT} stack on the screen.
|
|
|
2230 @item o
|
|
|
2231 @tab
|
|
|
2232 Continue executing commands until the @command{NEXT} stack is smaller
|
|
|
2233 than it was before. If you are using @command{NEXT}s like procedures,
|
|
|
2234 then this effectively means that the procedure will run until it
|
|
|
2235 returns. A breakpoint or the end of the program also end this.
|
|
|
2236 @item p
|
|
|
2237 @tab
|
|
|
2238 Displays the value of all onespot and twospot variables.
|
|
|
2239 @item q
|
|
|
2240 @tab
|
|
|
2241 Aborts the current program and exits the debugger.
|
|
|
2242 @item r@var{LINE}
|
|
|
2243 @tab
|
|
|
2244 Reinstates once all abstained commands on line @var{LINE}.
|
|
|
2245 @item s
|
|
|
2246 @tab
|
|
|
2247 Executes one command.
|
|
|
2248 @item t
|
|
|
2249 @tab
|
|
|
2250 Continues execution until the end of the program or a breakpoint: each
|
|
|
2251 command that executes is displayed while this command is running.
|
|
|
2252 @item u@var{LINE}
|
|
|
2253 @tab
|
|
|
2254 Continues execution of the program until just before a command on line
|
|
|
2255 @var{LINE} is run (or a breakpoint or the end of the program).
|
|
|
2256 @item v@var{VAR}
|
|
|
2257 @tab
|
|
|
2258 Adds a `view' on variable @var{VAR} (which must be onespot or twospot),
|
|
|
2259 causing its value to be displayed on the screen whenever a command is
|
|
|
2260 printed on screen (for instance, because the command has just been
|
|
|
2261 stepped past, or due to the @samp{m} or @samp{t} commands).
|
|
|
2262 @item w
|
|
|
2263 @tab
|
|
|
2264 Displays the current line and current command onscreen.
|
|
|
2265 @item x@var{VAR}
|
|
|
2266 @tab
|
|
|
2267 Removes any view and any action that may be associated with it on
|
|
|
2268 variable @var{VAR} (which must be onespot or twospot).
|
|
|
2269 @item y@var{VAR}
|
|
|
2270 @tab
|
|
|
2271 Adds a view on variable @var{VAR}; also causes a break, as if a
|
|
|
2272 breakpoint was reached, whenever the value of that variable changes.
|
|
|
2273 @item z@var{VAR}
|
|
|
2274 @tab
|
|
|
2275 Adds a view on variable @var{VAR}; also causes a break, as if a
|
|
|
2276 breakpoint was reached, whenever that variable's value becomes 0.
|
|
|
2277 @item @var{VAR}
|
|
|
2278 @tab
|
|
|
2279 A onespot or twospot variable written by itself prints out the value of
|
|
|
2280 that variable.
|
|
|
2281 @item <@var{VAR}
|
|
|
2282 @tab
|
|
|
2283 @command{WRITEs IN} a new value for variable @var{VAR}. Note that input
|
|
|
2284 must be in the normal @samp{ONE TWO THREE} format; input in any other
|
|
|
2285 format will cause error E579 (@pxref{E579}) and as that is a fatal
|
|
|
2286 error, the debugger and program it's debugging will end.
|
|
|
2287 @item *
|
|
|
2288 @tab
|
|
|
2289 Displays the license conditions under which @command{ick} is
|
|
|
2290 distributed.
|
|
|
2291 @item ?
|
|
|
2292 @tab
|
|
|
2293 Displays a summary of what each command does. (@samp{@@} does the same
|
|
|
2294 thing.)
|
|
|
2295 @end multitable
|
|
|
2296
|
|
|
2297 While the code is executing (for instance, during a @samp{c}, @samp{k},
|
|
|
2298 @samp{o}, @samp{t} or @samp{u} command), it's possible to interrupt it
|
|
|
2299 with @kbd{@key{CTRL}-@key{C}} (on UNIX/Linux) or
|
|
|
2300 @kbd{@key{CTRL}-@key{BREAK}} (on Windows/DOS); this will cause the
|
|
|
2301 current command to finish running and the debugger prompt to come back
|
|
|
2302 up.
|
|
|
2303
|
|
|
2304 @ifset notsplit
|
|
|
2305 @partheading{PART II: THE @ical{} LANGUAGE}
|
|
|
2306 @end ifset
|
|
|
2307 @node Syntax
|
|
|
2308 @chapter Syntax
|
|
|
2309 @cindex syntax, INTERCAL
|
|
|
2310 @cindex INTERCAL, syntax
|
|
|
2311
|
|
|
2312 @ical{} programs consist of a list of statements. Execution of a
|
|
|
2313 program starts with its first statement; generally speaking each
|
|
|
2314 statement runs after the previous statement, although many situations
|
|
|
2315 can change this.
|
|
|
2316
|
|
|
2317 Whitespace is generally insignificant in @ical{} programs; it cannot be
|
|
|
2318 added in the middle of a keyword (unless the keyword contains whitespace
|
|
|
2319 itself) or inside a decimal number, but it can be added more or less
|
|
|
2320 anywhere else, and it can be removed from anywhere in the program as
|
|
|
2321 well.
|
|
|
2322
|
|
|
2323 An @ical{} statement consists of an optional line label, a statement
|
|
|
2324 identifier, an optional execution chance, the statement itself
|
|
|
2325 (@pxref{Statements}), and optionally @code{ONCE} or @code{AGAIN}.
|
|
|
2326
|
|
|
2327 @menu
|
|
|
2328 * Princeton and Atari Syntax:: There are two syntaxes for @ical{}
|
|
|
2329 * Line Labels:: Allowing lines to be referred to
|
|
|
2330 * Statement Identifiers:: Marking the start of a statement
|
|
|
2331 * Execution Chance:: Statements that might not execute
|
|
|
2332 * ONCE and AGAIN:: Self-abstaining and self-reinstating statements
|
|
|
2333 @end menu
|
|
|
2334
|
|
|
2335 @node Princeton and Atari Syntax
|
|
|
2336 @section Princeton and Atari Syntax
|
|
|
2337 @cindex syntax, dialects
|
|
|
2338 @cindex dialects of syntax
|
|
|
2339 @cindex character sets
|
|
|
2340
|
|
|
2341 The history of @ical{} is plagued with multiple syntaxes and character
|
|
|
2342 sets. The result has settled down with two versions of the syntax;
|
|
|
2343 the original Princeton syntax, and the Atari syntax (which is more
|
|
|
2344 suited to the operating systems of today).
|
|
|
2345
|
|
|
2346 @cindex syntax, Princeton
|
|
|
2347 @cindex Princeton syntax
|
|
|
2348 @subheading Princeton syntax
|
|
|
2349 @portability{some versions, version 0.18+, all versions, no}
|
|
|
2350
|
|
|
2351 The original @icst{} compiler was the Princeton compiler, which
|
|
|
2352 introduced what has become known as the Princeton syntax for @ical{};
|
|
|
2353 this is the syntax used in the original manual, for instance, and can
|
|
|
2354 be considered to be the `original' or `official' @ical{} syntax. It
|
|
|
2355 is notable for containing various characters not found in some
|
|
|
2356 character sets; for instance, it writes the operator for mingle as a
|
|
|
2357 cent sign (known as `change'). The other operator that often causes
|
|
|
2358 problems is the bookworm operator @samp{V}, backspace, @samp{-}, which
|
|
|
2359 is used for exclusive-or; the backspace can cause problems on some
|
|
|
2360 systems (which was probably the original intention). This syntax is
|
|
|
2361 also the default syntax in the @clcic{} compiler, which is the @i{de
|
|
|
2362 facto} standard for expanding the Princeton syntax to modern @ical{}
|
|
|
2363 features that are not found in @icst{}; however, it does not appear to
|
|
|
2364 have been used as the default syntax in any other compilers.
|
|
|
2365 Nowadays, there are other ways to write the required characters than
|
|
|
2366 using backspace; for instance, the cent sign appears in Latin-1 and
|
|
|
2367 UTF-8, and there are various characters that approximate bookworms
|
|
|
2368 (for instance, @clcic{} uses the Latin-1 yen symbol for this, which
|
|
|
2369 just to make things confusing, refers to a mingle in modern Atari
|
|
|
2370 syntax).
|
|
|
2371
|
|
|
2372 @cindex syntax, Atari
|
|
|
2373 @cindex Atari syntax
|
|
|
2374 @subheading Atari syntax
|
|
|
2375 @portability{some versions, yes, version 0.05+, yes}
|
|
|
2376
|
|
|
2377 The other main syntax is the Atari syntax, so called because it was
|
|
|
2378 originally used by the ``Atari implementation'' of @icst{}. It is not
|
|
|
2379 clear why the implementation was given this name, because the authors
|
|
|
2380 of the implementation are not known; it is not clear whether it has
|
|
|
2381 any connection with Atari other than running on an Atari computer, for
|
|
|
2382 instance. The syntax was designed to work better on ASCII-based
|
|
|
2383 systems, by avoiding the change character (although it can still be
|
|
|
2384 written as @samp{c}, backspace, @samp{/}, which the Atari compiler
|
|
|
2385 documentation claims that the Princeton compiler supported) in favour
|
|
|
2386 of a `big money' character (@samp{$}), and using the `what' (@samp{?})
|
|
|
2387 as an alternative character for exclusive-or. This is the syntax that
|
|
|
2388 @cic{} and @jic{} have always used, and is the one most commonly used
|
|
|
2389 for communicating @ical{} programs on Usenet and other similar fora
|
|
|
2390 (where ASCII is one of the most reliable-to-send character sets). It
|
|
|
2391 is also the syntax used for examples in this manual, for much the same
|
|
|
2392 reason. The Atari syntax for constructs more modern than @icst{} is
|
|
|
2393 normally taken to be that used by the @cic{} compiler, because it is
|
|
|
2394 the only Atari-syntax-based compiler that contains non-@icst{}
|
|
|
2395 constructs that actually need their own notation.
|
|
|
2396
|
|
|
2397 @node Line Labels
|
|
|
2398 @section Line Labels
|
|
|
2399 @cindex line label
|
|
|
2400 @cindex line number
|
|
|
2401
|
|
|
2402 @portability{yes, all versions, all versions, all versions}
|
|
|
2403
|
|
|
2404 The first part of an @ical{} statement is a line label that specifies
|
|
|
2405 what its line number is. This is optional; it's allowed to have a
|
|
|
2406 statement without a line number, although that prevents other commands
|
|
|
2407 referring to it by number. Line numbers must be constants, and unique
|
|
|
2408 within the program. However, they do not have to be in order; unlike
|
|
|
2409 some other languages with line numbers, a line with a higher number can
|
|
|
2410 come earlier in the program than a line with a lower number, and the
|
|
|
2411 numbers don't affect the order in which commands are executed.
|
|
|
2412
|
|
|
2413 A line label is a integer expressed in decimal within a wax/wane pair
|
|
|
2414 (@code{(} and @code{)}). For instance, this is a valid line label:
|
|
|
2415
|
|
|
2416 @example
|
|
|
2417 (1000)
|
|
|
2418 @end example
|
|
|
2419
|
|
|
2420 Note that line numbers from 1000 to 1999 are used by the system library,
|
|
|
2421 so using them within your own programs may produce unexpected errors if
|
|
|
2422 the system library is included. Apart from this, line numbers from 1 to
|
|
|
2423 65535 are allowed.
|
|
|
2424
|
|
|
2425 It has become reasonably customary for people writing @ical{} libraries
|
|
|
2426 to pick a range of 1000 line numbers (for instance, 3000 to 3999) and
|
|
|
2427 stick to that range for all line numbers used in the program (apart from
|
|
|
2428 when calling the system library), so if you want to write an @ical{}
|
|
|
2429 library, it may be a good idea to look at the existing libraries (in the
|
|
|
2430 @file{pit/lib} directory in the @cic{} distribution) and choose a range
|
|
|
2431 of numbers that nobody else has used. If you aren't writing a library,
|
|
|
2432 it may be a good idea to avoid such number ranges (that is, use only
|
|
|
2433 line numbers below 1000 or very high numbers that are unlikely to be
|
|
|
2434 used by libraries in the future), so that you can easily add libraries
|
|
|
2435 to your program without renumbering in the future.
|
|
|
2436
|
|
|
2437 @node Statement Identifiers
|
|
|
2438 @section Statement Identifiers
|
|
|
2439 @cindex statement identifier
|
|
|
2440 @findex DO
|
|
|
2441 @findex PLEASE
|
|
|
2442 @findex NOT
|
|
|
2443 @findex N'T
|
|
|
2444 @cindex abstain, at program start
|
|
|
2445 @cindex reinstate, at program start
|
|
|
2446 @cindex initial abstention
|
|
|
2447 @cindex abstained state
|
|
|
2448 @cindex reinstated state
|
|
|
2449
|
|
|
2450 @portability{yes, all versions, all versions, all versions}
|
|
|
2451
|
|
|
2452 After the line label (if a statement has one) comes the statement
|
|
|
2453 identifier, which marks where the statement starts. Either the label or
|
|
|
2454 the statement identifier, whichever one comes first, marks where the
|
|
|
2455 preceding statement finishes.
|
|
|
2456
|
|
|
2457 @anchor{DO}@anchor{PLEASE}
|
|
|
2458 The main statement identifier is @code{DO}. It also has two synonyms,
|
|
|
2459 @code{PLEASE} and @code{PLEASE DO}; these synonyms are the 'polite'
|
|
|
2460 forms of statement identifiers. Although the three identifiers have the
|
|
|
2461 same meaning, using either polite or non-polite identifiers too much can
|
|
|
2462 cause an error; the correct proportion is approximately 3 non-polite
|
|
|
2463 identifiers for every polite identifier used. None of these identifiers
|
|
|
2464 actually does anything else apart from marking where the statement
|
|
|
2465 starts; they leave the statements in the default `reinstated' state.
|
|
|
2466
|
|
|
2467 @anchor{NOT}@anchor{N'T}
|
|
|
2468 Adding @code{NOT} or @code{N'T} to the end of any of these identifiers,
|
|
|
2469 to create a statement identifier such as @code{DO NOT} or @code{PLEASE
|
|
|
2470 DON'T}, also creates a valid statement identifier. These differ in
|
|
|
2471 meanings from the previous set of identifiers, though; they cause the
|
|
|
2472 statement they precede to not be executed by default; that is, the
|
|
|
2473 command will be skipped during execution (this is known as the
|
|
|
2474 `abstained' state). This applies even if the command in question is in
|
|
|
2475 fact a syntax error, thus causing this to be a useful method of writing
|
|
|
2476 comments. One common idiom is to write code like this:
|
|
|
2477
|
|
|
2478 @example
|
|
|
2479 PLEASE NOTE: This is a comment.
|
|
|
2480 @end example
|
|
|
2481
|
|
|
2482 The statement identifier (@code{PLEASE NOT}) is the only part of this
|
|
|
2483 statement that is valid @ical{}; however, because the statement
|
|
|
2484 identifier is in the negated form that contains @code{NOT}, the syntax
|
|
|
2485 error won't be executed, and therefore this is a valid statement. (In
|
|
|
2486 @ical{}, syntax errors happen at runtime, so a program containing a
|
|
|
2487 statement like @code{DOUBT THIS WILL WORK} will still compile, and will
|
|
|
2488 not end due to the syntax error unless that statement is actually
|
|
|
2489 executed. @xref{E000}.)
|
|
|
2490
|
|
|
2491 The @code{ABSTAIN} and @code{REINSTATE} statements can override the
|
|
|
2492 @code{NOT} or otherwise on a statement identifier; see @ref{ABSTAIN}.
|
|
|
2493
|
|
|
2494 In backtracking programs, @code{MAYBE} is also a valid statement
|
|
|
2495 identifier; see @ref{MAYBE}. It comes before the other keywords in the
|
|
|
2496 statement identifier, and an implicit @code{DO} is added if there wasn't
|
|
|
2497 one already in the statement identifier (so @code{MAYBE}, @code{MAYBE
|
|
|
2498 DO}, @code{MAYBE DON'T}, @code{MAYBE PLEASE}, and so on are all valid
|
|
|
2499 statement identifiers).
|
|
|
2500
|
|
|
2501 @node Execution Chance
|
|
|
2502 @section Execution Chance
|
|
|
2503 @cindex execution chance
|
|
|
2504 @cindex double-oh-seven
|
|
|
2505 @findex %
|
|
|
2506
|
|
|
2507 @portability{yes, all versions, version 0.02+, all versions}
|
|
|
2508
|
|
|
2509 It's possible to specify that a command should be run only a certain
|
|
|
2510 proportion of the time, at random. This is a rarely used feature of
|
|
|
2511 @ical{}, although it is the only way to introduce randomness into a
|
|
|
2512 program. (The @cic{} compiler approximates this with pseudorandomness.)
|
|
|
2513 An execution chance specification comes immediately after the statement
|
|
|
2514 identifier, but before the rest of the statement, and consists of a
|
|
|
2515 double-oh-seven (@code{%}) followed by an integer from 1 to 99
|
|
|
2516 inclusive, written in decimal; this gives the percentage chance of the
|
|
|
2517 statement running. The execution chance only acts to prevent a
|
|
|
2518 statement running when it otherwise would have run; it cannot cause a
|
|
|
2519 statement that would otherwise not have run to run. For instance, the
|
|
|
2520 statement @code{DO %40 WRITE OUT #1} has a 40% chance of writing out
|
|
|
2521 @samp{I}, but the statement @code{DON'T %40 WRITE OUT #1} has no chance
|
|
|
2522 of writing out @code{I} or anything else, because the @code{N'T}
|
|
|
2523 prevents it running and the double-oh-seven cannot override that.
|
|
|
2524
|
|
|
2525 @node ONCE and AGAIN
|
|
|
2526 @section ONCE and AGAIN
|
|
|
2527 @cindex ABSTAIN, self-abstaining
|
|
|
2528 @cindex REINSTATE, self-reinstating
|
|
|
2529 @cindex self-abstaining
|
|
|
2530 @cindex self-reinstating
|
|
|
2531 @findex ONCE
|
|
|
2532 @findex AGAIN
|
|
|
2533 @anchor{ONCE}@anchor{AGAIN}
|
|
|
2534
|
|
|
2535 @portability{no, version 0.25+, no, no}
|
|
|
2536
|
|
|
2537 The last part of a statement is an optional @code{ONCE} or @code{AGAIN}.
|
|
|
2538 @code{ONCE} specifies that the statement is self-abstaining or
|
|
|
2539 self-reinstating (this will be explained below); @code{AGAIN} specifies
|
|
|
2540 that the statement should behave like it has already self-reinstated or
|
|
|
2541 self-abstained. Whether the behaviour is self-abstention or
|
|
|
2542 self-reinstatement depends on whether the statement was initially
|
|
|
2543 abstained or not; a @code{ONCE} on an initially reinstated statement or
|
|
|
2544 @code{AGAIN} on an initially abstained statement indicates a
|
|
|
2545 self-abstention, and a @code{ONCE} on an initially abstained statement
|
|
|
2546 or @code{AGAIN} on an initially reinstated statement indicates a
|
|
|
2547 self-reinstatement.
|
|
|
2548
|
|
|
2549 The first time a self-abstaining statement is encountered, it is
|
|
|
2550 executed as normal, but the statement is then abstained from and
|
|
|
2551 therefore will not run in future. Likewise, the first time
|
|
|
2552 self-reinstating statement is encountered, it is not executed (as is
|
|
|
2553 normal for an abstained statement), but then becomes reinstated and will
|
|
|
2554 run in future. In each of these cases, the @code{ONCE} effectively
|
|
|
2555 changes to an @code{AGAIN}; the @code{ONCE} only happens once, as might
|
|
|
2556 be expected.
|
|
|
2557
|
|
|
2558 @code{REINSTATING} a currently abstained self-abstaining statement or
|
|
|
2559 @code{ABSTAINING} (that is, with the @code{ABSTAIN} or @code{REINSTATE}
|
|
|
2560 commands) a currently reinstated self-reinstating statement causes the
|
|
|
2561 @code{AGAIN} on the statement to change back into a @code{ONCE}, so the
|
|
|
2562 statement will again self-abstain or self-reinstate. Likewise,
|
|
|
2563 @code{REINSTATING} a currently abstained self-reinstating statement or
|
|
|
2564 @code{ABSTAINING} a currently reinstated self-abstaining statement
|
|
|
2565 causes its @code{ONCE} to turn into an @code{AGAIN}.
|
|
|
2566
|
|
|
2567 Historical note: @code{ONCE} was devised by Malcom Ryan as a method of
|
|
|
2568 allowing synchronisation between threads in a multithreaded program
|
|
|
2569 (@code{ONCE} is atomic with the statement it modifies, that is, there is
|
|
|
2570 no chance that threads will change between the statement and the
|
|
|
2571 @code{ONCE}). @code{AGAIN} was added to Malcom Ryan's Threaded Intercal
|
|
|
2572 standard on the suggestion of Kyle Dean, as a method of adding extra
|
|
|
2573 flexibility (and to allow the @code{ONCE}s to happen multiple times,
|
|
|
2574 which is needed to implement some multithreaded algorithms).
|
|
|
2575
|
|
|
2576 @node Expressions
|
|
|
2577 @chapter Expressions
|
|
|
2578 @cindex expressions
|
|
|
2579
|
|
|
2580 Many @ical{} statements take expressions as arguments. Expressions are
|
|
|
2581 made up out of operands and operators between them. Note that there is
|
|
|
2582 no operator precedence in @ical{}; different compilers resolve
|
|
|
2583 ambiguities different ways, and some versions of some compilers
|
|
|
2584 (including the original @icst{} compiler) will cause error messages on
|
|
|
2585 compiling or executing an ambiguous expression, so it's safest to fully
|
|
|
2586 group each expression.
|
|
|
2587
|
|
|
2588 @menu
|
|
|
2589 * Constants and Variables:: The basic operands that make up expressions
|
|
|
2590 * Grouping Rules:: How to specify grouping in expressions
|
|
|
2591 * Operators:: Joining operands into more complex expressions
|
|
|
2592 @end menu
|
|
|
2593
|
|
|
2594 @node Constants and Variables
|
|
|
2595 @section Constants and Variables
|
|
|
2596 @cindex constant
|
|
|
2597 @cindex variable
|
|
|
2598 @cindex mesh
|
|
|
2599 @cindex onespot
|
|
|
2600 @cindex twospot
|
|
|
2601 @cindex tail
|
|
|
2602 @cindex hybrid
|
|
|
2603 @findex #
|
|
|
2604 @findex .
|
|
|
2605 @findex :
|
|
|
2606 @findex ,
|
|
|
2607 @findex ;
|
|
|
2608
|
|
|
2609 @portability{yes, all versions, all versions, all versions}
|
|
|
2610
|
|
|
2611 The basic operands in @ical{} are constants and variables. These
|
|
|
2612 together make up what in other languages are known as `lvalues', that
|
|
|
2613 is, operands to which values can be assigned. (Constants can also be
|
|
|
2614 lvalues in @ical{}, but by default @cic{} turns this off because it
|
|
|
2615 carries an efficiency penalty and can be confusing; this can be turned
|
|
|
2616 on with the @option{-v} option (@pxref{-v}).)
|
|
|
2617
|
|
|
2618 Constants can have any integer value from 0 to 65535 inclusive; higher
|
|
|
2619 values (up to 4294967295) can be generated in programs, but cannot be
|
|
|
2620 specified literally as constants. (The usual way to work around this
|
|
|
2621 limitation is to interleave two constants together; see @ref{Mingle}.) A
|
|
|
2622 constant is written as a mesh (@code{#}) followed by a number in
|
|
|
2623 decimal. At the start of the program, all constants have the same value
|
|
|
2624 as the number that identifies them; for instance, @code{#100} has 100 as
|
|
|
2625 its value, and it's strongly advised not to change the value of a
|
|
|
2626 constant during the execution of a program.
|
|
|
2627
|
|
|
2628 There are four types of variable: 16-bit and 32-bit unsigned integers,
|
|
|
2629 and arrays of 16-bit and 32-bit unsigned integers. These are
|
|
|
2630 represented with a spot, twospot, tail, and hybrid (@code{.}, @code{:},
|
|
|
2631 @code{,}, and @code{;}) respectively. For this reason, integers within
|
|
|
2632 the range 0 to 65535 inclusive are known as `onespot numbers', and
|
|
|
2633 integers within the range 0 to 4294967295 inclusive are known as
|
|
|
2634 `twospot numbers'; variables with those ranges are known as onespot and
|
|
|
2635 twospot variables. (Note that arrays did not work in @cic{} before
|
|
|
2636 version 0.7.)
|
|
|
2637
|
|
|
2638 Variables are represented with a character representing their data type,
|
|
|
2639 followed by an integer from 1 to 65535 inclusive, written in decimal.
|
|
|
2640 Non-array variables don't need to be declared before they are used; they
|
|
|
2641 automatically exist in any program that uses them. For instance,
|
|
|
2642 @code{.1} and @code{.001} are the same variable, onespot number 1.
|
|
|
2643 Array variables need to be dimensioned before they are used, by
|
|
|
2644 assigning dimensions to them; see @ref{Calculate}.
|
|
|
2645
|
|
|
2646 @node Grouping Rules
|
|
|
2647 @section Grouping Rules
|
|
|
2648 @cindex grouping rules
|
|
|
2649 @cindex positional precedence
|
|
|
2650 @cindex spark
|
|
|
2651 @cindex rabbit-ears
|
|
|
2652 @cindex ears
|
|
|
2653 @findex '
|
|
|
2654 @findex "
|
|
|
2655
|
|
|
2656 Because there are no operator precedences in @ical{}, there are various
|
|
|
2657 solutions to specifying what precedences actually are.
|
|
|
2658
|
|
|
2659 @table @asis
|
|
|
2660
|
|
|
2661 @item The portable solution
|
|
|
2662
|
|
|
2663 All known versions of @ical{} accept the @icst{} grouping rules. These
|
|
|
2664 state that it's possible to specify that an operator takes precedence by
|
|
|
2665 grouping it inside sparks (@code{'}) or rabbit-ears (@code{"}), the same
|
|
|
2666 way as wax/wane pairs (parentheses) are used in other programming
|
|
|
2667 languages. @icst{} and earlier @cic{} versions demanded that
|
|
|
2668 expressions were grouped fully like this, and this practice is still
|
|
|
2669 recommended because it leads to portable programs and is easier to
|
|
|
2670 understand. Whether sparks or rabbit-ears (often called just `ears' for
|
|
|
2671 short) are used normally doesn't matter, and programmers can use one or
|
|
|
2672 the other for clarity or for aesthetic appeal. (One common technique is
|
|
|
2673 to use just sparks at the outermost level of grouping, just ears at the
|
|
|
2674 next level, just sparks at the next level, and so on; but expressions
|
|
|
2675 like @code{''#1~#2'~"#3~#4"'~#5} are completely unambiguous, at least to
|
|
|
2676 the compiler.)
|
|
|
2677
|
|
|
2678 There are, however, some complicated situations involving array
|
|
|
2679 subscripting where it is necessary to use sparks and ears at alternate
|
|
|
2680 levels, if you want to write a portable program. This limitation is in
|
|
|
2681 @cic{} to simplify the parsing process; @icst{} has the same limitation,
|
|
|
2682 probably for the same reason. Compare these two statements:
|
|
|
2683
|
|
|
2684 @example
|
|
|
2685 DO .1 <- ,3SUB",2SUB.1".2
|
|
|
2686 DO .1 <- ,3SUB",2SUB.1".2~.3"".4
|
|
|
2687 @end example
|
|
|
2688
|
|
|
2689 The problem is that in the first statement, the ears close a group, and
|
|
|
2690 in the second statement, the ears open a group, and it's impossible to
|
|
|
2691 tell the difference without unlimited lookahead in the expression.
|
|
|
2692 Therefore, in similar situations (to be precise, in situations where a
|
|
|
2693 group is opened inside an array subscript), it's necessary to use the
|
|
|
2694 other grouping character to the one that opened the current group if you
|
|
|
2695 want a portable program.
|
|
|
2696
|
|
|
2697 One final comment about sparks and rabbit-ears; if the next character in
|
|
|
2698 the program is a spot, as often happens because onespot variables are
|
|
|
2699 common choices for operands, a spark and the following spot can be
|
|
|
2700 combined into a wow (@code{!}). Unfortunately, none of the character
|
|
|
2701 sets that @cic{} accepts as input (UTF-8, Latin-1, and ASCII-7) contain
|
|
|
2702 the rabbit character, although the Hollerith input format that @clcic{}
|
|
|
2703 can use does.
|
|
|
2704
|
|
|
2705 @item Positional precedences: @clcic{} rules
|
|
|
2706
|
|
|
2707 The precedence rules used by @clcic{} for grouping when full grouping
|
|
|
2708 isn't used are simple to explain: the largest part of the input that
|
|
|
2709 looks like an expression is taken to be that expression. The main
|
|
|
2710 practical upshot of this is that binary operators right-associate; that
|
|
|
2711 is, @code{.1~.2~.3} is equivalent to @code{.1~'.2~.3'}. @cic{} versions
|
|
|
2712 0.26 and later also right-associate binary operators so as to produce
|
|
|
2713 the same results as @clcic{} rules in this situation, but as nobody has
|
|
|
2714 yet tried to work out what the other implications of @clcic{} rules are
|
|
|
2715 they are not emulated in @cic{}, except possibly by chance.
|
|
|
2716
|
|
|
2717 @ianchor Prefix and infix unary operators
|
|
|
2718 @cindex unary operator, prefix
|
|
|
2719 @cindex unary operator, infix
|
|
|
2720
|
|
|
2721 In @icst{} and versions of @cic{} before 0.26, unary operators were
|
|
|
2722 always in the `infix' position. (If you're confused about how you can
|
|
|
2723 have an infix unary operator: they go one character inside a group that
|
|
|
2724 they apply to, or one character after the start of a constant or
|
|
|
2725 variable representation; so for instance, to portably apply the unary
|
|
|
2726 operator @code{&} to the variable @code{:1}, write @code{:&1}, and to
|
|
|
2727 portably apply it to the expression @code{'.1~.2'}, write
|
|
|
2728 @code{'&.1~.2'}.) @clcic{}, and versions of @cic{} from 0.26 onwards,
|
|
|
2729 allow the `prefix' position of a unary operator, which is just before
|
|
|
2730 whatever it applies to (as in @code{&:1}). This leads to ambiguities as
|
|
|
2731 to whether an operator is prefix or infix. The portable solution is, of
|
|
|
2732 course, to use only infix operators and fully group everything, but when
|
|
|
2733 writing for recent versions of @cic{}, it's possible to rely on its
|
|
|
2734 grouping rule, which is: unary operators are interpreted as infix where
|
|
|
2735 possible, but at most one infix operator is allowed to apply to each
|
|
|
2736 variable, constant, or group, and infix operators can't apply to
|
|
|
2737 anything else. So for instance, the @cic{} @code{'&&&.1~.2'} is
|
|
|
2738 equivalent to the portable @code{'&"&.&1"~.2'} (or the more readable
|
|
|
2739 version of this, @code{"&'"&.&1"~.2'"}, which is also portable). If
|
|
|
2740 these rules are counter-intuitive to you, remember that this is @ical{}
|
|
|
2741 we're talking about; note also that this rule is unique to @cic{}, at
|
|
|
2742 least at the time of writing, and in particular @clcic{} is likely to
|
|
|
2743 interpret this expression differently.
|
|
|
2744
|
|
|
2745 @end table
|
|
|
2746
|
|
|
2747 @node Operators
|
|
|
2748 @section Operators
|
|
|
2749 @cindex operator
|
|
|
2750
|
|
|
2751 Operators are used to operate on operands, to produce more complicated
|
|
|
2752 expressions that actually calculate something rather than just fetch
|
|
|
2753 information from memory. There are two types of operators, unary and
|
|
|
2754 binary operators, which operate on one and two arguments respectively.
|
|
|
2755 Binary operators are always written between their two operands; to
|
|
|
2756 portably write a unary operator, it should be in the `infix' position,
|
|
|
2757 one character after the start of its operand; see @ref{Prefix and infix
|
|
|
2758 unary operators} for the full details of how to write unary operators
|
|
|
2759 portably, and how else you can use them if you aren't aiming for
|
|
|
2760 portability. This section only describes @icst{} operators; many
|
|
|
2761 @ical{} extensions add their own operators.
|
|
|
2762
|
|
|
2763 @menu
|
|
|
2764 * Mingle:: Interleaving bits in two operands
|
|
|
2765 * Select:: Selecting from one operand according to another
|
|
|
2766 * Unary Binary Logic:: Binary logic on adjacent bits of an operand
|
|
|
2767 * Array Subscript:: Selecting elements of arrays
|
|
|
2768 @end menu
|
|
|
2769
|
|
|
2770 @node Mingle
|
|
|
2771 @subsection Mingle
|
|
|
2772 @cindex mingle
|
|
|
2773 @cindex interleave
|
|
|
2774 @findex $
|
|
|
2775
|
|
|
2776 @portability {yes, all versions, all versions, all versions}
|
|
|
2777
|
|
|
2778 Mingle, or interleave, is one of the two binary operators in @icst{}.
|
|
|
2779 However, different @ical{} compilers represent it in different ways, so
|
|
|
2780 it is impossible to write a mingle in a program completely portably,
|
|
|
2781 because it differs between Princeton and Atari syntax, and worse, the
|
|
|
2782 sequence of character codes needed to represent it in each syntax has
|
|
|
2783 varied from compiler to compiler.
|
|
|
2784
|
|
|
2785 The original @icst{} compiler (the Princeton compiler) used the
|
|
|
2786 'change' (cent) character for a mingle, represented as @code{c},
|
|
|
2787 backspace, @code{/}. (By the way, this is still the most portable way
|
|
|
2788 to write a mingle; both @cic{} and @clcic{} accept it, at least if a
|
|
|
2789 lowercase @code{c} is used, the Atari compiler accepted it, and its
|
|
|
2790 documentation claimed that the Princeton compiler also accepted it;
|
|
|
2791 @clcic{} also accepts a capital @code{C} before the backspace and
|
|
|
2792 @code{/}, and allows @code{|} rather than @code{/}.) The Atari
|
|
|
2793 compiler, another @icst{} compiler, used a 'big money' character
|
|
|
2794 (@code{$}) as the mingle character; this character is also the only
|
|
|
2795 one accepted for mingle by the @jic{} compiler. @cic{} originally
|
|
|
2796 also used the @code{$} character for mingle, and this character is the
|
|
|
2797 one most commonly seen in existing @cic{} programs, and most often
|
|
|
2798 used when giving examples of @ical{} on Usenet, because it exists in
|
|
|
2799 the ASCII-7 character set, and because it doesn't contain control
|
|
|
2800 characters. From version 0.18 of @cic{} onwards, various other units
|
|
|
2801 of currency (change, quid, and zlotnik if Latin-1 is used as the
|
|
|
2802 input, and euro if Latin-9 is used as the input) are accepted; from
|
|
|
2803 version 0.20 onwards, in addition to the Latin-1 characters, all the
|
|
|
2804 currency symbols in Unicode are accepted if UTF-8 is used as the input
|
|
|
2805 format. @clcic{} has always used the change character (either the
|
|
|
2806 Latin-1 version or the version that contains a backspace) for mingle.
|
|
|
2807 In this manual, mingle will be represented as @code{$}, but it's
|
|
|
2808 important to bear in mind that this character is not the most portable
|
|
|
2809 choice.
|
|
|
2810
|
|
|
2811 The mingle operator should be applied to two operands or expressions.
|
|
|
2812 To be portable, the operands must both be onespot expressions, that is
|
|
|
2813 expressions which have a 16-bit result; @cic{} relaxes this rule
|
|
|
2814 slightly and only requires that the result be in the onespot range.
|
|
|
2815 (This is because the data type of a select operator's value is meant to
|
|
|
2816 be determined at runtime; @cic{} determines all data types at compile
|
|
|
2817 time, so has to guess a 32-bit result for a select with a 32-bit type as
|
|
|
2818 its right operand even when the result might actually turn out to be of
|
|
|
2819 a 16-bit type, and so this behaviour prevents an error when a select
|
|
|
2820 operation returns a value with a 16-bit data type and is used as an
|
|
|
2821 argument to a mingle.) The result is a 32-bit value (that is, it is of a
|
|
|
2822 32-bit data type, even if its value fits into the onespot range), which
|
|
|
2823 consists of bits alternated from the two arguments; to be precise, its
|
|
|
2824 most significant bit is the most significant bit of its first argument,
|
|
|
2825 its second most significant bit is the most significant bit of its
|
|
|
2826 second argument, its third most significant bit is the second most
|
|
|
2827 significant bit of its first argument, and so on until its least
|
|
|
2828 significant bit, which is the least significant bit of its second
|
|
|
2829 argument.
|
|
|
2830
|
|
|
2831 One of the most common uses of interleaving is to create a constant with
|
|
|
2832 a value greater than 65535; for instance, 65536 is @code{#256$#0}. It
|
|
|
2833 is also commonly used in expressions that need to produce 32-bit
|
|
|
2834 results; except in some simple cases, this is usually coded by
|
|
|
2835 calculating separately the odd-numbered and even-numbered bits of the
|
|
|
2836 result, and mingling them together at the end. It is also used in
|
|
|
2837 expressions that need to left-shift values or perform similar
|
|
|
2838 value-increasing operations, as none of the other operators can easily
|
|
|
2839 do this; and mingle results are commonly used as the argument to unary
|
|
|
2840 binary logic operators, because this causes them to behave more like the
|
|
|
2841 binary logic operators found in some other languages.
|
|
|
2842
|
|
|
2843 @node Select
|
|
|
2844 @subsection Select
|
|
|
2845
|
|
|
2846 @portability{yes, all versions, all versions, all versions}
|
|
|
2847
|
|
|
2848 The select operator is one of the two binary operators in @icst{};
|
|
|
2849 unlike mingle, every known implementation of @ical{} ever has used the
|
|
|
2850 sqiggle character (@code{~}) as the representation of the select
|
|
|
2851 operator, meaning that writing it portably is easy.
|
|
|
2852
|
|
|
2853 The select operator takes two arguments, which can be of either
|
|
|
2854 datatype (that is, 16- or 32-bit). It returns a value made by
|
|
|
2855 selecting certain bits of its first operand indicated by the second
|
|
|
2856 operand, and right-justifying them. What it does is that it ignores
|
|
|
2857 all the bits of the first operand where the second operand has a 0 as
|
|
|
2858 the corresponding bit, that is, deletes them from a copy of the
|
|
|
2859 operand's value; the bits that are left are squashed together towards
|
|
|
2860 the least-significant end of the number, and the result is filled with
|
|
|
2861 0s to make it up to 16 or 32 bits. (In @icst{} the minimum multiple
|
|
|
2862 of 16 bits possible that the result fits into is chosen, although if
|
|
|
2863 :1 has the value 131061 (in hex, 1FFFF) the expression @code{#21~:1}
|
|
|
2864 produces a 32-bit result because 17 bits were selected, even though
|
|
|
2865 many of the leading bits were zeros; in @cic{} the data type of the
|
|
|
2866 result is the same as of the right operand of the select, so that it
|
|
|
2867 can be determined at compile time, and so using a unary binary logic
|
|
|
2868 operator on the result of select when the right operand has a 32-bit
|
|
|
2869 type is nonportable and not recommended.) As an example,
|
|
|
2870 @code{#21~:1} produces 21 as its result if :1 has the value 131061, 10
|
|
|
2871 as its result if :1 has the value 30 (1E in hex; the least significant
|
|
|
2872 bit of 21 is removed because it corresponds to a 0 in :1), and 7 as
|
|
|
2873 its result if :1 has the value 21 (because three bits in 21 are set,
|
|
|
2874 and those three bits from 21 are therefore selected by 21).
|
|
|
2875
|
|
|
2876 Select is used for right-shifts, to select every second bit from a
|
|
|
2877 number (either to produce what will eventually become an argument to
|
|
|
2878 mingle, or to interpret the result of a unary binary logic operator, or
|
|
|
2879 occasionally both), to test if a number is zero or not (by selecting it
|
|
|
2880 from itself and selecting 1 from the result), in some cases as a limited
|
|
|
2881 version of bitwise-and (that only works if the right operand is 1 less
|
|
|
2882 than a power of 2), and for many other purposes.
|
|
|
2883
|
|
|
2884 @node Unary Binary Logic
|
|
|
2885 @subsection Unary Binary Logic
|
|
|
2886 @cindex unary binary logic
|
|
|
2887 @cindex and
|
|
|
2888 @cindex or
|
|
|
2889 @cindex xor
|
|
|
2890 @cindex exor
|
|
|
2891 @cindex exclusive or
|
|
|
2892 @findex ?
|
|
|
2893 @findex &
|
|
|
2894 @findex V
|
|
|
2895 @cindex what
|
|
|
2896 @cindex ampersand
|
|
|
2897 @cindex book
|
|
|
2898
|
|
|
2899 @portability{yes, all versions, all versions, all versions}
|
|
|
2900
|
|
|
2901 There are three unary operators in @icst{}, each of which carries out
|
|
|
2902 a binary logic operation on adjacent bits of the number. The operators
|
|
|
2903 are and, or, and exclusive or; and and or are represented by an
|
|
|
2904 ampersand (@code{&}) and book (@code{V}) respectively, and exclusive
|
|
|
2905 or has the same notational problems as mingle, as it differs between
|
|
|
2906 Princeton and Atari syntax. It was represented by a bookworm, written
|
|
|
2907 @code{V}, backspace, @code{-}, in the Princeton @icst{}
|
|
|
2908 implementation, and this is still the most portable way to write it
|
|
|
2909 (@cic{} and @clcic{} accept it). The Atari implementation of @icst{}
|
|
|
2910 wrote it with a what (@code{?}), and this is the representation
|
|
|
2911 originally used by @cic{} (and still accepted), the only
|
|
|
2912 representation accepted by @jic{}, the one most commonly used on
|
|
|
2913 Usenet, and the one used in this manual (although again, it's worth
|
|
|
2914 pointing out that this isn't portable). @clcic{} approximates a
|
|
|
2915 bookworm with the yen character, which being a currency character is
|
|
|
2916 one of the possible representations for mingle in @cic{}; @cic{} uses
|
|
|
2917 the rather confusing method of interpreting a yen character as
|
|
|
2918 exclusive-or if input in Latin-1 but as mingle if input in UTF-8.
|
|
|
2919 (This usually does the right thing, because @clcic{} doesn't support
|
|
|
2920 UTF-8.) In the same way, @clcic{} has a @cic{} compatibility option
|
|
|
2921 to allow the use of @code{?} for exclusive-or.
|
|
|
2922
|
|
|
2923 The operators take each pair of consecutive bits in their arguments
|
|
|
2924 (that is, the least significant with the second least significant, the
|
|
|
2925 second least significant with the third least significant, the third
|
|
|
2926 least significant with the fourth least significant, and so on, with the
|
|
|
2927 pair consisting of the most significant and least significant being used
|
|
|
2928 to calculate the most significant bit of the result), and perform an
|
|
|
2929 appropriate logic operation on them; and sets a bit of the result if and
|
|
|
2930 only if both bits in the pair were set, or sets each bit corresponding to
|
|
|
2931 each pair where either bit was set, and exclusive or sets if and only if
|
|
|
2932 the bits in the pair had different values (that is, one was set, but not
|
|
|
2933 both). So for instance, @code{#&26} is 16 (26 is 1A in hexadecimal or
|
|
|
2934 11010 in binary); @code{#V26} is 31 (11111 in binary), and @code{#?26}
|
|
|
2935 is 23 (10111 in binary).
|
|
|
2936
|
|
|
2937 The most commonly seen use for these operators is to carry out bitwise
|
|
|
2938 ands, ors, and exclusive ors between two different 16-bit expressions,
|
|
|
2939 by mingling them together, applying a unary binary logic operator, and
|
|
|
2940 selecting every second bit of the result; such code often results due to
|
|
|
2941 people thinking in terms of some other language when writing @ical{},
|
|
|
2942 but is still often useful. (Historically, the first idiom added to the
|
|
|
2943 optimizer, apart from constant folding, was the mingle/unary/select
|
|
|
2944 sequence.) There are more imaginative uses; one impressive example is
|
|
|
2945 the exclusive or in the test for greater-than from the original @icst{}
|
|
|
2946 system library:
|
|
|
2947
|
|
|
2948 @example
|
|
|
2949 DO :5 <- "'?":1~'#65535$#0'"$":2~'#65535$#0'"'
|
|
|
2950 ~'#0$#65535'"$"'?":1~'#0$#65535'"$":2~'#0$
|
|
|
2951 #65535'"'~'#0$#65535'"
|
|
|
2952 DO .5 <- '?"'&"':2~:5'~'"'?"'?":5~:5"~"#65535~
|
|
|
2953 #65535"'~'#65535$#0'"$#32768'~'#0$#65535'"
|
|
|
2954 $"'?":5~:5"~"#65535$#65535"'~'#0$#65535'"'
|
|
|
2955 "$"':5~:5'~#1"'~#1"$#2'~#3
|
|
|
2956 @end example
|
|
|
2957
|
|
|
2958 The first statement works out the value of :1 bitwise exclusive or :2;
|
|
|
2959 the second statement then works out whether the most significant set bit
|
|
|
2960 in :5 (that is, the most significant bit that differs between :1 and :2)
|
|
|
2961 corresponds to a set bit in :2 or not. In case that's a bit too
|
|
|
2962 confusing to read, here's the corresponding optimizer idiom (in OIL):
|
|
|
2963
|
|
|
2964 @example
|
|
|
2965 ((_1~:2)~((?32(:2~:2))^#2147483648))->(_1>(:2^_1))
|
|
|
2966 @end example
|
|
|
2967
|
|
|
2968 (Here, the ^ refers to a bitwise exclusive or, an operation found in OIL
|
|
|
2969 but not in @ical{}, which is why the @ical{} version is so much longer.)
|
|
|
2970 The @ical{} version also has some extra code to check for equality and
|
|
|
2971 to produce 1 or 2 as the output rather than 0 or 1.
|
|
|
2972
|
|
|
2973 @node Array Subscript
|
|
|
2974 @subsection Array Subscript
|
|
|
2975 @cindex arrays, subscripting
|
|
|
2976 @cindex subscripts
|
|
|
2977 @findex SUB
|
|
|
2978
|
|
|
2979 @portability{yes, version 0.7+, all versions, all versions}
|
|
|
2980
|
|
|
2981 In order to access the elements of an array, either to read or write
|
|
|
2982 the array, it is necessary to use the array subscript operator
|
|
|
2983 @code{SUB}. Note that an array element is not a variable, so it is
|
|
|
2984 not accepted as an acceptable argument to statements like
|
|
|
2985 @code{IGNORE}; however, it can be assigned to.
|
|
|
2986
|
|
|
2987 The syntax for an array element is the array, followed by the keyword
|
|
|
2988 @code{SUB}, followed by an expression for the element number in the
|
|
|
2989 array. In the case of a multidimensional array, more than one
|
|
|
2990 expression is given after the keyword @code{SUB} to give the location
|
|
|
2991 of the element in each of the array's dimensions. The first element
|
|
|
2992 in an array or array dimension is numbered 1.
|
|
|
2993
|
|
|
2994 For instance, this is a legal (but not particularly useful) @ical{}
|
|
|
2995 program with no syntax errors that shows some of the syntaxes possible
|
|
|
2996 with array subscripting:
|
|
|
2997
|
|
|
2998 @example
|
|
|
2999 PLEASE ,1 <- #2
|
|
|
3000 DO .1 <- #2
|
|
|
3001 DO ,1 SUB .1 <- #1
|
|
|
3002 DO ,1 SUB #1 <- ,1 SUB #2
|
|
|
3003 PLEASE ;1 <- #2 BY #2
|
|
|
3004 DO ;1 SUB #1 #2 <- ,1 SUB ,1 SUB .1
|
|
|
3005 DO READ OUT ;1SUB#1.1
|
|
|
3006 DO GIVE UP
|
|
|
3007 @end example
|
|
|
3008
|
|
|
3009 Grouping can get complicated when nested array subscripting is used,
|
|
|
3010 particularly with multiple subscripts. It is the programmer's job to
|
|
|
3011 write an unambiguous statement, and also obey the extra grouping rules
|
|
|
3012 that apply to array subscripts; see @ref{Grouping Rules}.
|
|
|
3013
|
|
|
3014 @node Statements
|
|
|
3015 @chapter Statements
|
|
|
3016 @cindex statements
|
|
|
3017 @cindex statements, INTERCAL
|
|
|
3018
|
|
|
3019 There is a wide range of statements available to @ical{} programs;
|
|
|
3020 some identifiably belong to a particular variant or dialect (such as
|
|
|
3021 Backtracking @ical{}), but others can be considered to be part of the
|
|
|
3022 'core language'. The statements listed here are those that the @cic{}
|
|
|
3023 compiler will accept with no compiler switches to turn on particular
|
|
|
3024 dialect options. Note that many statements have slightly different
|
|
|
3025 effects in different implementations of @ical{}; known
|
|
|
3026 incompatibilities are listed here, but it's important to check your
|
|
|
3027 program on multiple compilers when attempting to write a portable
|
|
|
3028 program.
|
|
|
3029
|
|
|
3030 @menu
|
|
|
3031 * Syntax Error:: Why use a deliberate syntax error?
|
|
|
3032 * Calculate:: Assigning to variables and arrays
|
|
|
3033 * NEXT FORGET and RESUME:: @icst{}-style flow control
|
|
|
3034 * STASH and RETRIEVE:: Value stacks and scoping
|
|
|
3035 * IGNORE and REMEMBER:: Creating read-only variables
|
|
|
3036 * ABSTAIN and REINSTATE:: Dynamic DOs and DON'Ts
|
|
|
3037 * READ OUT and WRITE IN:: @ical{} input and output
|
|
|
3038 * GIVE UP:: How to end a program
|
|
|
3039 * TRY AGAIN:: Control flow without loops
|
|
|
3040 * COME FROM and NEXT FROM:: Time-reversed GOTO
|
|
|
3041 @end menu
|
|
|
3042
|
|
|
3043 @node Syntax Error
|
|
|
3044 @section Syntax Error
|
|
|
3045 @cindex syntax error
|
|
|
3046 @cindex comment
|
|
|
3047 @findex COMMENT
|
|
|
3048 @findex COMMENTS
|
|
|
3049 @findex COMMENTING
|
|
|
3050 @portability{yes,version 0.15+,all versions,all versions}
|
|
|
3051
|
|
|
3052 One of the more commonly-used commands in @ical{} is the syntax error.
|
|
|
3053 A properly-written syntax error looks nothing like any known @ical{}
|
|
|
3054 command; a syntax error that looks vaguely like a command but isn't
|
|
|
3055 may confuse @cic{} before version 0.28, and possibly other compilers,
|
|
|
3056 into bailing out at compile time in some situations (this is known as
|
|
|
3057 a `serious syntax error'), and so is not portable. For other syntax
|
|
|
3058 errors, though, the semantics are easily explained: there is a
|
|
|
3059 run-time error whenever the syntax error is actually executed, and the
|
|
|
3060 line containing the syntax error is used as the error message.
|
|
|
3061
|
|
|
3062 One purpose of this is to allow your programs to produce their own
|
|
|
3063 custom errors at run time; however, it's very important to make sure
|
|
|
3064 that they start and end in the right place, by manipulating where
|
|
|
3065 statement identifiers appear. Here's a correct example from the
|
|
|
3066 system library:
|
|
|
3067
|
|
|
3068 @example
|
|
|
3069 DOUBLE OR SINGLE PRECISION ARITHMETIC OVERFLOW
|
|
|
3070 @end example
|
|
|
3071
|
|
|
3072 This is a valid @ical{} command, that produces an error when run (note
|
|
|
3073 the @code{DO} at the start). An even more common use is to produce an
|
|
|
3074 initially abstained syntax error by using an appropriate statement
|
|
|
3075 identifier, for instance
|
|
|
3076
|
|
|
3077 @example
|
|
|
3078 PLEASE NOTE THAT THIS IS A COMMENT
|
|
|
3079 @end example
|
|
|
3080
|
|
|
3081 This would produce an error if reinstated somehow, but assuming that
|
|
|
3082 this isn't done, this is a line of code that does nothing, which is
|
|
|
3083 therefore equivalent to a comment in other programming languages.
|
|
|
3084 (The initial abstention is achieved with the statement identifier
|
|
|
3085 @code{PLEASE NOT}; the extra @code{E} causes the command to be a
|
|
|
3086 syntax error, and this particular construction is idiomatic.)
|
|
|
3087
|
|
|
3088 Referring to the set of all syntax errors in a program (or the set of
|
|
|
3089 all commands of any other given type) is achieved with a special
|
|
|
3090 keyword known as a `gerund'; gerund support for syntax errors is
|
|
|
3091 resonably recent, and only exists in @clcic{} (version 1.-94.-3 and
|
|
|
3092 later, with @code{COMMENT}, @code{COMMENTS}, or @code{COMMENTING}),
|
|
|
3093 and @cic{} (@code{COMMENT} in version 0.26 and later, and also
|
|
|
3094 @code{COMMENTS} and @code{COMMENTING} in version 0.27 and later).
|
|
|
3095 Therefore, it is not portable to refer to the set of all syntax errors
|
|
|
3096 by gerund; using a line label is a more portable way to refer to an
|
|
|
3097 individual syntax-error command.
|
|
|
3098
|
|
|
3099 @node Calculate
|
|
|
3100 @section Calculate
|
|
|
3101 @findex CALCULATING
|
|
|
3102 @cindex calculate
|
|
|
3103 @cindex assignment
|
|
|
3104 @cindex arrays, dimensioning
|
|
|
3105 @cindex dimensioning arrays
|
|
|
3106 @cindex variables, assignment
|
|
|
3107 @portability{yes, all versions, all versions, all versions}
|
|
|
3108
|
|
|
3109 At present, the only @ical{} command that contains no keywords (apart
|
|
|
3110 from the statement identifier and possibly @code{ONCE} or
|
|
|
3111 @code{AGAIN}) is what is known as the `calculate' command. It is used
|
|
|
3112 to assign values to variables, array elements, and arrays; assigning a
|
|
|
3113 value to an array changes the number of elements that that array can
|
|
|
3114 hold, and causes the values of all elements previously in that array
|
|
|
3115 to be lost. The syntax of a calculate command is as follows:
|
|
|
3116
|
|
|
3117 @example
|
|
|
3118 DO .1 <- ':2~:3'~#55
|
|
|
3119 @end example
|
|
|
3120
|
|
|
3121 That is, the command is written as a variable or array element, then
|
|
|
3122 the @code{<-} operator (known as an `angle-worm' and pronounced
|
|
|
3123 `gets'), then an expression to assign to it. In the special case when
|
|
|
3124 an array is being dimensioned by assigning a value to it, the
|
|
|
3125 expression can contain the keyword @code{BY} to cause the array to
|
|
|
3126 become multidimensional; so for a 3 by 4 by 5 array, it would be
|
|
|
3127 possible to write
|
|
|
3128
|
|
|
3129 @example
|
|
|
3130 DO ,1 <- #3 BY #4 BY #5
|
|
|
3131 @end example
|
|
|
3132
|
|
|
3133 The calculate command always evaluates the expression, even if for
|
|
|
3134 some reason the assignment can't be done (for instance, if the
|
|
|
3135 variable being assigned to is read-only); this is important if the
|
|
|
3136 expression has side-effects (for instance, giving an overflow error).
|
|
|
3137 If the variable does happen to be read-only, there is not an error;
|
|
|
3138 the expression being assigned to it is just evaluated, with the
|
|
|
3139 resulting value being discarded.
|
|
|
3140
|
|
|
3141 The gerund to refer to calculations is @code{CALCULATING}; however, if
|
|
|
3142 you are planning to use this, note that a bug in older versions of
|
|
|
3143 @cic{} means that assignments to arrays are not affected by this
|
|
|
3144 gerund before version 0.27.
|
|
|
3145
|
|
|
3146 @clcic{} from 1.-94.-4 onwards, and @cic{} from 0.26 onwards, allow
|
|
|
3147 arbitrary expressions on the left hand side of an assignment (@cic{}
|
|
|
3148 only if the @code{-v} option is used); for more information on how
|
|
|
3149 such `reverse assignments' work, see @ref{Operand Overloading}.
|
|
|
3150
|
|
|
3151 @node NEXT FORGET and RESUME
|
|
|
3152 @section NEXT, FORGET and RESUME
|
|
|
3153 @findex NEXT
|
|
|
3154 @findex FORGET
|
|
|
3155 @findex RESUME
|
|
|
3156 @findex NEXTING
|
|
|
3157 @findex FORGETTING
|
|
|
3158 @findex RESUMING
|
|
|
3159 @cindex NEXT stack
|
|
|
3160 @cindex flow control, INTERCAL-72
|
|
|
3161 @cindex stack, NEXT
|
|
|
3162 @cindex stack, instruction pointer
|
|
|
3163 @anchor{NEXT}
|
|
|
3164 @anchor{FORGET}
|
|
|
3165 @anchor{RESUME}
|
|
|
3166 @portability{yes, all versions, see text, all versions}
|
|
|
3167
|
|
|
3168 The only flow-control commands in @icst{} were @code{NEXT},
|
|
|
3169 @code{RESUME}, and @code{FORGET}; together these manipulate a stack of
|
|
|
3170 locations in the program known as the `NEXT stack'. Although all
|
|
|
3171 @ical{} compilers have implemented these, from @clcic{} version 0.05
|
|
|
3172 onwards @clcic{} has considered them obsolete, and therefore a special
|
|
|
3173 command-line switch needs to be used to enable them. (They are still
|
|
|
3174 the most portable flow-control commands currently available, though,
|
|
|
3175 precisely because @icst{} implements nothing else.) Note that there
|
|
|
3176 is a strict limit of 80 locations on the NEXT stack, enforced by all
|
|
|
3177 known @ical{} compilers; this helps to enforce good programming style,
|
|
|
3178 by discouraging NEXT-stack leaks (which are otherwise quite easy to
|
|
|
3179 write).
|
|
|
3180
|
|
|
3181 Here are examples to show the syntax of these three statements:
|
|
|
3182
|
|
|
3183 @example
|
|
|
3184 DO (1000) NEXT
|
|
|
3185 DO FORGET '.1~.1'~#1
|
|
|
3186 DO RESUME .5
|
|
|
3187 @end example
|
|
|
3188
|
|
|
3189 The @code{NEXT} command takes a line label as its argument (unlike
|
|
|
3190 most other @ical{} commands, it comes after its argument rather than
|
|
|
3191 before); both @code{FORGET} and @code{RESUME} take expressions.
|
|
|
3192 (@clcic{} from version 0.05 onwards also allows an expression in
|
|
|
3193 @code{NEXT}, rather than a label, to give a computed @code{NEXT}, but
|
|
|
3194 this behaviour was not implemented in other compilers, and is
|
|
|
3195 deprecated in @clcic{} along with noncomputed @code{NEXT}; if computed
|
|
|
3196 @code{NEXT} is ever implemented in @cic{}, it will likely likewise be
|
|
|
3197 deprecated upon introduction). (Update: it was implemented in @cic{}
|
|
|
3198 version 0.28, but only as part of the external calls system, so it
|
|
|
3199 cannot be used in ordinary programs; a sample expansion library gives
|
|
|
3200 in-program access to a limited form of computed @code{NEXT}, but
|
|
|
3201 should probably not be used.) Running a @code{NEXT} causes the
|
|
|
3202 program control to transfer to the command whose line label is
|
|
|
3203 referenced, and also saves the location in the program immediately
|
|
|
3204 after the @code{NEXT} command on the top of the NEXT stack.
|
|
|
3205
|
|
|
3206 In order to remove items from the @code{NEXT} stack, to prevent it
|
|
|
3207 filling up (which is what happens with a naive attempt to use the
|
|
|
3208 @code{NEXT} command as an equivalent to what some other languages call
|
|
|
3209 GOTO), it is possible to use the @code{FORGET} or @code{RESUME}
|
|
|
3210 commands. They each remove a number of items from the NEXT stack
|
|
|
3211 equal to their argument; @code{RESUME} also transfers control flow to
|
|
|
3212 the last location removed from the @code{NEXT} stack this way. Trying
|
|
|
3213 to remove no items, or more items than there are in the stack, does
|
|
|
3214 not cause an error when @code{FORGET} is used (no items or all the
|
|
|
3215 items are removed respectively); however, both of these cases are
|
|
|
3216 errors in a @code{RESUME} statement.
|
|
|
3217
|
|
|
3218 Traditionally, boolean values in @ical{} programs have been stored
|
|
|
3219 using #1 and #2 as the two logic levels. This is because the easiest
|
|
|
3220 way to implement an if-like construct in @icst{} is by @code{NEXTING},
|
|
|
3221 then @code{NEXTING} again, then @code{RESUMING} either by 1 or 2
|
|
|
3222 according to an expression, and then if the expression evaluated to 1
|
|
|
3223 @code{FORGETTING} the remaining NEXT stack entry. By the way, the
|
|
|
3224 previous sentence also explained what the appropriate gerunds are for
|
|
|
3225 @code{NEXT}, @code{RESUME}, and @code{FORGET}.
|
|
|
3226
|
|
|
3227 @node STASH and RETRIEVE
|
|
|
3228 @section STASH and RETRIEVE
|
|
|
3229 @anchor{STASH}
|
|
|
3230 @anchor{RETRIEVE}
|
|
|
3231 @findex STASH
|
|
|
3232 @findex RETRIEVE
|
|
|
3233 @findex STASHING
|
|
|
3234 @findex RETRIEVING
|
|
|
3235 @cindex stack, variable
|
|
|
3236 @cindex stashes
|
|
|
3237 @cindex variables, stashes
|
|
|
3238 @portability{yes, all versions, all versions, all versions}
|
|
|
3239
|
|
|
3240 The NEXT stack is not the only stack available in an @ical{} program;
|
|
|
3241 each variable used in the program also has its own stack, which holds
|
|
|
3242 values of the same type as the variable. The @code{STASH} command
|
|
|
3243 pushes a variable's value onto that variable's stack; @code{RETRIEVE}
|
|
|
3244 can be used in the same way to pop the top element of a variable's
|
|
|
3245 stack to replace that variable's value. The syntax is the same as
|
|
|
3246 most other @ical{} commands, with the word @code{STASH} or
|
|
|
3247 @code{RETRIEVE} followed by the variable or variables to stash or
|
|
|
3248 retrieve:
|
|
|
3249
|
|
|
3250 @example
|
|
|
3251 DO STASH .1 + ;2
|
|
|
3252 DO RETRIEVE ,3
|
|
|
3253 @end example
|
|
|
3254
|
|
|
3255 Note that it is possible to stash or retrieve multiple variables at
|
|
|
3256 once, by listing their names separated by intersections (@code{+});
|
|
|
3257 it's even possible to stash or retrieve a variable twice in the same
|
|
|
3258 statement.
|
|
|
3259
|
|
|
3260 It is not entirely clear how @code{RETRIEVE} interacts with
|
|
|
3261 @code{IGNORE} in historical @icst{} compilers; the three modern
|
|
|
3262 @ical{} compilers all use different rules for the interaction (and the
|
|
|
3263 @cic{} maintainers recommend that if anyone decides to write their own
|
|
|
3264 compiler, they choose yet another different rule so that looking at
|
|
|
3265 the interaction (the so-called `ignorret test') can be used as a
|
|
|
3266 method of determining which compiler is running):
|
|
|
3267
|
|
|
3268 @cindex @code{IGNORE}/@code{RETRIEVE} interaction
|
|
|
3269 @cindex @code{RETRIEVE}/@code{IGNORE} interaction
|
|
|
3270 @cindex ignorret test
|
|
|
3271 @itemize
|
|
|
3272 @item
|
|
|
3273 @cic{} treats a retrieval just like an assignment. That is, a
|
|
|
3274 read-only variable will not be changed by a retrieval, and will remain
|
|
|
3275 read-only, but the side-effect of popping that variable's stash will
|
|
|
3276 still happen.
|
|
|
3277
|
|
|
3278 @item
|
|
|
3279 @jic{} ignores the read-only status of a variable when retrieving it
|
|
|
3280 from a stash; the value of the variable changes despite being
|
|
|
3281 read-only. The variable remains read-only; the @code{RETRIEVE} simply
|
|
|
3282 allows a change to its value despite the read-only status.
|
|
|
3283
|
|
|
3284 @item
|
|
|
3285 @clcic{} is the most complicated; it stores read-only status or
|
|
|
3286 otherwise in the stash, along with the variable's value. This means
|
|
|
3287 that if a variable was stashed when read-only, retrieving it will
|
|
|
3288 retrieve its value and set it to read-only regardless of its previous
|
|
|
3289 read-only status; likewise, if a variable was stashed when read-write,
|
|
|
3290 retrieving it will retrieve its value and set it to read-write even if
|
|
|
3291 it was previously read-only.
|
|
|
3292
|
|
|
3293 @end itemize
|
|
|
3294
|
|
|
3295 The appropriate gerunds for @code{STASH} and @code{RETRIEVE} are
|
|
|
3296 @code{STASHING} and @code{RETRIEVING} respectively.
|
|
|
3297
|
|
|
3298 @node IGNORE and REMEMBER
|
|
|
3299 @section IGNORE and REMEMBER
|
|
|
3300 @anchor{IGNORE}
|
|
|
3301 @anchor{REMEMBER}
|
|
|
3302 @findex IGNORE
|
|
|
3303 @findex IGNORING
|
|
|
3304 @findex REMEMBER
|
|
|
3305 @findex REMEMBERING
|
|
|
3306 @cindex variables, read-only
|
|
|
3307 @cindex variables, read-write
|
|
|
3308 @cindex read-only variables
|
|
|
3309 @cindex read-write variables
|
|
|
3310 @cindex variables, ignoring
|
|
|
3311 @cindex variables, remembering
|
|
|
3312 @portability{yes, all versions, all versions, all versions}
|
|
|
3313
|
|
|
3314 Variables in @ical{} can be either read-write or read-only. At the
|
|
|
3315 start of a program, all variables are read-write, but this status can
|
|
|
3316 be changed dynamically during execution of a program using the
|
|
|
3317 @code{IGNORE} and @code{REMEMBER} statements (whose gerunds are
|
|
|
3318 @code{IGNORING} and @code{REMEMBERING} respectively). The syntax is
|
|
|
3319 the same as for @code{STASH} and @code{RETRIEVE}: the command's name
|
|
|
3320 followed by an intersection-separated list of variables. For
|
|
|
3321 instance:
|
|
|
3322
|
|
|
3323 @example
|
|
|
3324 DO IGNORE .4
|
|
|
3325 DO REMEMBER ,4 + ;5
|
|
|
3326 @end example
|
|
|
3327
|
|
|
3328 Using the @code{IGNORE} statement sets a variable to be read-only (or
|
|
|
3329 does nothing if it's read-only already); @code{REMEMBER} sets it to be
|
|
|
3330 read-write. Any attempt to assign to a read-only variable silently
|
|
|
3331 fails. One place that this is used is in the system library; instead
|
|
|
3332 of not assigning to a variable in certain control flow paths, it
|
|
|
3333 instead sets it to be read-only so that subsequent assignments don't
|
|
|
3334 change its value (and sets it to be read-write at the end, which
|
|
|
3335 succeeds even if it was never set read-only in the first place); the
|
|
|
3336 advantage of this is that it doesn't need to remember what flow path
|
|
|
3337 it's on except in the variable's ignorance status.
|
|
|
3338
|
|
|
3339 The interaction between @code{IGNORE} and @code{RETRIEVE} was never
|
|
|
3340 defined very clearly, and is in fact different in @cic{}, @clcic{} and
|
|
|
3341 @jic{}; for more details, see @ref{RETRIEVE}.
|
|
|
3342
|
|
|
3343 @node ABSTAIN and REINSTATE
|
|
|
3344 @section ABSTAIN and REINSTATE
|
|
|
3345 @anchor{ABSTAIN}
|
|
|
3346 @anchor{REINSTATE}
|
|
|
3347 @findex ABSTAIN
|
|
|
3348 @findex ABSTAINING
|
|
|
3349 @findex REINSTATE
|
|
|
3350 @findex REINSTATING
|
|
|
3351 @cindex abstain, during execution
|
|
|
3352 @cindex reinstate, during execution
|
|
|
3353 @portability{yes, all versions, all versions, all versions}
|
|
|
3354
|
|
|
3355 The statement identifier of a statement determines whether it's
|
|
|
3356 in an abstained or reinstated state at the start of a program; these
|
|
|
3357 states determine whether the statement runs at all when it's
|
|
|
3358 encountered. It is, however, possible to change this state
|
|
|
3359 dynamically during a program's execution, and the statements to do
|
|
|
3360 this are rather appropriately named @code{ABSTAIN} and
|
|
|
3361 @code{REINSTATE}. There are two forms of each, one which takes a
|
|
|
3362 single line label (which must be constant in most compilers, but can
|
|
|
3363 instead be an expression in recent @clcic{} versions), and one which
|
|
|
3364 takes an intersection-delimited list of gerunds. They look like this:
|
|
|
3365
|
|
|
3366 @example
|
|
|
3367 DO ABSTAIN FROM ABSTAINING + REINSTATING
|
|
|
3368 DO ABSTAIN FROM (10)
|
|
|
3369 DO REINSTATE CALCULATING
|
|
|
3370 DO REINSTATE (22)
|
|
|
3371 @end example
|
|
|
3372
|
|
|
3373 (This also illustrates the gerunds used for these commands; note that
|
|
|
3374 @code{ABSTAINING} from @code{REINSTATING} is generally a bad idea@!)
|
|
|
3375 The line referenced, or every command represented by any gerund
|
|
|
3376 referenced, are reinstated or abstained as appropriate (effectively
|
|
|
3377 changing the DO to DON'T (or PLEASE to PLEASE DON'T, etc.@:), or vice
|
|
|
3378 versa). Using these forms of @code{ABSTAIN} and/or @code{REINSTATE}
|
|
|
3379 won't abstain from a command that's already abstained, or reinstate a
|
|
|
3380 command that's already reinstated.
|
|
|
3381
|
|
|
3382 There is a strange set of restrictions on @code{ABSTAIN} and
|
|
|
3383 @code{REINSTATE} that has existed since @icst{}; historically such
|
|
|
3384 restrictions have not always been implemented, or have not been
|
|
|
3385 implemented properly. They together define an unusual interaction of
|
|
|
3386 @code{ABSTAIN} and @code{GIVE UP} (note, for instance, that there
|
|
|
3387 isn't a gerund for @code{GIVE UP}). The wording used in the @icst{}
|
|
|
3388 manual is:
|
|
|
3389
|
|
|
3390 @quotation
|
|
|
3391 [...] the statement DO ABSTAIN FROM GIVING UP is not accepted, even
|
|
|
3392 though DON'T GIVE UP is. [...] DO REINSTATE GIVING UP is invalid, and
|
|
|
3393 attempting to REINSTATE a GIVE UP statement by line label will have no
|
|
|
3394 effect. Note that this insures that DON'T GIVE UP will always be a
|
|
|
3395 "do-nothing" statement.
|
|
|
3396 @end quotation
|
|
|
3397
|
|
|
3398 This restriction was not implemented at all in the only @clcic{}
|
|
|
3399 version before 0.02 (i.e.@: version 0.01), or in @cic{} versions
|
|
|
3400 before 1.26. The restriction was implemented in @cic{} version 1.26
|
|
|
3401 and @clcic{} versions 0.02 and later as ``@code{GIVE UP} cannot be
|
|
|
3402 @code{REINSTATED} or @code{ABSTAINED FROM}''; however, this is not
|
|
|
3403 strictly the same as the definition used by @icst{} (@cic{} still uses
|
|
|
3404 this definition in @clcic{} compatibility mode). The @jic{}
|
|
|
3405 implementation of this restriction is to make @code{REINSTATING} or
|
|
|
3406 @code{ABSTAINING} from a line label that refers to a @code{GIVE UP}
|
|
|
3407 statement a compile-time error, but this does not fit the @icst{}
|
|
|
3408 definition either. The definition adopted with version 0.27 and
|
|
|
3409 later of @cic{}, which is hopefully correct, is to allow abstaining
|
|
|
3410 from a @code{GIVE UP} statement by line number but to rule out the
|
|
|
3411 other three cases (reinstating by line number silently fails,
|
|
|
3412 reinstating or abstaining by gerund is impossible because there is no
|
|
|
3413 gerund).
|
|
|
3414
|
|
|
3415 As well as @clcic{}'s extension to abstain/reinstate by computed line
|
|
|
3416 number, there is also (since version 0.25) a @cic{}-specific extension
|
|
|
3417 to @code{ABSTAIN}, also known as `computed abstain', but with a
|
|
|
3418 different syntax and different semantics. It's written like an
|
|
|
3419 ordinary @code{ABSTAIN}, but with an expression between the words
|
|
|
3420 @code{ABSTAIN} and @code{FROM}, for instance:
|
|
|
3421
|
|
|
3422 @example
|
|
|
3423 DO ABSTAIN #1 FROM (1000)
|
|
|
3424 DO ABSTAIN .2 FROM WRITING IN
|
|
|
3425 @end example
|
|
|
3426
|
|
|
3427 Unlike non-computed @code{ABSTAIN}, this form allows a command to be
|
|
|
3428 abstained from even if it's already been abstained from; so if the
|
|
|
3429 first example command is run and line (1000) is already abstained, it
|
|
|
3430 becomes `double-abstained'. The number of times the statement is
|
|
|
3431 abstained from is equal to the number of times it was already
|
|
|
3432 abstained from, plus the expression (whereas with non-computed
|
|
|
3433 abstain, it ends up abstained once if it wasn't abstained at all, and
|
|
|
3434 otherwise stays at the same abstention status). Reinstating a
|
|
|
3435 statement always de-abstains it exactly once; so double-abstaining
|
|
|
3436 from a statement, for instance, means it needs to be reinstated twice
|
|
|
3437 before it will actually execute.
|
|
|
3438
|
|
|
3439 There are many uses for @code{ABSTAIN} (both the computed and
|
|
|
3440 non-computed versions) and @code{REINSTATE}, especially when
|
|
|
3441 interacting with @code{ONCE} and @code{AGAIN} (@pxref{ONCE and
|
|
|
3442 AGAIN}); the computed version, in particular, is a major part of a
|
|
|
3443 particular concise way to write conditionals and certain kinds of
|
|
|
3444 loops. They also play an important role in multithreaded programs.
|
|
|
3445
|
|
|
3446 @node READ OUT and WRITE IN
|
|
|
3447 @section READ OUT and WRITE IN
|
|
|
3448 @anchor{READ OUT}
|
|
|
3449 @anchor{WRITE IN}
|
|
|
3450 @findex READ OUT
|
|
|
3451 @findex READING OUT
|
|
|
3452 @findex WRITE IN
|
|
|
3453 @findex WRITING IN
|
|
|
3454 @cindex I/O
|
|
|
3455 @cindex input
|
|
|
3456 @cindex output
|
|
|
3457
|
|
|
3458 The @code{READ OUT} and @code{WRITE IN} commands are the output and
|
|
|
3459 input commands in @ical{}; they allow communication between the
|
|
|
3460 program and its user. There was a numeric I/O mechanism implemented
|
|
|
3461 in @icst{}, and it (or trivial variants) have been likewise
|
|
|
3462 implemented in all more modern variants. However, it had some obvious
|
|
|
3463 deficiences (such as not being able to read its own output) which
|
|
|
3464 meant that other methods of I/O were implemented in @cic{} and
|
|
|
3465 @clcic{}.
|
|
|
3466
|
|
|
3467 The syntax of @code{READ OUT} and @code{WRITE IN} is the same in all
|
|
|
3468 cases: the name of the command followed by an intersection-separated
|
|
|
3469 list of items; the form of each item, the compiler you are using, and
|
|
|
3470 its command line arguments together determine what sort of I/O is
|
|
|
3471 used, which can be different for different elements in the list.
|
|
|
3472
|
|
|
3473 @menu
|
|
|
3474 * INTERCAL-72 I/O:: Spelt-out numbers and Roman numerals
|
|
|
3475 * C-INTERCAL I/O:: The Turing Tape I/O system
|
|
|
3476 * CLC-INTERCAL I/O:: Baudot and mingled binary
|
|
|
3477 @end menu
|
|
|
3478
|
|
|
3479 @node INTERCAL-72 I/O
|
|
|
3480 @subsection INTERCAL-72 I/O
|
|
|
3481 @cindex I/O, INTERCAL-72
|
|
|
3482 @cindex input, INTERCAL-72
|
|
|
3483 @cindex output, INTERCAL-72
|
|
|
3484 @cindex INTERCAL-72, I/O
|
|
|
3485 @cindex Roman numerals
|
|
|
3486
|
|
|
3487 @portability{yes, all versions, see text, all versions}
|
|
|
3488
|
|
|
3489 @icst{} had its own versions of I/O commands; these commands are
|
|
|
3490 available in all modern @ical{} compilers as well (but @clcic{}
|
|
|
3491 implements output slightly differently). To distinguish @icst{} input
|
|
|
3492 and output from the other more modern types of I/O, the @code{READ
|
|
|
3493 OUT} and @code{WRITE IN} commands must take one of the following
|
|
|
3494 values: a onespot or twospot variable, a single element of a tail or
|
|
|
3495 hybrid array, or (in the case of @code{READ OUT}) a constant, meaning
|
|
|
3496 that these are some examples of the possible forms:
|
|
|
3497
|
|
|
3498 @example
|
|
|
3499 READ OUT .1
|
|
|
3500 READ OUT ;2 SUB .3:4
|
|
|
3501 READ OUT #3
|
|
|
3502 WRITE IN :4
|
|
|
3503 WRITE IN ,5 SUB #6
|
|
|
3504 @end example
|
|
|
3505
|
|
|
3506 The statements do what you would expect; @code{READ OUT} outputs its
|
|
|
3507 argument to the user, and @code{WRITE IN} inputs a number from the
|
|
|
3508 user and assigns it to the variable or array element referenced. (If
|
|
|
3509 the variable, or the array that contains the array element, happens to
|
|
|
3510 be read-only, the input or output still happens but in the case of
|
|
|
3511 @code{WRITE IN} silently skips the assignment, instead throwing away
|
|
|
3512 the input.) The formats used for input and output are, however,
|
|
|
3513 different from each other and from the formats used by most mainstream
|
|
|
3514 languages.
|
|
|
3515
|
|
|
3516 Input is achieved by writing a number in decimal, one digit at a time,
|
|
|
3517 with each digit written out as a word; so to input the number 12345, a
|
|
|
3518 user would have to type @code{ONE TWO THREE FOUR FIVE} as input (if
|
|
|
3519 they were using English, the most portable choice of language). In
|
|
|
3520 @icst{} only English is accepted as a language, but other compilers
|
|
|
3521 accept other languages in addition. @cic{} from version 0.10 onwards
|
|
|
3522 accepts English, Sanskrit, Basque, Tagalog, Classical Nahuatl,
|
|
|
3523 Georgian, and Kwakiutl; also Volap@"uk from version 0.11 onwards, and
|
|
|
3524 Latin from version 0.20 onwards. @jic{} accepts the same languages,
|
|
|
3525 except with Esperanto instead of Latin; from version 0.05 of @clcic{}
|
|
|
3526 onwards, the same list of languages as @cic{} is supported (apart from
|
|
|
3527 Latin, which was added in version 1.-94.-8), plus Scottish Gaelic.
|
|
|
3528
|
|
|
3529 The format that output can be read in is a modified form of Roman
|
|
|
3530 numerals, known as `butchered' Roman numerals. @icst{}, @cic{} and
|
|
|
3531 @jic{} do this the same way; @clcic{} is somewhat different. The
|
|
|
3532 characters @samp{I}, @samp{V}, @samp{X}, @samp{L}, @samp{C}, @samp{D},
|
|
|
3533 and @samp{M} mean 1, 5, 10, 50, 100, 500 and 1000 respectively,
|
|
|
3534 placing a lower-valued letter after a higher-valued letter adds them,
|
|
|
3535 and placing a lower-valued letter before a higher-valued letter
|
|
|
3536 subtracts it from the value; so @samp{XI} is 11 and @samp{IX} is 9,
|
|
|
3537 for instance. In @icst{}, @cic{}, and @jic{}, a bar over a numeral
|
|
|
3538 multiplies its value by 1000, and writing a letter in lowercase
|
|
|
3539 multiplies its value by 1000000; however, @clcic{} uses lowercase to
|
|
|
3540 represent multiplication by 1000 and for multiplication by 1000000
|
|
|
3541 writes a backslash before the relevant numeral.
|
|
|
3542
|
|
|
3543 @node C-INTERCAL I/O
|
|
|
3544 @subsection C-INTERCAL I/O
|
|
|
3545 @cindex I/O, C-INTERCAL
|
|
|
3546 @cindex input, C-INTERCAL
|
|
|
3547 @cindex output, C-INTERCAL
|
|
|
3548 @cindex C-INTERCAL, I/O
|
|
|
3549 @cindex Turing Tape
|
|
|
3550
|
|
|
3551 @portability{no, version 0.07+, version 0.05+, no}
|
|
|
3552
|
|
|
3553 @cic{}'s method of character-based (rather than numeric) input and
|
|
|
3554 output is known as the Turing Tape method; it is a binary
|
|
|
3555 (character-set-agnostic) input/output mechanism. To specify that
|
|
|
3556 @cic{}-style I/O is being used, an array must be used as the argument
|
|
|
3557 to @code{READ OUT} or @code{WRITE IN}; as the syntax is the same as
|
|
|
3558 for @clcic{}'s I/O, command-line arguments and the capabilities of the
|
|
|
3559 version of the compiler being used serve to distinguish the two
|
|
|
3560 mechanisms.
|
|
|
3561
|
|
|
3562 The character-based input writes as many characters into a tail or
|
|
|
3563 hybrid array as will fit, one character in each element. The number
|
|
|
3564 that's written into the array is not the character code, though, but
|
|
|
3565 the difference between the character code and the previous character
|
|
|
3566 code, modulo 256. (To be precise, the code is the new character minus
|
|
|
3567 the previous character, or 256 minus (the previous character minus the
|
|
|
3568 new character) if the previous character had a higher character code;
|
|
|
3569 the 'previous character' is the previous character from the input, not
|
|
|
3570 the previous character written into the array.) End-of-file causes
|
|
|
3571 256 to be written into the array. The concept is that of a circular
|
|
|
3572 tape containing all the characters, where the program measures how
|
|
|
3573 many spaces it needs to move along the tape to reach the next
|
|
|
3574 character. The 'previous character' starts at 0, but is preserved
|
|
|
3575 throughout the entire program, even from one @code{WRITE IN} to the
|
|
|
3576 next.
|
|
|
3577
|
|
|
3578 Character-based output uses a similar model, but conceptually the
|
|
|
3579 output device moves on the inside of the tape, rather than on the
|
|
|
3580 outside. Therefore, the character is that is actually output is the
|
|
|
3581 bit-reversal of the difference between the last character output
|
|
|
3582 before it was bit-reversed and the number found in the array
|
|
|
3583 (subtracting in that order, and adding 256 if the result is
|
|
|
3584 negative). (Rather than trying to parse the previous sentence, you
|
|
|
3585 may find it easier to look either at the source code to the compiler
|
|
|
3586 if you have it (the relevant part is binout in @file{src/cesspool.c})
|
|
|
3587 or at some example @cic{} programs that do text-based I/O.)
|
|
|
3588
|
|
|
3589 @node CLC-INTERCAL I/O
|
|
|
3590 @subsection CLC-INTERCAL I/O
|
|
|
3591 @cindex Baudot
|
|
|
3592 @cindex I/O, Baudot
|
|
|
3593 @cindex I/O, CLC-INTERCAL
|
|
|
3594 @cindex CLC-INTERCAL I/O
|
|
|
3595 @cindex input, CLC-INTERCAL
|
|
|
3596 @cindex output, CLC-INTERCAL
|
|
|
3597
|
|
|
3598 @portability{no, see text, all versions, no}
|
|
|
3599
|
|
|
3600 There are also two @clcic{}-specific I/O mechanisms. These are
|
|
|
3601 Baudot-based text I/O (which is also implemented from @cic{} version
|
|
|
3602 0.27 onwards), and @clcic{} generalised binary I/O (not implemented in
|
|
|
3603 @cic{}).
|
|
|
3604
|
|
|
3605 Baudot text-based I/O is specified by using a tail array as an
|
|
|
3606 argument to @code{WRITE IN} or @code{READ OUT}. (A tail array can
|
|
|
3607 also be used to specify @cic{}-style Turing Tape I/O. In order to
|
|
|
3608 determine which is used: both @cic{} and @clcic{} use their own sort
|
|
|
3609 of I/O unless a command-line argument instructs them to use the
|
|
|
3610 other.) In the case of @code{WRITE IN}, one line of input is
|
|
|
3611 requested from the user (@cic{} requires this to be input in Latin-1,
|
|
|
3612 and will then automatically convert it; @clcic{} gives the option of
|
|
|
3613 various character sets for this input as command-line options); the
|
|
|
3614 final newline is removed from this line, then it is converted to
|
|
|
3615 extended Baudot and stored in the tail array specified (causing an
|
|
|
3616 error if the array is too small). Because Baudot is only a 5-bit
|
|
|
3617 character set, each element is padded to 16 bits; @clcic{} pads with
|
|
|
3618 zeros, @cic{} pads with random bits. Trying to input at end-of-file
|
|
|
3619 will act as if the input were a blank line. @code{READ OUT} is the
|
|
|
3620 reverse; it interprets the array as extended Baudot and converts it to
|
|
|
3621 an appropriate character set (Latin-1 for @cic{}, or whatever was
|
|
|
3622 specified on the command line for @clcic{}), which is output to the
|
|
|
3623 user, followed by a newline. Note that the Baudot is often longer
|
|
|
3624 than the corresponding character in other character sets due to the
|
|
|
3625 need to insert shift codes; for information on the extended Baudot
|
|
|
3626 character set, @ref{Character Sets}.
|
|
|
3627
|
|
|
3628 Generalised binary I/O is specified using a hybrid array as an
|
|
|
3629 argument to @code{WRITE IN} or @code{READ OUT}. Input works by
|
|
|
3630 reading in a number of bytes equal to the length of the array (without
|
|
|
3631 trying to interpret them or translating them to a different character
|
|
|
3632 set), prepending a byte with 172 to the start, padding each byte to 16
|
|
|
3633 bits with random data, then replacing each pair of consecutive bytes
|
|
|
3634 (that is, the first and second, the second and third, the third and
|
|
|
3635 fourth, and so on) with (the first element selected from the second
|
|
|
3636 element) mingled with (the complement of the first element selected from
|
|
|
3637 the complement of the second element). Output is the exact opposite
|
|
|
3638 of this process. End-of-file reads a 0, which is padded with 0s
|
|
|
3639 rather than random data; if a non-end-of-file 0 comes in from the
|
|
|
3640 data, its padding will contain at least one 1. Any
|
|
|
3641 all-bits-0-even-the-padding being read out will be skipped.
|
|
|
3642
|
|
|
3643 @node GIVE UP
|
|
|
3644 @section GIVE UP
|
|
|
3645 @findex GIVE UP
|
|
|
3646 @cindex quitting
|
|
|
3647 @cindex exiting
|
|
|
3648
|
|
|
3649 @portability{yes, all versions, all versions, all versions}
|
|
|
3650
|
|
|
3651 The @code{GIVE UP} command causes the program to end (or, in a
|
|
|
3652 multithreaded program, causes the current thread to end). It is
|
|
|
3653 written simply as @code{GIVE UP}. There is not much else to say about
|
|
|
3654 it, except to mention that it is the only way to end the program
|
|
|
3655 without an error unless the last line of the program is @code{TRY
|
|
|
3656 AGAIN}, and that it has an unusual interaction with @code{ABSTAIN};
|
|
|
3657 for details of this, see @ref{ABSTAIN}. (Going past the last command
|
|
|
3658 in the program is an error.)
|
|
|
3659
|
|
|
3660 There is no gerund for @code{GIVE UP}; in particular, @code{GIVING UP}
|
|
|
3661 is a syntax error.
|
|
|
3662
|
|
|
3663 @node TRY AGAIN
|
|
|
3664 @section TRY AGAIN
|
|
|
3665 @findex TRY AGAIN
|
|
|
3666 @cindex loops, entire program
|
|
|
3667
|
|
|
3668 @portability{no, version 0.25+, no, no}
|
|
|
3669
|
|
|
3670 The @code{TRY AGAIN} command is a very simple command with many
|
|
|
3671 limitations; its effect is to place the entire program in a loop. If
|
|
|
3672 it exists, it must be the very last command in the program (it cannot
|
|
|
3673 even be followed by syntax errors), and it causes execution of the
|
|
|
3674 program to go back to the first command. If the @code{TRY AGAIN}
|
|
|
3675 command is abstained or for some other reason doesn't execute when
|
|
|
3676 reached, it exits the program without the error that would usually be
|
|
|
3677 caused by going past the last line of code.
|
|
|
3678
|
|
|
3679 The gerund for @code{TRY AGAIN} is @code{TRYING AGAIN}.
|
|
|
3680
|
|
|
3681 @node COME FROM and NEXT FROM
|
|
|
3682 @section COME FROM and NEXT FROM
|
|
|
3683 @anchor{COME FROM}
|
|
|
3684 @anchor{NEXT FROM}
|
|
|
3685 @findex COME FROM
|
|
|
3686 @findex NEXT FROM
|
|
|
3687 @cindex reverse goto
|
|
|
3688 @cindex goto, time-reversed
|
|
|
3689 @cindex time-reversed goto
|
|
|
3690
|
|
|
3691 @portability{no, see text, see text, see text}
|
|
|
3692
|
|
|
3693 The @code{COME FROM} statement (incidentally also invented in 1972,
|
|
|
3694 but not in connection with @ical{}) is the main control-flow command
|
|
|
3695 in @clcic{} (which deprecates @code{NEXT}), and one of two main
|
|
|
3696 control flow structures in other modern @ical{} compilers. It takes
|
|
|
3697 either a label or an expression as its argument; these forms are
|
|
|
3698 noncomputed @code{COME FROM} and computed @code{COME FROM}.
|
|
|
3699
|
|
|
3700 Noncomputed @code{COME FROM} was implemented in version 0.5 of @cic{},
|
|
|
3701 but did not conform to modern-day semantics until version 0.7; it is
|
|
|
3702 available in every version of @clcic{} and @jic{}. Computed
|
|
|
3703 @code{COME FROM} support is available in every version of @clcic{} and
|
|
|
3704 in @cic{} from version 0.25 onwards, but not in @jic{}; the variant
|
|
|
3705 @code{NEXT FROM} of @code{COME FROM} is available from @clcic{}
|
|
|
3706 version 1.-94.-8 and @cic{} version 0.26 (both computed and
|
|
|
3707 noncomputed). @cic{} and @clcic{} also have a from-gerund form of
|
|
|
3708 @code{COME FROM} and @code{NEXT FROM}, which was also implemented from
|
|
|
3709 @clcic{} version 1.-94.-8 and @cic{} version 0.26.
|
|
|
3710
|
|
|
3711 The basic rule of @code{COME FROM} is that if a @code{COME FROM}
|
|
|
3712 statement references another statement, whenever that statement is
|
|
|
3713 reached, control flow will be transferred to the @code{COME FROM}
|
|
|
3714 after that statement finishes executing. (@code{NEXT FROM} is
|
|
|
3715 identical except that in addition to the @code{COME FROM} behaviour,
|
|
|
3716 the location immediately after the statement that was nexted from is
|
|
|
3717 saved on the NEXT stack, in much the same way as if the statement
|
|
|
3718 being nexted from was itself a @code{NEXT}.)
|
|
|
3719
|
|
|
3720 Here are examples of noncomputed, computed, and from-gerund @code{COME
|
|
|
3721 FROM}:
|
|
|
3722
|
|
|
3723 @example
|
|
|
3724 DO COME FROM (10)
|
|
|
3725 DO COME FROM #2$'.1~#1'
|
|
|
3726 DO COME FROM COMING FROM
|
|
|
3727 @end example
|
|
|
3728
|
|
|
3729 (The last example is an infinite loop. If it said @code{DO NEXT FROM
|
|
|
3730 NEXTING FROM}, it would not be an infinite loop because the NEXT stack
|
|
|
3731 would overflow and cause an error. This also establishes the gerunds
|
|
|
3732 used for @code{COME FROM} and @code{NEXT FROM}.)
|
|
|
3733
|
|
|
3734 There are some things to be careful with involving @code{COME FROM}
|
|
|
3735 and @code{NEXT FROM}. First, if the statement come from or nexted
|
|
|
3736 from happens to be a @code{NEXT}, the @code{NEXT} doesn't count as
|
|
|
3737 'finishing executing' until the NEXT stack entry created by the
|
|
|
3738 @code{NEXT} is @code{RESUME}d to. In particular, this means that if
|
|
|
3739 @code{FORGET} is used to remove the entry, or a @code{RESUME} with a
|
|
|
3740 large argument resumes a lower entry, the @code{COME FROM} doesn't
|
|
|
3741 steal execution at all.
|
|
|
3742
|
|
|
3743 Second, you may be wondering what happens if two @code{COME FROM}s or
|
|
|
3744 @code{NEXT FROM}s aim at the same line. In a non-multithreaded
|
|
|
3745 program (whether a program is multithreaded or not is determined by a
|
|
|
3746 compiler option for those compilers that support it), this is an
|
|
|
3747 error; but it is only an error if the statement that they both point
|
|
|
3748 to finishes running, and both @code{COME FROM}s or @code{NEXT FROM}s
|
|
|
3749 try to execute as a result (they might not if, for instance, one is
|
|
|
3750 abstained or has a double-oh-seven causing it not to run some of the
|
|
|
3751 time). If both @code{COME FROM}s or @code{NEXT FROM}s are
|
|
|
3752 noncomputed, however, a compiler can (but does not have to) give a
|
|
|
3753 compile time error if two @code{COME FROM}s or @code{NEXT FROM}s share
|
|
|
3754 a label, and so that situation should be avoided in portable code.
|
|
|
3755 (If it is wanted, one solution that works for @cic{} and @clcic{} is
|
|
|
3756 to use computed @code{COME FROM}s or @code{NEXT FROM}s with a constant
|
|
|
3757 expression.)
|
|
|
3758
|
|
|
3759 @node System Library
|
|
|
3760 @chapter System Library
|
|
|
3761 @cindex system libary
|
|
|
3762 @cindex syslib
|
|
|
3763
|
|
|
3764 @portability{yes, all versions, no, all versions}
|
|
|
3765
|
|
|
3766 @ical{} has a system library, called @samp{syslib}. It is included
|
|
|
3767 automatically at the end of your program by the compiler whenever your
|
|
|
3768 program refers to a line from (1000) to (1999) without defining any
|
|
|
3769 line in that range in the program. (Although it is not added
|
|
|
3770 automatically by the compiler in @clcic{}, it is trivial to
|
|
|
3771 concatenate a copy onto the end of the program; copies of the system
|
|
|
3772 library are available from many sources on the Internet, including a
|
|
|
3773 version in the example code that comes with @cic{}.)
|
|
|
3774
|
|
|
3775 The intention of the system library is to provide a range of useful
|
|
|
3776 capabilities, like multiplication, that can otherwise be hard to write
|
|
|
3777 in @ical{}. System library routines are used by @code{NEXTING} to
|
|
|
3778 their line number (@pxref{NEXT}), where they will make changes to
|
|
|
3779 certain variables depending on certain other variables (depending on
|
|
|
3780 which routine is called), and @code{RESUME} back to the original
|
|
|
3781 program. As the system library is itself written in @ical{}, there
|
|
|
3782 are some restrictions that need to be obeyed for calls to it to be
|
|
|
3783 guaranteed to work; none of the variables it uses (@code{.1} to
|
|
|
3784 @code{.6} and @code{:1} to @code{:5}) should be read-only or
|
|
|
3785 overloaded (although the value of any variables that aren't mentioned
|
|
|
3786 in the routine's description will be preserved by the routine), and
|
|
|
3787 none of the lines in it should have their abstention status changed by
|
|
|
3788 lines outside it (this can happen with blatant infractions like
|
|
|
3789 @code{DO ABSTAIN FROM (1500)} or more subtle problems like
|
|
|
3790 gerund-abstention) or have @code{COME FROM}s or @code{NEXT FROM}s
|
|
|
3791 aiming at them.
|
|
|
3792
|
|
|
3793 The system library is currently available in all bases from 2 to 7
|
|
|
3794 (@pxref{TriINTERCAL}), but not every command is available in every
|
|
|
3795 base, and @cic{} is the only one of the three compilers listed above
|
|
|
3796 that use the system library to ship with a version in bases other than
|
|
|
3797 2. (This table was originally based on the @icst{} manual, but has
|
|
|
3798 had extra information added for bases other than 2.) Here, ``overflow
|
|
|
3799 checked'' means that #1 is assigned to .4 if there is not an overflow,
|
|
|
3800 and #2 is assigned to .4 if there is; ``overflow captured'' means that
|
|
|
3801 if there is overflow, the digit that overflowed is stored in the
|
|
|
3802 variable referenced. In all cases, division by 0 returns 0.
|
|
|
3803
|
|
|
3804 @multitable @columnfractions .1 .7 .15
|
|
|
3805 @headitem Line @tab Description @tab Bases
|
|
|
3806 @item (1000) @tab
|
|
|
3807 .3 <- .1 plus .2, error exit on overflow
|
|
|
3808 @tab 2, 3, 4, 5, 6, 7
|
|
|
3809 @item (1009) @tab
|
|
|
3810 .3 <- .1 plus .2, overflow checked
|
|
|
3811 @tab 2, 3, 4, 5, 6, 7
|
|
|
3812 @item (1010) @tab
|
|
|
3813 .3 <- .1 minus .2, no action on overflow
|
|
|
3814 @tab 2, 3, 4, 5, 6, 7
|
|
|
3815 @item (1020) @tab
|
|
|
3816 .1 <- .1 plus #1, no action on overflow
|
|
|
3817 @tab 2, 3, 4, 5, 6, 7
|
|
|
3818 @item (1030) @tab
|
|
|
3819 .3 <- .1 times .2, error exit on overflow
|
|
|
3820 @tab 2, 3, 4, 5, 6, 7
|
|
|
3821 @item (1039) @tab
|
|
|
3822 .3 <- .1 times .2, overflow checked
|
|
|
3823 @tab 2, 3, 4, 5, 6, 7
|
|
|
3824 @item (1040) @tab
|
|
|
3825 .3 <- .1 divided by .2
|
|
|
3826 @tab 2, 3, 4, 5, 6, 7
|
|
|
3827 @item (1050) @tab
|
|
|
3828 .2 <- :1 divided by .1, error exit on overflow
|
|
|
3829 @tab 2, 3, 4, 5, 6, 7
|
|
|
3830 @item (1200) @tab
|
|
|
3831 .2 <- .1 times #2, overflow captured in .3
|
|
|
3832 @tab 4, 6
|
|
|
3833 @item (1210) @tab
|
|
|
3834 .2 <- .1 divided by #2, one digit after the quartic or sextic point
|
|
|
3835 stored in .3
|
|
|
3836 @tab 4, 6
|
|
|
3837 @item (1500) @tab
|
|
|
3838 :3 <- :1 plus :2, error exit on overflow
|
|
|
3839 @tab 2, 3, 4, 5, 6, 7
|
|
|
3840 @item (1509) @tab
|
|
|
3841 :3 <- :1 plus :2, overflow checked
|
|
|
3842 @tab 2, 3, 4, 5, 6, 7
|
|
|
3843 @item (1510) @tab
|
|
|
3844 :3 <- :1 minus :2, no action on overflow
|
|
|
3845 @tab 2, 3, 4, 5, 6, 7
|
|
|
3846 @item (1520) @tab
|
|
|
3847 :1 <- .1 concatenated with .2
|
|
|
3848 @tab 2, 3, 4, 5, 6, 7
|
|
|
3849 @item (1530) @tab
|
|
|
3850 :1 <- .1 times .2
|
|
|
3851 @tab 2, 3, 4, 5, 6, 7
|
|
|
3852 @item (1540) @tab
|
|
|
3853 :3 <- :1 times :2, error exit on overflow
|
|
|
3854 @tab 2, 3, 4, 5, 6, 7
|
|
|
3855 @item (1549) @tab
|
|
|
3856 :3 <- :1 times :2, overflow checked
|
|
|
3857 @tab 2, 3, 4, 5, 6, 7
|
|
|
3858 @item (1550) @tab
|
|
|
3859 :3 <- :1 divided by :2
|
|
|
3860 @tab 2, 3, 4, 5, 6, 7
|
|
|
3861 @item (1700) @tab
|
|
|
3862 :2 <- :1 times #2, overflow captured in .1
|
|
|
3863 @tab 4, 6
|
|
|
3864 @item (1710) @tab
|
|
|
3865 :2 <- :1 divided by #2, one digit after the quartic or sextic point
|
|
|
3866 stored in .1
|
|
|
3867 @tab 4, 6
|
|
|
3868 @item (1720) @tab
|
|
|
3869 :2 <- :1 times the least significant digit of .1, overflow captured in
|
|
|
3870 .2
|
|
|
3871 @tab 5, 7
|
|
|
3872 @item (1900) @tab
|
|
|
3873 .1 <- uniform random number from #0 to #65535
|
|
|
3874 @tab 2, 3, 4, 5, 6, 7
|
|
|
3875 @item (1910) @tab
|
|
|
3876 .2 <- normal random number from #0 to .1, with standard deviation .1
|
|
|
3877 divided by #12
|
|
|
3878 @tab 2, 3, 4, 5, 6, 7
|
|
|
3879 @end multitable
|
|
|
3880
|
|
|
3881 If you happen to be using base 2, and are either using the external
|
|
|
3882 call system (@pxref{External Calls}) or are willing to use it, it is
|
|
|
3883 possible to use a version of the system library written in C for
|
|
|
3884 speed, rather than the default version (which is written in @ical{}).
|
|
|
3885 To do this, use the command line options @option{-eE} (before the
|
|
|
3886 @ical{} file), and @option{syslibc} (at the end of the command line).
|
|
|
3887
|
|
|
3888 @ifset notsplit
|
|
|
3889 @partheading{PART III: @ical{} DIALECTS AND EXTENSIONS}
|
|
|
3890 @end ifset
|
|
|
3891 @node TriINTERCAL
|
|
|
3892 @chapter TriINTERCAL
|
|
|
3893 @cindex TriINTERCAL
|
|
|
3894 @cindex ternary
|
|
|
3895 @cindex whirlpool
|
|
|
3896 @cindex sharkfin
|
|
|
3897 @cindex BUT
|
|
|
3898 @cindex add-without-carry
|
|
|
3899 @cindex subtract-without-borrow
|
|
|
3900 @cindex controlled unary operator
|
|
|
3901 @findex ^
|
|
|
3902 @findex @@
|
|
|
3903
|
|
|
3904 @portability{no, version 0.7+, version 1.-94.-8+, no}
|
|
|
3905
|
|
|
3906 One extension to @ical{} that is implemented by both @cic{} and
|
|
|
3907 @clcic{} is known as TriINTERCAL, and extends @ical{} to bases other
|
|
|
3908 than binary. Unlike ordinary @ical{} programs, which have the
|
|
|
3909 extension @samp{.i}, TriINTERCAL programs in bases from 3 to 7 (the
|
|
|
3910 only allowed bases) have extensions from @samp{.3i} to @samp{.7i}
|
|
|
3911 respectively.
|
|
|
3912
|
|
|
3913 The change of numeric base only affects expressions, and in particular
|
|
|
3914 the behaviour of operators, and the range of variables. (The onespot
|
|
|
3915 and twospot ranges become the highest number of trits or other digits
|
|
|
3916 in the base required that fit inside the binary ranges, so for
|
|
|
3917 instance, the maximum value of a onespot variable in ternary is 59048,
|
|
|
3918 or 3 to the power 10 minus 1.) Interleave/mingle is the simplest to
|
|
|
3919 explain; it alternates digits just as it alternated bits in binary.
|
|
|
3920 The other operators all change, as follows:
|
|
|
3921
|
|
|
3922 @itemize
|
|
|
3923
|
|
|
3924 @item
|
|
|
3925 Exclusive-or becomes two operators, known either as
|
|
|
3926 subtract-without-borrow and add-without-carry due to their
|
|
|
3927 mathematical interpretations, or what and sharkfin after their Atari
|
|
|
3928 syntax representations (@code{?} and @code{^}). (In Princeton syntax,
|
|
|
3929 these are the bookworm or yen sign, and a spike (@code{|}).) The two
|
|
|
3930 operators do the same thing in binary, but differ in higher bases.
|
|
|
3931 (Nevertheless, it is an error to use a sharkfin in binary, because it
|
|
|
3932 is a so-called `controlled unary operator', as are the rest of the
|
|
|
3933 new operators defined in this section, which has a lower limit on
|
|
|
3934 which base it is allowed in.) Instead of doing the exclusive-or
|
|
|
3935 operation, the bits being combined are either subtracted or added; if
|
|
|
3936 the result is out of range for the base being used, the base is added
|
|
|
3937 or subtracted from the result until it is in range. (For the
|
|
|
3938 subtraction, the bit that was less significant is subtracted from the
|
|
|
3939 bit that was more significant in any given pair of bits, except for
|
|
|
3940 the subtraction between the most and least significant bits, where the
|
|
|
3941 most significant bit is subtracted from the least.)
|
|
|
3942
|
|
|
3943 @item
|
|
|
3944 The AND and OR operators are generalised into an entire sequence of
|
|
|
3945 operators; the number of operators available is the same as the base
|
|
|
3946 that is being used. In base 3, the third operator is known as BUT; in
|
|
|
3947 other bases, there are no commonly accepted names for the extra
|
|
|
3948 operators, so names that reflect the notation are used here.
|
|
|
3949
|
|
|
3950 The way to think of it is this: in base 2, an AND gives the result 0
|
|
|
3951 if either argument is a 0, and otherwise a 1, and likewise, an OR
|
|
|
3952 gives the result 1 if either argument is a 1, and otherwise a 0; they
|
|
|
3953 could be said to favour 0 over 1 and 1 over 0 respectively. In base
|
|
|
3954 3, AND favours 0 over 2 over 1, OR favours 2 over 1 over 0, and BUT
|
|
|
3955 favours 1 over 0 over 2. (The symbol for BUT is @code{@@} (a
|
|
|
3956 `whirlpool', which is another name for the BUT operation) in Atari
|
|
|
3957 syntax, and @code{?} in Princeton syntax.) The pattern continues: in
|
|
|
3958 base 4, AND favours 0 over 3 over 2 over 1, BUT favours 1 over 0 over
|
|
|
3959 3 over 2, 2BUT (written @code{2@@} or @code{2?}) favours 2 over 1 over
|
|
|
3960 0 over 3, and OR favours 3 over 2 over 1 over 0. (This can be
|
|
|
3961 extended to higher bases following the same pattern, introducing
|
|
|
3962 operators @code{3@@} or @code{3?}, etc., to favour 3, etc., when
|
|
|
3963 neither AND (which always favours 0) nor OR (which favours the highest
|
|
|
3964 digit in the base) are available.) All the whirlpool operators are
|
|
|
3965 controlled unary operators, which are only legal when both the base
|
|
|
3966 contains the favoured digit, and they aren't redundant to AND nor OR.
|
|
|
3967
|
|
|
3968 @item
|
|
|
3969 Select has its semantics modified to deal with more than one nonzero
|
|
|
3970 digit in the base. It starts off by doing an AND (in whatever base is
|
|
|
3971 being used) between the two numbers being selected; then the bits of
|
|
|
3972 the result are sorted by the bits of the right-hand argument to the
|
|
|
3973 select, with bits corresponding to 0s in the right-hand argument
|
|
|
3974 ending up more significant than bits corresponding to high digits in
|
|
|
3975 the right-hand argument. In base 2, this has the same effect as a
|
|
|
3976 traditional-style select.
|
|
|
3977
|
|
|
3978 @end itemize
|
|
|
3979
|
|
|
3980 Note that the base doesn't affect anything other than variable ranges
|
|
|
3981 and expressions; in particular, it doesn't affect the bit-reversal
|
|
|
3982 used by Turing Tape I/O. (The tape still has characters written on it
|
|
|
3983 in binary, even though the program uses a different base.)
|
|
|
3984
|
|
|
3985 @node Multithreading and Backtracking
|
|
|
3986 @chapter Multithreading and Backtracking
|
|
|
3987 @cindex multithreading
|
|
|
3988 @cindex threading
|
|
|
3989 @cindex Threaded INTERCAL
|
|
|
3990 @cindex Backtracking INTERCAL
|
|
|
3991
|
|
|
3992 The multithreading and backtracking extensions to @ical{} were
|
|
|
3993 originally invented by Malcom Ryan, who implemented @code{COME
|
|
|
3994 FROM}-based multithreading as a modified version of @cic{}, known as
|
|
|
3995 Threaded @ical{}, but did not implement backtracking. (The same
|
|
|
3996 functionality is implemented in @cic{} today, but with different code.
|
|
|
3997 Most likely, this means that the original code was better.) He also
|
|
|
3998 invented the original version of Backtracking @ical{}, but did not
|
|
|
3999 implement it; the only known implementation is the @cic{} one. A
|
|
|
4000 different version of multithreading, using @code{WHILE}, was
|
|
|
4001 implemented as part of @clcic{} (like all extensions first available
|
|
|
4002 in @clcic{}, it is most likely due to Claudio Calvelli) and then added
|
|
|
4003 to @cic{}, although its implications were not noticed for some time
|
|
|
4004 afterwards.
|
|
|
4005
|
|
|
4006 So nowadays, three freely-mixable threading-like extensions to @ical{}
|
|
|
4007 exist, all of which are implemented in @cic{}. (A fourth, Quantum
|
|
|
4008 @ical{}, is implemented in @clcic{} but not @cic{}, and so will not be
|
|
|
4009 discussed further here.) If you're wondering about the description of
|
|
|
4010 backtracking as a threading-like extension, it's implemented with much
|
|
|
4011 of the same code as multithreading in @cic{}, because the @ical{}
|
|
|
4012 version can be seen as roughly equivalent to multithreading where the
|
|
|
4013 threads run one after another rather than simultaneously. (This
|
|
|
4014 conceptualisation is probably more confusing than useful, though, and
|
|
|
4015 is also not strictly correct. The same could probably be said about
|
|
|
4016 @ical{} as a whole, for that matter.)
|
|
|
4017
|
|
|
4018 @menu
|
|
|
4019 * Multithreading using COME FROM:: Creating separate threads.
|
|
|
4020 * Multithreading using WHILE:: Creating connected threads.
|
|
|
4021 * Backtracking:: Multithreading in series, not parallel.
|
|
|
4022 @end menu
|
|
|
4023
|
|
|
4024 @node Multithreading using COME FROM
|
|
|
4025 @section Multithreading using COME FROM
|
|
|
4026 @cindex @code{COME FROM}, multithreading
|
|
|
4027 @cindex @code{NEXT FROM}, multithreading
|
|
|
4028 @cindex multithreading, separate threads
|
|
|
4029 @cindex threading, separate
|
|
|
4030 @cindex threading, unwoven
|
|
|
4031 @cindex separate threads
|
|
|
4032 @cindex unwoven threads
|
|
|
4033
|
|
|
4034 @portability{no, version 0.25+, version 0.05+, no}
|
|
|
4035
|
|
|
4036 The original multithreading implementation worked by giving a new
|
|
|
4037 meaning to what was previously an error condition. If in a
|
|
|
4038 multithreaded program (a program is marked as multithreaded using
|
|
|
4039 options to a compiler) two or more @code{COME FROM}s or @code{NEXT
|
|
|
4040 FROM}s (or a mixture of the these) attempt to steal control
|
|
|
4041 simultaneously, the original thread splits into multiple threads, one
|
|
|
4042 for each of the commands trying to take control, and a different
|
|
|
4043 command gains control of the program in each case.
|
|
|
4044
|
|
|
4045 From then on, all the threads run simultaneously. The only thing
|
|
|
4046 shared between threads (apart from the environment in which they run)
|
|
|
4047 is the abstained/reinstated status of each command; everything else is
|
|
|
4048 separate. This means, for instance, that it's possible to change the
|
|
|
4049 value of a variable in one thread, and it will not affect the
|
|
|
4050 corresponding variable in other threads created this way. Likewise,
|
|
|
4051 there is a separate NEXT stack in each thread; if both a @code{COME
|
|
|
4052 FROM} and a @code{NEXT FROM} aim at the same line, for instance, the
|
|
|
4053 @code{NEXT FROM} thread will end up with a NEXT stack entry that isn't
|
|
|
4054 in the @code{COME FROM} thread, created by the @code{NEXT FROM}
|
|
|
4055 itself. This is known as unwoven thread creation; none of the threads
|
|
|
4056 created this way are `woven' with any of the other threads created
|
|
|
4057 this way. (Whether threads are woven depends on how they were
|
|
|
4058 created.) If the thread being split was itself woven with other
|
|
|
4059 threads, exactly one of the resulting threads after the split is woven
|
|
|
4060 with the threads that the original thread was woven to, but the rest
|
|
|
4061 will not be woven to anything. (If that seems a somewhat unusual
|
|
|
4062 rule: well, this is @ical{}.)
|
|
|
4063
|
|
|
4064 In @cic{}, there are other guarantees that can be made about unwoven
|
|
|
4065 threads (that is, threads not woven to any other thread). In
|
|
|
4066 particular, they can all be guaranteed to run at approximately the
|
|
|
4067 same speed; to be more precise, the number of commands that have been
|
|
|
4068 given the chance to execute in any given thread will not differ by
|
|
|
4069 more than 2 from the number of commands that have been given the
|
|
|
4070 chance to execute in any other thread that was created at the same
|
|
|
4071 time. (However, @code{COME FROM}s and @code{NEXT FROM}s can make this
|
|
|
4072 relationship less precise; it is unspecified (in the technical sense
|
|
|
4073 that means the compiler can choose any option it likes and change its
|
|
|
4074 mind on a whim without telling anyone) whether a @code{COME FROM} or
|
|
|
4075 @code{NEXT FROM} aiming at the current command counts towards the
|
|
|
4076 command total or not, thus causing the relationship to become weaker
|
|
|
4077 the more of them have the chance to execute. In versions of @cic{}
|
|
|
4078 from 0.27 onwards, there is a third guarantee; that if a @code{COME
|
|
|
4079 FROM} comes from itself, it will actually give other threads at least
|
|
|
4080 some chance to run, at some speed, by counting itself as a command
|
|
|
4081 every now and then; previously this requirement didn't exist, meaning
|
|
|
4082 that a @code{COME FROM} could block all threads if it aimed for itself
|
|
|
4083 due to the speed restrictions and the fact that @code{COME FROM}s need
|
|
|
4084 not count towards the total command count.) Also, all commands,
|
|
|
4085 including any @code{ONCE} or @code{AGAIN} attached to the command, are
|
|
|
4086 atomic; this means that it's impossible for another thread to conflict
|
|
|
4087 with what the command is doing. (In a departure from the usual
|
|
|
4088 @ical{} status quo, these guarantees are somewhat @emph{better} than
|
|
|
4089 in most other languages that implement threading, amusingly continuing
|
|
|
4090 to leave @ical{} with the status of being unlike any other mainstream
|
|
|
4091 language.)
|
|
|
4092
|
|
|
4093 The only way to communicate between unwoven threads is by changing the
|
|
|
4094 abstention status of commands; this always affects all threads in the
|
|
|
4095 program, whether woven or not. (The combination of @code{ABSTAIN} and
|
|
|
4096 @code{ONCE} is one way to communicate atomically, due to the atomic
|
|
|
4097 nature of @code{ONCE}.)
|
|
|
4098
|
|
|
4099 If there are at least two threads, the @code{GIVE UP} command ends the
|
|
|
4100 current thread, rather than the current program.
|
|
|
4101
|
|
|
4102 @node Multithreading using WHILE
|
|
|
4103 @section Multithreading using WHILE
|
|
|
4104 @findex WHILE
|
|
|
4105 @anchor{WHILE}
|
|
|
4106 @cindex multithreading, connected threads
|
|
|
4107 @cindex threading, connected
|
|
|
4108 @cindex threading, woven
|
|
|
4109 @cindex connected threads
|
|
|
4110 @cindex woven threads
|
|
|
4111
|
|
|
4112 @portability{no, version 0.27+, version 0.05+, no}
|
|
|
4113
|
|
|
4114 The @code{WHILE} command (which is not strictly speaking a command,
|
|
|
4115 but more a sort of metacommand that joins commands) is a second method
|
|
|
4116 of achieving multithreading. (In @clcic{}, there are at least two
|
|
|
4117 other meanings for @code{WHILE}, but only the one implemented in
|
|
|
4118 @cic{} is discussed here.) The syntax is somewhat unusual, and
|
|
|
4119 consists of two commands separated by the @code{WHILE} keyword, but
|
|
|
4120 sharing the statement identifier, execution chance, and any
|
|
|
4121 @code{ONCE}/@code{AGAIN} keyword that may be present. For instance:
|
|
|
4122
|
|
|
4123 @example
|
|
|
4124 (1) DO COME FROM ".2~.2"~#1 WHILE :1 <-
|
|
|
4125 "'?.1$.2'~'"':1/.1$.2'~#0"$#65535'"$
|
|
|
4126 "'"'&.1$.2'~'#0$#65535'"$#0'~#32767$#1"
|
|
|
4127 @end example
|
|
|
4128
|
|
|
4129 (OK, maybe that's an unnecessarily complicated example, and maybe it
|
|
|
4130 shouldn't have included the @code{/} operator which is part of another
|
|
|
4131 @ical{} extension (@pxref{Operand Overloading}). Still, I thought
|
|
|
4132 that maybe you'd want to see how addition can be implemented in @ical{}.)
|
|
|
4133
|
|
|
4134 A @code{WHILE} command starts two threads (the original thread that
|
|
|
4135 ran that command and a new one), one of which runs the command to the
|
|
|
4136 left of the @code{WHILE} and one of which runs the command to the
|
|
|
4137 right. Any line number applies to the left-hand command, not the
|
|
|
4138 WHILE as a whole, which is a metalanguage construct. @code{NEXTING
|
|
|
4139 FROM}, @code{ABSTAINING FROM} or similar behaviour with respect to the
|
|
|
4140 @code{WHILE} itself is impossible, although it's certainly possible to
|
|
|
4141 abstain from either of its operands (and abstaining from the left
|
|
|
4142 operand has much the same effect as abstaining from the @code{WHILE}
|
|
|
4143 itself; the right-hand thread deliberately takes a bit of time to get
|
|
|
4144 started just so that this behaviour happens). The right-command
|
|
|
4145 thread starts just before the left command is run (so @code{NEXTING},
|
|
|
4146 etc.@:, directly to the left command will not start that loop in the
|
|
|
4147 first place); if that command finishes (which may be almost
|
|
|
4148 immediately for something like a calculate command, or take a long
|
|
|
4149 time for something like @code{NEXT}), that thread loops and reruns
|
|
|
4150 that command as long as the left command has not finished;
|
|
|
4151 @code{COMING FROM} that command, or a @code{NEXT}/@code{NEXT FROM}
|
|
|
4152 from/aiming at that command, doesn't count as finishing that command
|
|
|
4153 until it is @code{RESUME}d back to (if possible; if it's come from,
|
|
|
4154 that command can never end and the right-hand loop will continue
|
|
|
4155 forever, or until it @code{GIVE}s @code{UP} or the loop ends due to
|
|
|
4156 the command ending later in another thread). A @code{WHILE} command
|
|
|
4157 itself exists across all threads of a multithreaded program in a way;
|
|
|
4158 for each left-hand command that ends (in any thread), the next time a
|
|
|
4159 right-hand command of the same @code{WHILE} ends it will cause the
|
|
|
4160 thread it's looping in to end, regardless of whether that thread
|
|
|
4161 corresponds to the thread in which the left-hand command ended. (As
|
|
|
4162 well as a right-hand command ending, there's also the possibility that
|
|
|
4163 it never got started; there is a delay before the right-hand command
|
|
|
4164 runs during which a left-hand command ending can prevent the
|
|
|
4165 right-hand thread starting in the first place; this counts as the same
|
|
|
4166 sort of event as terminating a right-hand loop, and can substitute for
|
|
|
4167 it anywhere a right-hand command ending is mentioned.) There is one
|
|
|
4168 exception, in that if two or more left-hand commands end in a space of
|
|
|
4169 time in which no right-hand commands for that @code{WHILE} ends, they
|
|
|
4170 together only cause one right-hand command to end. (What, did you
|
|
|
4171 expect the logical and orthogonal behaviour?)
|
|
|
4172
|
|
|
4173 The two threads produced by a @code{WHILE} (the original thread and a
|
|
|
4174 new copy of it) have more in common than ordinary @ical{} threads
|
|
|
4175 created by @code{COME FROM}; ordinary threads share only
|
|
|
4176 @code{ABSTAIN}/@code{REINSTATE} information, whereas the
|
|
|
4177 @code{WHILE}-produced threads count as `woven' threads which also
|
|
|
4178 share variables and stashes. (They still have separate instruction
|
|
|
4179 pointers, separate instruction pointer stacks, such as the NEXT stack,
|
|
|
4180 and separate choicepoint lists. Overloading information is shared,
|
|
|
4181 though.) Being woven is a relationship between two or more threads,
|
|
|
4182 rather than an attribute of a thread, although a thread can be
|
|
|
4183 referred to as being unwoven if it is not woven to any other thread.
|
|
|
4184
|
|
|
4185 Ordinary multithreading cannot create woven threads. When threads are
|
|
|
4186 created by multiple @code{COME FROM}s from an original thread, which
|
|
|
4187 was woven with at least one other thread, one of the resulting threads
|
|
|
4188 counts as the `original' thread and remains woven; the rest are `new'
|
|
|
4189 threads which initially start out with the same data as the original,
|
|
|
4190 but are not woven with anything. Backtracking in a thread
|
|
|
4191 (@pxref{Backtracking}) causes it to unweave with any threads it may be
|
|
|
4192 woven with at the time (so the data in the thread that backtracks is
|
|
|
4193 set back to the data it, and the threads it was woven with at the
|
|
|
4194 time, had at the time of the @code{MAYBE}, but the other threads
|
|
|
4195 continue with the same data as before). The only way to cause three
|
|
|
4196 or more threads to become woven is with a new @code{WHILE} inside one
|
|
|
4197 of the threads that is already woven, which causes all the new threads
|
|
|
4198 to be woven together (the weaving relationship is transitive).
|
|
|
4199
|
|
|
4200 @node Backtracking
|
|
|
4201 @section Backtracking
|
|
|
4202 @cindex backtracking
|
|
|
4203 @cindex choicepoints
|
|
|
4204 @cindex dormant thread
|
|
|
4205 @cindex threading, in series
|
|
|
4206 @cindex threading, dormant
|
|
|
4207
|
|
|
4208 @portability{no, version 0.25+, no, no}
|
|
|
4209
|
|
|
4210 A somewhat unusual threading construct that's available is
|
|
|
4211 backtracking. In case you haven't come across it before (the concept
|
|
|
4212 exists in other languages but is implemented differently and usually
|
|
|
4213 in a less general way), the basic idea is that instead of executing or
|
|
|
4214 not executing a command, you can @code{MAYBE} execute a command. This
|
|
|
4215 causes the command to be executed, but also creates a dormant thread
|
|
|
4216 in which the command wasn't executed; at any time later, the program
|
|
|
4217 can either decide that it liked the consequences of the command and
|
|
|
4218 @code{GO AHEAD} and get rid of the dormant thread, or decide that it
|
|
|
4219 didn't like the consquences of the command and @code{GO BACK} to the
|
|
|
4220 dormant thread, discarding the current one. The dormant thread is
|
|
|
4221 more commonly called a `choicepoint', that is, a point at which a
|
|
|
4222 choice was made but a different choice can still be made, and is
|
|
|
4223 generally not thought of as a thread at all by most programmers. (In
|
|
|
4224 case you're wondering: dormant threads are always unwoven.)
|
|
|
4225
|
|
|
4226 @anchor{MAYBE}
|
|
|
4227 @findex MAYBE
|
|
|
4228 @cindex choicepoints, creating
|
|
|
4229 To create a choicepoint, the statement identifier @code{MAYBE} is
|
|
|
4230 used, rather than the more usual @code{DO} or @code{PLEASE}.
|
|
|
4231 (Combination statement identifiers are still allowed, but must be in
|
|
|
4232 the order @code{MAYBE PLEASE DO NOT} with optionally some parts
|
|
|
4233 omitted, or different versions of @code{NOT} used, or both.) Here's an
|
|
|
4234 example:
|
|
|
4235
|
|
|
4236 @example
|
|
|
4237 MAYBE DON'T GIVE UP
|
|
|
4238 @end example
|
|
|
4239
|
|
|
4240 When a command whose statement identifer contains @code{MAYBE} is
|
|
|
4241 reached, it is executed or not executed as normal, but in addition a
|
|
|
4242 choicepoint is created containing the program as it is at that time.
|
|
|
4243 Only @code{ABSTAIN} and @code{REINSTATE}, which always affect all
|
|
|
4244 threads in a program (even choicepoints), can alter the values stored
|
|
|
4245 in the choicepoint; so in this way, a choicepoint is also somewhat
|
|
|
4246 similar to the concept of a continuation in other languages. The
|
|
|
4247 choicepoint is placed on a choicepoint stack, which is maintained
|
|
|
4248 separately for each thread in much the same way that stashes and the
|
|
|
4249 @code{NEXT} stack are.
|
|
|
4250
|
|
|
4251 @anchor{GO BACK}
|
|
|
4252 @findex GO BACK
|
|
|
4253 @cindex choicepoints, activating
|
|
|
4254 The choicepoint does not actually do anything immediately, but if the
|
|
|
4255 program doesn't like the look of where it's ended up, or it decides to
|
|
|
4256 change its mind, or just wants to try all the possibilities, it can
|
|
|
4257 call the @code{GO BACK} command (which has no arguments, and is just
|
|
|
4258 the statement identifier, optional execution chance, @code{GO BACK},
|
|
|
4259 and optional @code{ONCE} or @code{AGAIN}). This causes the current
|
|
|
4260 thread to unweave from all other threads and then replace itself with
|
|
|
4261 the thread created by the choicepoint on top of the choicepoint stack.
|
|
|
4262 The difference is that this time, the abstention or reinstatement
|
|
|
4263 status of the command that was modified with @code{MAYBE} is
|
|
|
4264 temporarily reversed for determining whether it runs or not (this
|
|
|
4265 reversal only lasts immediately after the @code{GO BACK}, and does not
|
|
|
4266 affect uses of the command in other threads or later in the same
|
|
|
4267 thread), so unless it has been @code{ABSTAIN}ed or @code{REINSTATE}d
|
|
|
4268 in the meantime it will run if and only if it wasn't run the first
|
|
|
4269 time. The choicepoint stack's top entry is replaced by a `stale'
|
|
|
4270 choicepoint that definitely isn't a thread; attempting to @code{GO
|
|
|
4271 BACK} to a stale choicepoint instead causes the stale choicepoint to
|
|
|
4272 be deleted and the program to continue executing. (This is what gives
|
|
|
4273 @ical{}'s backtracking greater flexibility in some ways than some
|
|
|
4274 other languages; to get backtracking without the stale choicepoints
|
|
|
4275 having an effect, simply run @code{COME FROM} the @code{GO BACK} as
|
|
|
4276 the previous statement.)
|
|
|
4277
|
|
|
4278 Note that, though, when a thread splits into separate threads (whether
|
|
|
4279 woven or unwoven), the choicepoint stack doesn't split completely, but
|
|
|
4280 remains joined at the old top of stack. The two choicepoint stacks
|
|
|
4281 can add and remove items independently, but an attempt to @code{GO
|
|
|
4282 BACK} to before the current thread split off from any other threads
|
|
|
4283 that are still running instead causes the current thread to end,
|
|
|
4284 although it will @code{GO BACK} as normal if all other threads that
|
|
|
4285 split off from it or that it split off from since the top choicepoint
|
|
|
4286 of the stack was created have ended since. This means that it's
|
|
|
4287 possible to backtrack past a thread splitting and get the effect of
|
|
|
4288 the thread unsplitting, as long as both resulting threads backtrack;
|
|
|
4289 this is another way in which @ical{}'s backtracking is more flexible
|
|
|
4290 than that of some other languages.
|
|
|
4291
|
|
|
4292 @anchor{GO AHEAD}
|
|
|
4293 @findex GO AHEAD
|
|
|
4294 @cindex choicepoints, discarding
|
|
|
4295 If, on the other hand, a program decides that it likes where it is and
|
|
|
4296 doesn't need to @code{GO BACK}, or it wants to @code{GO BACK} to a
|
|
|
4297 choicepoint lower down the stack while skipping some of the ones
|
|
|
4298 nearer the top of the stack, it can run the @code{GO AHEAD} command,
|
|
|
4299 which removes the top choicepoint on the stack, whether it's a genuine
|
|
|
4300 choicepoint or just a stale one.
|
|
|
4301
|
|
|
4302 Both @code{GO AHEAD} and @code{GO BACK} cause errors if an attempt is
|
|
|
4303 made to use them when the choicepoint stack is empty.
|
|
|
4304
|
|
|
4305 @node Operand Overloading
|
|
|
4306 @chapter Operand Overloading
|
|
|
4307 @cindex operand overloading
|
|
|
4308 @findex /
|
|
|
4309 @cindex slat
|
|
|
4310 @cindex reverse assignment
|
|
|
4311
|
|
|
4312 @portability{no, version 0.26+, version 0.05+, no}
|
|
|
4313
|
|
|
4314 (Operand overloading in @cic{} is nowhere near as advanced as it is in
|
|
|
4315 @clcic{}. This chapter only explains the partial implementation used
|
|
|
4316 by @cic{}; for a full implementation, see @clcic{} and its
|
|
|
4317 documentation.)
|
|
|
4318
|
|
|
4319 Operand overloading is a method of using a onespot or twospot variable
|
|
|
4320 as a substitute for an expression. When a variable is overloaded to
|
|
|
4321 an expression (which could be another variable, or something more
|
|
|
4322 complex), any uses of that variable cause the expression to be
|
|
|
4323 substituted instead.
|
|
|
4324
|
|
|
4325 At the beginning of the program, all variables stand for themselves;
|
|
|
4326 so @code{.1} really does mean @code{.1}, for instance. The meaning of
|
|
|
4327 a variable can be overloaded using the slat operator (@code{/}), which
|
|
|
4328 is the same in both Princeton and Atari syntax: it is a binary
|
|
|
4329 operator whose left argument must be a onespot or twospot variable and
|
|
|
4330 whose right argument can be any expression. The slat operator returns
|
|
|
4331 the true value of its left argument, but as a side effect, changes the
|
|
|
4332 meaning of its left argument to be its right argument. Here is an
|
|
|
4333 example:
|
|
|
4334
|
|
|
4335 @example
|
|
|
4336 DO .1 <- .2/'.3~.4'
|
|
|
4337 @end example
|
|
|
4338
|
|
|
4339 The example causes @code{.2}'s true value to be assigned to @code{.1}
|
|
|
4340 (unless of course @code{.1} is read-only), but also causes @code{.2}
|
|
|
4341 from then on to actually mean @code{'.3~.4'}, except when it's the
|
|
|
4342 left operand of a slat operator. So for instance, @code{DO .1 <- .2}
|
|
|
4343 would actually assign @code{'.3~.4'} to @code{.1}. Somewhat
|
|
|
4344 confusingly, this also works in the other direction; @code{DO .2 <-
|
|
|
4345 .1} would assign @code{.1} to @code{'.3~.4'}, which would have the
|
|
|
4346 effect of changing the values of @code{.3} and @code{.4} so that
|
|
|
4347 @code{'.3~.4'} had the correct value, or throw an error if it couldn't
|
|
|
4348 manage this. (The general rule in this case is that any variable or
|
|
|
4349 constant in the expression that overloads the variable is at risk of
|
|
|
4350 being changed; this is known as a `reverse assignment'. Code like
|
|
|
4351 @code{DO .1 <- .1/#1} is entirely capable of changing the value of
|
|
|
4352 @code{#1}, although to protect new @ical{} users @cic{} will refuse to
|
|
|
4353 carry out operations that change the value of constants unless a
|
|
|
4354 command-line switch (@pxref{-v}) is used to give it permission. In
|
|
|
4355 @cic{}, changing the value of a constant only changes meshes with that
|
|
|
4356 value, but in @clcic{} it can also change non-mesh uses of that
|
|
|
4357 constant, so doing so is not portable anyway.)
|
|
|
4358
|
|
|
4359 When multiple overloading rules are in effect, they are all applied;
|
|
|
4360 overloading @code{.1} to @code{'.2~.3'} and @code{.2} to
|
|
|
4361 @code{'.3$.4'} will cause @code{.1} to refer to @code{''.3$.4'~.3'}.
|
|
|
4362 However, this expansion stops if this would cause a loop; to be
|
|
|
4363 precise, overloading is not expanded if the expansion is nested within
|
|
|
4364 the same expansion at a higher level (so @code{.1/.2} and @code{.2/.1}
|
|
|
4365 together cause @code{.1} to expand to @code{.2}, which expands to
|
|
|
4366 @code{.1}, which cannot expand any further). In @cic{}, the
|
|
|
4367 expression on the right hand side of a slat is not evaluated and not
|
|
|
4368 expanded by operand overloading.
|
|
|
4369
|
|
|
4370 @code{STASHING} a variable causes its overloading information to be
|
|
|
4371 stashed too; @code{RETRIEVING} it causes its overload rule to also be
|
|
|
4372 retrieved from the stash (or any overload rule on the variable to be
|
|
|
4373 removed if there wasn't one when the variable was stashed).
|
|
|
4374
|
|
|
4375 Overloading a onespot variable to a twospot variable or vice versa is
|
|
|
4376 possible, but the results are unlikely to be predictable, especially
|
|
|
4377 if a onespot variable is used to handle a twospot value. Possible
|
|
|
4378 outcomes include truncating the value down to the right bitwidth,
|
|
|
4379 throwing an error if a value outside the onespot range is used, and
|
|
|
4380 even temporarily handling the entire twospot value as long as it
|
|
|
4381 doesn't end up eventually being assigned a value greater than twospot.
|
|
|
4382
|
|
|
4383 Note that reverse assignments can cause unpredictable behaviour if an
|
|
|
4384 attempt is made to reverse-assign the same variable twice in the same
|
|
|
4385 expression. In particular, sequences of commands like @code{DO .1 <-
|
|
|
4386 .2/'.3$.3' DO .2 <- #6} are liable to succeed assigning garbage to
|
|
|
4387 @code{.3} rather than failing as they ought to do, and likewise any
|
|
|
4388 situation where a variable is reverse-assigned twice in the same
|
|
|
4389 expression may assign garbage to it. This behaviour is seen as
|
|
|
4390 unsatisfactory, though, and plans exist to improve it for future
|
|
|
4391 versions.
|
|
|
4392
|
|
|
4393 @node PIC-INTERCAL
|
|
|
4394 @chapter PIC-INTERCAL
|
|
|
4395 @cindex PIC-INTERCAL
|
|
|
4396 @cindex embedded systems
|
|
|
4397 @cindex microcontrollers
|
|
|
4398
|
|
|
4399 @portability{no, version 0.26+, no, no}
|
|
|
4400
|
|
|
4401 PIC-INTERCAL is a simplified version of @ical{} designed especially
|
|
|
4402 for embedded systems, designed to minimise code and data usage by
|
|
|
4403 @ical{} programs so that they can fit on devices whose memory is
|
|
|
4404 measured in bytes rather than megabytes. (It is named after the first
|
|
|
4405 microcontroller for which code was successfully generated, and which
|
|
|
4406 influenced the choices of commands, the PIC16F628 manufactured by
|
|
|
4407 Microchip, and is most likely to be portable to other microcontrollers
|
|
|
4408 in the same range.) @cic{} only compilers as far as C code when
|
|
|
4409 producing PIC-INTERCAL; it is up to the user to find the appropriate
|
|
|
4410 cross-compiler to translate this C into the relevant dialect of
|
|
|
4411 machine code. (Two header files in the distribution,
|
|
|
4412 @file{src/pick1.h} and @file{src/pick2.h}, don't have any affect on
|
|
|
4413 the compiler but are referenced by the generated code, and the intent
|
|
|
4414 is for the user to change them to suit the behaviour of the PIC
|
|
|
4415 compiler used, because these are not as standardised as C compilers
|
|
|
4416 for everyday systems.)
|
|
|
4417
|
|
|
4418 There are several restrictions on PIC-INTERCAL programs:
|
|
|
4419
|
|
|
4420 @itemize
|
|
|
4421
|
|
|
4422 @item
|
|
|
4423 It's impossible to store more than one item in the STASH for any given
|
|
|
4424 variable.
|
|
|
4425
|
|
|
4426 @item
|
|
|
4427 Many errors are not checked at runtime; it is the programmer's job to
|
|
|
4428 ensure that runtime errors are avoided. (The few errors that are
|
|
|
4429 detected will send the program into an infinite loop, as there is no
|
|
|
4430 sensible way to exit from a PIC program.)
|
|
|
4431
|
|
|
4432 @item
|
|
|
4433 Double-oh-sevens are not randomised, but instead depend merely on
|
|
|
4434 whether the probability given is greater than 50% or not.
|
|
|
4435
|
|
|
4436 @item
|
|
|
4437 The NEXT stack is limited to 16 entries rather than the usual 80.
|
|
|
4438
|
|
|
4439 @item
|
|
|
4440 @code{ABSTAIN} and @code{REINSTATE} still work, but cannot be computed
|
|
|
4441 @code{ABSTAIN}s, and will not necessarily work when used to affect the
|
|
|
4442 system library or calls to it.
|
|
|
4443
|
|
|
4444 @item
|
|
|
4445 @code{READ OUT} and @code{WRITE IN} don't work. (See below for a
|
|
|
4446 replacement.)
|
|
|
4447
|
|
|
4448 @item
|
|
|
4449 @code{COME FROM} and @code{NEXT FROM} must aim at a label, not an
|
|
|
4450 expression or gerund.
|
|
|
4451
|
|
|
4452 @item
|
|
|
4453 Multithreading and TriINTERCAL cannot be used on PICs. (Operand
|
|
|
4454 overloading can be used, but only if your PIC cross-compiler supports
|
|
|
4455 function pointers; some don't.)
|
|
|
4456
|
|
|
4457 @end itemize
|
|
|
4458
|
|
|
4459 @anchor{PIN}
|
|
|
4460 @findex PIN
|
|
|
4461 @cindex I/O, PIC-INTERCAL
|
|
|
4462 In order to provide I/O capabilities, a new command @code{PIN} is
|
|
|
4463 available. It controls up to 16 I/O pins on the PIC or other embedded
|
|
|
4464 system; an I/O pin is capable of receiving or sending voltages to an
|
|
|
4465 electrical or electronic circuit. This explanation assumes that the
|
|
|
4466 device being controlled is a PIC16F628A, and therefore has its pins in
|
|
|
4467 two blocks of 8 named @samp{PORTA} and @samp{PORTB}; for other
|
|
|
4468 microcontrollers, adapting the code in @file{src/pick1.h} is likely to
|
|
|
4469 be necessary to tell the compiler how to control the I/O pins, and the
|
|
|
4470 way in which this done will affect which I/O pins it is that the
|
|
|
4471 program will end up being able to communicate with.
|
|
|
4472
|
|
|
4473 The @code{PIN} command takes one twospot variable as its argument,
|
|
|
4474 like this:
|
|
|
4475
|
|
|
4476 @example
|
|
|
4477 DO PIN :2
|
|
|
4478 @end example
|
|
|
4479
|
|
|
4480 The twospot variable is conceptually divided into 4 blocks of 8 bits.
|
|
|
4481 The highest two blocks control the directions of the pins in
|
|
|
4482 @code{PORTB} (most significant block) and @code{PORTA} (second most
|
|
|
4483 significant block); a 1 on any bit means that the corresponding I/O
|
|
|
4484 pin should be set to send data, and a 0 means that it should be set to
|
|
|
4485 receive data. The lower two blocks control the values on the pins
|
|
|
4486 that are sending (and are ignored for receiving pins); the second
|
|
|
4487 least significant block controls @code{PORTB} and the least
|
|
|
4488 significant block controls @code{PORTA}, with a 1 causing the program
|
|
|
4489 to set the output voltage to that of the microcontroller's negative
|
|
|
4490 voltage supply rail, and a 0 causing the program to set the output
|
|
|
4491 voltage to that of the microcontroller's positive voltage supply
|
|
|
4492 rail. (These voltages may vary on other systems; consult your
|
|
|
4493 system's datasheet and the changes you made to the header files.)
|
|
|
4494 After setting the pins, the @code{PIN} command then reads them as part
|
|
|
4495 of the same operation, this time setting the values of the lower
|
|
|
4496 blocks that are receiving, rather than setting the pins from the lower
|
|
|
4497 blocks that are sending. However, 1 and 0 bits on all bits of the
|
|
|
4498 twospot variable have the opposite meaning when doing this, so that 1
|
|
|
4499 means receiving/positive voltage rail and 0 means sending/negative
|
|
|
4500 voltage rail. There is no way to input without output, or vice versa,
|
|
|
4501 but it's trivial to just send the same output again (which has no
|
|
|
4502 effect, because the voltage on sending pins is maintained at the same
|
|
|
4503 level until it is changed), or to ignore the input received.
|
|
|
4504
|
|
|
4505 @node CREATE
|
|
|
4506 @chapter CREATE
|
|
|
4507 @findex CREATE
|
|
|
4508 @cindex creating syntax
|
|
|
4509 @cindex syntax, creating
|
|
|
4510
|
|
|
4511 @portability{no, version 0.28+, see text, no}
|
|
|
4512
|
|
|
4513 The @code{CREATE} command allows the creation of new syntax at
|
|
|
4514 runtime. @clcic{} has had such a command since 1.-94.-8, but its
|
|
|
4515 syntax is completely different and incompatible with the @cic{}
|
|
|
4516 version, and so is not documented here (see the @clcic{} documentation
|
|
|
4517 for more details). The @cic{} version is only defined if the
|
|
|
4518 @code{-a} option is used on the command line (and a runtime error E000
|
|
|
4519 otherwise), because it forces the operand overloading code to be
|
|
|
4520 introduced and so slows down every variable access in the program.
|
|
|
4521
|
|
|
4522 The syntax of the @code{CREATE} command is to write @code{CREATE},
|
|
|
4523 then a line label, then anything. OK, well not quite anything; you're
|
|
|
4524 restricted to syntax that is supported by the `just-in-case' compiler
|
|
|
4525 that runs on comments at compile time just in case they gain a meaning
|
|
|
4526 later (see below). The anything provides an example statement to
|
|
|
4527 @code{CREATE}; statements which look the same (but may differ in
|
|
|
4528 details) are created. Typical syntax for a @code{CREATE} statement
|
|
|
4529 would therefore look something like this:
|
|
|
4530
|
|
|
4531 @example
|
|
|
4532 DO CREATE (5) SWITCH .1 WITH .2
|
|
|
4533 @end example
|
|
|
4534
|
|
|
4535 There is also computed @code{CREATE}, working identically to ordinary
|
|
|
4536 @code{CREATE} except that the line number is taken from an expression
|
|
|
4537 and the created command must start with a letter (to avoid an
|
|
|
4538 ambiguity if the expression giving the line label happens to be an
|
|
|
4539 array reference), with a syntax like this:
|
|
|
4540
|
|
|
4541 @example
|
|
|
4542 DO CREATE .5 SWITCH .1 WITH .2
|
|
|
4543 @end example
|
|
|
4544
|
|
|
4545 Here, a new @code{SWITCH WITH} statement (there is no such statement
|
|
|
4546 in @ical{} normally) is being created. This command makes it possible
|
|
|
4547 to do this:
|
|
|
4548
|
|
|
4549 @example
|
|
|
4550 DO SWITCH .3 WITH .4
|
|
|
4551 @end example
|
|
|
4552
|
|
|
4553 Normally that line would be an error (E000) due to being unrecognised,
|
|
|
4554 but having been @code{CREATE}d, it's now a real statement. (The
|
|
|
4555 gerund to affect created statements is @code{COMMENT}, just like
|
|
|
4556 before they were created; the gerund to affect @code{CREATE} itself is
|
|
|
4557 @code{CREATION} (@code{CREATING} is also allowed, but not as
|
|
|
4558 elegant).) When the created statement is encountered, it @code{NEXT}s
|
|
|
4559 to line (5), the line number specified in the @code{CREATE} statement.
|
|
|
4560 In order for the code there to be able to affect the variables
|
|
|
4561 mentioned in the statement, the variables @code{:1601} (for the first
|
|
|
4562 variable or expression mentioned), @code{:1602} (for the second
|
|
|
4563 variable or expression mentioned), and so on, are @code{STASH}ed and
|
|
|
4564 then overloaded to the respective expressions or variables mentioned
|
|
|
4565 in the created command; so @code{:1601} has been overloaded to mean
|
|
|
4566 @code{.3} and @code{:1602} has been overloaded to mean @code{.4} at
|
|
|
4567 this point. Then, the code at (5) runs; if it returns via a
|
|
|
4568 @code{RESUME #1}, @code{:1601} and @code{:1602} will be
|
|
|
4569 @code{RETRIEVE}d automatically and the program will continue from
|
|
|
4570 after the created statement. (If you do not resume to that point, say
|
|
|
4571 if you're creating a flow control statement, you'll have to deal with
|
|
|
4572 the stashes for the 1600-range variables yourself.)
|
|
|
4573
|
|
|
4574 So what syntax is available in created statements@? All the capital
|
|
|
4575 letters except @samp{V} (which is an operator in @ical{}) are
|
|
|
4576 available and can be used freely and as many times as desired; they
|
|
|
4577 match themselves literally. However, they are not allowed to spell an
|
|
|
4578 @ical{} keyword at any point (so watch out for @code{DO} and
|
|
|
4579 @code{FROM}, for instance). Whitespace is allowed, but is ignored
|
|
|
4580 (both in the @code{CREATE} template statement, and in the code being
|
|
|
4581 created; so @code{DO SW ITCH :8 WITH :50} will also have been
|
|
|
4582 created). Then, there are three groups of matchable data: scalar
|
|
|
4583 variables (onespot or twospot variables, as used in the examples
|
|
|
4584 above) match other scalar variables, array elements (like @code{,4 SUB
|
|
|
4585 '.5~.6'}) match other array elements, and other expressions match
|
|
|
4586 other other expressions. Two matchable data may not appear
|
|
|
4587 consecutively in a created command, but must be separated by at least
|
|
|
4588 one capital letter (to prevent array-subscript-related ambiguities;
|
|
|
4589 remember that the just-in-case compiler has to compile these
|
|
|
4590 statements at compile time without knowing what they are). The actual
|
|
|
4591 expressions used in the @code{CREATE} statement don't matter; they're
|
|
|
4592 just examples for the runtime to match against.
|
|
|
4593
|
|
|
4594 @cindex CREATE, operators
|
|
|
4595 It is also possible (from @cic{} version 0.29 onwards) to create new
|
|
|
4596 operators. Such operators are always binary operators (that is, they
|
|
|
4597 take two arguments and parse like mingle or select), and always return
|
|
|
4598 32-bit results. There are three types of legal names for such
|
|
|
4599 operators, all of which are treated equivalently: lowercase letters,
|
|
|
4600 punctuation marks otherwise unused in @ical{}, and overstrikes
|
|
|
4601 consisting of a character, a backspace, and another character (apart
|
|
|
4602 from overstrikes already used for built-in @ical{} operators). The
|
|
|
4603 syntax for creating an operator looks like one of these:
|
|
|
4604
|
|
|
4605 @example
|
|
|
4606 DO CREATE (5) x
|
|
|
4607 DO CREATE .5 =
|
|
|
4608 @end example
|
|
|
4609
|
|
|
4610 The arguments to the operator will be overloaded onto :1601 and :1602
|
|
|
4611 (which are, like with @code{CREATE}d statements, stashed before the
|
|
|
4612 overloading happens), and the return value is read from :1603 (which
|
|
|
4613 is stashed, then overloaded to itself). All these three variables are
|
|
|
4614 retrieved again after the operator finishes evaluating.
|
|
|
4615
|
|
|
4616 Note that it is a very unwise idea to use a @code{CREATE}d operator in
|
|
|
4617 the expression for a computed @code{COME FROM} or @code{NEXT FROM},
|
|
|
4618 because this always leads to an infinite regress; whenever any line
|
|
|
4619 label is reached (including the line label that the @code{CREATE}
|
|
|
4620 statement pointed at), the expression needs to be evaluated in order
|
|
|
4621 to determine whether to @code{COME FROM} that point, which in turn
|
|
|
4622 involves evaluating lines which have labels.
|
|
|
4623
|
|
|
4624 Some other points: a newer @code{CREATE} statement supercedes an older
|
|
|
4625 @code{CREATE} statement if they give equivalent templates, multiple
|
|
|
4626 @code{CREATE} statements may aim at the same line (this is the
|
|
|
4627 recommended technique for creating a statement that can handle
|
|
|
4628 expressions even if they're array elements or variables; you do this
|
|
|
4629 by specifying multiple templates in multiple @code{CREATE}
|
|
|
4630 statements), and strange things happen if a twospot variable in the
|
|
|
4631 1600-range is used as an argument to a created statement itself
|
|
|
4632 (because of the stash/retrieve, such a variable can usually be read,
|
|
|
4633 but may not always be able to be written without the data being lost).
|
|
|
4634
|
|
|
4635 @node External Calls
|
|
|
4636 @chapter External Calls
|
|
|
4637 @cindex external calls
|
|
|
4638 @cindex other languages
|
|
|
4639 @cindex foreign functions
|
|
|
4640 @cindex calls, external
|
|
|
4641
|
|
|
4642 @portability{no, version 0.28+, no, no}
|
|
|
4643
|
|
|
4644 @cic{} has a feature allowing @ical{} and non-@ical{} code to be
|
|
|
4645 mixed. This is achieved by causing the non-@ical{} programs to
|
|
|
4646 participate in the @ical{} line-numbering model. The same feature
|
|
|
4647 allows expansion libraries to be linked into the code.
|
|
|
4648
|
|
|
4649 To create a combined program containing @ical{} and non-@ical{} code,
|
|
|
4650 use @command{ick} as the compiler as normal, but specify both the
|
|
|
4651 @ical{} and non-@ical{} source files on the command line, and use the
|
|
|
4652 @option{-e} command-line option. @command{ick} will invoke other
|
|
|
4653 compilers as necessary, after modifying the source files accordingly.
|
|
|
4654 At present, external calls are only supported to and from C.
|
|
|
4655
|
|
|
4656 In each case, it will be the @ical{} program that is invoked first.
|
|
|
4657 (This means that it is impossible to link together more than one
|
|
|
4658 @ical{} program, but you probably don't want to, because concatenating
|
|
|
4659 the programs is likely to have a similar effect.) You can get the
|
|
|
4660 @ical{} program to @code{NEXT} to the non-@ical{} program immediately,
|
|
|
4661 or the non-@ical{} program to @code{COME FROM} or @code{NEXT FROM} the
|
|
|
4662 @ical{} program immediately, to obtain the effect of running the
|
|
|
4663 non-@ical{} program first.
|
|
|
4664
|
|
|
4665 Note that external calls are incompatible with PIC-INTERCAL and with
|
|
|
4666 multithreading; note also that you must use @command{gcc} as your
|
|
|
4667 compiler, and @acronym{GNU} cpp and ld, for them to work in the
|
|
|
4668 current version of @cic{}.
|
|
|
4669
|
|
|
4670 @menu
|
|
|
4671 * External Calls to C:: How to put @ical{} calls in C.
|
|
|
4672 * External Calls to Funge-98:: Linking Befunge-98 and @ical{}.
|
|
|
4673 * Miscellaneous External Calls:: Other things you can link in.
|
|
|
4674 * Using External Calls:: What happens when you use -e.
|
|
|
4675 * Expansion Libraries:: Expanding the compiler's capabilities.
|
|
|
4676 @end menu
|
|
|
4677
|
|
|
4678 @node External Calls to C
|
|
|
4679 @section External Calls to C
|
|
|
4680 @cindex C
|
|
|
4681 @cindex other languages, C
|
|
|
4682 @cindex external calls, to C
|
|
|
4683
|
|
|
4684 @portability{no, version 0.28+, no, no}
|
|
|
4685
|
|
|
4686 Linking C and @ical{} programs is achieved by placing various
|
|
|
4687 constructs into the C programs that are equivalent to various @ical{}
|
|
|
4688 constructs. It is possible to simulate a line with a label and a
|
|
|
4689 dummy command (which serves as a @code{COME FROM} suckpoint and
|
|
|
4690 @code{NEXT} target), a command with a line label, @code{NEXT},
|
|
|
4691 @code{RESUME}, and @code{FORGET}, and @code{COME FROM} and @code{NEXT
|
|
|
4692 FROM}. Onespot and twospot variables are accessible from inside the C
|
|
|
4693 program, where they can be read and written; however, the @ical{}
|
|
|
4694 program cannot access any variables inside the C program that weren't
|
|
|
4695 part of the @ical{} program originally.
|
|
|
4696
|
|
|
4697 To prevent various logical impossibilities, there are restrictions on
|
|
|
4698 where these can be used and what preparation is needed before they are
|
|
|
4699 used. Also, the semantics are not always exactly what you might
|
|
|
4700 expect for technical reasons.
|
|
|
4701
|
|
|
4702 It should be observed that the @ical{} link intrudes on the user
|
|
|
4703 namespace. To prevent possible namespace clashes, no identifiers
|
|
|
4704 starting with @code{ick_} or @code{ICK_} should be used anywhere in
|
|
|
4705 the linked C program for any reason, except where specified in this
|
|
|
4706 manual.
|
|
|
4707
|
|
|
4708 @menu
|
|
|
4709 * External C Call Infrastructure:: Enabling a C program for external calls
|
|
|
4710 * ick_startup:: Doing things at startup
|
|
|
4711 * ick_linelabel:: Labelling lines...
|
|
|
4712 * ick_labeledblock:: ...and labelling blocks
|
|
|
4713 * ick_comefrom and ick_nextfrom:: Stealing control from elsewhere
|
|
|
4714 * ick_next:: The INTERCAL answer to subroutine calls
|
|
|
4715 * ick_resume:: Going back to before a NEXT
|
|
|
4716 * ick_forget:: Discarding NEXT stack entries
|
|
|
4717 * ick_get/setone/twospot:: Accessing INTERCAL variables from C
|
|
|
4718 * ick_create:: CREATE statements via external calls
|
|
|
4719 * External Calls and auto:: Considerations for auto variables
|
|
|
4720 @end menu
|
|
|
4721
|
|
|
4722 @node External C Call Infrastructure
|
|
|
4723 @subsection External C Call Infrastructure
|
|
|
4724 @cindex C, external call infrastructure
|
|
|
4725 @cindex external calls, C infrastructure
|
|
|
4726
|
|
|
4727 For a C program to be connected to an @ical{} program, it needs to be
|
|
|
4728 marked with the correct header file, and needs to have functions marked
|
|
|
4729 for communication with the @ical{} program.
|
|
|
4730
|
|
|
4731 @table @code
|
|
|
4732
|
|
|
4733 @item #include <ick_ec.h>
|
|
|
4734 @cindex ick_ec.h
|
|
|
4735 The header file @file{ick_ec.h} must be included using the
|
|
|
4736 preprocessor in any file which uses any of the @ical{} external call
|
|
|
4737 functions, variables, or macros. (Note that this file may not
|
|
|
4738 necessarily exist, or exist in the usual place; @command{ick} will
|
|
|
4739 deal with making sure the correct header file is included.) This will
|
|
|
4740 include @file{stdint.h} (a standard C header file, which must exist on
|
|
|
4741 your system), so that you can access @ical{} variables (the @ical{}
|
|
|
4742 types onespot, twospot, tail, hybrid correspond to the C types
|
|
|
4743 uint16_t, uint32_t, uint16_t*, uint32_t* respectively); also, it will
|
|
|
4744 provide the prototypes for all the functions and definitions for all
|
|
|
4745 the macros needed to use the external calls system with C.
|
|
|
4746
|
|
|
4747 @item ICK_EC_FUNC_START
|
|
|
4748 @itemx ICK_EC_FUNC_END
|
|
|
4749 @findex ICK_EC_FUNC_START
|
|
|
4750 @findex ICK_EC_FUNC_END
|
|
|
4751 Many of the @ical{} interface macros (@code{ick_linelabel},
|
|
|
4752 @code{ick_comefrom}, and @code{ick_nextfrom}) make it possible to
|
|
|
4753 jump from an @ical{} program to a C program. Because C doesn't allow
|
|
|
4754 jumping into the middle of a function, there has to be some way to
|
|
|
4755 create a block of code which @emph{can} be jumped into. This is what
|
|
|
4756 these two macros achieve.
|
|
|
4757
|
|
|
4758 This declaration and definition:
|
|
|
4759
|
|
|
4760 @example
|
|
|
4761 ICK_EC_FUNC_START(identifier)
|
|
|
4762 @{
|
|
|
4763 /* code goes here */
|
|
|
4764 @}
|
|
|
4765 ICK_EC_FUNC_END
|
|
|
4766 @end example
|
|
|
4767
|
|
|
4768 is equivalent to this:
|
|
|
4769
|
|
|
4770 @example
|
|
|
4771 void identifier(void)
|
|
|
4772 @{
|
|
|
4773 /* code goes here */
|
|
|
4774 @}
|
|
|
4775 @end example
|
|
|
4776
|
|
|
4777 except that it is possible to jump from an @ical{} program into the
|
|
|
4778 declared and defined program. (If you need to write a prototype for
|
|
|
4779 the function early, @code{void identifier(void);} is perfectly
|
|
|
4780 acceptable, but an early prototype is not required unless you call the
|
|
|
4781 function from earlier within the C code.) Of course, you can
|
|
|
4782 substitute any identifier that's legal as a function name for
|
|
|
4783 @code{identifier} (as long as it doesn't start with @code{ick_} or
|
|
|
4784 @code{ICK_}). The resulting function is a function (for instance, you
|
|
|
4785 can take its address or call it in the usual ways); the only
|
|
|
4786 differences are that it can be jumped into from @ical{} code and that
|
|
|
4787 it is constrained to take no arguments and return no data. (It can
|
|
|
4788 still access global and @ical{} variables.) If the function is jumped
|
|
|
4789 into from @ical{} code, but then control flow reaches the end of the
|
|
|
4790 function, or the function @code{return;}s but was not called from C,
|
|
|
4791 the resulting behaviour is undefined; @cic{} will attempt to continue
|
|
|
4792 by some means at that point, but may fail. If a function is unsure
|
|
|
4793 whether it gained control from C or from INTERCAL code, it may use
|
|
|
4794 @code{ick_return_or_resume} (described below).
|
|
|
4795
|
|
|
4796 Because you are not allowed to declare two C functions with the same
|
|
|
4797 name (even in different modules), all functions declared with
|
|
|
4798 @code{ICK_EC_FUNC_START} must have unique names across the entire
|
|
|
4799 compilation.
|
|
|
4800
|
|
|
4801 @end table
|
|
|
4802
|
|
|
4803 @node ick_startup
|
|
|
4804 @subsection ick_startup
|
|
|
4805 @findex ick_startup
|
|
|
4806 @cindex startup code, C
|
|
|
4807
|
|
|
4808 It is sometimes necessary for a C program to do its own initialisation
|
|
|
4809 before the INTERCAL program starts running. To do so, it can use the
|
|
|
4810 @code{ick_startup} macro inside a function declared with
|
|
|
4811 @code{ICK_EC_FUNC_START}; the syntax is @code{ick_startup(block)},
|
|
|
4812 where the argument is an expression, statement, or compound statement
|
|
|
4813 to run. The argument itself must not contain any ick_-prefixed macros
|
|
|
4814 or functions except possibly ick_create, may have side effects, and
|
|
|
4815 must fit the C preprocessor's idea of what a macro argument should
|
|
|
4816 look like (it's more used to parsing expressions than blocks; the
|
|
|
4817 general rule is to avoid commas except when they're directly or
|
|
|
4818 indirectly inside parentheses or strings).
|
|
|
4819
|
|
|
4820 @node ick_linelabel
|
|
|
4821 @subsection ick_linelabel
|
|
|
4822 @findex ick_linelabel
|
|
|
4823 @cindex line labels, C
|
|
|
4824
|
|
|
4825 A line label is something that can be @code{NEXT}ed to and @code{COME
|
|
|
4826 FROM}. Unlike an @ical{} line label, it does not label a statement,
|
|
|
4827 and therefore attempts to @code{ABSTAIN} or @code{REINSTATE} it may be
|
|
|
4828 errors, or may be ignored (it's unspecified which, which means that
|
|
|
4829 either may happen for any or no reason, but exactly one will happen in
|
|
|
4830 any given case, although the choice might not be consistent).
|
|
|
4831
|
|
|
4832 The macro @code{ick_linelabel(expression);} may appear anywhere a
|
|
|
4833 compound statement would normally be able to appear. (That is, it
|
|
|
4834 looks like a function call being used as a standalone expression, but
|
|
|
4835 in fact the places where it can appear are more limited.) In contrast
|
|
|
4836 to ordinary line labels, an expression can be used rather than just a
|
|
|
4837 constant; however, the behaviour is undefined if the expression has
|
|
|
4838 side-effects. Upon encountering the line label, any @code{COME FROM}s
|
|
|
4839 or @code{NEXT FROM}s aiming at the line label (including
|
|
|
4840 @code{ick_comefrom}s and @code{ick_nextfrom}s) will steal control from
|
|
|
4841 the program; @code{RESUMING} after a @code{NEXT FROM} will work, but
|
|
|
4842 suffers from the same caveats as setjmp/longjmp do (any auto variables
|
|
|
4843 that change their value between the @code{NEXT FROM} and @code{RESUME}
|
|
|
4844 will have their value clobbered (i.e. their value is no longer
|
|
|
4845 reliable and should not be accessed)). Note that the @ical{}
|
|
|
4846 variables are immune to this problem. You can also avoid the problem
|
|
|
4847 by marking variables as @code{volatile} in the C program.
|
|
|
4848
|
|
|
4849 It is possible to @code{NEXT} or @code{ick_next} to a
|
|
|
4850 @code{ick_linelabel}, which has the same effect as saving the
|
|
|
4851 @code{NEXT} stack, calling the function containing the
|
|
|
4852 @code{ick_linelabel} and then immediately doing a C @code{goto} to an
|
|
|
4853 imaginary label preceding it. Due to this possibility, an
|
|
|
4854 @code{ick_linelabel} is only allowed within a function defined with
|
|
|
4855 @code{ICK_EC_FUNC_START}.
|
|
|
4856
|
|
|
4857 @node ick_labeledblock
|
|
|
4858 @subsection ick_labeledblock
|
|
|
4859 @findex ick_labeledblock
|
|
|
4860 @cindex labeled blocks
|
|
|
4861 @cindex blocks, labeled
|
|
|
4862
|
|
|
4863 In @ical{} programs, labels don't stand on their own, but instead
|
|
|
4864 label a statement. The difference between a standalone line label and
|
|
|
4865 a line label that labels a statement is that @code{COME FROM}s will
|
|
|
4866 come from the @emph{label itself} (which is before the next statement)
|
|
|
4867 when aiming at a standalone line label, but the @emph{end of the
|
|
|
4868 statement} when aiming at a labeled statement. To achieve the same
|
|
|
4869 effect in C, the macro @code{ick_labeledblock} is available; it can be
|
|
|
4870 used as @code{ick_labeledblock(expression,expression)} or
|
|
|
4871 @code{ick_labeledblock(expression,statement)}; the first argument is
|
|
|
4872 the label, and the second argument is an expression or statement to
|
|
|
4873 label (if an expression is labeled, it will be converted to a
|
|
|
4874 statement that evaluates it for its side effects and discards the
|
|
|
4875 result). It is even permitted to label a block statement in this way.
|
|
|
4876 Note, however, that you have to contend with the C preprocessor's
|
|
|
4877 ideas of where macro arguments begin and end when doing this. Other
|
|
|
4878 than the position of the @code{COME FROM} target created by the label,
|
|
|
4879 this behaves the same way as @code{ick_linelabel} (so for instance,
|
|
|
4880 computed line labels are allowed, but the expression that computes
|
|
|
4881 them must not have side effects, and it is only allowed within a
|
|
|
4882 function defined with @code{ICK_EC_FUNC_START}).
|
|
|
4883
|
|
|
4884 @node ick_comefrom and ick_nextfrom
|
|
|
4885 @subsection ick_comefrom and ick_nextfrom
|
|
|
4886 @findex ick_comefrom
|
|
|
4887 @findex ick_nextfrom
|
|
|
4888 @cindex COME FROM, in C
|
|
|
4889 @cindex NEXT FROM, in C
|
|
|
4890
|
|
|
4891 The @code{ick_comefrom} and @code{ick_nextfrom} macros are, like the
|
|
|
4892 other @ical{} flow control macros (as opposed to functions), only
|
|
|
4893 allowed within a function defined with @code{ICK_EC_FUNC_START}. They
|
|
|
4894 act almost exactly like the @ical{} statements of the same name
|
|
|
4895 (although note that C statements cannot be @code{ABSTAIN}ed
|
|
|
4896 @code{FROM} even if they act the same way as @ical{} statements);
|
|
|
4897 they are written as @code{ick_comefrom(expression);} and
|
|
|
4898 @code{ick_nextfrom(expression);} respectively (note that they must be
|
|
|
4899 called as statements, and cannot be used as part of an expression).
|
|
|
4900 Whenever a standalone line label is encountered whose expression
|
|
|
4901 evaluates to the same number as the expression inside the
|
|
|
4902 @code{ick_comefrom} or @code{ick_nextfrom}, and that number is at most
|
|
|
4903 65535, then control will be transferred to the @code{ick_comefrom} or
|
|
|
4904 @code{ick_nextfrom}, leaving a @code{NEXT} stack entry behind in the
|
|
|
4905 case of @code{ick_nextfrom}; likewise, if the end of a labeled
|
|
|
4906 statement, expression or block is reached and the label has the right
|
|
|
4907 number. Some caveats: the expression need not be constant, but must
|
|
|
4908 not have side effects, must not be negative, and must fit into the
|
|
|
4909 range of an @code{unsigned long} in the C program (and the statement
|
|
|
4910 will do nothing if the expression evaluates to a value larger than
|
|
|
4911 65535). In keeping with the best C traditions, these caveats are not
|
|
|
4912 checked, but instead result in undefined behaviour if breached.
|
|
|
4913
|
|
|
4914 @findex ick_comefromif
|
|
|
4915 @findex ick_nextfromif
|
|
|
4916 There are also versions @code{ick_comefromif} and @code{ick_nextfromif},
|
|
|
4917 which take a second parameter, which is a condition that specifies
|
|
|
4918 whether control is actually stolen from the target. The condition may
|
|
|
4919 have side effects, and is only run when the line numbers match; it should
|
|
|
4920 return 0 or NULL to leave control flow alone, or nonzero to steal
|
|
|
4921 control, and should be either an integral type or a pointer type.
|
|
|
4922 Although side effects are allowed, the condition must not look at or
|
|
|
4923 alter @code{auto} or @code{register} variables in the enclosing function,
|
|
|
4924 not even if they are also marked @code{volatile}. (Global and
|
|
|
4925 @code{static} variables are fine, though.)
|
|
|
4926
|
|
|
4927 @node ick_next
|
|
|
4928 @subsection ick_next
|
|
|
4929 @findex ick_next
|
|
|
4930 @cindex NEXT, in C
|
|
|
4931
|
|
|
4932 @code{ick_next} is a macro that acts like the @ical{} statement
|
|
|
4933 @code{NEXT}. Contrary to the other @ical{}-like macros, it can be used
|
|
|
4934 in any function regardless of whether it was defined with
|
|
|
4935 @code{ICK_EC_FUNC_START}; however, it must still be used as a statement
|
|
|
4936 by itself, and a call to it looks like @code{ick_next(expression);}. The
|
|
|
4937 expression is the label to @code{NEXT} to, and works under the same rules
|
|
|
4938 as the expressions for @code{ick_comefrom}; it need not be constant
|
|
|
4939 (unlike in @cic{}!), but must not have side effects, must not be
|
|
|
4940 negative, must fit into the range of an unsigned long, and is ignored if
|
|
|
4941 it is over 65535. If there happen to be multiple labels with the correct
|
|
|
4942 value at the time, the compiler will @code{NEXT} to one of them. Bear in
|
|
|
4943 mind that there is a limit of 80 entries to the @code{NEXT} stack, and
|
|
|
4944 that this limit is enforced.
|
|
|
4945
|
|
|
4946 If the resulting @code{NEXT} stack entry is @code{RESUME}d to, the
|
|
|
4947 program will continue after the @code{ick_next} as if via @code{setjmp},
|
|
|
4948 with all the usual restrictions that that entails; if the resulting
|
|
|
4949 @code{NEXT} stack entry is forgotten, then the @code{ick_next} call will
|
|
|
4950 never return. (Notice the 'as if via setjmp' condition allows you to
|
|
|
4951 preserve the vales of @code{auto} and @code{alloca}-allocated storage as
|
|
|
4952 long as its value has not changed since the @code{ick_next} was called,
|
|
|
4953 which is a significantly more lenient condition than that normally
|
|
|
4954 imposed on such variables (@pxref{External Calls and auto}).
|
|
|
4955
|
|
|
4956 @node ick_resume
|
|
|
4957 @subsection ick_resume
|
|
|
4958 @findex ick_resume
|
|
|
4959 @cindex RESUME, in C
|
|
|
4960
|
|
|
4961 @code{ick_resume} is a macro, but there are few restrictions on its use;
|
|
|
4962 it is permitted to use it inside an expression (but it returns void,
|
|
|
4963 making this not particularly useful), and acts like a function which
|
|
|
4964 takes an unsigned short argument, returns void, and has a prototype (but
|
|
|
4965 you cannot take its address; if you need to be able to do that, write a
|
|
|
4966 wrapper function for it). It can be used within any function regardless
|
|
|
4967 of how it was declared, and never returns; instead, it pops the specified
|
|
|
4968 number of @code{NEXT} stack entries and resumes execution at the last one
|
|
|
4969 popped, just as the @ical{} statement does. This causes the same errors
|
|
|
4970 as the @ical{} statement if the number of entries popped is zero or
|
|
|
4971 larger than the @code{NEXT} stack.
|
|
|
4972
|
|
|
4973 @findex ick_return_or_resume
|
|
|
4974 There is also a macro @code{ick_return_or_resume();}; it can only be used
|
|
|
4975 inside a function defined with @code{ICK_EC_FUNC_START}, and is
|
|
|
4976 equivalent to @code{return;} if the function was called from C, or
|
|
|
4977 @code{ick_resume(1);} if the function was called from @ical{}. It's
|
|
|
4978 therefore a safe way to return from such a C function if you don't know
|
|
|
4979 how control reached it in the first place.
|
|
|
4980
|
|
|
4981 @node ick_forget
|
|
|
4982 @subsection ick_forget
|
|
|
4983 @findex ick_forget
|
|
|
4984 @cindex FORGET, in C
|
|
|
4985
|
|
|
4986 The @code{ick_forget} macro removes @code{NEXT} stack entries, and the
|
|
|
4987 corresponding C stack entries. It must be called as a statement by
|
|
|
4988 itself, and its invocation looks like this: @code{ick_forget(expr);},
|
|
|
4989 where the expression is the number of @code{NEXT} stack entries to forget
|
|
|
4990 (all of them will be forgotten if the number is higher than the number of
|
|
|
4991 entries). The expression will be casted to an @code{unsigned short}.
|
|
|
4992
|
|
|
4993 @code{ick_forget} can only be used inside a function declared with
|
|
|
4994 @code{ICK_EC_FUNC_START}. As it is removing stack entries both in
|
|
|
4995 @ical{} and in C, it will clobber the value of all @code{auto} variables
|
|
|
4996 created since the highest remaining @code{NEXT} stack entry came into
|
|
|
4997 being (or since the start of the program, if the @code{NEXT} stack is
|
|
|
4998 emptied by the command) and also deallocate all @code{alloca} storage
|
|
|
4999 allocated since then. It also causes the return address of the current
|
|
|
5000 function to become undefined, so that function must not return; control
|
|
|
5001 may leave it via @code{RESUME}, or via @code{COME FROM}, or via
|
|
|
5002 @code{NEXT} or @code{NEXT FROM} followed by the relevant @code{NEXT}
|
|
|
5003 stack entry being forgotten (the function is still 'running' but
|
|
|
5004 suspended while the @code{NEXT} stack entry still exists). (Note that
|
|
|
5005 these restrictions are stronger than those on @code{RESUME}; this is
|
|
|
5006 because @code{RESUME} preserves most of the stack, but @code{FORGET}
|
|
|
5007 destroys parts of the stack and therefore cannot avoid destroying the
|
|
|
5008 data stored there. It could be much worse; a previous (never released)
|
|
|
5009 version of the code didn't remove those parts of the stack in many
|
|
|
5010 circumstances, leading to a stack leak that caused programs to segfault
|
|
|
5011 after a while.)
|
|
|
5012
|
|
|
5013 @node ick_get/setone/twospot
|
|
|
5014 @subsection ick_get/setone/twospot
|
|
|
5015 @findex ick_getonespot
|
|
|
5016 @findex ick_setonespot
|
|
|
5017 @findex ick_gettwospot
|
|
|
5018 @findex ick_settwospot
|
|
|
5019 @cindex variables, from C
|
|
|
5020
|
|
|
5021 This class of four functions make it possible to get and set @ical{}
|
|
|
5022 scalar variables from C code. Their prototypes are as follows:
|
|
|
5023
|
|
|
5024 @example
|
|
|
5025 uint16_t ick_getonespot(unsigned short varnumber);
|
|
|
5026 void ick_setonespot(unsigned short varnumber, uint16_t newvalue);
|
|
|
5027 uint32_t ick_gettwospot(unsigned short varnumber);
|
|
|
5028 void ick_settwospot(unsigned short varnumber, uint32_t newvalue);
|
|
|
5029 @end example
|
|
|
5030
|
|
|
5031 The program will error out with a fatal error (@pxref{E200}) if the
|
|
|
5032 variable you request is mentioned nowhere in the @ical{} program; if
|
|
|
5033 you attempt to set an @code{IGNORE}d variable, the attempt will
|
|
|
5034 silently fail (just as if you assigned to it in an @ical{} program).
|
|
|
5035 The get functions are safe to use in a computed line label, so you can
|
|
|
5036 use them to produce computed line labels that depend on @ical{}
|
|
|
5037 variables. (@code{uint16_t} and @code{uint32_t} are standard C data
|
|
|
5038 types; if your system doesn't provide them, get better system header
|
|
|
5039 files.)
|
|
|
5040
|
|
|
5041 If you care about speed, note that .1 is the fastest variable of all
|
|
|
5042 to access, and otherwise variables first mentioned near the top of the
|
|
|
5043 @ical{} program will be faster to access than variables mentioned
|
|
|
5044 lower down.
|
|
|
5045
|
|
|
5046 @node ick_create
|
|
|
5047 @subsection ick_create
|
|
|
5048 @cindex CREATE, in C
|
|
|
5049 @cindex C, CREATE
|
|
|
5050
|
|
|
5051 The @code{ick_create} function (prototype: @code{void
|
|
|
5052 ick_create(char*, unsigned long)}) allows the external calls system to
|
|
|
5053 be used to create new @ical{} syntax; to do this, you give a
|
|
|
5054 `signature' representing the syntax you want to define and a line
|
|
|
5055 number to the function (which are its two arguments, respectively).
|
|
|
5056 The signature defines the syntax that you are defining; whenever that
|
|
|
5057 syntax is encountered within the @ical{} program, it will @code{NEXT}
|
|
|
5058 to the line number you specify, which can do various clever things and
|
|
|
5059 then @code{RESUME} back to the @ical{} program (or if you're defining
|
|
|
5060 a flow-control operation, you might want to leave the @code{NEXT}
|
|
|
5061 stack entry there and do other things). However, note that the
|
|
|
5062 overloading of @code{:1601}, etc.@:, will still take place as in the
|
|
|
5063 @ical{} version of @code{CREATE} if the @option{-a} option is used
|
|
|
5064 (@pxref{-a}), so care is needed when writing flow control statements
|
|
|
5065 that they work both with and without the option and don't cause
|
|
|
5066 @code{STASH} leaks (which means no @code{FORGET}ting the relevant
|
|
|
5067 @code{NEXT} stack entry, and no looking at 1600-range variables).
|
|
|
5068 This allows the external calls system to define whole new @ical{}
|
|
|
5069 commands, with the same power as any other programming language.
|
|
|
5070
|
|
|
5071 There are various restrictions on what syntax you can @code{CREATE}
|
|
|
5072 with this method, which are best explained by an explanation of the
|
|
|
5073 relevant @cic{} compiler internals. When an @ical{} program is
|
|
|
5074 compiled by @cic{}, any unrecognised statements it comes across are
|
|
|
5075 compiled by a `just-in-case' compiler that attempts to compile them
|
|
|
5076 anyway with no knowledge of their syntax, just in case the syntax
|
|
|
5077 becomes defined later. (E000 (@pxref{E000}) will be thrown when such
|
|
|
5078 statements are encountered at runtime, unless the syntax has been
|
|
|
5079 @code{CREATE}d since to give a statement a meaning.) For the
|
|
|
5080 just-in-case compiler to run, the resulting statement must be
|
|
|
5081 completely unrecognised; this means that it may contain no keywords
|
|
|
5082 (not even a sequence of letters that forms a keyword, such as
|
|
|
5083 @code{FROM} or @code{DO}), it must consist only of variable names,
|
|
|
5084 expressions, and capital letters other than @samp{V} (because @samp{V}
|
|
|
5085 is a unary operator, so otherwise there would be ambiguity), and in
|
|
|
5086 which any two variable names or expressions are separated by at least
|
|
|
5087 one capital letter. The compiler will produce a `signature' for the
|
|
|
5088 unknown command that can be defined.
|
|
|
5089
|
|
|
5090 @cindex signatures
|
|
|
5091 @cindex CREATE, signatures
|
|
|
5092 A signature consists of a sequence of characters (and is represented
|
|
|
5093 as a null-terminated string; the runtime makes a shallow copy of the
|
|
|
5094 string and keeps it until the end of the program, so arrangements must
|
|
|
5095 be made to ensure that the storage in which the string is allocated
|
|
|
5096 stays around that long, but this opens up interesting possibilities in
|
|
|
5097 which the signature that was actually @code{CREATE}d can be modified
|
|
|
5098 retroactively); whitespace is not allowed in a signature. Capital
|
|
|
5099 letters can be used (apart from @samp{V}), and match the same capital
|
|
|
5100 letters literally in the @ical{} syntax being created; also available
|
|
|
5101 are the special characters @samp{.,;~}, which match respectively a
|
|
|
5102 scalar variable (a onespot or twospot variable such as @code{:1}), an
|
|
|
5103 array variable (such as @code{;2}), an array element (such as @code{,3
|
|
|
5104 SUB #4 #5}), and an expression that isn't a variable name and isn't an
|
|
|
5105 array element (such as @code{.4$.5}). If you want to be able to match
|
|
|
5106 other things (say, to be able to match all expressions), you will need
|
|
|
5107 to submit multiple signatures using multiple calls to
|
|
|
5108 @code{ick_create}; maybe you could write a library to do that
|
|
|
5109 automatically.
|
|
|
5110
|
|
|
5111 @code{CREATE}d operators also have signatures, but of quite a
|
|
|
5112 different form. The signature for a single-character operator is a
|
|
|
5113 lowercase u, followed by its character code in hexadecimal (no leading
|
|
|
5114 zeros, and in lowercase); the signature for an overstrike is a
|
|
|
5115 lowercase o, followed by the lower relevant character code in
|
|
|
5116 hexadecimal, followed by a lowercase x, followed by the higher
|
|
|
5117 relevant character code in hexadecimal.
|
|
|
5118
|
|
|
5119 The routine that is @code{NEXT}ed to will presumably want to be able
|
|
|
5120 to see what in the @ical{} program was matched by the signature, so a
|
|
|
5121 range of function-like macros is provided to access that. They must
|
|
|
5122 be run from within the invocation of the function which was
|
|
|
5123 @code{NEXT}ed into by the created syntax (@pxref{External Calls and
|
|
|
5124 auto} for when a function invocation ends, which could be sooner than
|
|
|
5125 you think when the @cic{} external calls system is used), and are
|
|
|
5126 undefined behaviour when that invocation did not gain control from a
|
|
|
5127 @code{CREATE}d statement. Here are their effective prototypes:
|
|
|
5128
|
|
|
5129 @example
|
|
|
5130 int ick_c_width(int);
|
|
|
5131 int ick_c_isarray(int);
|
|
|
5132 unsigned short ick_c_varnumber(int);
|
|
|
5133 uint32_t ick_c_value(int);
|
|
|
5134 /* These require -a to work */
|
|
|
5135 uint32_t ick_c_getvalue(int);
|
|
|
5136 void ick_c_setvalue(int, uint32_t);
|
|
|
5137 @end example
|
|
|
5138
|
|
|
5139 The first argument to all these macros is the position of the match in
|
|
|
5140 the signature (0 for the first non-capital-letter match in the
|
|
|
5141 signature, 1 for the second, and so on until no more items are left in
|
|
|
5142 the signature to match); specifying a position that isn't in the
|
|
|
5143 signature is undefined behaviour.
|
|
|
5144
|
|
|
5145 @code{ick_c_width} returns the data type, as a width in bits, of the
|
|
|
5146 expression (or the width in bits of an element of the passed in
|
|
|
5147 array), and @code{ick_c_isarray} returns 1 if the argument was an
|
|
|
5148 array variable or 0 if it was an expression (array elements and scalar
|
|
|
5149 variables are expressions). @code{ick_c_varnumber} returns the
|
|
|
5150 variable's number (for instance 123 for @code{.123}), or 0 if the
|
|
|
5151 corresponding argument was not a variable; in the cases where the
|
|
|
5152 argument was a variable, these three functions together provide enough
|
|
|
5153 information to figure out which variable (which is useful if you're
|
|
|
5154 writing an extension which takes a variable name as an argument).
|
|
|
5155
|
|
|
5156 @code{ick_c_value} returns the value of the corresponding expression
|
|
|
5157 at the time the @code{CREATE}d command was called;
|
|
|
5158 @code{ick_c_getvalue} is almost equivalent, but only works if the
|
|
|
5159 @option{-a} option (@pxref{-a}) was used during compilation, and
|
|
|
5160 returns the value of the corresponding expression now. (The uint32_t
|
|
|
5161 return type is large enough to hold either a onespot or twospot value,
|
|
|
5162 and will be zero-extended if the corresponding expression had onespot
|
|
|
5163 type.) @code{ick_c_setvalue} also depends on @option{-a}, and will
|
|
|
5164 assign to the corresponding expression (be careful not to provide a
|
|
|
5165 value that is too large for it!@:). In the case that the corresponding
|
|
|
5166 expression is not a variable, this will attempt to perform a reverse
|
|
|
5167 assignment to the expression, and can produce ordinary @ical{} errors
|
|
|
5168 if it fails. It is not possible to redimension an array this way, as
|
|
|
5169 this is assignment, not a calculate operation.
|
|
|
5170
|
|
|
5171 @node External Calls and auto
|
|
|
5172 @subsection External Calls and auto
|
|
|
5173 @cindex auto
|
|
|
5174 @cindex alloca
|
|
|
5175 @cindex external calls, and auto
|
|
|
5176 @cindex C, auto/alloca
|
|
|
5177
|
|
|
5178 Because the external calls system merges the @ical{} @code{NEXT} stack
|
|
|
5179 with the C return value and data storage stack (note for pedants: the C
|
|
|
5180 standards nowhere mandate the existence of such a stack, or even mention
|
|
|
5181 one, but the restrictions stated in them imply that implementations have
|
|
|
5182 to act as if such a stack existed, because of the way the scoping rules
|
|
|
5183 and recursion work), the external calls system therefore has severe
|
|
|
5184 effects on data that happens to be stored there. (In @ical{} terms,
|
|
|
5185 imagine what would happen if data could be stored on the @code{NEXT}
|
|
|
5186 stack; if C used the more sensible system of having a @code{STASH} for
|
|
|
5187 each variable, these problems would never occur in the first place,
|
|
|
5188 instead causing an entirely different set of problems.) Similar
|
|
|
5189 considerations apply to the common nonstandard C extension @code{alloca},
|
|
|
5190 which dynamically alters the size of the stack; also, in what goes below,
|
|
|
5191 @code{register} variables should be considered to be @code{auto}, because
|
|
|
5192 the compiler may choose to allocate them on the stack. Theoretical
|
|
|
5193 considerations would lead one to conclude that variable-length arrays
|
|
|
5194 should obey most of the same restrictions; in practice, though, it's
|
|
|
5195 unwise to attempt to mix those with @ical{} code at all, except by
|
|
|
5196 separating them into separate functions which aren't flagged with
|
|
|
5197 @code{ICK_EC_FUNC_START} and use no @code{ick_}-prefixed identifiers,
|
|
|
5198 even indirectly. (They may cause a compile to fail completely because
|
|
|
5199 they don't mix well with @code{goto}.)
|
|
|
5200
|
|
|
5201 In the description below, @ical{} commands should be taken to include the
|
|
|
5202 equivalent C macros.
|
|
|
5203
|
|
|
5204 @code{NEXT}/@code{NEXT FROM} paired with @code{RESUME} have the least
|
|
|
5205 effect, and the most obvious effect, on @code{auto} variables in the
|
|
|
5206 function that was @code{NEXT}ed from, which is the same effect that the
|
|
|
5207 standard C function @code{longjmp} has. That is, @code{alloca} storage
|
|
|
5208 stays intact, and @code{auto} variables have their values `clobbered'
|
|
|
5209 (that is, their value is no longer reliable and should not be used) if
|
|
|
5210 they changed since the corresponding @code{NEXT} and are not marked as
|
|
|
5211 @code{volatile}. (This is a very easy restriction to get around, because
|
|
|
5212 changing the values of such variables is quite difficult without using
|
|
|
5213 statically-allocated pointers to point to them (a dubious practice in any
|
|
|
5214 case), and @code{volatile} is trivial to add to the declaration.)
|
|
|
5215
|
|
|
5216 @code{COME FROM} has more restrictions; it deallocates all @code{alloca}
|
|
|
5217 storage in the function that was @code{COME FROM}, and functions that
|
|
|
5218 called it or that called functions that called it, etc.@:, using C calls
|
|
|
5219 (as opposed to @code{NEXT}), and those invocations of the functions will
|
|
|
5220 cease to exist (thus destroying any @code{auto} variables in them), even
|
|
|
5221 in the case of @code{COMING FROM} a function into the same function.
|
|
|
5222 @code{auto} variables in the function that is come into will start
|
|
|
5223 uninitialised, even if initialisers are given in their declaration, and
|
|
|
5224 it will be a `new' invocation of that function. (It is quite possible
|
|
|
5225 that the uninitialised values in the @code{auto} variables will happen by
|
|
|
5226 chance to have the values they had in some previous invocation of the
|
|
|
5227 function, though, because they are likely to be stored in much the same
|
|
|
5228 region of memory; but it is highly unwise to rely on this.) Note that
|
|
|
5229 @code{volatile} will not help here. Observant or source-code-reading
|
|
|
5230 readers may note that there is a mention of an @code{ick_goto} in the
|
|
|
5231 source code to @cic{}; this is undocumented and this manual does not
|
|
|
5232 officially claim that such a macro exists (after all, if it did, what in
|
|
|
5233 @ical{} could it possibly correspond to?), but if such a macro does exist
|
|
|
5234 it obeys the same restrictions as @code{COME FROM}.
|
|
|
5235
|
|
|
5236 @code{FORGET} is the worst of all in terms of preserving data on the
|
|
|
5237 stack; it deallocates @code{alloca} data and clobbers or deletes
|
|
|
5238 @code{auto} variables in all function invocations that have come into
|
|
|
5239 existence since the @code{NEXT} that created the topmost remaining
|
|
|
5240 @code{NEXT} stack entry was called, or since the start of the program if
|
|
|
5241 the @code{NEXT} stack is emptied, and the current function will continue
|
|
|
5242 in a new invocation. @code{volatile} is useless in preventing this,
|
|
|
5243 because the relevant parts of the stack where the data were stored are
|
|
|
5244 deleted by the command (that's what @code{FORGET} does, remove stack).
|
|
|
5245 If any of these data are required, they have to be backed up into static
|
|
|
5246 storage (variables declared with @code{static} or global variables), or
|
|
|
5247 into heap storage (as in with @code{malloc}), or other types of storage
|
|
|
5248 (such as temporary files) which are not on the stack. (Incidentally,
|
|
|
5249 suddenly deleting parts of the stack is excellent at confusing C
|
|
|
5250 debuggers; but even @code{RESUME} and @code{COME FROM} tend to be
|
|
|
5251 sufficient to confuse such debuggers. More worrying is probably the fact
|
|
|
5252 that the C standard provides a portable method for deleting the stack
|
|
|
5253 like that, and in fact the external calls runtime library is written in
|
|
|
5254 standard freestanding-legal C89 (with the exception of
|
|
|
5255 @option{+printflow} debug output which requires a hosted implementation),
|
|
|
5256 meaning that in theory it would be possible to split it out to create an
|
|
|
5257 implementation of a C-plus-COME-FROM-and-NEXT language, and doing so
|
|
|
5258 would not be particularly difficult.)
|
|
|
5259
|
|
|
5260 Note that @ical{} variables are not stored on the C stack, nor are any of
|
|
|
5261 the metadata surrounding them, and so are not affected unduly by control
|
|
|
5262 flow operations.
|
|
|
5263
|
|
|
5264 @node External Calls to Funge-98
|
|
|
5265 @section External Calls to Funge-98
|
|
|
5266 @cindex .b98
|
|
|
5267 @cindex external calls, Funge
|
|
|
5268 @cindex external calls, Befunge
|
|
|
5269 @cindex Funge
|
|
|
5270 @cindex Befunge
|
|
|
5271
|
|
|
5272 @portability{no, version 0.29+, no, no}
|
|
|
5273
|
|
|
5274 @cic{} supports linking @ical{} programs with Funge-98 programs (to be
|
|
|
5275 precise, only Befunge-98 programs are currently supported). However,
|
|
|
5276 it does not ship with a Funge-98 interpreter, and such an interpreter
|
|
|
5277 needs to be linked to the resulting program in order to run the
|
|
|
5278 Befunge program. Therefore, you need to convert a third-party
|
|
|
5279 Funge-98 interpreter to a library usable by @cic{} before you can use
|
|
|
5280 this part of the external calls system (@pxref{Creating the Funge-98
|
|
|
5281 Library}); however, this only has to be done once.
|
|
|
5282
|
|
|
5283 Once the library has been created, you can link an @ical{} program
|
|
|
5284 with a Befunge-98 program by invoking @command{ick} like this:
|
|
|
5285
|
|
|
5286 @example
|
|
|
5287 ick -e intercalprogram.i befungeprogram.b98
|
|
|
5288 @end example
|
|
|
5289
|
|
|
5290 You can link no more than one Befunge-98 program at once (just like
|
|
|
5291 you can link no more than one @ical{} program at once). Also, the
|
|
|
5292 @ical{} program must come first on the command line.
|
|
|
5293
|
|
|
5294 It is legal to link @ical{}, C, and Befunge-98 simultaneously;
|
|
|
5295 however, the identifiers used in the third-party Funge-98 interpreter
|
|
|
5296 have not been mangled to avoid collisions, and therefore problems may
|
|
|
5297 be caused if the C program uses the same identifiers as the Funge-98
|
|
|
5298 interpreter.
|
|
|
5299
|
|
|
5300 @menu
|
|
|
5301 * Creating the Funge-98 Library:: How to create the Funge-98 library.
|
|
|
5302 * The IFFI Fingerprint:: External calls from Funge's view.
|
|
|
5303 @end menu
|
|
|
5304
|
|
|
5305 @node Creating the Funge-98 Library
|
|
|
5306 @subsection Creating the Funge-98 Library
|
|
|
5307 @cindex libick_ecto_b98.a
|
|
|
5308 @cindex Funge, installing
|
|
|
5309 @cindex Befunge, installing
|
|
|
5310 @cindex libraries, Funge
|
|
|
5311 @cindex libraries, Befunge
|
|
|
5312
|
|
|
5313 Before external calls to Funge-98 can be used, the relevant library
|
|
|
5314 must be compiled. (After the library has been compiled, then you will
|
|
|
5315 need to reinstall @cic{}; however, you will not need to recompile
|
|
|
5316 @cic{}.)
|
|
|
5317
|
|
|
5318 At present, only the cfunge Funge-98 interpreter can be converted into
|
|
|
5319 a library suitable for use by @cic{}; also, doing this is only
|
|
|
5320 supported on POSIX systems (although if someone gets it to work on
|
|
|
5321 DOS/Windows, the author of this manual would be interested to hear
|
|
|
5322 about it.) Also, a source-code distribution (rather than a binary
|
|
|
5323 distribution) is needed. One way to obtain the latest cfunge sources
|
|
|
5324 is via the bzr version-control system, using the following command
|
|
|
5325 (correct as of the time of writing, but as always, links can become
|
|
|
5326 dead):
|
|
|
5327
|
|
|
5328 @example
|
|
|
5329 bzr branch http://rage.kuonet.org/~anmaster/bzr/cfunge
|
|
|
5330 @end example
|
|
|
5331
|
|
|
5332 (As a licensing note, note that cfunge is licensed under the GNU
|
|
|
5333 General Public licence version 3, whereas @cic{} is licensed under
|
|
|
5334 version 2 and all later versions of that licence; although these terms
|
|
|
5335 are obviously compatible with each other, you must ensure yourself
|
|
|
5336 that your program has appropriate licensing terms to allow a GPLv3
|
|
|
5337 library to be linked to it.)
|
|
|
5338
|
|
|
5339 Once you have downloaded the cfunge sources, you need to compile them
|
|
|
5340 into a library suitable for use with @cic{} (note that this is a
|
|
|
5341 somewhat different process to compiling them into a standalone
|
|
|
5342 Funge-98 interpreter). There is a script provided in the @cic{}
|
|
|
5343 distribution to do this, @file{etc/cftoec.sh}. It must be run in the
|
|
|
5344 @file{etc} subdirectory of the @cic{} distribution (i.e. the directory
|
|
|
5345 the script itself is in), and must be given the path to the root
|
|
|
5346 directory of the cfunge source distribution (that is, the directory
|
|
|
5347 that contains the @file{src}, @file{lib} and @file{tools}
|
|
|
5348 subdirectories of that distribution) as its only argument. Note that
|
|
|
5349 it may give some compiler warnings on compilation; my experience is
|
|
|
5350 that warnings about C99 inlining can be safely ignored (they reflect a
|
|
|
5351 deficiency in @command{gcc} itself that luckily seems to be irrelevant
|
|
|
5352 in this case), but other warnings may indicate problems in the exact
|
|
|
5353 versions of the sources that you downloaded (and errors definitely
|
|
|
5354 indicate such problems).
|
|
|
5355
|
|
|
5356 Once the library has been created, it will appear as the new file
|
|
|
5357 @file{lib/libick_ecto_b98.a} in the @cic{} distribution (the cfunge
|
|
|
5358 distribution will be left unchanged); reinstalling @cic{} will install
|
|
|
5359 this file to its proper location. (It is also in a valid location to
|
|
|
5360 be able to be run if you aren't installing @cic{} but instead just
|
|
|
5361 running it from the distribution's directory.)
|
|
|
5362
|
|
|
5363 @node The IFFI Fingerprint
|
|
|
5364 @subsection The IFFI Fingerprint
|
|
|
5365 @cindex IFFI
|
|
|
5366 @cindex fingerprint
|
|
|
5367 @cindex external calls, from Funge's view
|
|
|
5368 @cindex Funge, fingerprint
|
|
|
5369 @cindex Befunge, fingerprint
|
|
|
5370
|
|
|
5371 @i{This section will not make much sense to a non-Funge programmer;
|
|
|
5372 therefore, if you are not used to Funge, you probably want to skip it.}
|
|
|
5373
|
|
|
5374 To a Funge program, the external calls interface is accessed via a
|
|
|
5375 Funge-98 'fingerprint' defined by the interpreter. The name of the
|
|
|
5376 fingerprint is 0x49464649, or as text, @samp{IFFI}.
|
|
|
5377
|
|
|
5378 When a program formed by linking @ical{} and Befunge-98 is run, the
|
|
|
5379 first thing that happens is some internal @ical{} initialisation which
|
|
|
5380 is not visible to either program, and then initialisation routines
|
|
|
5381 specified in the Befunge-98 program run (if an initialisation routine
|
|
|
5382 is also specified in a linked C program using ick_startup, it is
|
|
|
5383 unspecified whether the C or Befunge-98 initialisation happens first.)
|
|
|
5384 In the Befunge program, the initialisation routine consists of
|
|
|
5385 everything that happens until the @samp{Y} command in the @samp{IFFI}
|
|
|
5386 fingerprint is run; the author of the Funge-98 must load the
|
|
|
5387 @samp{IFFI} fingerprint themselves during this initialisation to
|
|
|
5388 access that command. (This is so that the Befunge program ends up
|
|
|
5389 complying with the Funge-98 standard; commands not defined in that
|
|
|
5390 standard cannot be used until a fingerprint is loaded.) During
|
|
|
5391 initialisation, no commands from the @samp{IFFI} fingerprint may be
|
|
|
5392 used except @samp{Y} and @samp{A}. (If a different command is used,
|
|
|
5393 @samp{C}, @samp{M}, and @samp{X} remove the arguments they would use
|
|
|
5394 from the stack (if any) but otherwise do nothing, and the other
|
|
|
5395 commands in the @samp{IFFI} fingerprint reflect.)
|
|
|
5396
|
|
|
5397 After the @samp{Y} command is called, the @ical{} program starts
|
|
|
5398 running; in order for the Befunge program to regain control, it has to
|
|
|
5399 be @code{NEXT}ed to from the @ical{} program, or @code{COME} or
|
|
|
5400 @code{NEXT FROM} the @ical{} program, or contain the line label to
|
|
|
5401 which syntax in the @ical{} program was @code{CREATE}d. (In other
|
|
|
5402 words, the normal @ical{} ways of transferring information between
|
|
|
5403 parts of a program.) In order to do this, therefore, line labels and
|
|
|
5404 @ical{} control flow statements must be placed into the Befunge
|
|
|
5405 program.
|
|
|
5406
|
|
|
5407 @cindex marker
|
|
|
5408 @cindex Funge, marker
|
|
|
5409 @cindex Befunge, marker
|
|
|
5410 Code like @code{COME FROM (100)} is a single statement in @ical{}, but
|
|
|
5411 several statements in Funge-98; therefore, some method of telling the
|
|
|
5412 interpreter where to start executing to look for @code{COME FROM}s,
|
|
|
5413 @code{NEXT FROM}s, and line labels is needed. The method used by
|
|
|
5414 @cic{} is that of the 'marker'; a marker is represented by character
|
|
|
5415 0xB7 (a mid-dot in Latin-1) in the input Funge-98 program, but is
|
|
|
5416 transformed to a capital @samp{M} by @command{ick}. (The reason for
|
|
|
5417 using a special character for a marker and transforming it rather than
|
|
|
5418 just using @samp{M} is to prevent occurences of @samp{M} in comments
|
|
|
5419 and string literals, etc.@:, having an effect on the control flow of
|
|
|
5420 the program.) Whenever a @code{NEXT} or line label is encountered (in
|
|
|
5421 the @ical{} program, the Funge program or elsewhere), the Funge
|
|
|
5422 program is executed starting from each marker in each cardinal
|
|
|
5423 direction to look for line labels or @code{COME}/@code{NEXT FROM}s
|
|
|
5424 respectively. Therefore, @code{COME FROM (100)} is written in
|
|
|
5425 Funge-98 as @code{Maa*C} (where the M is a marker in the source code),
|
|
|
5426 and likewise the line label @code{(100)} would be written as
|
|
|
5427 @code{Maa*L}. (This code can be written in any cardinal direction,
|
|
|
5428 that is left to right, top to bottom, right to left, or bottom to top,
|
|
|
5429 but not diagonally or flying.) There are likely to be unused
|
|
|
5430 directions from markers, which will be evaluated too; you can (and
|
|
|
5431 must) close these off by reflecting code execution back into that
|
|
|
5432 marker, another marker, or a non-marker @code{M}. Note also that a
|
|
|
5433 marker remains in Funge-space even if the @code{M} on the same square
|
|
|
5434 is deleted (the marker itself is not visible to the @code{g} command,
|
|
|
5435 though).
|
|
|
5436
|
|
|
5437 Here are the commands in the @samp{IFFI} fingerprint:
|
|
|
5438 @cindex IFFI, commands
|
|
|
5439 @table @code
|
|
|
5440 @item A
|
|
|
5441 @cindex CREATE, in Funge
|
|
|
5442 This command pops a line number and then an 0"gnirts"-format string
|
|
|
5443 from the stack; they are used as the line number and signature to
|
|
|
5444 @code{CREATE} syntax in the @ical{} program; for details of the format
|
|
|
5445 of the signature, see @ref{ick_create}. Although using this command
|
|
|
5446 during speculative execution works, doing so is not recommended; if
|
|
|
5447 the target line number for @code{CREATE}d syntax is changed during
|
|
|
5448 speculative execution to find the line that that syntax corresponds
|
|
|
5449 to, its effect is delayed until after the original line is found and
|
|
|
5450 execution continues from that point. (Side effects during speculative
|
|
|
5451 execution are never recommended, because they might or might not be
|
|
|
5452 optimised away.)
|
|
|
5453 @item C
|
|
|
5454 @cindex COME FROM, in Funge
|
|
|
5455 During speculative execution to find @code{COME FROM}s and @code{NEXT
|
|
|
5456 FROM}s, pops a line label off the top of the stack and does a
|
|
|
5457 @code{COME FROM} that location. During speculative excution to find
|
|
|
5458 line labels, pops the top of the stack and ends that particular
|
|
|
5459 speculative execution as a failure. When not doing speculative
|
|
|
5460 execution, pops and discards the top element of the stack.
|
|
|
5461 @item D
|
|
|
5462 This command must only be used when the Funge program is executing a
|
|
|
5463 @code{CREATE}d command, and allows access to the arguments that
|
|
|
5464 command has. It pops an integer off the top of the stack, and treats
|
|
|
5465 it as an argument position (0-based, so 0 refers to the first
|
|
|
5466 argument, 1 refers to the second, and so on). Note that providing an
|
|
|
5467 invalid argument number, or running this command when not implementing
|
|
|
5468 a @code{CREATE}d command, leads to undefined behaviour (possibly a
|
|
|
5469 reflection, possibly a segfault, possibly worse).
|
|
|
5470
|
|
|
5471 The command pushes information about the argument chosen onto the
|
|
|
5472 stack; the following information is pushed from bottom to top:
|
|
|
5473 @itemize
|
|
|
5474 @item
|
|
|
5475 The data type of the argument, in bits (16 if the argument was a
|
|
|
5476 onespot variable or expression of onespot type, and 32 if the argument
|
|
|
5477 was a twospot variable or expression of twospot type). Note that this
|
|
|
5478 is under the @cic{} typing rules, rather than the @icst{} typing rules
|
|
|
5479 (that is, select's type is always that of its right argument no matter
|
|
|
5480 how many bits are actually selected).
|
|
|
5481 @item
|
|
|
5482 1 if the argument is an array variable, 0 if it is a scalar value.
|
|
|
5483 @item
|
|
|
5484 0 if the argument is not a variable, or the variable's number if it is
|
|
|
5485 (e.g.@: @code{.123} would push 123 here, but @code{.1~.2} would push
|
|
|
5486 0).
|
|
|
5487 @item
|
|
|
5488 The argument's value at the time that the @code{CREATE}d instruction
|
|
|
5489 was called.
|
|
|
5490 @item
|
|
|
5491 The argument's value now, or alternatively a repeat of the previous
|
|
|
5492 stack element if @option{-a} (@pxref{-a}) was not used. (Without
|
|
|
5493 @option{-a}, the information needed to re-evaluate the expression is
|
|
|
5494 not available.)
|
|
|
5495 @end itemize
|
|
|
5496 @item F
|
|
|
5497 @cindex FORGET, in Funge
|
|
|
5498 During speculative execution, this command reflects; otherwise, this
|
|
|
5499 command pops an integer from the top of stack, and @code{FORGET}s that
|
|
|
5500 many @code{NEXT} stack entries (or all of them if the argument given
|
|
|
5501 is negative).
|
|
|
5502 @item G
|
|
|
5503 @cindex variables, Funge, accessing
|
|
|
5504 This command pops an integer from the top of stack. If it is
|
|
|
5505 positive, the value of the onespot variable whose name is the popped
|
|
|
5506 integer is pushed onto the stack; if it is negative, the value of the
|
|
|
5507 twospot variable whose name is minus the popped integer is pushed onto
|
|
|
5508 the stack; and if it is zero, the command reflects. If the referenced
|
|
|
5509 variable is not in the @ical{} program at all, this causes an @ical{}
|
|
|
5510 error due to referencing a nonexistent variable.
|
|
|
5511 @item L
|
|
|
5512 @cindex line label, in Funge
|
|
|
5513 During speculative execution to find @code{COME FROM}s and @code{NEXT
|
|
|
5514 FROM}s, this command pops and discards the top stack element, then
|
|
|
5515 ends that speculative execution. During speculative execution to find
|
|
|
5516 a line label, this command pops an integer from the top of stack and
|
|
|
5517 succeeds with that integer as the line label (that is, it is possible
|
|
|
5518 to @code{NEXT} to an @code{L} in the Funge program if a marker,
|
|
|
5519 followed by code to push the correct line number onto the stack,
|
|
|
5520 precedes that @code{L}). When not doing speculative execution, the
|
|
|
5521 integer on the top of the stack is used as a line label (assuming it
|
|
|
5522 is in the range 1--65535, otherwise it is popped and discarded), and
|
|
|
5523 a search is made for @code{COME FROM}s and @code{NEXT FROM}s aiming
|
|
|
5524 for that line label (including in the @ical{} program and the Befunge
|
|
|
5525 program itself, as well as programs in any other language which may be
|
|
|
5526 linked in). Note that just as in @ical{}, it is possible to
|
|
|
5527 @code{NEXT} to a line label which has a @code{COME FROM} aiming for
|
|
|
5528 it, in which case the @code{COME FROM} will come from that line label
|
|
|
5529 as soon as the @code{NEXT} transfers control to it.
|
|
|
5530 @item M
|
|
|
5531 Does nothing if not in speculative execution, or ends the current
|
|
|
5532 speculative execution with failure. (This is so that code like
|
|
|
5533 @example
|
|
|
5534 v
|
|
|
5535 >M5C
|
|
|
5536 ^
|
|
|
5537 @end example
|
|
|
5538 does exactly the same thing as @code{COME FROM (5)}, even when, for
|
|
|
5539 instance, it is entered from the left in the Funge program, rather
|
|
|
5540 than gaining control from the line label @code{(5)}.)
|
|
|
5541 @item N
|
|
|
5542 @cindex NEXT, in Funge
|
|
|
5543 During speculative execution, reflects. Otherwise, pops the top stack
|
|
|
5544 element, interprets it as a line label, and @code{NEXT}s to that line
|
|
|
5545 label (this may start speculative execution to look for line labels,
|
|
|
5546 but might not if it isn't needed, for instance if the line label in
|
|
|
5547 question is in the @ical{} program or in a C program linked to the
|
|
|
5548 Befunge program).
|
|
|
5549 @item R
|
|
|
5550 @cindex RESUME, in Funge
|
|
|
5551 During speculative execution, reflects. Otherwise, pops the top stack
|
|
|
5552 element, removes that many items from the @code{NEXT} stack, and
|
|
|
5553 @code{RESUME}s at the last item removed. (If the top stack element
|
|
|
5554 was zero, negative, or too large, this will cause a fatal error in the
|
|
|
5555 @ical{} program.)
|
|
|
5556 @item S
|
|
|
5557 @cindex variables, Funge, setting
|
|
|
5558 Pops a variable number (interpreted as onespot if positive, or minus
|
|
|
5559 the number of a twospot variable if negative) and an integer from the
|
|
|
5560 stack, and sets the referenced variable to the integer. This reflects
|
|
|
5561 if an attempt is made to set the nonexistent variable 0, causes a
|
|
|
5562 fatal error in the @ical{} program if an attempt is made to set a
|
|
|
5563 variable that doesn't exist there, and does not set read-only
|
|
|
5564 variables (but pops the stack anyway). If the integer is too high for
|
|
|
5565 the variable it is being stored in, only the least significant 16 or
|
|
|
5566 32 bits from it will be used; and likewise, if it is negative, it will
|
|
|
5567 be treated as the two's complement of the number given.
|
|
|
5568 @item V
|
|
|
5569 Pops a @code{CREATE}d argument index and an integer from the top of
|
|
|
5570 stack. (This is undefined behaviour if not in the implementation of a
|
|
|
5571 @code{CREATE}d statement, or if the referenced argument does not
|
|
|
5572 exist; as with the @code{D} instruction, 0 refers to the first
|
|
|
5573 argument, 1 to the second, and so on.) If the @option{-a} option is
|
|
|
5574 not used, this command does nothing; otherwise, the value of the
|
|
|
5575 argument will be set to the integer. (This involves doing a reverse
|
|
|
5576 assignment if the argument is a non-variable expression, as usual, and
|
|
|
5577 causes a fatal error in the @ical{} program if the reverse assignment
|
|
|
5578 is impossible or an attempt is made to assign a scalar to an array.)
|
|
|
5579 @item X
|
|
|
5580 @cindex NEXT FROM, in Funge
|
|
|
5581 This is identical to @code{C}, except that it does a @code{NEXT FROM}
|
|
|
5582 rather than a @code{COME FROM}.
|
|
|
5583 @end table
|
|
|
5584
|
|
|
5585 As with external calls to C, terminating any program involved (whether
|
|
|
5586 the @ical{} program with @code{GIVE UP}, the Befunge program with
|
|
|
5587 @code{@@} or @code{q}, or a C program with @code{exit()}) causes all
|
|
|
5588 programs involved to terminate, and likewise a fatal error will end
|
|
|
5589 all programs with an error.
|
|
|
5590
|
|
|
5591 One final point which is probably worth mentioning is that flow
|
|
|
5592 control instructions only record the IP's position and direction,
|
|
|
5593 nothing else; so for instance, if the stack is modified in one part of
|
|
|
5594 the code, those modifications will remain even after a @code{RESUME},
|
|
|
5595 for instance.
|
|
|
5596
|
|
|
5597 @node Miscellaneous External Calls
|
|
|
5598 @section Miscellaneous External Calls
|
|
|
5599 @cindex external calls, miscellaneous
|
|
|
5600 @cindex miscellaneous external calls
|
|
|
5601 @cindex libraries, external calls
|
|
|
5602 @cindex external calls, libraries
|
|
|
5603 @cindex C99
|
|
|
5604 @cindex external calls, C99
|
|
|
5605
|
|
|
5606 @portability{no, version 0.29+, no, no}
|
|
|
5607
|
|
|
5608 It is possible to specify other information to the external calls
|
|
|
5609 system by using the filename list after all the options are given. To
|
|
|
5610 be precise, certain filename patterns are recognised and used to
|
|
|
5611 change the options that are used to compile the externally-called
|
|
|
5612 files.
|
|
|
5613
|
|
|
5614 The @samp{.c99} extension is treated identically to @samp{.c}, except
|
|
|
5615 that it causes the file with that extension to be preprocessed as C99
|
|
|
5616 (the more modern version of the C standard, the older C89 is more
|
|
|
5617 common), and that all C files involved will be compiled and linked as
|
|
|
5618 C99. (This corresponds to @option{-std=c99} in @command{gcc}.)
|
|
|
5619
|
|
|
5620 The @samp{.a} extension indicates that an object-code library should
|
|
|
5621 be linked in to the final program. This is most commonly used to link
|
|
|
5622 in the maths library @file{libm.a} and other such system libraries.
|
|
|
5623 If the filename is of the form @samp{lib*.a}, then the file will be
|
|
|
5624 searched for in the standard directories for libraries on your system,
|
|
|
5625 and also where the @cic{} libraries are stored (which may be the same
|
|
|
5626 place); otherwise, the current directory will be searched.
|
|
|
5627 (Specifying @file{libm.a} on the command line corresponds to passing
|
|
|
5628 @option{-lm} to @command{gcc}.)
|
|
|
5629
|
|
|
5630 @node Using External Calls
|
|
|
5631 @section Using External Calls
|
|
|
5632 @cindex using external calls
|
|
|
5633 @cindex external calls, using
|
|
|
5634
|
|
|
5635 Whatever language your source files are written in, when @option{-e}
|
|
|
5636 is used (@pxref{-e}), the compiler will go through much the same
|
|
|
5637 steps.
|
|
|
5638
|
|
|
5639 First, the @ical{} program specified is compiled into a C program that
|
|
|
5640 uses the @ical{} external call conventions for its control flow
|
|
|
5641 operations. The resulting @samp{.c} file will be left behind in the
|
|
|
5642 same directory (even if @option{-g} isn't used); if you look at it,
|
|
|
5643 you'll see the @code{#include <ick_ec.h>} line, and the other
|
|
|
5644 hallmarks of an external call program (for instance, @ical{}
|
|
|
5645 @code{NEXT}s will translate into slightly modified @code{ick_next}s;
|
|
|
5646 the modification is simply to allow the correct line number to be
|
|
|
5647 displayed in case of error).
|
|
|
5648
|
|
|
5649 After that, the resulting files are preprocessed twice. First, the C
|
|
|
5650 preprocessor is run on the files; then, a special @cic{}
|
|
|
5651 `preprocessor' is run on the files. (`Preprocessor' is a bit of a
|
|
|
5652 misnomer here, as it's near the end of the compilation process;
|
|
|
5653 `postprocessor' would likely be more accurate, or maybe
|
|
|
5654 `interprocessor'.) Its job is to fix line labels between the gotos
|
|
|
5655 that are used to implement jumping into the middle of a C function, to
|
|
|
5656 assign unique numbers to things that need them, and to keep track of
|
|
|
5657 which functions need to be checked for line labels and for @code{COME
|
|
|
5658 FROM}s and @code{NEXT FROM}s. The resulting file will have the
|
|
|
5659 extension @samp{.cio}; it is almost human-readable, especially if you
|
|
|
5660 run it through a C code indenter, and consists of C code (or code in
|
|
|
5661 whatever language is being linked to the @ical{} code, but so far only
|
|
|
5662 C is accepted) and instructions to @command{gcc}. The @samp{.cio}
|
|
|
5663 file will be left behind for you to look at, if you like.
|
|
|
5664
|
|
|
5665 Once the @samp{.cio} files have been produced, @command{gcc} is used
|
|
|
5666 to compile all the @samp{.cio} files and link them together into an
|
|
|
5667 executable; the executable will have the same name as the @ical{}
|
|
|
5668 source, minus any extension (and on DJGPP, assuming that its version
|
|
|
5669 of @command{gcc} could handle the resulting command line (not
|
|
|
5670 necessarily guaranteed), a @samp{.exe} extension is added), and will
|
|
|
5671 consist of all the C files linked together with the @ical{}. Any
|
|
|
5672 functions named @code{main} in the C files will be deleted; likewise,
|
|
|
5673 if there is a name clash between any two functions, the one in the
|
|
|
5674 file named earlier on the command line will be used. There is
|
|
|
5675 presumably some use for this feature, although I haven't figured out
|
|
|
5676 what it is yet.
|
|
|
5677
|
|
|
5678 Extending this to other compiled languages is mostly a problem of
|
|
|
5679 determining how they fit into the @ical{} control structure, which is
|
|
|
5680 not a trivial task, and of figuring out how to link them to C code,
|
|
|
5681 which in some cases is trivial (especially if the language is one that
|
|
|
5682 @command{gcc} can compile!) and in other cases is very difficult. If
|
|
|
5683 anyone has any ideas of new languages that could be added to the
|
|
|
5684 external calls system, feel free to contact the current @cic{}
|
|
|
5685 maintainer with suggestions or patches.
|
|
|
5686
|
|
|
5687 @node Expansion Libraries
|
|
|
5688 @section Expansion Libraries
|
|
|
5689 @cindex expansion libraries
|
|
|
5690 @cindex libraries
|
|
|
5691
|
|
|
5692 @portability{no, version 0.28+, no, no}
|
|
|
5693
|
|
|
5694 The @cic{} distribution comes with libraries that can be used to
|
|
|
5695 extend its capabilities; they are implemented using the external call
|
|
|
5696 mechanism, and are in effect standard files to include using that
|
|
|
5697 mechanism. To use an expansion library, give the @option{-e} option
|
|
|
5698 to @command{ick} (note that this means you cannot use them with the
|
|
|
5699 debugger or profiler, nor with multithreaded or backtracking
|
|
|
5700 programs), and specify the expansion library's name at the end of the
|
|
|
5701 command line (or to be precise, anywhere after the initial @ical{}
|
|
|
5702 file). The libraries themselves are written in C and have a @samp{.c}
|
|
|
5703 extension, and are human-readable; @cic{} will look for them in the
|
|
|
5704 same places as it looks for the system library (including in the
|
|
|
5705 current directory, so you can test your own expansion libraries
|
|
|
5706 without having to install them).
|
|
|
5707
|
|
|
5708 Expansion libraries use C identifiers which start with the string
|
|
|
5709 @samp{ick_my_} (this is not used by the compiler, and is explicitly
|
|
|
5710 not affected by the prohibition on identifiers starting @samp{ick_}
|
|
|
5711 when writing an expansion library), and use line labels in the range
|
|
|
5712 (1600) to (1699). (Most programs will be avoiding this range anyway,
|
|
|
5713 because it's inside the (1000) to (1999) range reserved for the system
|
|
|
5714 library, but the system library doesn't use it, in much the same way
|
|
|
5715 that the identifiers used are inside the range reserved for the
|
|
|
5716 compiler, but the compiler doesn't use them.)
|
|
|
5717
|
|
|
5718 Expansion libraries are available from @cic{} version 0.28; @clcic{}
|
|
|
5719 has a similar concept (that of `preloads'), but implemented a
|
|
|
5720 completely different way.
|
|
|
5721
|
|
|
5722 @subheading syslibc
|
|
|
5723 @findex syslibc
|
|
|
5724 @cindex system library, in C
|
|
|
5725 @cindex C, system library
|
|
|
5726
|
|
|
5727 @option{syslibc} is an implementation of the base-2 @ical{} system
|
|
|
5728 library in C (@pxref{System Library}); using it in programs running in
|
|
|
5729 other bases is accepted by the compiler, but likely to produce
|
|
|
5730 unpredictable results. When using this expansion library, you also
|
|
|
5731 need to give the @option{-E} option (@pxref{-E+,,-E}) so that the main
|
|
|
5732 system library is not included, or it will be used in preference to
|
|
|
5733 the expansion library. All documented features of the @ical{} base-2
|
|
|
5734 system library are implemented, but most undocumented features are
|
|
|
5735 not, so @ical{} programs which relied on them (dubious behaviour in
|
|
|
5736 any case) will not work with @option{syslibc}. The main reason to use
|
|
|
5737 this library is to increase the speed of an @ical{} program; however,
|
|
|
5738 note that the speed gains in arithmetic will be accompanied by the
|
|
|
5739 performance penalty of using the external calls infrastructure, unless
|
|
|
5740 you were already using it.
|
|
|
5741
|
|
|
5742 @subheading compunex
|
|
|
5743 @findex compunex
|
|
|
5744 @cindex computed NEXT
|
|
|
5745 @cindex NEXT, computed
|
|
|
5746
|
|
|
5747 As an example of using @code{ick_create}, a very simple expansion
|
|
|
5748 library is provided to enable a computed NEXT capability, by defining
|
|
|
5749 a new command @code{COMPUNEX}. It is used as @code{DO .1 COMPUNEX}
|
|
|
5750 (allowing any expression in place of the .1), and is similar to an
|
|
|
5751 ordinary @code{NEXT}, but has two limitations: it takes up two
|
|
|
5752 @code{NEXT} stack entries, and the top one should not be
|
|
|
5753 @code{RESUMEd} past or forgotten (thus it isn't a particularly useful
|
|
|
5754 command, except maybe to produce the equivalent of something like
|
|
|
5755 function pointers). By the way, note that @cic{} avoids computed
|
|
|
5756 @code{NEXT} mainstream for much the same way that @clcic{} avoids
|
|
|
5757 @code{NEXT} altogether; it makes things too easy. This example is
|
|
|
5758 provided mostly just to demonstrate the syntax, and the care that
|
|
|
5759 needs to be taken with implementing flow control operators.
|
|
|
5760
|
|
|
5761 @samp{compunex} is double-deprecated; an alternative is the following
|
|
|
5762 sequence of commands involving computed @command{CREATE}:
|
|
|
5763
|
|
|
5764 @example
|
|
|
5765 DO CREATE .1 ABC
|
|
|
5766 DO ABC
|
|
|
5767 @end example
|
|
|
5768
|
|
|
5769 This sequence emulates all features of @code{NEXT} (although it has
|
|
|
5770 different gerunds and is two statements, not one), making it much more
|
|
|
5771 useful for simulating computed @code{NEXT} than @code{COMPUNEX}
|
|
|
5772 is. (There's no need to avoid forgetting the return value; although
|
|
|
5773 this skips the @code{CREATE} cleanup, none is required because the
|
|
|
5774 created statement @code{ABC} (any other statement would do just as
|
|
|
5775 well) takes no arguments.)
|
|
|
5776
|
|
|
5777 @node Differences to Other Compilers
|
|
|
5778 @chapter Differences to Other Compilers
|
|
|
5779 @cindex INTERCAL compilers
|
|
|
5780
|
|
|
5781 The @cic{} compiler exists in a world of several other compilers.
|
|
|
5782
|
|
|
5783 @subheading Differences to the Princeton compiler
|
|
|
5784 @cindex Princeton compiler
|
|
|
5785 The Princeton compiler was the first @ical{} compiler available, and
|
|
|
5786 compiled @icst{}. Using @command{convickt} (@pxref{convickt}) to
|
|
|
5787 translate its programs from the original EBCDIC to Latin-1 or
|
|
|
5788 Atari-syntax ASCII is required to run them under the @cic{} compiler,
|
|
|
5789 but apart from that there should be no problems; everything that that
|
|
|
5790 compiler can do can be reproduced by @cic{}, even including some of
|
|
|
5791 its bugs. The only potential problems may be where constructs were
|
|
|
5792 nonportable or dubious to begin with (such as the
|
|
|
5793 @code{IGNORE}/@code{RETRIEVE} interaction), or where commands intended
|
|
|
5794 to be syntax errors were used in the program but have a meaning in
|
|
|
5795 @cic{}. For extra portability, it's possible to use the @code{-t}
|
|
|
5796 compiler option to @command{ick} (@pxref{-t}) to tell it to interpret
|
|
|
5797 the program as @icst{}, but as @cic{}'s dialect of @ical{} is
|
|
|
5798 basically backward-compatible anyway this mostly serves to check newer
|
|
|
5799 programs for compatibility with older compilers.
|
|
|
5800
|
|
|
5801 @subheading Differences to the Atari compiler
|
|
|
5802 @cindex Atari compiler
|
|
|
5803 The Atari compiler was another implementation of @icst{}, which was
|
|
|
5804 basically identical to the Princeton compiler apart from its use of
|
|
|
5805 ASCII and Atari syntax. Everything said under the previous section
|
|
|
5806 applies, except that as it uses the same syntax as @cic{} anyway
|
|
|
5807 (@cic{}'s syntax was based on the Atari compiler's), there is no need
|
|
|
5808 to use @command{convickt}.
|
|
|
5809
|
|
|
5810 @subheading Differences to @jic{}
|
|
|
5811 @cindex J-INTERCAL
|
|
|
5812 The @jic{} compiler is an implementation of @ical{} written in Java
|
|
|
5813 that compiles @ical{} into Java (and so has a similar relationship
|
|
|
5814 with Java to that of the @cic{} compiler (which is written in C and
|
|
|
5815 compiles into C) with C). @jic{} has much the same feature set as
|
|
|
5816 older versions of @cic{}, with a few changes (such as the addition of
|
|
|
5817 Esperanto and error messages coming up in different situations).
|
|
|
5818 @jic{} programs should run fine on @cic{} without trouble (as it is
|
|
|
5819 also an Atari syntax compiler), except in nonportable cases such as
|
|
|
5820 @code{IGNORE}/@code{RETRIEVE} interaction.
|
|
|
5821
|
|
|
5822 @subheading Differences to @clcic{}
|
|
|
5823 @cindex CLC-INTERCAL
|
|
|
5824 The @clcic{} compiler is the most modern @ical{} compiler apart from
|
|
|
5825 @cic{} (both compilers are maintained and updated every now and then
|
|
|
5826 as of the time of writing, so which is more modern is normally a
|
|
|
5827 matter of when you happen to check). Unlike the other three compilers
|
|
|
5828 mentioned above, it has a quite significant feature set, including
|
|
|
5829 many features not implemented or only partially implemented in @cic{},
|
|
|
5830 and is responsible for the origin of many of the features added in
|
|
|
5831 more recent versions of @cic{}. Generally speaking, a @clcic{}
|
|
|
5832 program that uses its advanced features is unlikely to run on @cic{},
|
|
|
5833 or vice versa, whatever you do (apart from completely rewriting the
|
|
|
5834 more advanced parts of the program.)
|
|
|
5835
|
|
|
5836 However, there are certain steps that can be taken to transfer less
|
|
|
5837 advanced programs from one compiler to the other. First, translate
|
|
|
5838 the program to Latin-1 Princeton syntax (if translating from @clcic{}
|
|
|
5839 to @cic{}) or Atari syntax (if translating from @cic{} to @clcic{}),
|
|
|
5840 maybe using @command{convickt}, if necessary. (Note that here the
|
|
|
5841 program is being translated to the syntax that is not default for the
|
|
|
5842 target compiler.) Then use command-line arguments to switch the
|
|
|
5843 compiler into the correct emulation mode for the other compiler;
|
|
|
5844 @cic{} uses the options @option{-xX}, and on @clcic{} this is done by
|
|
|
5845 selecting the appropriate preloads, or by changing the program's file
|
|
|
5846 extension to @samp{.ci}. In each case other options may be needed to
|
|
|
5847 turn on various extensions (maybe @option{-m} or @option{-v} if
|
|
|
5848 translating to @cic{}, maybe the preload for gerund-based @code{COME
|
|
|
5849 FROM} if translating to @clcic{}), and if translating to @clcic{} you
|
|
|
5850 need to append the system library to your program yourself because
|
|
|
5851 @clcic{} doesn't load it automatically.
|
|
|
5852
|
|
|
5853 In the case of very simple programs, or if you want to spend the
|
|
|
5854 effort in translating compiler-specific code from one compiler to
|
|
|
5855 another, you may be able to work without emulation options. (This is
|
|
|
5856 a good target to aim for, in any case.) In such a case, you would do
|
|
|
5857 nothing other than possibly edit the program to be more portable and a
|
|
|
5858 possible character set and syntax change using @command{convickt}. If
|
|
|
5859 you need compiler-specific code, you may be able to detect the
|
|
|
5860 compiler in the code itself and adapt accordingly; making use of the
|
|
|
5861 @code{IGNORE}/@code{RETRIEVE} interaction is one way to do this, as it
|
|
|
5862 differs between @cic{}, @jic{}, and @clcic{}. The other things to
|
|
|
5863 watch out for when doing this are that @clcic{} needs an explicit
|
|
|
5864 option to enable the use of @code{NEXT}, that @clcic{} doesn't load
|
|
|
5865 the system library itself (you need to manually append it to the end
|
|
|
5866 of the program) and that you probably shouldn't number a line (666)
|
|
|
5867 unless you know what you're doing, because that line number has a
|
|
|
5868 special meaning in @clcic{}.
|
|
|
5869
|
|
|
5870 @ifset notsplit
|
|
|
5871 @partheading{PART IV: APPENDICES AND INDICES}
|
|
|
5872 @end ifset
|
|
|
5873 @node Character Sets
|
|
|
5874 @appendix Character Sets
|
|
|
5875 @cindex character sets
|
|
|
5876 @cindex Atari, character set
|
|
|
5877 @cindex Baudot
|
|
|
5878 @cindex EBCDIC
|
|
|
5879 @cindex Latin-1
|
|
|
5880
|
|
|
5881 The following table explains the equivalences between the various
|
|
|
5882 character sets used for @ical{}: 7-bit ASCII Atari syntax, 5-bit
|
|
|
5883 Baudot Princeton syntax, 8-bit EBCDIC Princeton syntax, and 8-bit
|
|
|
5884 Latin-1 Princeton syntax. (The Baudot and EBCDIC are the @clcic{}
|
|
|
5885 versions, which are used by @ical{} compilers but basically nowhere
|
|
|
5886 else.) The characters themselves are not shown in the table below,
|
|
|
5887 because they would have to be shown in some syntax, which would be
|
|
|
5888 misleading. (Atari syntax is used throughout this manual; you could
|
|
|
5889 convert from that, assuming you have an ASCII table handy.) You can
|
|
|
5890 also use the @command{convickt} command-line tool to translate @ical{}
|
|
|
5891 programs from one format to another (@pxref{convickt}). Note that
|
|
|
5892 Baudot has more than one 'shift state'; the shift state (1, 2, 3, or
|
|
|
5893 4) is written before the hexadecimal code for each character, and *
|
|
|
5894 represents a character available in every shift state. To change from
|
|
|
5895 one shift state to another, use character 1f to change from shift
|
|
|
5896 states 3 or 4 to 1, or from 1 or 2 to 2, and character 1b to change
|
|
|
5897 from shift states 1 or 2 to 3, or from 3 or 4 to 4.
|
|
|
5898
|
|
|
5899 @multitable {@b{Atari}}{@b{Baudot}}{@b{EBCDIC}}{@b{Latin-1}}
|
|
|
5900 @headitem Atari @tab Baudot @tab EBCDIC @tab Latin-1
|
|
|
5901 @item 09 @tab N/A @tab 09 @tab 09
|
|
|
5902 @item 0a @tab * 02 @tab 0a @tab 0a
|
|
|
5903 @item 0d @tab * 08 @tab 0d @tab 0d
|
|
|
5904 @item 20 @tab * 04 @tab 40 @tab 20
|
|
|
5905 @item 21 @tab 3 0d @tab 4f @tab 21
|
|
|
5906 @item 22 @tab 3 11 @tab 7f @tab 22
|
|
|
5907 @item 23 @tab 4 06 @tab 7b @tab 23
|
|
|
5908 @item 24 @tab 4 01 @tab 4a @tab a2
|
|
|
5909 @item 25 @tab 4 1c @tab 6c @tab 25
|
|
|
5910 @item 26 @tab 3 1a @tab 50 @tab 26
|
|
|
5911 @item 27 @tab 3 0b @tab 7d @tab 27
|
|
|
5912 @item 28 @tab 3 0f @tab 4d @tab 28
|
|
|
5913 @item 29 @tab 3 12 @tab 5d @tab 29
|
|
|
5914 @item 2a @tab 4 09 @tab 5c @tab 2a
|
|
|
5915 @item 2b @tab 4 03 @tab 4e @tab 2b
|
|
|
5916 @item 2c @tab 3 0c @tab 6b @tab 2c
|
|
|
5917 @item 2d @tab 3 03 @tab 60 @tab 2d
|
|
|
5918 @item 2e @tab 3 1c @tab 4b @tab 2e
|
|
|
5919 @item 2f @tab 3 1d @tab 61 @tab 2f
|
|
|
5920 @item 30 @tab 3 16 @tab f0 @tab 30
|
|
|
5921 @item 31 @tab 3 17 @tab f1 @tab 31
|
|
|
5922 @item 32 @tab 3 13 @tab f2 @tab 32
|
|
|
5923 @item 33 @tab 3 01 @tab f3 @tab 33
|
|
|
5924 @item 34 @tab 3 0a @tab f4 @tab 34
|
|
|
5925 @item 35 @tab 3 10 @tab f5 @tab 35
|
|
|
5926 @item 36 @tab 3 15 @tab f6 @tab 36
|
|
|
5927 @item 37 @tab 3 07 @tab f7 @tab 37
|
|
|
5928 @item 38 @tab 3 06 @tab f8 @tab 38
|
|
|
5929 @item 39 @tab 3 18 @tab f9 @tab 39
|
|
|
5930 @item 3a @tab 3 0e @tab 7a @tab 3a
|
|
|
5931 @item 3b @tab 3 1e @tab 5e @tab 3b
|
|
|
5932 @item 3c @tab 4 0f @tab 4c @tab 3c
|
|
|
5933 @item 3d @tab 4 07 @tab 7e @tab 3d
|
|
|
5934 @item 3e @tab 4 12 @tab 6e @tab 3e
|
|
|
5935 @item 3f @tab 4 0c @tab 65 @tab a5
|
|
|
5936 @item 40 @tab 3 19 @tab 6f @tab 3f
|
|
|
5937 @item 41 @tab 1 03 @tab c1 @tab 41
|
|
|
5938 @item 42 @tab 1 19 @tab c2 @tab 42
|
|
|
5939 @item 43 @tab 1 0e @tab c3 @tab 43
|
|
|
5940 @item 44 @tab 1 09 @tab c4 @tab 44
|
|
|
5941 @item 45 @tab 1 01 @tab c5 @tab 45
|
|
|
5942 @item 46 @tab 1 0d @tab c6 @tab 46
|
|
|
5943 @item 47 @tab 1 1a @tab c7 @tab 47
|
|
|
5944 @item 48 @tab 1 14 @tab c8 @tab 48
|
|
|
5945 @item 49 @tab 1 06 @tab c9 @tab 49
|
|
|
5946 @item 4a @tab 1 0b @tab d1 @tab 4a
|
|
|
5947 @item 4b @tab 1 0f @tab d2 @tab 4b
|
|
|
5948 @item 4c @tab 1 13 @tab d3 @tab 4c
|
|
|
5949 @item 4d @tab 1 1c @tab d4 @tab 4d
|
|
|
5950 @item 4e @tab 1 0c @tab d5 @tab 4e
|
|
|
5951 @item 4f @tab 1 18 @tab d6 @tab 4f
|
|
|
5952 @item 50 @tab 1 16 @tab d7 @tab 50
|
|
|
5953 @item 51 @tab 1 17 @tab d8 @tab 51
|
|
|
5954 @item 52 @tab 1 0a @tab d9 @tab 52
|
|
|
5955 @item 53 @tab 1 05 @tab e2 @tab 53
|
|
|
5956 @item 54 @tab 1 10 @tab e3 @tab 54
|
|
|
5957 @item 55 @tab 1 07 @tab e4 @tab 55
|
|
|
5958 @item 56 @tab 1 1e @tab e5 @tab 56
|
|
|
5959 @item 57 @tab 1 12 @tab e6 @tab 57
|
|
|
5960 @item 58 @tab 1 1d @tab e7 @tab 58
|
|
|
5961 @item 59 @tab 1 15 @tab e8 @tab 59
|
|
|
5962 @item 5a @tab 1 11 @tab e9 @tab 5a
|
|
|
5963 @item 5b @tab 4 10 @tab 9e @tab 5b
|
|
|
5964 @item 5c @tab 4 05 @tab N/A @tab 5c
|
|
|
5965 @item 5d @tab 4 13 @tab 5a @tab 5d
|
|
|
5966 @item 5e @tab 4 0d @tab 6a @tab 7c
|
|
|
5967 @item 5f @tab 4 15 @tab 7c @tab 40
|
|
|
5968 @item 60 @tab N/A @tab N/A @tab 60
|
|
|
5969 @item 61 @tab 2 03 @tab 81 @tab 61
|
|
|
5970 @item 62 @tab 2 19 @tab 82 @tab 62
|
|
|
5971 @item 63 @tab 2 0e @tab 83 @tab 63
|
|
|
5972 @item 64 @tab 2 09 @tab 84 @tab 64
|
|
|
5973 @item 65 @tab 2 01 @tab 85 @tab 65
|
|
|
5974 @item 66 @tab 2 0d @tab 86 @tab 66
|
|
|
5975 @item 67 @tab 2 1a @tab 87 @tab 67
|
|
|
5976 @item 68 @tab 2 14 @tab 88 @tab 68
|
|
|
5977 @item 69 @tab 2 06 @tab 89 @tab 69
|
|
|
5978 @item 6a @tab 2 0b @tab 91 @tab 6a
|
|
|
5979 @item 6b @tab 2 0f @tab 92 @tab 6b
|
|
|
5980 @item 6c @tab 2 13 @tab 93 @tab 6c
|
|
|
5981 @item 6d @tab 2 1c @tab 94 @tab 6d
|
|
|
5982 @item 6e @tab 2 0c @tab 95 @tab 6e
|
|
|
5983 @item 6f @tab 2 18 @tab 96 @tab 6f
|
|
|
5984 @item 70 @tab 2 16 @tab 97 @tab 70
|
|
|
5985 @item 71 @tab 2 17 @tab 98 @tab 71
|
|
|
5986 @item 72 @tab 2 0a @tab 99 @tab 72
|
|
|
5987 @item 73 @tab 2 05 @tab a2 @tab 73
|
|
|
5988 @item 74 @tab 2 10 @tab a3 @tab 74
|
|
|
5989 @item 75 @tab 2 07 @tab a4 @tab 75
|
|
|
5990 @item 76 @tab 2 1e @tab a5 @tab 76
|
|
|
5991 @item 77 @tab 2 12 @tab a6 @tab 77
|
|
|
5992 @item 78 @tab 2 1d @tab a7 @tab 78
|
|
|
5993 @item 79 @tab 2 15 @tab a8 @tab 79
|
|
|
5994 @item 7a @tab 2 11 @tab a9 @tab 7a
|
|
|
5995 @item 7b @tab 4 0a @tab 9c @tab 7b
|
|
|
5996 @item 7c @tab 4 1e @tab fe @tab N/A
|
|
|
5997 @item 7d @tab 4 11 @tab dc @tab 7d
|
|
|
5998 @item 7e @tab 4 0b @tab a1 @tab 7e
|
|
|
5999 @end multitable
|
|
|
6000
|
|
|
6001 @node convickt
|
|
|
6002 @appendix convickt
|
|
|
6003 @cindex convickt
|
|
|
6004 @cindex character sets, converting
|
|
|
6005 @cindex converting between character sets
|
|
|
6006
|
|
|
6007 A variety of character sets have historically been used to represent
|
|
|
6008 @ical{} programs. Atari syntax was designed specifically for use with
|
|
|
6009 ASCII-7, and all Atari-syntax-based @ical{} compilers accept that
|
|
|
6010 character set as possible input. (@cic{} also accepts Latin-1 and
|
|
|
6011 UTF-8.) However, the story is more complicated with Princeton syntax;
|
|
|
6012 the original Princeton compiler was designed to work with EBCDIC, but
|
|
|
6013 because modern computers are often not designed to work with this
|
|
|
6014 character set other character sets are often used to represent it,
|
|
|
6015 particularly Latin-1. The @clcic{} compiler accepts Latin-1, a custom
|
|
|
6016 dialect of EBCDIC, Baudot, and a punched-card format as input; @cic{}
|
|
|
6017 can cope with Latin-1 Princeton syntax, but for the other character
|
|
|
6018 sets, for other compilers, or just for getting something
|
|
|
6019 human-readable, it's useful to have a conversion program.
|
|
|
6020 @command{convickt} is an @ical{} character set conversion program
|
|
|
6021 designed with these needs in mind.
|
|
|
6022
|
|
|
6023 The syntax for using @command{convickt} is
|
|
|
6024
|
|
|
6025 @example
|
|
|
6026 convickt @var{inputset} @var{outputset} [@var{padding}]
|
|
|
6027 @end example
|
|
|
6028
|
|
|
6029 (that is, the input and output character sets are compulsory, but the
|
|
|
6030 parameter specifying what sort of padding to use is optional).
|
|
|
6031
|
|
|
6032 The following values for @var{inputset} and @var{outputset} are
|
|
|
6033 permissible:
|
|
|
6034
|
|
|
6035 @table @samp
|
|
|
6036 @item latin1
|
|
|
6037 Latin-1, or to give it its official name ISO-8859-1, is the character
|
|
|
6038 set most commonly used for transmitting @clcic{} programs, and
|
|
|
6039 therefore nowadays the most popular character set for Princeton syntax
|
|
|
6040 programs. Because it is identical to ASCII-7 in all codepoints that
|
|
|
6041 don't have the high bit set, most of the characters in it can be read
|
|
|
6042 by most modern editors and terminals. It is also far more likely to
|
|
|
6043 be supported by modern editors than EBCDIC, Baudot, or punched cards,
|
|
|
6044 all of which have fallen into relative disuse since 1972. It is also
|
|
|
6045 the only input character set that @cic{} supports for Princeton syntax
|
|
|
6046 programs. It uses 8 bit characters.
|
|
|
6047
|
|
|
6048 @item ebcdic
|
|
|
6049 EBCDIC is an 8-bit character set that was an alternative to ASCII in
|
|
|
6050 1972, and is the character set used by the original Princeton
|
|
|
6051 compiler. Unfortunately, there is no single standard version; the
|
|
|
6052 version of EBCDIC used by @command{convickt} is the one that @clcic{}
|
|
|
6053 uses. It is the default input character set that @clcic{} uses
|
|
|
6054 (although more recent versions of @clcic{} instead try to guess the
|
|
|
6055 input character set based on the input program.)
|
|
|
6056
|
|
|
6057 @item baudot
|
|
|
6058 Baudot is a 5-bit character set with shift codes; therefore when
|
|
|
6059 storing it in a file on an 8-bit computer, padding is needed to fill
|
|
|
6060 in the remaining three bits. The standard Baudot character set does
|
|
|
6061 not contain all the characters needed by @ical{}; therefore, @clcic{}
|
|
|
6062 uses repeated shift codes to add two more sets of characters.
|
|
|
6063 @command{convickt} uses the @clcic{} version of Baudot, so as to be
|
|
|
6064 able to translate programs designed for that compiler; however,
|
|
|
6065 standard Baudot is also accepted in input if it contains no redundant
|
|
|
6066 shift codes, and if the input contains no characters not in standard
|
|
|
6067 Baudot, the output will be written so that it is both correct standard
|
|
|
6068 Baudot and correct @clcic{} Baudot for those characters.
|
|
|
6069
|
|
|
6070 @item atari
|
|
|
6071 This option causes @command{convickt} to attempt a limited conversion
|
|
|
6072 to or from Atari syntax; this uses ASCII-7 as the character set, but
|
|
|
6073 also tries to translate between Atari and Princeton syntax at the
|
|
|
6074 character level, which is sometimes but not always effective. For
|
|
|
6075 instance, @code{?} is translated from Atari to Princeton as a yen
|
|
|
6076 sign, and from Princeton to Atari as a whirlpool (@code{@@}); this
|
|
|
6077 sort of behaviour is often capable of translating expressions
|
|
|
6078 automatically, but will fail when characters outside ASCII-7 (Atari)
|
|
|
6079 or Latin-1 (Princeton) are used, and will not, for instance, translate
|
|
|
6080 a Princeton @code{V}, backspace, @code{-} into Atari @code{?}, but
|
|
|
6081 instead leave it untouched. ASCII-7 is a 7-bit character set, so on
|
|
|
6082 an 8 bit computer, there is one bit of padding that needs to be
|
|
|
6083 generated; note, however, that it is usual nowadays to clear the top
|
|
|
6084 bit when transmitting ASCII-7, which the `printable' and `zero'
|
|
|
6085 padding styles will do, but the `random' style may not do.
|
|
|
6086
|
|
|
6087 @end table
|
|
|
6088
|
|
|
6089 When using a character set where not all bits in each byte are
|
|
|
6090 specified, a third argument can be given to specify what sort of
|
|
|
6091 padding to use for the top bits of each character. There are three
|
|
|
6092 options for this:
|
|
|
6093
|
|
|
6094 @multitable {printable}{Keep the output in the range 32-126 where possible}
|
|
|
6095 @headitem Option @tab Meaning
|
|
|
6096 @item printable
|
|
|
6097 @tab Keep the output in the range 32-126 where possible
|
|
|
6098 @item zero
|
|
|
6099 @tab Zero the high bits in the output
|
|
|
6100 @item random
|
|
|
6101 @tab Pad with random bits (avoiding all-zero bytes)
|
|
|
6102 @end multitable
|
|
|
6103
|
|
|
6104 Note that not all conversions are possible. If a character cannot be
|
|
|
6105 converted, it will normally be converted to a NUL byte (which is
|
|
|
6106 invalid in every character set); note that this will prevent
|
|
|
6107 round-tripping, because NUL is interpreted as end-of-input if given in
|
|
|
6108 the input. There is one exception; if the character that could not be
|
|
|
6109 converted is a tab character, it will be converted to the other
|
|
|
6110 character set's representation of a space character, if possible,
|
|
|
6111 because the two characters have the same meaning in @ical{} (the only
|
|
|
6112 difference is if the command is a syntax error that's printed as an
|
|
|
6113 error message). (The exception exists to make it possible to
|
|
|
6114 translate existing @ical{} source code into Baudot.)
|
|
|
6115
|
|
|
6116 @node Optimizer Idiom Language
|
|
|
6117 @appendix Optimizer Idiom Language
|
|
|
6118 @cindex Optimizer Idiom Language
|
|
|
6119 @cindex OIL
|
|
|
6120
|
|
|
6121 One file in the @cic{} distribution (@file{src/idiotism.oil}) is written
|
|
|
6122 in Optimizer Idiom Language, a programming language designed especially
|
|
|
6123 for expressing optimizer idioms for @ical{} in an easily editable form
|
|
|
6124 (well, at least it's easier than the unmaintainable set of idioms
|
|
|
6125 hard-coded in C that were used in previous versions of the @ical{}
|
|
|
6126 compiler).
|
|
|
6127
|
|
|
6128 @menu
|
|
|
6129 * Basics: OIL Basics. The basics of how an OIL program works.
|
|
|
6130 * Syntax: OIL Syntax. How to write comments, idioms, and groups.
|
|
|
6131 * Expressions: OIL Expressions. Expressions are the basis of idioms.
|
|
|
6132 * Patterns: OIL Patterns. Filling in the left hand side of an idiom.
|
|
|
6133 * Replacements: OIL Replacements. Syntax for the right hand side.
|
|
|
6134 * Loops: OIL Loops. Simplifying and shortening programs.
|
|
|
6135 * Tips: OIL Tips. Some tips about using OIL.
|
|
|
6136 * Example: OIL Example. An example of how OIL can work.
|
|
|
6137 @end menu
|
|
|
6138
|
|
|
6139 @node OIL Basics
|
|
|
6140 @appendixsec OIL Basics
|
|
|
6141 @cindex OIL, basics
|
|
|
6142 @cindex @file{src/idiotism.oil}
|
|
|
6143 @cindex @file{idiotism.oil}
|
|
|
6144 @cindex OIL, execution
|
|
|
6145
|
|
|
6146 The structure of an @acronym{OIL} file consists of a sequence of idioms.
|
|
|
6147 An optimizer idiom looks for a certain pattern in an expression (which
|
|
|
6148 could be an @ical{} expression, or an expression that has already been
|
|
|
6149 partly optimized and therefore contains some non-@ical{} operators), and
|
|
|
6150 replaces it with a replacement that's `simpler' in some sense (in the
|
|
|
6151 case of @cic{}, `simpler' is interpreted to mean `compiles into a faster
|
|
|
6152 or smaller executable when run through a C compiler'). When an
|
|
|
6153 @acronym{OIL} program acts on an input @ical{} file, it keeps on
|
|
|
6154 matching idioms to simplify expressions, until none of the idioms act
|
|
|
6155 any more (and if a situation occurs where idioms can keep matching
|
|
|
6156 indefinitely, the compiler goes into an infinite loop; so don't allow
|
|
|
6157 that to happen); at present, the idioms are tried from left to right,
|
|
|
6158 from the leaves of an expression to its root, and from the start of the
|
|
|
6159 OIL file to the end; but don't rely on that, because it's subject to
|
|
|
6160 change (and gets confusing when you think about what happens when the
|
|
|
6161 program actually does a replacement). Anyway, the point is that if an
|
|
|
6162 idiom can match an expression, and another idiom doesn't change it
|
|
|
6163 first, then the idiom will be matched against that part of the
|
|
|
6164 expression eventually, and the program won't end until there are no
|
|
|
6165 idioms that match the optimized expression.
|
|
|
6166
|
|
|
6167 At present, the only place that @acronym{OIL} is used in the @cic{}
|
|
|
6168 compiler is when the @option{-O} option (@pxref{-O+,,-O}) is used in
|
|
|
6169 base 2. (Syntax is planned to extend @acronym{OIL} to higher bases, and
|
|
|
6170 some of this is documented and even implemented, but there's no way to
|
|
|
6171 use it.) The idioms are read from the file @file{src/idiotism.oil}
|
|
|
6172 during the compilation of the @cic{} from sources; you can change the
|
|
|
6173 idioms, but you will then have to recompile the distribution (and if you
|
|
|
6174 are using the @command{config.sh} method, also reinstall, but that will
|
|
|
6175 be pretty fast.)
|
|
|
6176
|
|
|
6177 @node OIL Syntax
|
|
|
6178 @appendixsec OIL Syntax
|
|
|
6179 @cindex OIL, syntax
|
|
|
6180 @cindex syntax, of OIL
|
|
|
6181
|
|
|
6182 An @acronym{OIL} file is encoded as an @acronym{ASCII} text file using
|
|
|
6183 no codepoints outside the range 0-127; using 10 for newline (as on a
|
|
|
6184 UNIX or Linux system) is always acceptable, but using 13 then 10 (as is
|
|
|
6185 common on Windows or DOS) for newline is acceptable only if your C
|
|
|
6186 compiler recognizes that as a newline. I have no idea what happens if
|
|
|
6187 you use just 13 on an Apple computer on which that is the common newline
|
|
|
6188 convention.
|
|
|
6189
|
|
|
6190 @cindex OIL, comments
|
|
|
6191 @cindex comments, OIL
|
|
|
6192 Comments can be given anywhere in the file by writing lines starting
|
|
|
6193 with semicolons (known as hybrids to @ical{} programmers). It's also
|
|
|
6194 possible to write a semicolon after part of a line to comment out the
|
|
|
6195 rest of the line. Inside braced C expressions, comments can be given
|
|
|
6196 anywhere whitespace would be allowed by placing them between @code{/*}
|
|
|
6197 and @code{*/} (in such cases, the comments will be copied verbatim to
|
|
|
6198 the C temporary files used when building the @cic{} compiler, where your
|
|
|
6199 C compiler will ignore them). Whitespace is ignored nearly everywhere;
|
|
|
6200 the only places it isn't ignored are in the middle of a decimal
|
|
|
6201 constant, inside square brackets, immediately after one of the
|
|
|
6202 characters @samp{.:#_@}}, and anywhere that C doesn't allow it in quoted
|
|
|
6203 C code. (This means that you can even place it inside operators like &&
|
|
|
6204 if you like, as long as they're part of OIL code and not C code,
|
|
|
6205 although doing this is not recommended.) If you use whitespace in a
|
|
|
6206 situation where it isn't ignored, that's almost certainly an error.
|
|
|
6207
|
|
|
6208 @cindex OIL, idiom groups
|
|
|
6209 Idioms are grouped into groups of idioms by placing an identifier in
|
|
|
6210 square brackets before the group; this follows the rules for C
|
|
|
6211 identifiers, except that there's a maximum length of 30 characters.
|
|
|
6212 This identifier is the `name' of the group, which has no effect except
|
|
|
6213 on optimizer debug output; for that matter, the only effect a group has
|
|
|
6214 is that all idioms in the group look the same in optimizer debug output,
|
|
|
6215 because they have the same name. It's recommended that idioms only have
|
|
|
6216 the same name if they are the same idiom, possibly written in several
|
|
|
6217 ways. For example, a shift by 0 has no effect and may as well be
|
|
|
6218 removed from the output; the way to express this in OIL is:
|
|
|
6219
|
|
|
6220 @example
|
|
|
6221 [nullshift]
|
|
|
6222 (_1 >> #0)->(_1)
|
|
|
6223 (_1 << #0)->(_1)
|
|
|
6224 @end example
|
|
|
6225
|
|
|
6226 Here, nullshift is the name of the group of idioms, and two idioms are
|
|
|
6227 given; one which removes a null rightshift, and one which removes a null
|
|
|
6228 leftshift.
|
|
|
6229
|
|
|
6230 @cindex OIL, idioms
|
|
|
6231 @cindex idiom
|
|
|
6232 As the example above shows, the syntax of an idiom itself is
|
|
|
6233
|
|
|
6234 @example
|
|
|
6235 (pattern)->(replacement)
|
|
|
6236 @end example
|
|
|
6237
|
|
|
6238 The parentheses here are actually part of the pattern and/or
|
|
|
6239 replacement, and as such sparks (apostrophes) or rabbit-ears (double
|
|
|
6240 quotes) can be used instead; they're shown in the syntax because the
|
|
|
6241 outer layer of parenthesising is always required. Both the pattern and
|
|
|
6242 replacement are @acronym{OIL} expressions, although they both have their
|
|
|
6243 own special syntax elements as well.
|
|
|
6244
|
|
|
6245 @node OIL Expressions
|
|
|
6246 @appendixsec OIL Expressions
|
|
|
6247 @cindex expressions, OIL
|
|
|
6248 @cindex OIL, expressions
|
|
|
6249
|
|
|
6250 An @acronym{OIL} expression is built around subexpressions connected by
|
|
|
6251 infix binary operators and/or preceded by prefix unary operators, the
|
|
|
6252 same way as in C or @ical{} (although unary operators must be entirely
|
|
|
6253 before their argument; the one character later position is not allowed.)
|
|
|
6254 As in @ical{}, there is no operator precedence; expressions must be very
|
|
|
6255 fully bracketed to show unambiguously what the precedences must be, and
|
|
|
6256 then more so; for instance, bracketing marks must be placed around the
|
|
|
6257 argument of a unary operator in most circumstances. Bracketing of
|
|
|
6258 expressions can be done with parentheses, sparks (apostrophes) or
|
|
|
6259 rabbit-ears (double-quotes).
|
|
|
6260
|
|
|
6261 The following unary and binary operators are allowed in OIL expressions:
|
|
|
6262
|
|
|
6263 @cindex OIL, operators
|
|
|
6264 @cindex operators, OIL
|
|
|
6265 @multitable {@code{@@216..@@516}}{@ical{} unary generalised whirlpool (16-bit)}
|
|
|
6266 @item @code{$} @tab INTERCAL mingle
|
|
|
6267 @item @code{~} @tab INTERCAL select
|
|
|
6268 @item @code{&16} @tab INTERCAL unary AND (16-bit)
|
|
|
6269 @item @code{V16} @tab INTERCAL unary OR (16-bit)
|
|
|
6270 @item @code{?16} @tab INTERCAL unary XOR (16-bit)
|
|
|
6271 @item @code{^16} @tab INTERCAL unary sharkfin (16-bit)
|
|
|
6272 @item @code{@@16} @tab INTERCAL unary whirlpool (16-bit)
|
|
|
6273 @item @code{@@216..@@516} @tab INTERCAL unary generalised whirlpool (16-bit)
|
|
|
6274 @item @code{&32} @tab INTERCAL unary AND (32-bit)
|
|
|
6275 @item @code{V32} @tab INTERCAL unary OR (32-bit)
|
|
|
6276 @item @code{?32} @tab INTERCAL unary XOR (32-bit)
|
|
|
6277 @item @code{^32} @tab INTERCAL unary sharkfin (32-bit)
|
|
|
6278 @item @code{@@32} @tab INTERCAL unary whirlpool (32-bit)
|
|
|
6279 @item @code{@@232..@@532} @tab INTERCAL unary generalised whirlpool (32-bit)
|
|
|
6280 @item @code{&} @tab C binary bitwise AND
|
|
|
6281 @item @code{|} @tab C binary bitwise OR
|
|
|
6282 @item @code{^} @tab C binary bitwise XOR
|
|
|
6283 @item @code{+} @tab C addition
|
|
|
6284 @item @code{-} @tab C subtraction
|
|
|
6285 @item @code{*} @tab C multiplication
|
|
|
6286 @item @code{/} @tab C integer division
|
|
|
6287 @item @code{%} @tab C modulus
|
|
|
6288 @item @code{>} @tab C greater than
|
|
|
6289 @item @code{<} @tab C less than
|
|
|
6290 @item @code{~} @tab C unary bitwise complement
|
|
|
6291 @item @code{!=} @tab C not equals operator
|
|
|
6292 @item @code{==} @tab C equals operator
|
|
|
6293 @item @code{&&} @tab C logical AND
|
|
|
6294 @item @code{||} @tab C logical OR
|
|
|
6295 @item @code{>>} @tab C bitwise rightshift
|
|
|
6296 @item @code{<<} @tab C bitwise leftshift
|
|
|
6297 @item @code{!} @tab C unary logical NOT
|
|
|
6298 @end multitable
|
|
|
6299
|
|
|
6300 (Note that in some cases two operators are expressed the same way, but
|
|
|
6301 that this doesn't matter because one is unary and the other is binary so
|
|
|
6302 that there can't be any ambiguity, only confusion. Also note that
|
|
|
6303 unlike @ical{} unary logic operators, OIL unary logic operators must
|
|
|
6304 have a bitwidth stated.)
|
|
|
6305
|
|
|
6306 It hasn't yet been explained what operands these operators have to
|
|
|
6307 operate on; the syntax for those depends on whether it's a pattern or
|
|
|
6308 replacement that the expression is representing.
|
|
|
6309
|
|
|
6310 @node OIL Patterns
|
|
|
6311 @appendixsec OIL Patterns
|
|
|
6312 @cindex patterns
|
|
|
6313 @cindex OIL, patterns
|
|
|
6314
|
|
|
6315 Patterns are simply @acronym{OIL} expressions; the expressions match
|
|
|
6316 either original @ical{} input or expressions produced by earlier idioms.
|
|
|
6317 Each operator must match the same operator in the (possibly
|
|
|
6318 partially-optimised) input; the operands themselves are pattern
|
|
|
6319 templates specifying what operands in the input they can match.
|
|
|
6320
|
|
|
6321 One special simple form of match is possible: @code{#@var{NUMBER}},
|
|
|
6322 where @var{NUMBER} is in decimal, matches a constant with that value.
|
|
|
6323 (Unlike in @ical{}, this constant is not limited to being a onespot
|
|
|
6324 value; it is, however, limited to being at most twospot, as are all
|
|
|
6325 operands and intermediate values in @acronym{OIL}.)
|
|
|
6326
|
|
|
6327 Otherwise, an operand consists of the following parts, written in order:
|
|
|
6328
|
|
|
6329 @cindex operands, OIL, in patterns
|
|
|
6330 @cindex patterns, operands
|
|
|
6331 @enumerate
|
|
|
6332
|
|
|
6333 @item
|
|
|
6334 A character to specify the data type of what's being matched. Usually,
|
|
|
6335 this will be @code{_} to specify that any data type can be matched. In
|
|
|
6336 a few cases, you may want to use @code{.} or @code{:} to specify that
|
|
|
6337 you only want to match a onespot or twospot value respectively (that is,
|
|
|
6338 16- or 32-bit). You can also use @code{#}; this specifies a value that
|
|
|
6339 can be any width, but must be known to be a constant with a known value
|
|
|
6340 at optimize time (either because it was hardcoded as a constant
|
|
|
6341 originally or because a constant was produced there by the optimizer,
|
|
|
6342 for instance via a constant folding optimization).
|
|
|
6343
|
|
|
6344 @item
|
|
|
6345 Optionally, an expression in braces (@code{@{} and @code{@}}). This
|
|
|
6346 expression is written in C, not @acronym{OIL} (as are all expressions in
|
|
|
6347 braces), and puts an extra condition on whether the pattern matches.
|
|
|
6348 The exact meaning of this will be explained later.
|
|
|
6349
|
|
|
6350 @item
|
|
|
6351 A reference number, which must be one decimal digit long. A reference
|
|
|
6352 number of 0 causes the operand to be discarded immediately after
|
|
|
6353 matching; normally, you will want to specify a positive reference
|
|
|
6354 number. Two operands with the same reference number must be exactly the
|
|
|
6355 same for the pattern to match (for instance, both references to the same
|
|
|
6356 variable, or identical subexpressions). The reference number also
|
|
|
6357 allows the operand to be referenced by C expressions on other operands
|
|
|
6358 and by replacements. Reference numbers must be unique within the idiom
|
|
|
6359 (unless two or reference numbers are deliberately the same so that the
|
|
|
6360 operands they reference have to be identical to produce a match), and
|
|
|
6361 they are scoped only as far as the containing idiom; they don't carry
|
|
|
6362 from one idiom to another.
|
|
|
6363
|
|
|
6364 @end enumerate
|
|
|
6365
|
|
|
6366 Note that syntax like @code{#2} is ambiguous given what comes so far;
|
|
|
6367 the first interpretation is the one that is taken in practice, and if
|
|
|
6368 the second interpretation is wanted the operand should be expressed as
|
|
|
6369 @code{#@{1@}2}, using a no-op braced expression to tell them apart.
|
|
|
6370 This particular no-op is recommended because it's detected and optimized
|
|
|
6371 by the @code{OIL} compiler.
|
|
|
6372
|
|
|
6373 Braced expressions, which must be written purely in C, add extra
|
|
|
6374 conditions; they must return nonzero to allow a possible match or zero
|
|
|
6375 to prevent one. They can reference the following variables and
|
|
|
6376 functions:
|
|
|
6377
|
|
|
6378 @cindex functions, OIL in C
|
|
|
6379 @cindex OIL, functions in C
|
|
|
6380 @cindex C, within OIL
|
|
|
6381 @anchor{C functions in OIL}
|
|
|
6382 @table @code
|
|
|
6383
|
|
|
6384 @item c
|
|
|
6385 @itemx c@var{NUMBER}
|
|
|
6386 @findex c
|
|
|
6387 @findex c1--c9
|
|
|
6388
|
|
|
6389 This accesses a calculation made automatically by the compiled
|
|
|
6390 @acronym{OIL} program to identify which bits of the operand can possibly
|
|
|
6391 be set, and which ones cannot be. @code{c} by itself refers to the
|
|
|
6392 operand to which the braced expression is attached; if a number is
|
|
|
6393 given, it refers to another node (the number is interpreted as a
|
|
|
6394 reference number). The actual value of @code{c} is a 32-bit unsigned
|
|
|
6395 integer, each bit of which is true, or 1, if there is any chance that
|
|
|
6396 the corresponding bit of the operand might be 1, and false, or 0, if
|
|
|
6397 it's known for certain that the corresponding bit of the operand is 0.
|
|
|
6398
|
|
|
6399 For instance:
|
|
|
6400
|
|
|
6401 @example
|
|
|
6402 _@{!(c&4294901760LU)@}1
|
|
|
6403 @end example
|
|
|
6404
|
|
|
6405 The constant given here is FFFF0000 when expressed in hexadecimal; the
|
|
|
6406 point is that the expression matches any operand that is known to have a
|
|
|
6407 value no greater than 65535. Unless the operand is the argument to a
|
|
|
6408 unary AND, this check generally makes more sense than explicitly
|
|
|
6409 specifying @code{.} rather than @code{_}, because it will identify both
|
|
|
6410 16- and 32-bit values as long as they're small enough to fit into a
|
|
|
6411 onespot variable. This code could, for instance, be used to check that
|
|
|
6412 an argument to a mingle must be small enough before optimising it (this
|
|
|
6413 is important because an optimisation shouldn't optimise an error -- in
|
|
|
6414 this case, an overflowing mingle -- into a non-error).
|
|
|
6415
|
|
|
6416 @item x
|
|
|
6417 @itemx x@var{NUMBER}
|
|
|
6418 @findex x
|
|
|
6419 @findex x1--x9
|
|
|
6420
|
|
|
6421 @code{x} is like @code{c}, and refers to operands in the same way,
|
|
|
6422 except that it can only refer to an operand marked with @code{#}. It
|
|
|
6423 holds the value of that constant (a 32-bit unsigned integer), which will
|
|
|
6424 be known to the optimizer at optimize time. One common use of this is
|
|
|
6425 to detect whether a constant happens to be a power of 2, although there
|
|
|
6426 are many other possibilities that may be useful.
|
|
|
6427
|
|
|
6428 @item r
|
|
|
6429 @findex r
|
|
|
6430
|
|
|
6431 When inside a loop, @code{r} is the value of the loop counter. (It's
|
|
|
6432 almost certainly a mistake if you have a loop but don't reference the
|
|
|
6433 loop counter at least once, and usually at least twice, within the
|
|
|
6434 loop.) @xref{OIL Loops}.
|
|
|
6435
|
|
|
6436 @item and16
|
|
|
6437 @itemx and32
|
|
|
6438 @itemx or16
|
|
|
6439 @itemx or32
|
|
|
6440 @itemx xor16
|
|
|
6441 @itemx xor32
|
|
|
6442 @itemx iselect
|
|
|
6443 @itemx mingle
|
|
|
6444 @findex and16
|
|
|
6445 @findex and32
|
|
|
6446 @findex or16
|
|
|
6447 @findex or32
|
|
|
6448 @findex xor16
|
|
|
6449 @findex xor32
|
|
|
6450 @findex iselect
|
|
|
6451 @findex mingle
|
|
|
6452
|
|
|
6453 These are all functions with one argument (apart from iselect and
|
|
|
6454 mingle, which each take two arguments); they exist so that @ical{}
|
|
|
6455 operators can be used by C expressions. They all take unsigned longs as
|
|
|
6456 input and output, even if they are onespot operators. Note that it's
|
|
|
6457 entirely possible for these to cause a compile-time error if used on
|
|
|
6458 invalid arguments (such as mingling with an operand over 65535), or to
|
|
|
6459 silently truncate an invalid argument down to the right number of bits;
|
|
|
6460 both of these should be avoided if possible, so the optimiser should
|
|
|
6461 check first to make sure that it doesn't use any of these functions on
|
|
|
6462 invalid arguments.
|
|
|
6463
|
|
|
6464 @item xselx
|
|
|
6465 @findex xselx
|
|
|
6466
|
|
|
6467 This function returns its argument selected with itself; so
|
|
|
6468 @code{xselx(c)} is shorthand for @code{iselect(c,c)}. When the argument
|
|
|
6469 is very complicated, this can save a lot of space in the original
|
|
|
6470 @acronym{OIL} program.
|
|
|
6471
|
|
|
6472 @item setbitcount
|
|
|
6473 @findex setbitcount
|
|
|
6474
|
|
|
6475 This function simply returns the number of bits with value 1 in its
|
|
|
6476 argument. This is sometimes useful with respect to various
|
|
|
6477 select-related optimisations, and can be a useful alternative to having
|
|
|
6478 to take logarithms in various situations.
|
|
|
6479
|
|
|
6480 @item smudgeright
|
|
|
6481 @itemx smudgeleft
|
|
|
6482 @findex smudgeright
|
|
|
6483 @findex smudgeleft
|
|
|
6484
|
|
|
6485 The @code{smudgeright} function returns its argument but with all the
|
|
|
6486 bits less significant than the most significant bit with value 1 set to
|
|
|
6487 1; likewise, @code{smudgeleft} returns its argument with all the bits
|
|
|
6488 more significant than the least significant bit with value 1 set to 1.
|
|
|
6489
|
|
|
6490 @end table
|
|
|
6491
|
|
|
6492 Note that all @acronym{OIL} character is done internally using unsigned
|
|
|
6493 32-bit numbers, and C expressions you write should do the same. The
|
|
|
6494 practical upshot of this is that you should write @code{LU} after any
|
|
|
6495 constant you write in C code; if you don't do this, you are reasonably
|
|
|
6496 likely to get compiler warnings, and the resulting program may not work
|
|
|
6497 reliably, although the @acronym{OIL} compiler itself will not complain.
|
|
|
6498
|
|
|
6499 Here's a more complicated example of an optimizer operand:
|
|
|
6500
|
|
|
6501 @example
|
|
|
6502 #@{!(x&2863311530LU)&&iselect(x,1431655765LU)==
|
|
|
6503 xselx(iselect(x,1431655765LU))@}3
|
|
|
6504 @end example
|
|
|
6505
|
|
|
6506 It helps to understand this if you know that 2863311530 in hexadecimal
|
|
|
6507 is AAAAAAAA and 1431655765 in hexadecimal is 55555555. (It's worth
|
|
|
6508 putting a comment with some frequently-used decimal constants in an
|
|
|
6509 @acronym{OIL} input file to help explain what these numbers mean and
|
|
|
6510 make the code more maintainable.) The operand matches any constant
|
|
|
6511 integer which has no bits in common with AAAAAAAA, and for which if any
|
|
|
6512 bit in common with 55555555 is set, all less significant bits in common
|
|
|
6513 with that number are also set.
|
|
|
6514
|
|
|
6515 @node OIL Replacements
|
|
|
6516 @appendixsec OIL Replacements
|
|
|
6517 @cindex OIL, replacements
|
|
|
6518 @cindex replacements
|
|
|
6519
|
|
|
6520 Replacements have much the same syntax as patterns. The expressions are
|
|
|
6521 parsed in much the same way; however, one peculiarity of replacements is
|
|
|
6522 that bitwidths must be specified. @ical{} has a typecaster that figures
|
|
|
6523 out whether each expression is 16 bits or 32 bits wide, but it runs
|
|
|
6524 before the optimizer, and as the optimizer can produce expressions whose
|
|
|
6525 bitwidths don't obey @ical{}'s rules, this information needs to be
|
|
|
6526 inserted somehow in a replacement. In @cic{}, it usually doesn't matter
|
|
|
6527 what the bitwidth is, and in cases where it doesn't matter the normal
|
|
|
6528 operators (@code{$}, @code{~}, and so on) can be used. (Note that the
|
|
|
6529 bit width of the entire replacement is always set to the same bit width
|
|
|
6530 as the bit width of the expression matched by the pattern; so you don't
|
|
|
6531 have to worry about the effect on unary logical operators that might be
|
|
|
6532 operating on the expression being optimized. This is an exception to
|
|
|
6533 the normal bitwidth rules for a replacement.) In cases where it does
|
|
|
6534 matter (due to @cic{}'s lenient interpretation of bitwidth on mingle
|
|
|
6535 inputs, the only place it matters is in the input to @ical{} unary
|
|
|
6536 logical operators), both the bitwidth of the operator and the argument
|
|
|
6537 on which it operates must be explicitly given, and given as the same
|
|
|
6538 value; to set the bitwidth of an operator's result, simply write the
|
|
|
6539 bitwidth (16 or 32 for onespot and twospot respectively) immediately
|
|
|
6540 after the operator; for instance, @code{!=32} will generate a not-equals
|
|
|
6541 operation with a 32-bit bitwidth. If an operator's width is set to 16,
|
|
|
6542 and during the course of execution of the optimized program, a value
|
|
|
6543 that doesn't fit into 16 bits is encountered, that's undefined behaviour
|
|
|
6544 and anything might happen (most likely, though, the program will just
|
|
|
6545 act as though its width had been set to 32 bits instead); this error
|
|
|
6546 condition is not detected. Also note that operators like @code{&32}
|
|
|
6547 already have a bitwidth specified, so specifying @code{&3232} (or worse,
|
|
|
6548 @code{&3216}) is not allowed.
|
|
|
6549
|
|
|
6550 @cindex operands, OIL, in replacements
|
|
|
6551 @cindex replacements, operands
|
|
|
6552 Replacement operands are simpler than pattern operands, because there
|
|
|
6553 are only a few forms they can take.
|
|
|
6554
|
|
|
6555 @table @code
|
|
|
6556 @item _@var{NUMBER}
|
|
|
6557 @itemx .@var{NUMBER}
|
|
|
6558 @itemx :@var{NUMBER}
|
|
|
6559
|
|
|
6560 This tells the optimiser to copy the operand or expression with
|
|
|
6561 reference number @var{NUMBER} to this point in the replacement used for
|
|
|
6562 the expression matched by the pattern. The three forms are identical;
|
|
|
6563 the last two are provided for aesthetic reasons (it can look better and
|
|
|
6564 be clearer to match @code{.1} in the pattern with @code{.1} in the
|
|
|
6565 replacement, for instance). You cannot use @code{#@var{NUMBER}} here to
|
|
|
6566 copy in a constant from the left-hand side, though, nor
|
|
|
6567 @code{#@{1@}@var{NUMBER}}, because the first means something else and
|
|
|
6568 the second is undefined behaviour (that is, no behaviour for the second
|
|
|
6569 case has been specifically implemented in the compiler and therefore its
|
|
|
6570 behaviour is unpredictable and subject to change in future versions);
|
|
|
6571 use @code{_@var{NUMBER}} to copy over a constant with an unknown at
|
|
|
6572 optimizer compile time (but known at optimize time) value from the left
|
|
|
6573 hand side, as you can do with any other operand being copied.
|
|
|
6574
|
|
|
6575 @item #@var{NUMBER}
|
|
|
6576
|
|
|
6577 Insert a constant with the literal value @var{NUMBER} here.
|
|
|
6578
|
|
|
6579 @item #@{@var{EXPRESSION}@}0
|
|
|
6580
|
|
|
6581 Calculate the value of @var{EXPRESSION} (a C expression, which can
|
|
|
6582 reference the same variables and functions as a C expression in a
|
|
|
6583 pattern can; see @ref{C functions in OIL}) and insert a constant with
|
|
|
6584 the calculated value here. (That is, a value is calculated at
|
|
|
6585 optimise-time and the resulting value is therefore constant at
|
|
|
6586 runtime.)
|
|
|
6587
|
|
|
6588 @end table
|
|
|
6589
|
|
|
6590 As an example, here's an idiom that moves C bitwise AND operations
|
|
|
6591 inside leftshifts. (This is useful because if the optimizer has
|
|
|
6592 generated a large sequence of mixed ANDs and bitshifts, moving all the
|
|
|
6593 ANDs to one end allows them to be clumped together and optimized down to
|
|
|
6594 one AND, whilst the shifts can all be combined into one large shift.)
|
|
|
6595
|
|
|
6596 @example
|
|
|
6597 ((_1 << #@{1@}2) & #@{1@}3)->((_1 & #@{x3>>x2@}0) << _2)
|
|
|
6598 @end example
|
|
|
6599
|
|
|
6600 @node OIL Loops
|
|
|
6601 @appendixsec OIL Loops
|
|
|
6602 @cindex loops, OIL
|
|
|
6603 @cindex OIL, loops
|
|
|
6604
|
|
|
6605 When writing idioms, sometimes instead of using very complicated
|
|
|
6606 expressions to try to match multiple situations at once it's easier to
|
|
|
6607 have a separate idiom for each possible situation; for instance, it's
|
|
|
6608 easier to write idioms for right-shift by 1, right-shift by 2,
|
|
|
6609 right-shift by 3, etc.@:, rather than a general idiom to rightshift by any
|
|
|
6610 amount. When the idioms follow a pattern, as they will do in basically
|
|
|
6611 every case of this sort, it's possible to automatically generate them
|
|
|
6612 using a loop. For instance, idioms to optimize a one-bit rightshift
|
|
|
6613 and a two-bit rightshift are:
|
|
|
6614
|
|
|
6615 @example
|
|
|
6616 (_1~#@{xselx(x)<<1==x&&x@}2)->((_1&_2)>>#1)
|
|
|
6617 (_1~#@{xselx(x)<<2==x&&x@}2)->((_1&_2)>>#2)
|
|
|
6618 @end example
|
|
|
6619
|
|
|
6620 Adding a loop to automatically generate the idioms, and placing a name
|
|
|
6621 for the group of idioms at the start, produces the following code:
|
|
|
6622
|
|
|
6623 @example
|
|
|
6624 [rshift]
|
|
|
6625 <#1-#31
|
|
|
6626 (_1~#@{xselx(x)<<r==x&&x@}2)->((_1&_2)>>#@{r@}0)
|
|
|
6627 >
|
|
|
6628 @end example
|
|
|
6629
|
|
|
6630 That's 31 different idioms, generated with a loop. As the above example
|
|
|
6631 shows, a loop starts with @code{<#@var{NUMBER}-#@var{NUMBER}} and ends
|
|
|
6632 with @code{>}; a different idiom is generated for each possible value of
|
|
|
6633 the loop counter @code{r} in the range given by the opening line of the
|
|
|
6634 loop. Loops must be placed around idioms, but inside a group of
|
|
|
6635 idioms. Note the use of @code{#@{r@}0} to generate a constant whose
|
|
|
6636 value is equal to the value of the loop counter.
|
|
|
6637
|
|
|
6638 @node OIL Tips
|
|
|
6639 @appendixsec OIL Tips
|
|
|
6640 @cindex tips, OIL
|
|
|
6641 @cindex OIL, tips
|
|
|
6642
|
|
|
6643 Here are some tips for the best use of @acronym{OIL}:
|
|
|
6644
|
|
|
6645 @itemize
|
|
|
6646
|
|
|
6647 @item
|
|
|
6648 @findex MAXTOFREE
|
|
|
6649 The @acronym{OIL} compiler has a few deficiencies, such as error
|
|
|
6650 messages that don't give you much of an idea of what you did wrong (to
|
|
|
6651 compensate for this, it does give a reasonably accurate line and
|
|
|
6652 character number where the error happened), limits on things like how
|
|
|
6653 deep expressions can be nested and how many idioms are allowed (if you
|
|
|
6654 hit the first, you should really break it up into smaller idioms if
|
|
|
6655 possible, and if you hit the second, increase @code{MAXTOFREE} in oil.y;
|
|
|
6656 this isn't a limit on the number of idioms but on the number of strings
|
|
|
6657 that are allocated internally to process the idioms), and lack of error
|
|
|
6658 checking (invalid @acronym{OIL} may produce errors in the @acronym{OIL}
|
|
|
6659 compiler, or cause the output C code to contain errors or warnings, or
|
|
|
6660 may even appear to work).
|
|
|
6661
|
|
|
6662 @item
|
|
|
6663 When you have symmetrical operators in an idiom (like C binary logical
|
|
|
6664 operators), you need to write the idiom both ways round (in the same
|
|
|
6665 group of idioms, preferably), or write another idiom to standardise the
|
|
|
6666 format first; the first method can get very tedious when there are many
|
|
|
6667 symmetrical operators in an idiom, and the second is prone to optimizer
|
|
|
6668 loops and subtle errors (both methods have been used in the provided
|
|
|
6669 @file{idiotism.oil} file.)
|
|
|
6670
|
|
|
6671 @item
|
|
|
6672 Idioms should preferably be as general as possible, broken down into
|
|
|
6673 many separate idioms rather than all as one big idiom, and match the
|
|
|
6674 smallest part of the expression being optimized that is necessary for
|
|
|
6675 the idiom to be correct in all circumstances; all of these help to
|
|
|
6676 improve the performance of the optimizer in terms of what it can
|
|
|
6677 optimize.
|
|
|
6678
|
|
|
6679 @item
|
|
|
6680 If a program's optimizing incorrectly, or you just want to see how the
|
|
|
6681 optimizer deals with a particular program, it's possible to debug the
|
|
|
6682 optimizer by giving the @option{-h}, @option{-H}, or @option{-hH}
|
|
|
6683 (@pxref{-h}) switch to the @cic{} compiler, which will cause debug
|
|
|
6684 information to be output on stderr. @option{-h} will show the initial
|
|
|
6685 and final expressions for each expression that was given as input to the
|
|
|
6686 optimizer, as well as a list of all optimizations used, in a language
|
|
|
6687 that's a sort of mix of C, @ical{}, and @acronym{OIL}; @option{-H} will
|
|
|
6688 do the same, and also show the intermediate stages in the optimization.
|
|
|
6689 @option{-hH} is like @option{-H}, but produces its output entirely in C,
|
|
|
6690 so that the various intermediate stages can be tried with a C compiler,
|
|
|
6691 or for people who are fed up of reading @ical{}. @option{-H} can be a
|
|
|
6692 useful learning resource for people who want to understand how a
|
|
|
6693 particular @ical{} expression works.
|
|
|
6694
|
|
|
6695 @item
|
|
|
6696 Make sure that the optimizer doesn't change a statement from a run-time
|
|
|
6697 error into something that silently succeeds@! Checking which bits can
|
|
|
6698 and can't be 1 is one good way to avoid this, especially with mingles.
|
|
|
6699 (At present, there are some idioms that can turn run-time errors into
|
|
|
6700 compile-time errors, such as with the expression
|
|
|
6701 @code{''#65535$#65535'$#0'}; this could be avoided, but for the time
|
|
|
6702 being it isn't.)
|
|
|
6703
|
|
|
6704 @item
|
|
|
6705 You can help@! If you find an idiom that the optimizer isn't optimizing
|
|
|
6706 correctly, feel free to add it, or multiple idioms that come to the same
|
|
|
6707 thing, to @file{idiotism.oil}. In such a case, it would help other
|
|
|
6708 users if you would submit your new optimizer idiom to the project
|
|
|
6709 (@pxref{Reporting Bugs}); this will help other users and future releases
|
|
|
6710 of @ical{}, and also has a chance of allowing other users to check your
|
|
|
6711 new idioms to see if they cause problems or could be written better.
|
|
|
6712
|
|
|
6713 @end itemize
|
|
|
6714
|
|
|
6715 @node OIL Example
|
|
|
6716 @appendixsec OIL Example
|
|
|
6717 @cindex OIL, example
|
|
|
6718 @cindex examples, OIL
|
|
|
6719
|
|
|
6720 To finish off this appendix, here's an example of the power of
|
|
|
6721 @acronym{OIL}; this is the optimization of an idiom from the @icst{}
|
|
|
6722 system library, as shown with @option{-H}; this should give a good idea
|
|
|
6723 of how @acronym{OIL} programs work. (All the relevant idioms are in
|
|
|
6724 @file{idiotism.oil} as of the time of writing.) Note how the expression
|
|
|
6725 is reduced one small step at a time; the smallness of the steps makes
|
|
|
6726 the optimizer more general, because if the original expression had been
|
|
|
6727 slightly different, the optimizer wouldn't have come to the same result
|
|
|
6728 but could have optimized it quite a bit of the way, up to the point
|
|
|
6729 where the optimizations were no longer valid; in an older version of
|
|
|
6730 @ical{}, this idiom was simply hardcoded as a special case and so slight
|
|
|
6731 variations of it weren't optimized at all. If you look at the idioms
|
|
|
6732 themselves, it'll also be apparent how @code{c} (the record of which
|
|
|
6733 bits of an expression can be 1 and which bits can't be) is important
|
|
|
6734 information in being able to apply an optimization more aggressively.
|
|
|
6735
|
|
|
6736 @ifhtml
|
|
|
6737 @smallexample
|
|
|
6738 .3 <- ((((((((.3 $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6739 [minglefold]
|
|
|
6740 .3 <- ((((((((.3 $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6741 [lshift16]
|
|
|
6742 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6743 [noopor]
|
|
|
6744 .3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6745 [minglefold]
|
|
|
6746 .3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6747 [lshift16]
|
|
|
6748 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6749 [noopor]
|
|
|
6750 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6751 [minglefold]
|
|
|
6752 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0xaaaaaaf) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6753 [lshift16]
|
|
|
6754 .3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) | 0x0) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6755 [noopor]
|
|
|
6756 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ (0xfff $ 0xf))
|
|
|
6757 [minglefold]
|
|
|
6758 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ 0xaaaaff)
|
|
|
6759 [lshift16]
|
|
|
6760 .3 <- (((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7) | 0x0)
|
|
|
6761 [noopor]
|
|
|
6762 .3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6763 [nullshift]
|
|
|
6764 .3 <- (((((((((((.3 & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6765 [combinelrshift]
|
|
|
6766 .3 <- ((((((((((.3 & 0x7fff) << 0x1) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6767 [andintolshift]
|
|
|
6768 .3 <- ((((((((((.3 & 0x7fff) & 0x3fff) << 0x1) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6769 [combinellshift]
|
|
|
6770 .3 <- (((((((((.3 & 0x7fff) & 0x3fff) << 0x2) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6771 [combinelrshift]
|
|
|
6772 .3 <- ((((((((.3 & 0x7fff) & 0x3fff) << 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6773 [andintolshift]
|
|
|
6774 .3 <- ((((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) << 0x3) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6775 [combinellshift]
|
|
|
6776 .3 <- (((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x4) >> 0x3) & 0x1ff) << 0x7)
|
|
|
6777 [combinelrshift]
|
|
|
6778 .3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) & 0x1ff) << 0x7)
|
|
|
6779 [andintolshift]
|
|
|
6780 .3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x1) << 0x7)
|
|
|
6781 [combinellshift]
|
|
|
6782 .3 <- (((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x8)
|
|
|
6783 [combineand]
|
|
|
6784 .3 <- ((((.3 & 0x3fff) & 0xfff) & 0xff) << 0x8)
|
|
|
6785 [combineand]
|
|
|
6786 .3 <- (((.3 & 0xfff) & 0xff) << 0x8)
|
|
|
6787 [combineand]
|
|
|
6788 .3 <- ((.3 & 0xff) << 0x8)
|
|
|
6789 @end smallexample
|
|
|
6790 @end ifhtml
|
|
|
6791 @ifnothtml
|
|
|
6792 @quotation
|
|
|
6793 .3 <- ((((((((.3 $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6794 [minglefold]@*
|
|
|
6795 .3 <- ((((((((.3 $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6796 [lshift16]@*
|
|
|
6797 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6798 [noopor]@*
|
|
|
6799 .3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6800 [minglefold]@*
|
|
|
6801 .3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6802 [lshift16]@*
|
|
|
6803 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6804 [noopor]@*
|
|
|
6805 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6806 [minglefold]@*
|
|
|
6807 .3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0xaaaaaaf) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6808 [lshift16]@*
|
|
|
6809 .3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) | 0x0) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6810 [noopor]@*
|
|
|
6811 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ (0xfff $ 0xf))@*
|
|
|
6812 [minglefold]@*
|
|
|
6813 .3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ 0xaaaaff)@*
|
|
|
6814 [lshift16]@*
|
|
|
6815 .3 <- (((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7) | 0x0)@*
|
|
|
6816 [noopor]@*
|
|
|
6817 .3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6818 [nullshift]@*
|
|
|
6819 .3 <- (((((((((((.3 & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6820 [combinelrshift]@*
|
|
|
6821 .3 <- ((((((((((.3 & 0x7fff) << 0x1) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6822 [andintolshift]@*
|
|
|
6823 .3 <- ((((((((((.3 & 0x7fff) & 0x3fff) << 0x1) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6824 [combinellshift]@*
|
|
|
6825 .3 <- (((((((((.3 & 0x7fff) & 0x3fff) << 0x2) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6826 [combinelrshift]@*
|
|
|
6827 .3 <- ((((((((.3 & 0x7fff) & 0x3fff) << 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6828 [andintolshift]@*
|
|
|
6829 .3 <- ((((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6830 [combinellshift]@*
|
|
|
6831 .3 <- (((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x4) >> 0x3) & 0x1ff) << 0x7)@*
|
|
|
6832 [combinelrshift]@*
|
|
|
6833 .3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) & 0x1ff) << 0x7)@*
|
|
|
6834 [andintolshift]@*
|
|
|
6835 .3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x1) << 0x7)@*
|
|
|
6836 [combinellshift]@*
|
|
|
6837 .3 <- (((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x8)@*
|
|
|
6838 [combineand]@*
|
|
|
6839 .3 <- ((((.3 & 0x3fff) & 0xfff) & 0xff) << 0x8)@*
|
|
|
6840 [combineand]@*
|
|
|
6841 .3 <- (((.3 & 0xfff) & 0xff) << 0x8)@*
|
|
|
6842 [combineand]@*
|
|
|
6843 .3 <- ((.3 & 0xff) << 0x8)@*
|
|
|
6844 @end quotation
|
|
|
6845 @end ifnothtml
|
|
|
6846
|
|
|
6847 @node Copying
|
|
|
6848 @appendix Copying
|
|
|
6849 @cindex copyright
|
|
|
6850 @cindex copying conditions
|
|
|
6851
|
|
|
6852 The majority of the files in the @cic{} distribution are licensed
|
|
|
6853 under the GNU General Public License (version 2 or later), but with
|
|
|
6854 some exceptions. The files @file{ick-wrap.c} and @file{pickwrap.c}
|
|
|
6855 are licensed under a license that allows them to be used for any
|
|
|
6856 purpose and redistributed at will, and are explicitly not GPL'd. This
|
|
|
6857 means that C source code generated by the compiler has the same
|
|
|
6858 copyright conditions as the original @ical{} source. (Note that the
|
|
|
6859 libraries @file{libick.a} and @file{libickmt.a} are GPL, though, so
|
|
|
6860 you cannot redistribute an executable produced by @command{ick} or by
|
|
|
6861 linking a C file to either of those libraries unless the original
|
|
|
6862 @ical{} source was GPL.) For similar reasons, the expansion libraries
|
|
|
6863 @file{syslibc.c} and @file{compunex.c} (currently the only ones in the
|
|
|
6864 distribution) is explicitly public domain. Also, this manual, and the
|
|
|
6865 files that are the source code for creating it, are licensed under the
|
|
|
6866 GNU Free Documentation License rather than the GPL, and the licenses
|
|
|
6867 themselves (@file{fdl-1-2.txi} and @file{COPYING.txt}) are licensed
|
|
|
6868 under a license that allows verbatim redistribution but not creation
|
|
|
6869 of derivative works. All other files, though (including the
|
|
|
6870 @command{man} pages, which are not part of @emph{this} manual), are
|
|
|
6871 licensed under the GPL. For the full text of the GPL, see the file
|
|
|
6872 @file{COPYING.txt} in the distribution.
|
|
|
6873
|
|
|
6874 @menu
|
|
|
6875 * GNU Free Documentation License:: License for copying this manual.
|
|
|
6876 @end menu
|
|
|
6877
|
|
|
6878 @node GNU Free Documentation License
|
|
|
6879 @appendixsec GNU Free Documentation License
|
|
|
6880 @cindex GFDL
|
|
|
6881 @cindex FDL
|
|
|
6882 @cindex GNU Free Documentation License
|
|
|
6883 @cindex Free Documentation License
|
|
|
6884
|
|
|
6885 @include fdl-1-2.txi
|
|
|
6886
|
|
|
6887 @node Main Index
|
|
|
6888 @unnumbered Index
|
|
|
6889
|
|
|
6890 This is the index of everything in this manual. (Note that in some
|
|
|
6891 versions of the manual this is called @samp{Main Index} to prevent it
|
|
|
6892 transforming into a page called @file{index.html} in the HTML version of
|
|
|
6893 the manual. The complications that that caused were really odd.)
|
|
|
6894
|
|
|
6895 @printindex cp
|
|
|
6896
|
|
|
6897 @bye
|
|
|
6898
|
