Retitle "System Library" to "System Libraries", add a section
[intercal:intercal.git] / doc / ick.txi
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 Libraries::                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 * Installation on DOS::  For users of DOS with DJGPP
245 * Uninstalling::         If you don't want to use the software
246 * Reporting Bugs::       If it doesn't work or you know how to fix it
247 * Distributing::         How to make your own @cic{} distribution
248 @end menu
249
250 @node Obtaining
251 @section Obtaining
252 @cindex obtaining C-INTERCAL
253 @cindex C-INTERCAL, obtaining a copy
254
255 @cic{} distributions have been stored in many different places over
256 time; it can sometimes be hard to make sure that you are finding the
257 most recent version.  In order to make sure that you have the most
258 recent version, the easiest way is to look at the
259 @uref{news:alt.lang.intercal,,alt.lang.intercal newsgroup}; all releases
260 of the @cic{} compiler ought to be announced there.  (If you are
261 interested in what other @ical{} compilers are available, it may also be
262 worth looking there.)  If you don't have access to a newsreader, your
263 newsreader doesn't cover that newsgroup, or the distance between
264 releases has been too large for your news server to keep the message,
265 it's likely that you can find the announcement in an archive on the
266 World Wide Web; at the time of writing (2007), the archives of the
267 newsgroup are stored by @uref{http://groups.google.com,Google Groups},
268 and a search for @samp{alt.lang.intercal} there should tell you where to
269 find a copy.
270
271 If you're looking for the latest version, note that the number after the
272 dot represents the major version number; you want to maximise this in
273 favour of the number before the dot, which is the bugfix level within a
274 major version.  (Major versions are released as version 0.whatever; if a
275 new version comes out that fixes bugs but adds no new features, nowadays
276 its number will be of the form 1.whatever, with the same major number.
277 This has not always been the case, though.)
278
279 @node Unpacking
280 @section Unpacking
281 @cindex C-INTERCAL, unzipping
282 @cindex C-INTERCAL, unpacking
283 @cindex unzipping C-INTERCAL
284 @cindex unpacking C-INTERCAL
285 @cindex ick-@value{VERSIONDASH}.pax.*
286
287 @cic{} is distributed in compressed pax format; for instance, you may
288 find it as a @samp{.pax.lzma} file if you have the @command{unlzma}
289 decompression program (this is advised, as it's the smallest);
290 @samp{.pax.bz2} is larger and @samp{.pax.gz} is larger still.  Most
291 computers can decompress files in this format, even if they don't
292 realise it, because pax is forwards-compatible with tar; try renaming
293 the extension from @samp{.pax} to @samp{.tar} after decompressing to
294 see if you have a progam that can decompress it.  (If you're wondering
295 why such an apparently non-standard format is being used, this is is
296 actually a case where @cic{} is being perfectly nonstandard by
297 conforming to the standards; tar is no longer specified by POSIX, and
298 pax is its replacement. It's just that pax never really caught on.)
299
300 It doesn't matter where you extract the distribution file to: it's best
301 if you don't put it anywhere special.  If you aren't an administrator,
302 you should extract the file to somewhere in your home directory (Linux
303 or UNIX-like systems) or to your My Documents directory (recent versions
304 of Windows; if you're using an older version, then you @emph{are} an
305 administrator, or at least have the same privileges, and can extract it
306 anywhere).  Some commands that you might use to extract it:
307
308 @table @asis
309
310 @item Generic UNIX/Linux
311
312 @example
313 unlzma ick-@value{VERSIONDASH}.pax.lzma
314 tar xvf ick-@value{VERSIONDASH}.pax
315 @end example
316 @i{or}
317 @example
318 bunzip2 ick-@value{VERSIONDASH}.pax.bz2
319 tar xvf ick-@value{VERSIONDASH}.pax
320 @end example
321 @i{or}
322 @example
323 gunzip ick-@value{VERSIONDASH}.pax.gz
324 tar xvf ick-@value{VERSIONDASH}.pax
325 @end example
326
327 On most UNIX-based and Linux-based systems, @command{tar} will be
328 available to unpack the installation files once they've been
329 uncompressed with @command{gunzip}.  (I've heard that some BSD systems
330 have @command{pax} itself to decompress the files, although have not
331 been able to verify this; some Linux distributions also have
332 @command{pax} in their package managers.  Both tar and pax should work
333 fine, though.)  @command{gunzip} is also likely to be available (and
334 @command{bunzip2} and @command{unlzma} are less likely, but use those
335 versions if you have them to save on your bandwidth); if it isn't, you
336 will need to download a copy from the Internet.
337
338 @item Using GNU tar
339
340 @example
341 tar xzvf ick-@value{VERSIONDASH}.pax.gz
342 @end example
343 @i{or}
344 @example
345 tar xqvf ick-@value{VERSIONDASH}.pax.bz2
346 @end example
347
348 If you are using the GNU version of @command{tar} (which is very likely
349 on Linux), you can combine the two steps into one as shown here,
350 except when using the lzma-compressed version.
351
352 @item Using DJGPP
353
354 @example
355 djtar -x ick-@value{VERSIONDASH}.pax.gz
356 @end example
357
358 On a DOS system, you will have to install DJGPP anyway to be able to
359 compile the distribution, and once you've done that you will be able
360 to use DJGPP's decompressing and unpacking utility to extract the
361 files needed to install the distribution.  (You will need to type this
362 at the command line; on Windows 95 and later, try choosing Run...@:
363 from the start menu then typing @command{cmd} (or @command{command} if
364 that fails) in the dialog box that opens to get a command prompt,
365 which you can exit by typing @command{exit}.  After typing any command
366 at a command line, press @key{RET} to tell the shell to execute that
367 command.)
368
369 @item On Windows
370
371 If you're running a Windows system, you could always try
372 double-clicking on the ick-@value{VERSIONDASH}.pax.gz file; probably
373 renaming it to have the extension @samp{.tgz} is likely to give the
374 best results.  It's quite possible that you'll have a program
375 installed that's capable of decompressing and unpacking it.
376 Unfortunately, I can't guess what program that might be, so I can't
377 give you any instructions for using it.
378
379 @end table
380
381 Whatever method you use, you should end up with a directory created
382 called @file{ick-@value{VERSION}}; this is your main installation
383 directory where all the processing done by the installation will be
384 carried out.  You will need to have that directory as the current
385 directory during install (at the command prompt in all the operating
386 systems I know, you can set the current directory by typing @command{cd
387 ick-@value{VERSION}}).
388
389 @node Simple Installation
390 @section Simple Installation
391 @cindex installation, simple
392 @cindex simple installation
393 @findex config.sh
394 @findex make
395 @findex make install
396 @cindex compiling, @command{ick} itself
397 @cindex installation, via autoconf and make
398 @cindex configuring
399
400 There are scripts included in the distribution to automate the process
401 of installing, in various ways.  The simplest method of installing on
402 most operating systems (on DOS, @pxref{Installation on DOS}) is to
403 use the following routine:
404
405 @enumerate
406
407 @item
408 Configure @cic{}, by running @command{configure}.  Although building
409 in the distribution directory works; it is recommended that you build
410 elsewhere; create a directory to build in (using @command{mkdir} on
411 most operating systems), then run @command{configure} from inside that
412 directory (for instance, you could do this from inside the main
413 installation directory:
414 @example
415 mkdir build
416 cd build
417 ../configure
418 @end example
419 to build in a subdirectory of the distribution called ``build'').  You
420 also specify where you want the files to be installed at this stage;
421 the default of @samp{/usr/local} is good for many people, but you may
422 want to install elsewhere (in particular, if you want to test out
423 @cic{} without installing it, create a new directory somewhere you
424 own and specify that as the place to install it, so the install will
425 actually just copy the files into the right structure for use instead
426 of installing them).  To specify a location, give the option
427 @option{--prefix=@var{location}} to configure; for instance,
428 @command{configure --prefix=/usr} would install in /usr.
429
430 @item
431 Compile the source code, with the command @command{make}.  The
432 Makefile will be set up for your version of @command{make}, and to
433 automatically recompile only what needs compiling (it will even
434 recompile the build system if you change that).
435
436 @item
437 Optionally, create libraries from third-party interpreters to add
438 support for more languages to the @cic{} external calls system; see
439 @ref{Creating the Funge-98 Library}.  (This step can be skipped; you
440 can also do it later, but if you do so you need to run the next step
441 again.)
442
443 @item
444 Install the executables, help files, include files, and libraries,
445 using @command{make install}.  (This is the only step that needs
446 root/administrator permissions; so on a system that uses sudo to
447 elevate permissions, for instance, write it as @command{sudo make
448 install} if you're installing into a directory that you can't write to
449 as a non-administrative user.) This step is optional; if you do not
450 install @cic{}, you can still run it by directly referencing the exact
451 location of the @command{ick} command.
452
453 @end enumerate
454
455 On all systems, it's worth just trying this to see if it works.  This
456 requires a lot of software on your computer to work, but all of it is
457 standard on Linux and UNIX systems.  The first command is a
458 shell-script which will analyse your system and set settings
459 accordingly; it will explain what it's doing and what settings it
460 detected, and create several files in the installation directory to
461 record its results.  (This is a configure script produced by the GNU
462 autoconf (configure); its autoconf source code is available in the
463 file @file{configure.ac}.)  The second command actually compiles the
464 source code to produce binaries; this takes the longest of any of the
465 steps.  You will see all the commands that it's running as it runs
466 them.  The third command will copy the files it's compiled to
467 appropriate shared locations on your system so that anyone on the
468 system can just use @command{ick}.
469
470 There may be various factors that prevent this simple installation
471 method working.  On a system not based on UNIX or Linux, you may find
472 that you don't have some of the software required to run this (for
473 instance, you may be missing the shell @command{sh}, and don't have
474 the shell @command{bash} which can emulate it, and so can't run
475 @command{sh config.sh} that depends on one of those shells being
476 available) and so this method won't work for you.  In such cases, one
477 solution may be to install all the software required; the GNU project
478 has a version of all the commands required, for instance, and there
479 may be ports available for your operating system.  However, the only
480 software absolutely required is a C compiler (@cic{} was designed to
481 work with @command{gcc} and is tested mostly with that compiler, but
482 in theory it should work with other C compilers too, and this is
483 tested on occasion) and the associated software needed to compile C
484 files to object files and executables, combine object files into
485 libraries, etc.
486
487 Another possibility that might stop this process working is if your
488 version of the relevant software is incompatible with the GNU versions
489 that were used for testing.  For instance, I have come across
490 proprietary versions of @command{lex} that need directives in the source
491 file to say in advance how much memory the lexer-generator needs to
492 allocate.  In such cases, pay attention to the error messages you're
493 getting; normally they will suggest trivial modifications to the source
494 files that will cause the compilation to work again.
495
496 @cindex installation, Debian
497 @cindex installation, Ubuntu
498 @cindex Debian
499 @cindex Ubuntu
500 Some Linux and UNIX systems (notably Debian and Ubuntu) don't have the
501 required files for compilation installed by default.  To install them,
502 just download and install the required packages: for Ubuntu at the
503 time of writing, they are @samp{binutils}, @samp{cpp}, @samp{gcc},
504 @samp{libc6-dev}, @samp{make} to compile @cic{}, and if you want to
505 modify it, you may also need @samp{autoconf}, @samp{automake},
506 @samp{bison}, and @samp{flex}.  For debugging help, you may also want
507 @samp{gdb}, and to recompile the documentation, you may need
508 @samp{groff}, @samp{tetex-bin}, @samp{texinfo}, and @samp{tidy}.  Of
509 course, if @ical{} ever (the author of this sentence was going to
510 write something like ``becomes popular, someone will probably package
511 up a compiler for Debian or Ubuntu anyway'', but at that point on a
512 whim did an Ubuntu package search for 'intercal' and actually came up
513 with two results, which look suspiciously like @cic{} and @clcic{},
514 later confirming this.  The author was vaguely aware that there was a
515 @clcic{} package floating around, but was unaware of the @cic{}
516 package, and as a result was too surprised to finish the sentence.)
517
518 If you're trying to do something unusual, you probably want to set some
519 of the settings yourself rather than letting the compilation process
520 guess everything.  In this case, use @command{configure --help} to
521 view the options that you can set on @command{configure}; there's a wide
522 range of settings that you can set available there, and one of them may
523 be what you want.
524
525 @node Installation on DOS
526 @section Installation on DOS
527 @cindex installing, DOS
528 @cindex DOS
529 @cindex DJGPP
530
531 On DOS-based systems, it's possible to install @cic{} via compiling it
532 using DJGPP, a free DOS development system. (You can obtain DJGPP via
533 its homepage, at @uref{http://www.delorie.com/djgpp/}.) The process
534 for installing it works like this:
535
536 @enumerate
537
538 @item
539 To start with, you will need to install DJGPP and various utilities
540 (especially many of the GNU utilities) that come with it. To do this,
541 see the instructions on DJGPP's website, and download and unpack any
542 additional packages on this list that you did not install as part of
543 those instructions (a filename by which the package can be found on
544 DJGPP mirrors is given, and a version number with which @cic{} was
545 tested is given as part of the filename, but other versions are likely
546 to work as well):
547
548 @itemize
549
550 @item
551 Unzip32 (@samp{unzip32.exe}) --- to unpack the other packages
552
553 @item
554 DJGPP development kit (@samp{v2/djdev203.zip}) --- needed for all
555 DJGPP compiles
556
557 @item
558 CS's DPMI Provider (@samp{v2misc/csdmpi7b.zip}) --- you need some DPMI
559 provider to run @cic{} on a plain DOS system, although this is not
560 needed on systems such as Microsoft Windows' emulation of DOS which
561 already include a DPMI provider
562
563 @item
564 GNU Binutils (@samp{v2gnu/bnu219b.zip}) --- needed to produce
565 executables
566
567 @item
568 gcc (@samp{v2gnu/gcc444b.zip}) --- used to compile C code
569
570 @item
571 GNU make (@samp{v2gnu/mak3791b.zip}) --- used to resolve dependencies
572 within the build system
573
574 @item
575 GNU bash (@samp{v2gnu/bsh204b.zip}) --- used to interpret build
576 scripts
577
578 @item
579 GNU Diffutils (@samp{v2gnu/dif20b.zip}) --- used by the build scripts
580
581 @item
582 GNU Fileutils (@samp{v2gnu/fil41b.zip}) --- used by the build scripts
583
584 @item
585 GNU Findutils (@samp{v2gnu/find41b.zip}) --- used by the build scripts
586
587 @item
588 GNU awk (@samp{v2gnu/gwk318b.zip}) --- used by the build scripts
589
590 @item
591 GNU sed (@samp{v2gnu/sed421b.zip}) --- used by the build scripts
592
593 @item
594 GNU Shellutils (@samp{v2gnu/shl2011b.zip}) --- used by the build
595 scripts
596
597 @item
598 GNU Textutils (@samp{v2gnu/txt20b.zip}) --- used by the build scripts,
599 and sometimes by @cic{} itself too
600
601 @end itemize
602
603 You might want to install other packages, particularly GNU Bison and
604 GNU Flex, in order to be able to rebuild certain parts of the compiler
605 if you change them. This is not necessary to simply be able to run
606 @cic{} without changing it, though.
607
608 @item
609 Test your DJGPP install to ensure it works, and make sure you have
610 environment variables set up correctly. In addition to the
611 @samp{DJGPP} variable that points to your @samp{DJGPP.ENV} file, and
612 the @samp{PATH} variable that needs to contain DJGPP's binaries
613 directory, you also need to set the @samp{DJDIR} environment variable
614 to point to the main DJGPP installation directory.
615
616 @item
617 Unpack a copy of @cic{} in its own directory, if you haven't
618 already (@pxref{Unpacking}).
619
620 @item
621 Load up a @command{bash} session, change to the @samp{buildaux}
622 subdirectory of your main @cic{} directory, and run the command
623 @command{build-dj.sh}. This will run the entire @cic{} build system,
624 and hopefully end up with executables you can run in the @samp{build}
625 subdirectory that will be created in your main @cic{} directory.
626
627 @item
628 If you wish, you can install @cic{} by using the command @command{make
629 install} from the new @samp{build} subdirectory. It will run just fine
630 in-place without a need to install, though, if you prefer.
631
632 @end enumerate
633
634 @node Uninstalling
635 @section Uninstalling
636 @cindex uninstalling
637 @cindex @command{ick}, uninstalling
638
639 It may happen that you decide to uninstall @cic{} after installing it;
640 this may be useful if you want to test the installation system, or
641 change the location you install programs, or for some reason you don't
642 want it on your computer.  It's worth uninstalling just before you
643 install a new version of @cic{} because this will save some disk space;
644 you cannot install two versions of @cic{} at once (at least, not in
645 the same directory; but you can change the --prefix of one of the
646 installations to get two versions at once).
647
648 If you installed @cic{} using @command{make install}, you can
649 uninstall it by using @command{make uninstall} from the installation
650 directory, assuming that it still exists.  If you can't use that
651 method for some reason, you can uninstall it by deleting the files
652 @file{ick} and @file{convickt} where your computer installs binaries
653 (with an extension like @samp{.exe} added if that's usual for binaries
654 on your operating system), @file{libick.a}, @file{libickmt.a},
655 @file{libickec.a}, and @file{libyuk.a} where your computer installs
656 libraries, and the subdirectories @file{ick-@value{VERSION}} in the
657 places where your computer installs data files and include files, and
658 their contents.
659
660 You can go further than uninstalling.  Running @command{make clean}
661 will delete any files created by compilation; @command{make distclean}
662 will delete those files, and also any files created by configuring.
663 It's probably a wise idea to uninstall before doing a distclean,
664 though, as otherwise information needed to uninstall will be deleted,
665 as that information is generated by @command{configure}. You can go
666 even further and use @command{make veryclean} which will delete not
667 only files created by configuring, but the entire build system; doing
668 so is not recommended unless you have some method of rebuilding the
669 build system from its original sources (a script to do this is
670 provided in repository versions of @cic{}, because the generated part
671 of the build system is not stored in the repository).
672
673 @node Reporting Bugs
674 @section Reporting Bugs
675 @cindex bugs, reporting
676 @cindex reporting bugs
677 @cindex patches, submitting
678 @cindex submitting patches
679
680 If you can't get @cic{} to install at all, or something goes wrong when
681 you're using it, reporting a bug is probably a good idea.  (This is
682 still important even if you figure out how to fix it, and the
683 information isn't in the manual, because the fix can be added to the
684 source code if possible, or at least to the manual, to benefit future
685 users.)  For general help, you may want to post to the
686 @uref{news:alt.lang.intercal,,alt.lang.intercal} news group; to report
687 a bug or submit a patch, email the person who released the most recent
688 @cic{} version (which you can determine by looking at that newsgroup).
689
690 If you do find a bug (either the compiler not behaving in the way you'd
691 expect, or if you find a way to cause E778 (@pxref{E778}) without
692 modifying the source code), it helps a lot if you can submit a bug
693 report explaining what causes it.  If you're not sure, say that; it
694 helps if you give examples of input, command line options, etc.@: that
695 cause the bug.  There are several debug options (@pxref{Debug Options})
696 that you can use to help pin down a bug if you're interested in trying
697 to solve the problem yourself; looking at the output C code can also
698 help pin down a bug if the compiler gets that far.
699
700 Information that should be given in a bug report is what you expect to
701 happen, what actually happens, what input and command line options you
702 gave to the compiler, what operating system you're using, any ideas you
703 might have as to what the problem is, and any appropriate debug traces
704 (for instance, @option{-H} (@pxref{-H+,,-H}) output if you think the bug
705 is in the optimizer).  Core dumps aren't portable between systems, so
706 don't send those; however, if you're getting an internal error and can
707 dump core with @option{-U} (@pxref{-U+,,-U}), it helps if you can load a
708 debugger (such as @command{gdb}) on the core dump, use the debugger to
709 produce a backtrace, and send that backtrace.
710
711 If you figure out how to solve the bug yourself, and want to submit the
712 patches to help other users (this also carries the advantage that your
713 patches will then be maintained along with the rest of the distribution,
714 and that you won't have to reapply them every time you upgrade to a
715 newer version of @cic{}), you must first agree to license your code
716 under the same license as the code that surrounds it (normally, that's
717 the GNU General Public License, but if you submit a patch to a file with
718 a different license, like this manual (yes, documentation patches are
719 useful too), you must agree to that license).  You will be credited for
720 the patch in the source code unless you specifically ask not to be or
721 you don't give your name (in both these cases, you must license the code
722 to the public domain so that it can be incorporated without the
723 attribution requirement).  Preferably, patches should be submitted in
724 the format created by the command @command{diff -u}; this command is
725 likely to be available on UNIX and Linux systems and versions are also
726 available for DOS and Windows (including a DJGPP port of the GNU
727 version).  If you can't manage that, just submit your new code with
728 enough lines of old code around it to show where it's meant to go, and a
729 description of approximately where in the file it was.  Patches should
730 be submitted by email to the person who most recently released a version
731 of @cic{}.
732
733 If you have a suggestion for a new feature, it makes sense to first
734 discuss it on the @uref{news:alt.lang.intercal,,alt.lang.intercal} news
735 group; other @ical{} compiler maintainers may also want to implement
736 that feature.  If you have developed code to implement that feature in
737 @cic{}, you can submit it the same way that you would submit a patch for
738 a bug.
739
740 @node Distributing
741 @section Distributing
742 @cindex C-INTERCAL, distributing
743 @cindex distributing C-INTERCAL
744 @cindex releasing C-INTERCAL
745
746 Due to the licensing conditions of @cic{}, you are allowed to release
747 your own version or distribution if you want to.  In such cases, it's
748 recommended that you follow the following guidelines:
749
750 @enumerate
751
752 @item
753 Make sure the new version is based on the most recent existing version.
754 Looking at the @uref{news:alt.lang.intercal,,alt.lang.intercal}
755 newsgroup will normally let you know what version is most recent.
756
757 @item
758 Increment the version number; if you add any new features, increment the
759 major version number (after the decimal point) and drop the minor version
760 number (before the decimal point) to 0, and otherwise increment the minor
761 version number.  You have to update the version number in the following
762 files: @file{configure.ac}, @file{configure}, and @file{doc/ick.txi}.  You
763 also have to rename the installation directory to reflect the new version
764 number.
765
766 @item
767 Add an entry to the @file{NEWS} file explaining what's new in the
768 version that you're releasing, following the same format as the other
769 entries.
770
771 @item
772 Update the @file{README} with a description of any new files you may
773 have added.
774
775 @item
776 Remove any autosave or backup files that may be littering the
777 installation directory or its subdirectories.
778
779 @item
780 Run @command{make distcheck}, which will make the distribution
781 paxballs, and rename them to have the correct extensions (Automake
782 thinks they're tarballs, so will use @samp{.tar} rather than
783 @samp{.pax}, and you have to fix this by hand).  @command{make
784 distcheck} will also perform some sanity checks on the build system of
785 the resulting paxball, which will help to ensure that nothing
786 important is missing from it.
787
788 @item
789 Place the new version somewhere on the Internet, and announce the
790 location and the fact that a new version has been released on
791 @uref{news:alt.lang.intercal,,alt.lang.intercal}.
792
793 @end enumerate
794
795 @node Invoking ick
796 @chapter Invoking ick
797 @cindex command line options
798 @cindex options, to @command{ick}
799 @cindex @command{ick}, command line options
800 @cindex @command{ick}, invoking
801 @cindex @command{ick}, options
802 @cindex compiling, @ical{} source code
803
804 All operations on @ical{} source code available in @cic{} are currently
805 carried out by the compiler @command{ick}.
806
807 The syntax is
808
809 @example
810 ick -options @var{inputfile}
811 @end example
812
813 @noindent
814 (Options can be given preceded by separate hyphens, or all in a row
815 after one hyphen, or a mixture; they're all single characters.)  By
816 default, this compiles one @ical{} program given as the input file
817 directly to an executable without doing anything fancy; usually you will
818 want to give options, which are described below.
819
820 @menu
821 * Language-affecting Options::       Options that specify language dialect
822 * Debug Options::                    Debug your code or ick itself
823 * Output Options::                   Specifying output format and location
824 * Optimizer Options::                Yes, you can optimize @ical{}!
825 * Other Options::                    Options not covered in other sections
826 * Options to Generated Programs::    Generated executables allow options too
827 * Environment Variables::            What environment variables affect ick
828 @end menu
829
830 @node Language-affecting Options
831 @section Language-affecting Options
832 @cindex options, language-affecting
833 @cindex language-affecting options
834 @cindex options, dialect
835 @cindex dialect options
836
837 The following command-line options to @command{ick} affect what dialect
838 of the @ical{} language is compiled by the compiler; you may need to set
839 one or more of these options if your input is not the default @cic{} but
840 instead some other language like @icst{} or @clcic{}, or just because
841 you like certainty or like being different with respect to your output.
842 Note that there is no command-line option corresponding to
843 @abbr{TriINTERCAL} (or the base 4-7 versions); instead, the numeric base
844 to use is determined by looking at the filename extension (@samp{.i} for
845 base 2, the default, or @samp{.3i} to @samp{.7i} for the base 3-7
846 versions.)
847
848 @table @option
849 @ianchor -b
850 @opindex -b
851 @cindex random bug
852 @cindex E774, disabling
853 If this option is @emph{not} given, there is a small chance that a
854 random bug appears in the compiler, which causes the programs it creates
855 to manifest a bug that causes error E774 (@pxref{E774}).  Giving the
856 option means that this bug will not happen.  (You may wonder why this
857 bug was preserved; it is in fact a bug that was carefully preserved
858 since the days of @icst{}, in this case, but the option to turn it off
859 is available as a workaround.  (There are no plans to fix this or any of
860 the other carefully preserved bugs any time soon, because that would
861 kind of defeat the point of having preserved them.)  Interestingly, the
862 @icst{} compiler documentation mentions a similar command-line option
863 that is a workaround for the same bug.)
864
865 @ianchor -m
866 @opindex -m
867 @cindex multithreading, enabling
868 @cindex backtracking, enabling
869 This option needs to be given to allow any multithreading or
870 backtracking commands or identifiers to be used.  (Unlike with other
871 language features, this is not autodetected because it's legal to have a
872 program with multiple COME FROM (@pxref{COME FROM}) commands aiming at
873 the same line even when it isn't multithreaded, in which case the
874 commands cause error E555 (@pxref{E555}) when that line is encountered
875 (with the usual caveats about both commands having to be active at the
876 time).)  Attempts to use non-COME FROM multithreading or backtracking
877 commands without this option produce error E405 (@pxref{E405}).
878
879 @ianchor -e
880 @opindex -e
881 @cindex external calls, enabling
882 This option makes it possible to link non-@ical{} programs with
883 @ical{} programs; instead of giving @ical{} programs only on the
884 command line, give one @ical{} program, followed by any number of
885 programs in other languages that have been written to be able to link
886 to @ical{} programs.  It also allows expansion libraries to be
887 specified on the command line, after the @ical{} program (expansion
888 libraries are given with no extension). For more information, see
889 @ref{External Calls}.  Also, both the @option{-a} and @option{-e}
890 options must be set to use CREATEd operators (regardless of whether
891 external calls are used or not).
892
893 @ianchorc -E
894 @opindex -E
895 @cindex system library, disabling
896 This option causes the system library to never be linked; this option
897 is only useful if your program references a line number in the range
898 1000 to 1999, contains no line numbers in that range, and yet still
899 doesn't want the system library to be linked in; therefore, it is
900 mostly useful with @option{-e} when adding in a custom replacement
901 system library written in a non-@ical{} language, especially the
902 expansion library @option{syslibc} (a system library replacement
903 written in C).
904
905 @ianchor -t
906 @opindex -t
907 @cindex INTERCAL-72 compatibility mode
908 @cindex compatibility, INTERCAL-72
909 This option tells the compiler to treat the source code as @icst{}; as a
910 result, any language constructs that are used but weren't available in
911 1972 will trigger error E111 (@pxref{E111}).
912
913 @ianchor -a
914 @opindex -a
915 @cindex CREATE, enabling
916 This option allows the CREATE statement (@pxref{CREATE}) to be used.
917 Note that enabling it carries a run-time penalty, as it means that
918 operand overloading code has to be generated for every variable in the
919 program. (This option is not necessarily needed for the external call
920 version of CREATE to work, but the external call version has fewer
921 features without it.)  Note that @option{-e} (@pxref{-e}) also needs
922 to be set to be able to CREATE operators.
923
924 @ianchor -v
925 @opindex -v
926 @cindex constants, assigning to
927 @cindex assigning to constants
928 It is possible to write @ical{} code sufficiently tortuous that it ends
929 up assigning to a constant.  Generally speaking, this isn't what you
930 wanted to do, so the compiler will kindly cause an error (E277;
931 @pxref{E277}) that stops the insanity at that point, but at the cost of a
932 significant amount of performance you can give this option to tell the
933 compiler to simply change the constant and keep on going anyway.  (Note
934 that unlike @clcic{}, this only changes uses of the constant preceded by
935 @code{#} in your program, not things like line numbers; you want
936 @uref{http://esolangs.org/wiki/Forte,Forte} for that.)  This option also
937 allows you to write arbitary expressions on the left of an assignment
938 statement if you wish.
939
940 @ianchorc -C
941 @opindex -C
942 @cindex clockface mode
943 When this option is given, the generated programs will write the number
944 4 as @samp{IIII} rather than @samp{IV}, in case you're writing a clock
945 program.
946
947 @ianchorc -P
948 @opindex -P
949 @cindex PIC-INTERCAL, command line option
950 @cindex E256, avoiding
951 @cindex E652, avoiding
952 This tells the compiler to treat the input as @abbr{PIC-INTERCAL}
953 (@pxref{PIC-INTERCAL}) rather than ordinary @cic{} input, and generate
954 PIC output code accordingly.  There are a lot of options that are
955 incompatible with this, as well as many language features, due to the
956 limited memory available on a PIC.  If you get error E256
957 (@pxref{E256}), you have this option given when it shouldn't be;
958 likewise, if you get error E652 (@pxref{E652}), you should be using this
959 option but aren't.  (A few simple programs are
960 @cic{}/@abbr{PIC-INTERCAL} polyglots, but such programs are incapable of
961 doing input or output, meaning that they aren't particularly useful.)
962
963 @ianchorc -X
964 @opindex -X
965 @cindex Princeton syntax, option
966 @cindex syntax, Princeton
967 The @cic{} and @clcic{} compilers use different notation for various
968 things, sometimes to the extent where the same notation is legal in both
969 cases but has a different meaning.  As this is the @cic{} compiler, it
970 rather guessably uses its own notation by default; however, the @clcic{}
971 notation can be used as the default instead using this option.  (In most
972 situations where there isn't an ambiguity about what something means,
973 you can use the `wrong' syntax freely.) The option causes ambiguous
974 characters like @code{?} to be interpreted with Princeton rather than
975 Atari meanings.
976
977 @ianchor -x
978 @opindex -x
979 @cindex CLC-INTERCAL compatibility mode
980 @cindex compatibility, CLC-INTERCAL
981 This option causes some constructs with different meanings in @cic{}
982 and @clcic{} to use the @clcic{} meaning rather than the @cic{}
983 meaning. At present, it affects the abstention of a GIVE UP
984 (@pxref{GIVE UP}) command by line number, which is possible as long as
985 this switch isn't given; reading through the @icst{} manual, there are
986 a lot of things that imply that this probably wasn't intended to be
987 possible, but as far as I can tell that manual doesn't actually
988 @emph{say} anywhere that this particular case is disallowed, even
989 though it rules out all other similar cases.  It also causes I/O on
990 array variables to be done in @clcic{}'s extended Baudot syntax,
991 rather than using the Turing Tape method.
992
993 @end table
994
995 @node Debug Options
996 @section Debug Options
997 @cindex options, debug
998 @cindex debug options
999
1000 Sometimes things will go wrong with your program, or with the way
1001 @command{ick} was installed.  There may even be unknown bugs in
1002 @command{ick} itself (if you find one of these, please report it).  The
1003 following options are used to debug the whole system on various levels.
1004
1005 @table @option
1006
1007 @ianchor -d
1008 @opindex -d
1009 @cindex debugging, parser
1010 @cindex parser, debugging
1011 @cindex debugging, lexical analyser
1012 @cindex lexical analyser, debugging
1013
1014 If you think that something has gone wrong with the parser, or you want
1015 to see how your program is being parsed, you can give this option on the
1016 command line.  All the debug output produced by the parser and lexical
1017 analyser will be output.
1018
1019 @ianchor -g
1020 @opindex -g
1021 @cindex debugging, C code
1022 @cindex C code, debugging
1023 @cindex C code, leaving in place
1024
1025 This option allows debugging of the final executable at the C code
1026 level.  Any C code generated will be left in place, and the @option{-g}
1027 option will be given to the C compiler that's used to compile the code,
1028 so all the information needed for a C debugger to be used on the
1029 executable will be present there.
1030
1031 @item -h
1032 @itemx -H
1033 @itemx -hH
1034 @anchor{-h}
1035 @anchor{-H+}
1036 @anchor{-hH}
1037 @opindex -h
1038 @opindex -H
1039 @opindex -hH
1040 @cindex optimizer, debugging
1041 @cindex debugging, optimizer
1042 @cindex OIL, debugging
1043 @cindex debugging, OIL
1044
1045 These options allow debugging of the optimiser, or produce output
1046 helpful for understanding how your program has been summarised.
1047 @option{-h} produces a summary of what optimiser rules were used, the
1048 initial expression and what it was optimised to; @option{-H} produces a
1049 more expanded view that shows each intermediate step of optimisation,
1050 and @option{-hH} shows the same output as @option{-H}, but written
1051 completely using C syntax (the other options output in a strange mix of
1052 @ical{} and C).
1053
1054 @ianchor -l
1055 @opindex -l
1056 @cindex warnings, enabling
1057
1058 This option turns on generation of warnings (@pxref{Warnings}).  To make
1059 sure that they aren't actually useful, or are only marginally useful,
1060 the warning generator is far too sensitive, and there is no way to
1061 decide which warnings are given and which ones aren't; you either get
1062 all of them or none.
1063
1064 @ianchor -p
1065 @opindex -p
1066 @cindex profiling
1067 @cindex yuk, profiling
1068
1069 This option causes the program to run immediately after being compiled,
1070 and profiles the resulting program to identify performance bottlenecks,
1071 etc.  The usefulness of this depends on the resolution of the timers on
1072 the computer and operating system; DOS, in particular, is really bad
1073 with timer resolution.  The output will be saved in a file called
1074 @file{yuk.out} when the program finishes running.  It's legal to turn on
1075 both the profiler and the interactive debugger at the same time, but if
1076 you do this the profiler will also identify bottlenecks in the person
1077 typing in commands to step through the program! The profiler will, in
1078 fact, identify all the timings that particular commands in the program
1079 take; so @code{WRITE IN} instructions will often show up as taking a
1080 long time due to their need to wait for input.
1081
1082 @ianchor -w
1083 @opindex -w
1084 @cindex +printflow, enabling
1085 @cindex printflow, enabling
1086
1087 This option causes the produced program to support the
1088 @option{printflow} option fully; when this option is not given,
1089 @option{printflow} will in most cases have partial or no support
1090 (except in multithreaded programs, where this option is redundant),
1091 because not all the code needed for it will be included in the program
1092 to save space.
1093
1094 @ianchor -u
1095 @opindex -u
1096 @cindex skeleton file, directory problems
1097 @cindex system library, directory problems
1098 @cindex syslib, directory problems
1099 @cindex directory problems
1100 @cindex E999, debugging
1101 @cindex E127, debugging
1102
1103 When you are getting problems with finding files -- for instance, the
1104 compiler can't find the skeleton file (@pxref{E999}) or the system
1105 library (@pxref{E127}) -- this option will let you know, on standard
1106 error, where the compiler is looking for files.  This may hopefully help
1107 you pin down where the file-finding problems are coming from, and also
1108 offers the option of simply placing copies of the files where the
1109 compiler is looking as a last resort.
1110
1111 @ianchor -y
1112 @opindex -y
1113 @cindex yuk, command line option
1114
1115 This is the main debugging option: it loads yuk, an interactive @ical{}
1116 debugger with ability to step through the program, set breakpoints, view
1117 and modify variables, etc.  @xref{yuk}.
1118
1119 @ianchorc -Y
1120 @opindex -Y
1121 @cindex external calls, debugging
1122 @cindex command line, showing intermediates
1123
1124 This options causes the command line to be displayed for all calls to
1125 other programs that @command{ick} makes (mostly to @command{gcc}); it
1126 is therefore useful for debugging problems with the command lines used
1127 when using the external calls system (@pxref{External Calls}).
1128
1129 @ianchorc -U
1130 @opindex -U
1131 @cindex internal errors, debugging
1132 @cindex debugging, internal errors
1133 @cindex internal errors, dumping core
1134 @cindex dumping core on error
1135 @cindex E778, debugging
1136
1137 The internal error E778 (@pxref{E778}) should never happen.  However,
1138 there are all sorts of potential problems that may come up, and if part
1139 of the code detects something impossible, or more usually when the
1140 operating system detects things have got too insane and segfaults,
1141 normally this error will just be generated and that's that.  (I most
1142 often get this when I've been writing a new section of code and have
1143 made a mistake; hopefully, all or at least most of these errors are
1144 fixed before release, though.)  If you want more information as to what's
1145 going on, you can give the @option{-U} option, which will cause the
1146 compiler to raise an abort signal when an internal error happens.  This
1147 can generally be caught by a debugger that's being run on @command{ick}
1148 itself at the time; on many systems, it will also cause a core dump.
1149
1150 @end table
1151
1152 @node Output Options
1153 @section Output Options
1154 @cindex output options
1155 @cindex options, output
1156
1157 These options allow you to control how far to compile (all the way to an
1158 executable, or only to C, etc.@:), and where the output will be created.
1159 Note that the output options may change depending on the other options
1160 selected; for instance, many of the debug options will prevent the code
1161 being compiled all the way to an executable.
1162
1163 @table @option
1164
1165 @ianchor -c
1166 @opindex -c
1167 @cindex code generation, stopping at C code
1168 @cindex C, stopping after C is generated
1169 @cindex output, C only
1170
1171 By default, the original @ical{} code will be compiled all the way to an
1172 executable, and the intermediate C and object files produced will be
1173 deleted.  Giving this option causes the compiler to stop when it has
1174 finished producing the C file, leaving the C file there as the final
1175 output of the compiler.  (Its filename is the same as the source file,
1176 but with @samp{.c} as its extension/suffix rather than the source file's
1177 extension.)  Without this option, an executable will be produced with the
1178 extension changed to whatever's appropriate for the system you are on
1179 (or omitted entirely if that's appropriate for the system).
1180
1181 This option also places verbose comments in the output C file.
1182
1183 @ianchor -o
1184 @opindex -o
1185 @cindex output, to standard output
1186 @cindex standard output
1187
1188 This option causes the compiler to progress no further than producing
1189 the C output file, but instead of writing it to a file writes it
1190 directly to standard output.  This might occasionally be useful when
1191 using @command{ick} as part of a pipe; it can also be useful to see how
1192 far the compiler gets with compiling code before an error happens, when
1193 you're trying to track down an error.
1194
1195 @end table
1196
1197 @node Optimizer Options
1198 @section Optimizer Options
1199 @cindex optimizer options
1200 @cindex options, optimizer
1201 @cindex optimization
1202
1203 There are various command line options that can be used to tell
1204 @command{ick} whether and in what ways to optimize code.
1205
1206 @table @option
1207
1208 @ianchor -f
1209 @opindex -f
1210 @cindex flow optimization
1211 @cindex optimization, flow
1212 @cindex optimization, control flow
1213
1214 This option requests the compiler to attempt to analyse the flow of the
1215 program and optimize accordingly; for instance, it will detect which
1216 commands can't possibly be @code{ABSTAINED} from and refrain from
1217 generating code to check the abstention status of those commands.
1218
1219 @ianchorc -F
1220 @opindex -F
1221 @cindex optimization, extreme
1222 @cindex extreme optimization
1223
1224 This option tells the compiler to optimize the output for speed.  This
1225 is done to crazy extremes; the compiler may take several hours/days
1226 analysing the program in some cases and still not come up with an
1227 improvement.  It turns on all the other optimizer options.  Note that
1228 not all systems accept this option, because it sometimes outputs a shell
1229 script disguised as an executable rather than an actual executable.
1230
1231 @ianchorc -O
1232 @opindex -O
1233 @cindex optimization, idioms
1234 @cindex idiom optimization
1235 @cindex optimization, OIL
1236 @cindex OIL, optimizing code
1237
1238 This option tells the compiler to apply optimizer idioms to the
1239 expressions in the code given, when appropriate.  The list of idioms is
1240 stored in the file @file{src/idiotism.oil}; note that it is compiled
1241 into the compiler, though, so you will have to rebuild and reinstall the
1242 compiler if you change it.  For more information about changing the list
1243 of idioms, see @ref{Optimizer Idiom Language}.
1244
1245 @end table
1246
1247 @node Other Options
1248 @section Other Options
1249 @cindex other options
1250 @cindex options, other
1251
1252 Some options just can't be classified.
1253
1254 @table @option
1255
1256 @item -@@
1257 @anchor{-at}
1258 @opindex -@@
1259 @cindex options, help
1260 @cindex help with options
1261 @cindex usage instructions, printing
1262
1263 If this option is given, the compiler doesn't run at all, but instead
1264 prints a set of instructions for using it, explaining which options are
1265 available on the system you're on and which options conflict with which
1266 other options.
1267
1268 @end table
1269
1270 @node Options to Generated Programs
1271 @section Options to Generated Programs
1272 @cindex generated programs, options
1273 @cindex options, to generated programs
1274
1275 Once the compiler runs and produces an output executable, that
1276 executable itself will accept a range of options that control the way it
1277 runs.  None of these options have to be used; a default value will be
1278 assumed if they aren't.
1279
1280 @table @option
1281
1282 @ianchorpm help
1283 @opindex +help
1284 @opindex -help
1285
1286 Whether @samp{+} or @samp{-} is given at the start of this option, it
1287 will cause the program to print out what options are available and what
1288 state they are in.  It will then cause the program to exit via an
1289 internal error.
1290
1291 @ianchorpm wimpmode
1292 @opindex +wimpmode
1293 @opindex -wimpmode
1294 @cindex wimpmode
1295 @cindex Roman numerals, disabling
1296 @cindex Arabic numberals, enabling
1297 @cindex input, in Arabic numerals
1298 @cindex output, in Arabic numerals
1299
1300 If the @samp{+} version of this is given (rather than the default
1301 @samp{-}), then the program will print a message explaining that you are
1302 a wimp (the mode itself is known as wimpmode), and for the rest of
1303 execution will input in Arabic numerals (@samp{123} rather than
1304 @samp{ONE TWO THREE}) and likewise will output in Arabic numerals rather
1305 than Roman numerals (such as @samp{CXXIII}).  True @ical{} programmers
1306 should rarely have to use this mode.
1307
1308 @ianchorpm traditional
1309 @opindex +traditional
1310 @opindex -traditional
1311
1312 This option does not actually appear to do anything.
1313
1314 @ianchorpm instapipe
1315 @opindex +instapipe
1316 @opindex -instapipe
1317 @cindex output, flushing
1318 @cindex flushing
1319
1320 This option causes standard output to be flushed whenever any characters
1321 are output when the @samp{+} version is used, rather than on each newline
1322 (the default @samp{-} version).  It is most useful for more responsive
1323 pipes when outputting binary data, and also useful for debugging very
1324 slow programs.
1325
1326 @ianchorpm printflow
1327 @opindex +printflow
1328 @opindex -printflow
1329 @cindex flow, printing
1330 @cindex debugging, flow
1331 @cindex debugging, multithreaded programs
1332 @cindex multithreading, debugging
1333 @cindex backtracking, debugging
1334
1335 The usual debugging methods don't work with multithreaded or
1336 backtracking programs.  This option exists to give at least a slim
1337 chance of working out what is going on with them.  It causes the
1338 program to print the line number of the command it thinks it may be
1339 executing next (i.e.@: the line number that would be printed if that
1340 line had an error) immediately after executing each command, and also
1341 an internal identifier for the thread that that command was in.  It
1342 also prints a trace of what parts of the multithreader are being
1343 activated; so for instance, it will tell you when a thread is being
1344 forked into multiple threads or when a choicepoint has been deleted.
1345 Note that the @option{-w} option (@pxref{-w}) must be given to gain
1346 full support for flow printing in non-multithreaded non-backtracking
1347 programs, because otherwise the required code to print this
1348 information will not be generated.
1349
1350 @ianchorpm mystery
1351 @opindex +mystery
1352 @opindex -mystery
1353
1354 This option is occasionally capable of doing something, but is
1355 deliberately undocumented.  Normally changing it will have no effect,
1356 but changing it is not recommended.
1357
1358 @end table
1359
1360 @node Environment Variables
1361 @section Environment Variables
1362 @cindex environment variables
1363
1364 Various environment variables can be set to affect the operation of
1365 @command{ick}.
1366
1367 @multitable @columnfractions .3 .7
1368 @headitem Variable @tab Meaning
1369 @item ICKINCLUDEDIR@*ICKLIBDIR@*ICKSYSDIR@*ICKCSKELDIR
1370 @tab
1371 These four environment variables suggest locations in which
1372 @command{ick} should look to find various files that it needs: the
1373 skeleton file, system library, C header files and libraries that it
1374 needs, constant-output optimiser, and the GNU General Public License
1375 (which the debugger needs to be able to display on demand for legal
1376 reasons).
1377 @c Note: ICKSYDIR and ICKCSKELDIR used to be one variable, ICKDATADIR.
1378 @item CC
1379 @tab
1380 The name of a C compiler to use (defaults to gcc, which is the only
1381 compiler with which @cic{} has been tested recently).  This option has
1382 no effect on DJGPP, where gcc is always used.
1383 @item ICKTEMP@*TMPDIR@*TEMP@*TMP
1384 @tab
1385 On DJGPP, @command{ick} creates temporary files to pass options to gcc
1386 as a method of getting around the limit on the length of a command line
1387 that can sometimes affect DOS programs.  These four environment
1388 variables are tried (in this order) to determine a location for the
1389 temporary file; if none of them are set, the current directory is used.
1390 @end multitable
1391
1392 @node Errors and Warnings
1393 @chapter Errors and Warnings
1394 @cindex @command{ick}, errors and warnings
1395 @cindex errors and warnings
1396
1397 Things may go wrong, either during the compilation or the execution of
1398 your program.  Note that some things that would be compile-time errors
1399 in many other languages -- such as syntax errors -- are in fact run-time
1400 errors in @ical{}.
1401
1402 Errors and warnings appear as an error code starting with @samp{ICL},
1403 followed by a three digit number, followed by @samp{I} for an error or
1404 @samp{W} for a warning.  However, they will be notated here as
1405 @samp{E000}, etc.@:, to save space and because consistency was never a
1406 strong point of @ical{}.  This is followed by a text description of the
1407 error, and a hint as to the location of the error.  This is not the line
1408 on which the error occurred, but rather the line on which the next
1409 command to be executed is.  To add to the fun, the calculation of the
1410 next command to be executed is done at compile-time rather than runtime,
1411 so it may be completely wrong due to things like abstention on
1412 @code{COME FROM}s or computed @code{COME FROM}s.  The moral of this
1413 story is that, if you really want to know where the error is, use a
1414 debugger.  Note also that if the error happens at compile-time, there is
1415 no guarantee that the line number given makes any sense at all.  Some
1416 errors don't give next line numbers, mostly those for which it doesn't
1417 make logical sense, such as E633 (@pxref{E633}).  After this is a
1418 suggestion to correct (or reconsider) the source code and to resubnit
1419 it.  (This typo has been carefully preserved for over a decade.)
1420
1421 @menu
1422 * Errors::                     Error messages that might be produced
1423 * Warnings::                   Warnings produced by the @option{-l} option
1424 @end menu
1425
1426 @node Errors
1427 @section Errors
1428 @cindex errors
1429 @cindex @command{ick}, errors
1430
1431 This is a list of the error messages that might be produced during the
1432 compilation or execution of an @ical{} program.
1433
1434 @table @asis
1435
1436 @ieanchor E000
1437 @cindex syntax error
1438
1439 This is an unusual error; it's what's printed when a syntax error is
1440 encounted at runtime, in a situation in which it would be executed.  (An
1441 @code{ABSTAIN}ed syntax error, for instance, would not be executed; this
1442 is one of the mechanisms available for writing comments.)  The text of
1443 the error message is simply the statement that couldn't be decoded.
1444
1445 @ieanchor E017
1446 @cindex constant, twospot
1447 @cindex overflow, in constant
1448 @quotation
1449 DO YOU EXPECT ME TO FIGURE THIS OUT?
1450 @end quotation
1451
1452 This error occurs when there is an attempt to use a constant with a
1453 value outside the onespot range; it's a compile-time error.
1454
1455 @ieanchor E079
1456 @cindex politesse
1457 @cindex @code{PLEASE}, proportion required
1458 @quotation
1459 PROGRAMMER IS INSUFFICIENTLY POLITE
1460 @end quotation
1461
1462 The balance between various statement identifiers is important.  If less
1463 than approximately one fifth of the statement identifiers used are the
1464 polite versions containing @code{PLEASE}, that causes this error at
1465 compile time.
1466
1467 @ieanchor E099
1468 @quotation
1469 PROGRAMMER IS OVERLY POLITE
1470 @end quotation
1471
1472 Of course, the same problem can happen in the other direction; this
1473 error is caused at compile time if over about one third of the statement
1474 identifiers are the polite form.
1475
1476 @ieanchor E111
1477 @quotation
1478 COMMUNIST PLOT DETECTED, COMPILER IS SUICIDING
1479 @end quotation
1480
1481 This error happens when you give the @option{-t} option (@pxref{-t}) but
1482 you use a language construct that wasn't available in @icst{}.  If this
1483 happens, then either there's a mistake in the program that prevents it
1484 being @icst{} or you shouldn't be compiling it as @icst{} in the first
1485 place.
1486
1487 @ieanchor E123
1488 @cindex black lagoon
1489 @cindex @code{NEXT}, stack overflow
1490 @cindex stack overflow
1491 @quotation
1492 PROGRAM HAS DISAPPEARED INTO THE BLACK LAGOON
1493 @end quotation
1494
1495 There is a hard limit of 80 @command{NEXT}s at a time; this is to
1496 discourage excessive use of @command{NEXTING} for things like recursion.
1497 (Recursive programs are entirely legal; you simply have to figure out
1498 how to do it with computed @command{COME FROM} instead.  (For the
1499 record, it is possible.  (Using lots of nested brackets when talking
1500 about recursion is great (yay!@:).)))  Another problem with writing the
1501 source code that can cause this error is a failure to properly
1502 @command{FORGET} the entry on the @command{NEXT} stack created when
1503 trying to simulate a goto.
1504
1505 @ieanchor E127
1506 @cindex system library, errors
1507 @cindex syslib, errors
1508 @quotation
1509 SAYING 'ABRACADABRA' WITHOUT A MAGIC WAND WON'T DO YOU ANY GOOD
1510 @end quotation
1511 Your program asked to include the system library (by specifying a line
1512 number from 1000 to 1999 inclusive without including a line with that
1513 number), but due to installation problems the compiler couldn't find the
1514 system library to include.  You could try using the @option{-u}
1515 (@pxref{-u}) option to see where the compiler's looking; that may give
1516 you an idea of where you need to copy the system library so that the
1517 compilation will work.  This error happens at compile time and doesn't
1518 give a next command line number.
1519
1520 @ieanchor E129
1521 @cindex @code{NEXT}, nonexistent target
1522 @quotation
1523 PROGRAM HAS GOTTEN LOST
1524 @end quotation
1525
1526 This error happens at compile time when the compiler can't figure out
1527 where a @code{NEXT} command is actually aiming (normally due to a typo
1528 in either the line label given or the line label on the line aimed
1529 for).  The logic behind this error means that the next line to be
1530 executed is unknown (after all, that's the whole point of the error)
1531 and is therefore not given.  The @option{-e} command-line option
1532 (@pxref{-e}) makes this error into a run-time error, because it allows
1533 @code{NEXT} commands to dynamically change targets at runtime, as well
1534 as line labels to dynamically change values, and thus the error is
1535 impossible to detect at compile time.
1536
1537 @ieanchor E139
1538 @cindex @code{ABSTAIN}, nonexistent target
1539 @cindex @code{REINTSTATE}, nonexistent target
1540 @quotation
1541 I WASN'T PLANNING TO GO THERE ANYWAY
1542 @end quotation
1543
1544 This error happens at compile time when an @code{ABSTAIN} or
1545 @code{REINSTATE} references a non-existent target line.  This generally
1546 happens for much the same reasons as E129 (@pxref{E129}).
1547
1548 @ieanchor E182
1549 @cindex line label, duplicate
1550 @cindex duplicate line label
1551 @quotation
1552 YOU MUST LIKE THIS LABEL A LOT!
1553 @end quotation
1554
1555 At present, it's impossible to have more than one line with the same
1556 line number.  That would make @code{NEXT} act too much like @code{COME
1557 FROM} in reverse to be interesting.  This error happens at compile
1558 time.  (For inconsistency, it @i{is} possible to have multiple lines
1559 with the same number as long as at most one of them is in an @ical{}
1560 program (the others have to be in programs in other languages included
1561 via the external calls system).)
1562
1563 @ieanchor E197
1564 @cindex line label, illegal value
1565 @cindex illegal line label value
1566 @cindex invalid line label value
1567 @quotation
1568 SO@!  65535 LABELS AREN'T ENOUGH FOR YOU?
1569 @end quotation
1570
1571 Legal values for line labels are 1 to 65535 (with values from 1000 to
1572 1999 reserved if you want to use the system library, and 1600 to 1699
1573 reserved if you're using other expansion libraries).  This error comes
1574 up if you use nonpositive or twospot values for a line label.
1575
1576 @ieanchor E200
1577 @cindex variable, illegal number
1578 @cindex illegal variable number
1579 @cindex invalid variable number
1580 @quotation
1581 NOTHING VENTURED, NOTHING GAINED
1582 @end quotation
1583
1584 You used a variable that isn't actually in your program.  Failing that
1585 (which would be quite impressive and is probably impossible, at least in
1586 the present version of @cic{}), you specified an illegal number for a
1587 variable (legal numbers are positive and onespot).  This error happens
1588 at compile time, at least for illegal variable numbers.
1589
1590 @ieanchor E222
1591 @cindex out of memory, during @code{STASH}
1592 @quotation
1593 BUMMER, DUDE!
1594 @end quotation
1595
1596 In @ical{}, you're allowed to @code{STASH} as much as you like; this
1597 makes the language Turing-complete and allows for unlimited recursion
1598 when combined with computed @code{COME FROM} in the right way.
1599 Unfortunately, real computers aren't so idealised; if you manage to
1600 write a program so memory-intensive that the computer runs out of memory
1601 to store stashes, it causes this error at runtime.  To fix this error,
1602 you either have to simplify the program or upgrade your computer's
1603 memory, and even then that will only help to some extent.
1604
1605 @ieanchor E240
1606 @cindex array, invalid dimension
1607 @cindex invalid array dimension
1608 @cindex illegal array dimension
1609 @quotation
1610 ERROR HANDLER PRINTED SNIDE REMARK
1611 @end quotation
1612
1613 Arrays have to be large enough to hold at least one element; you tried
1614 to dimension an array which isn't large enough to hold any data.  This
1615 error happens at run time.
1616
1617 @ieanchor E241
1618 @cindex array, wrong dimension
1619 @cindex wrong array dimension
1620 @cindex array, out of bounds
1621 @cindex out of bounds
1622 @quotation
1623 VARIABLES MAY NOT BE STORED IN WEST HYPERSPACE
1624 @end quotation
1625
1626 This error happens at run time when the subscripts given to an array
1627 are inconsistent with the way the array was dimensioned, either
1628 because there were the wrong number of subscripts or because a
1629 subscript was too large to fit in the array.  It can also happen when
1630 a multidimensional array is given to a command, such as @code{WRITE
1631 IN}, that expects it to be monodimensional.
1632
1633 @ieanchor E252
1634 @cindex I/O, out of memory
1635 @cindex out of memory, I/O
1636 @quotation
1637 I'VE FORGOTTEN WHAT I WAS ABOUT TO SAY
1638 @end quotation
1639
1640 This run-time error message is caused by the compiler running out of
1641 memory whilst trying to do I/O; at present, it can only happen during
1642 @clcic{}-style I/O.
1643
1644 @ieanchor E256
1645 @cindex PIC-INTERCAL, unsupported command
1646 @quotation
1647 THAT'S TOO HARD FOR MY TINY BRAIN
1648 @end quotation
1649
1650 Some commands simply aren't available in @abbr{PIC-INTERCAL}.  I mean,
1651 @acronym{PIC}s generally have less than a kilobyte of memory; you're not
1652 going to be able to use some of the more confusing language features
1653 with that sort of resource limitation.  The solution is to replace the
1654 affected command, or to not give the @option{-P} option
1655 (@pxref{-P+,,-P}) if you didn't mean to compile as @abbr{PIC-INTERCAL}
1656 in the first place.
1657
1658 @ieanchor E275
1659 @cindex overflow, over onespot
1660 @cindex overflow, over 16 bits
1661 @cindex onespot overflow
1662 @cindex 16 bit overflow
1663 @quotation
1664 DON'T BYTE OFF MORE THAN YOU CAN CHEW
1665 @end quotation
1666
1667 This error happens when there is an attempt to store a twospot value in
1668 a onespot variable.  The actual size of the value is what matters when
1669 counting its spots; so you can store the output of a mingle in a onespot
1670 variable if it happens to be less than or equal to 65535, for instance.
1671 (This is not necessarily the case in versions of @ical{} other than
1672 @cic{}, though, so you have to be careful with portability when doing
1673 this.)
1674
1675 @ieanchor E277
1676 @cindex reverse assignment, impossible
1677 @cindex reverse assignment, error
1678 @cindex operand overloading, impossible
1679 @cindex impossible reverse assignment
1680 @quotation
1681 YOU CAN ONLY DISTORT THE LAWS OF MATHEMATICS SO FAR
1682 @end quotation
1683
1684 Reverse assignments are not always mathematically possible.  Also,
1685 sometimes they require changing the value of a constant; this is only
1686 legal if you specifically specified that it was legal by using the
1687 @option{-v} option.  In the case of an impossible reverse assignment
1688 (including a situation in which operand overloading causes a reverse
1689 assignment to happen), this error happens at runtime.
1690
1691 This error can also come up when a scalar variable is overloaded to an
1692 array (which doesn't make sense, but could happen if someone exploited
1693 bugs in the CREATE statement (@pxref{CREATE})), and an attempt is made
1694 to read or assign to that variable.  (Subscripting a scalar variable
1695 is a syntax error, so there is no use for doing such an overload
1696 anyway.)
1697
1698 @ieanchor E281
1699 @cindex spark, nesting limit
1700 @cindex ears, nesting limit
1701 @cindex rabbit-ears, nesting limit
1702 @cindex nesting limit
1703 @findex SENESTMAX
1704 @quotation
1705 THAT MUCH QUOTATION AMOUNTS TO PLAGIARISM
1706 @end quotation
1707
1708 There is a limit of 256 on the number of nested spark/ears groups
1709 allowed.  If you somehow manage to exceed that limit, that will cause
1710 this error.  Try breaking the expression up into smaller expressions.
1711 (The limit is trivial to increase by changing @code{SENESTMAX} in
1712 @file{ick.h}; if you ever actually come across a program that hits the
1713 limit but wasn't designed to, just email the maintainer to request a
1714 higher limit.)
1715
1716 @ieanchor E333
1717 @cindex variables, limit
1718 @quotation
1719 YOU CAN'T HAVE EVERYTHING, WHERE WOULD YOU PUT IT?
1720 @end quotation
1721
1722 Your program references so many variables that the compiler couldn't
1723 cope.  This error is unlikely to ever happen; if it does, try reducing
1724 the number of variables you use by combining some into arrays.  This is
1725 a compile-time error.
1726
1727 @ieanchor E345
1728 @cindex out of memory
1729 @quotation
1730 THAT'S TOO COMPLEX FOR ME TO GRASP
1731 @end quotation
1732
1733 This is another compile-time error that's unlikely to ever happen;
1734 this one signifies the compiler itself running out of memory trying to
1735 compile your program.  The only solutions to this are to simplify your
1736 program, or to make more memory available to the compiler.
1737
1738 @ieanchor E404
1739 @cindex @code{GO BACK}, no choicepoint
1740 @cindex @code{GO AHEAD}, no choicepoint
1741 @quotation
1742 I'M ALL OUT OF CHOICES!
1743 @end quotation
1744
1745 Your program asked that a choicepoint be backtracked to or removed, but
1746 there aren't any choicepoints at the moment.  This runtime error usually
1747 indicates a logic mistake in your program.  In backtracking programs
1748 translated from other backtracking languages, this indicates that the
1749 program has failed.
1750
1751 @ieanchor E405
1752 @cindex multithreading, not enabled
1753 @cindex backtracking, not enabled
1754 @cindex @code{WHILE}, not enabled
1755 @cindex @code{MAYBE}, not enabled
1756 @cindex @code{GO AHEAD}, not enabled
1757 @cindex @code{GO BACK}, not enabled
1758 @quotation
1759 PROGRAM REJECTED FOR MENTAL HEALTH REASONS
1760 @end quotation
1761
1762 Your program used a construct that only makes sense when multithreading
1763 or backtracking (@code{WHILE}, @code{MAYBE}, @code{GO BACK}, or @code{GO
1764 AHEAD}), but you didn't specify the @option{-m} option (@pxref{-m}).  If
1765 you meant to write a multithreaded or backtracking program, just give
1766 that option; if you didn't, be careful what words you use in comments!
1767 This error happens at compile-time.
1768
1769 @ieanchor E436
1770 @cindex @code{RETRIEVE}, without stashing
1771 @cindex stash failure
1772 @quotation
1773 THROW STICK BEFORE RETRIEVING!
1774 @end quotation
1775
1776 In order to @code{RETRIEVE} a variable, it has to be @code{STASH}ed
1777 first; if it isn't, then this error happens at runtime.
1778
1779 @ieanchor E444
1780 @cindex @code{COME FROM}, no target
1781 @cindex @code{NEXT FROM}, no target
1782 @quotation
1783 IT CAME FROM BEYOND SPACE
1784 @end quotation
1785
1786 A @code{COME FROM} aiming at a line label --- as opposed to a computed
1787 @code{COME FROM}, which is allowed to be pointing at a nonexistent line
1788 --- must point to a valid line label.  The same applies to @code{NEXT
1789 FROM}.  This error happens at compile time if a nonexistent line label is
1790 found in one of these contexts.
1791
1792 @ieanchor E533
1793 @cindex overflow, over twospot
1794 @cindex overflow, over 32 bits
1795 @cindex twospot overflow
1796 @cindex 32 bit overflow
1797 @quotation
1798 YOU WANT MAYBE WE SHOULD IMPLEMENT 64-BIT VARIABLES?
1799 @end quotation
1800
1801 This error is like E275 (@pxref{E275}), but applies when an attempt is
1802 made at runtime to store a threespot value (or even a fourspot or
1803 morespot value) in a twospot variable, or a threespot or greater value
1804 is produced as an intermediate during a calculation (for instance by a
1805 mingle operation).  No values above twospot are allowed at any point
1806 during an @ical{} program; if you want to process higher numbers, you
1807 have to figure out a different way of storing them.
1808
1809 @ieanchor E553
1810 @cindex buffer overflow
1811 @quotation
1812 BETTER LATE THAN NEVER
1813 @end quotation
1814 Oops!  The compiler just noticed that it had a buffer overflow.
1815 (Normally programs catch buffer overflows before they happen;
1816 @cic{} catches them just afterwards instead.)  This only happens
1817 on systems which don't have a modern C standard library. Try using
1818 shorter or fewer filenames on the command line, to reduce the risk of
1819 such an overflow.
1820
1821 @ieanchor E555
1822 @cindex @code{COME FROM}, ambiguity
1823 @quotation
1824 FLOW DIAGRAM IS EXCESSIVELY CONNECTED
1825 @end quotation
1826
1827 Aiming two @code{COME FROM}s at the same line only makes sense in a
1828 multithreaded program.  In a non-multithread program, doing that will
1829 cause this error at compile time (if neither @code{COME FROM} is
1830 computed) or at run time (if the command that has just finished running
1831 is simultaneously the target of two or more @code{COME FROM}s).  This
1832 either indicates an error in your program or that you've forgotten to
1833 use the @option{-m} option (@pxref{-m}) if you are actually trying to
1834 split the program into two threads.
1835
1836 @ieanchor E562
1837 @cindex input, EOF
1838 @cindex EOF
1839 @cindex end of file
1840 @quotation
1841 I DO NOT COMPUTE
1842 @end quotation
1843
1844 The program asked for input, but for some reason it wasn't available.
1845 (This is a runtime error, obviously.)   The error may happen because the
1846 input is being piped in from a command or file which has reached
1847 end-of-file, or because the user typed @kbd{@key{CTRL}-@key{D}}
1848 (UNIX/Linux) or @kbd{@key{CTRL}-@key{Z}} (DOS/Windows) while the program
1849 was trying to @code{WRITE IN} some data.
1850
1851 @ieanchor E579
1852 @cindex input, invalid
1853 @quotation
1854 WHAT BASE AND/OR LANGUAGE INCLUDES @var{string}?
1855 @end quotation
1856
1857 When reading spelt-out-digit input, the input didn't seem to be a valid
1858 digit in English, Sanskrit, Basque, Tagalog, Classical Nahuatl,
1859 Georgian, Kwakiutl, Volap@"uk, or Latin.  This seems to have languages
1860 covered pretty well; what on earth were you using, or did you just make
1861 a spelling mistake?
1862
1863 @ieanchor E621
1864 @cindex @code{RESUME}, by 0
1865 @quotation
1866 ERROR TYPE 621 ENCOUNTERED
1867 @end quotation
1868
1869 The compiler encountered error E621 (@pxref{E621}).  This happens at
1870 runtime when the program requests that no entries are removed from the
1871 @code{NEXT} stack (which is possible), but that the last entry removed
1872 should be jumped to (which given the circumstances isn't, because no
1873 entries were removed).
1874
1875 @ieanchor E632
1876 @quotation
1877 THE NEXT STACK RUPTURES.  ALL DIE.  OH, THE EMBARRASSMENT!
1878 @end quotation
1879
1880 When an attempt is made to @code{RESUME} past the end of the @code{NEXT}
1881 stack, the program ends; however, this cause the program to end in a
1882 manner other than via @code{GIVE UP} or @code{DON'T TRY AGAIN}, so an
1883 error message must be printed, and this is that error message.
1884
1885 @ieanchor E633
1886 @quotation
1887 PROGRAM FELL OFF THE EDGE
1888 @end quotation
1889
1890 You can't just let execution run off the end of the program.  At least,
1891 that is, if it doesn't end with @code{TRY AGAIN}.  An attempt to do that
1892 causes this error at runtime.  Note that if your program references the
1893 system library, then it counts as being appended to your program and so
1894 the program will run into the first line of the system library rather
1895 than cause this error.  As it happens, the first line of the system
1896 library is a syntax error, so doing this will cause E000 (@pxref{E000})
1897 with the error text @samp{PLEASE KNOCK BEFORE ENTERING}.  There isn't a
1898 next statement to be executed with E633, so the next statement won't be
1899 given in the error message.
1900
1901 @ieanchor E652
1902 @cindex @code{PIN}, in a non-PIC program
1903 @quotation
1904 HOW DARE YOU INSULT ME!
1905 @end quotation
1906
1907 The @code{PIN} command doesn't make much sense for anything bigger than
1908 a @acronym{PIC}; using it in a non-@acronym{PIC} program causes this
1909 error at compile-time.  Try using the normal input and output mechanisms
1910 instead.  This error may also be a clue that you are trying to compile a
1911 @abbr{PIC-INTERCAL} program without giving the @option{-P} option
1912 (@pxref{-P+,,-P}).
1913
1914 @ieanchor E666
1915 @cindex out of memory, during compile
1916 @cindex too many input files
1917 @cindex line too long
1918 @quotation
1919 COMPILER HAS INDIGESTION
1920 @end quotation
1921
1922 There isn't a limit on the length of an input program other than your
1923 computer's memory; if your computer does run out of memory during
1924 compilation, it causes this error.  This error can also be caused if
1925 too many input files are specified on the command line; if you suspect
1926 this is the problem, split the compilation into separate compilations
1927 if you can, or otherwise you may be able to concatenate together your
1928 input files into larger but fewer files.  Yet another potential cause
1929 of this error is if a line in an input program is too long; sensible
1930 line-wrapping techniques are encouraged.
1931
1932 @ieanchor E774
1933 @cindex random bug, error message
1934 @quotation
1935 RANDOM COMPILER BUG
1936 @end quotation
1937
1938 No compiler is perfect; sometimes errors just happen at random.  In this
1939 case, the random error is E774.  If you don't like the idea that your
1940 program may be shot down by a random compiler bug, or you are doing
1941 something important, you can use the @option{-b} option (@pxref{-b}) to
1942 prevent this bug happening.  (You may wonder why this bug is in there at
1943 all if it's so easily prevented.  The answer is that such a bug was
1944 present in the original @icst{} compiler, which also had an option to
1945 turn the bug off.  It's also a reward for people who actually read the
1946 manual.)
1947
1948 @ieanchor E777
1949 @cindex directory problems, source file
1950 @cindex no source file
1951 @quotation
1952 A SOURCE IS A SOURCE, OF COURSE, OF COURSE
1953 @end quotation
1954
1955 You specified a file to compile on the command line, but the compiler
1956 couldn't find or couldn't open it.  This is almost certainly because you
1957 made a typo specifying the file.
1958
1959 @ieanchor E778
1960 @cindex internal errors
1961 @quotation
1962 UNEXPLAINED COMPILER BUG
1963 @end quotation
1964
1965 This should never come up, either at compile time or at run time.  It
1966 could come up at either when an internal check by the compiler or the
1967 runtime libraries realises that something has gone badly wrong; mistakes
1968 happen, and in such cases the mistake will have been detected.  (If this
1969 happens at compile time you can use the @option{-U} option
1970 (@pxref{-U+,,-U}) to cause the compiler to send an abort signal -- which
1971 normally causes a core dump -- when the error happens, to help debug
1972 what's causing it.)  More often, this error comes up when the operating
1973 system has noticed something impossible, like an attempt to free
1974 allocated memory twice or to write to a null pointer, and tells the
1975 compiler an error has occured, in which case the same response of
1976 putting up this error happens.  The point is that in all cases this
1977 error indicates a bug in the compiler (even if it happens at run time);
1978 in such cases, it would be very helpful if you figure out what caused it
1979 and send a bug report (@pxref{Reporting Bugs}).
1980
1981 @ieanchor E810
1982 @cindex yuk, input overflow
1983 @quotation
1984 ARE ONE-CHARACTER COMMANDS TOO SHORT FOR YOU?
1985 @end quotation
1986
1987 This is a debug-time error caused when you give too much input to the
1988 debugger when all it wanted was to know what you wanted to do next.
1989
1990 @ieanchor E811
1991 @cindex yuk, breakpoint overflow
1992 @cindex yuk, too many breakpoints
1993 @cindex breakpoints, too many
1994 @quotation
1995 PROGRAM IS TOO BADLY BROKEN TO RUN
1996 @end quotation
1997
1998 There's a limit to how many breakpoints you can have in a program;
1999 you've broken the limit and therefore broken the debugger.  This is a
2000 debug-time error.
2001
2002 @ieanchor E888
2003 @quotation
2004 I HAVE NO FILE AND I MUST SCREAM
2005 @end quotation
2006 @cindex output file, failure to write
2007
2008 The output file couldn't be written, maybe because the disk is full or
2009 because there's already a read-only file with the same name.  This is a
2010 compile-time error.
2011
2012 @ieanchor E899
2013 @quotation
2014 HELLO?
2015 CAN ANYONE GIVE ME A HAND HERE?
2016 @end quotation
2017 @cindex Funge, no external library
2018 @cindex Befunge, no external library
2019 @cindex external libraries, unavailable
2020 @cindex .b98, no external library
2021
2022 This error occurs at compile-time if a file type was requested for
2023 which the required libraries are unavailable.  (Support for Funge does
2024 not ship with the compiler; instead, you need to generate the library
2025 yourself from the cfunge sources.  For more information, see
2026 @ref{Creating the Funge-98 Library}.)
2027
2028 @ieanchor E990
2029 @cindex out of memory, multithreading
2030 @cindex out of memory, backtracking
2031 @cindex multithreading, out of memory
2032 @cindex backtracking, out of memory
2033 @quotation
2034 YOU HAVE TOO MUCH ROPE TO HANG YOURSELF
2035 @end quotation
2036
2037 There is no limit on the number of threads or choicepoints that you can
2038 have in a multithreaded or backtracking program (in a program that isn't
2039 multithreaded or backtracking, these are obviously limited to 1 and 0
2040 respectively).  However, your computer may not be able to cope; if it
2041 runs out of memory in the multithreader, it will cause this error at
2042 runtime.
2043
2044 @ieanchor E991
2045 @cindex unsupported file type
2046 @cindex invocation flag, unnown
2047 @quotation
2048 FLAG ETIQUETTE FAILURE BAD SCOUT NO BISCUIT
2049 @end quotation
2050
2051 This error occurs at runtime if an INTERCAL program was passed an unknown 
2052 option flag.
2053
2054 @ieanchor E993
2055 @cindex @code{TRY AGAIN}, not last
2056 @quotation
2057 I GAVE UP LONG AGO
2058 @end quotation
2059
2060 @code{TRY AGAIN} has to be the last command in a program, if it's there
2061 at all; you can't even follow it by comments, not even if you know in
2062 advance that they won't be @code{REINSTATE}d.  This error happens at
2063 compile time if a command is found after a @code{TRY AGAIN}.
2064
2065 @ieanchor E994
2066 @cindex illegal opcode
2067 @quotation
2068 NOCTURNAL EMISSION, PLEASE LAUNDER SHEETS IMMEDIATELY
2069 @end quotation
2070
2071 This error should never happen, and if it does indicates a compiler
2072 bug. It means the emitter function in the code degenerator has
2073 encountered an unknown opcode. Please send a copy of the program
2074 that triggered it to the INTERCAL maintainers.
2075
2076 @ieanchor E995
2077 @quotation
2078 DO YOU REALLY EXPECT ME TO HAVE IMPLEMENTED THAT?
2079 @end quotation
2080
2081 Some parts of the code haven't been written yet.  There ought to be no
2082 way to cause those to actually run; however, if you do somehow find a
2083 way to cause them to run, they will cause this error at compile time.
2084
2085 @ieanchor E997
2086 @cindex whirlpool, in base 2
2087 @cindex sharkfin, in base 2
2088 @cindex TriINTERCAL, operators in base 2
2089 @quotation
2090 ILLEGAL POSSESSION OF A CONTROLLED UNARY OPERATOR
2091 @end quotation
2092
2093 Some operators (such as whirlpool (@code{@@}) and sharkfin (@code{^}))
2094 only make sense in @abbr{TriINTERCAL} programs, and some have a minimum
2095 base in which they make sense.  This error happens at compile-time if
2096 you try to use an operator that conflicts with the base you're in (such
2097 as using @abbr{TriINTERCAL} operators in an @ical{} program in the
2098 default base 2).
2099
2100 @ieanchor E998
2101 @cindex unsupported file type
2102 @cindex file type, unsupported
2103 @quotation
2104 EXCUSE ME,
2105 YOU MUST HAVE ME CONFUSED WITH SOME OTHER COMPILER
2106 @end quotation
2107
2108 This error occurs just before compile-time if a file is encountered on
2109 the command line that @cic{} doesn't recognise.  (If this error
2110 occurs due to a @samp{.a}, @samp{.b98}, @samp{.c}, or @samp{.c99},
2111 then you forgot to enable the external calls system using @option{-e}
2112 (@pxref{-e}).)
2113
2114 @ieanchor E999
2115 @cindex skeleton file, errors
2116 @quotation
2117 NO SKELETON IN MY CLOSET, WOE IS ME!
2118 @end quotation
2119
2120 The skeleton file @file{ick-wrap.c} or @file{pickwrap.c} is needed to be
2121 able to compile @ical{} to C.  If the compiler can't find it, it will
2122 give this error message.  This indicates a problem with the way the
2123 compiler has been installed; try using the @option{-u} option
2124 (@pxref{-u}) to find out where it's looking (you may be able to place a
2125 copy of the skeleton file in one of those places).
2126
2127 @end table
2128
2129 @node Warnings
2130 @section Warnings
2131 @cindex warnings
2132 @cindex @command{ick}, warnings
2133
2134 This is a list of the warnings stored in the warning database.
2135 Warnings only come up when the @option{-l} option (@pxref{-l}) is
2136 given; even then, some of the warnings are not currently implemented
2137 and therefore will never come up.
2138
2139 @table @asis
2140
2141 @ieanchor W016
2142 @quotation
2143 DON'T TYPE THAT SO HASTILY
2144 @end quotation
2145
2146 The positional precedence rules for unary operators are somewhat
2147 complicated, and it's easy to make a mistake.  This warning is meant to
2148 detect such mistakes, but is not currently implemented.
2149
2150 @ieanchor W018
2151 @quotation
2152 THAT WAS MEANT TO BE A JOKE
2153 @end quotation
2154
2155 If an @ical{} expression has been translated from another language such
2156 as C, the optimiser is generally capable of translating it back into
2157 something similar to the original, at least in base 2.  When after
2158 optimisation there are still @ical{} operators left in an expression,
2159 then this warning is produced.  (Therefore, it's likely to come up quite
2160 a lot if optimisation isn't used@!)  The system library produces some of
2161 these warnings (you can tell if a warning has come up in the system
2162 library because you'll get a line number after the end of your program).
2163
2164 @ieanchor W112
2165 @cindex warnings, non-INTERCAL-72
2166 @cindex non-INTERCAL-72 warning
2167 @quotation
2168 THAT RELIES ON THE NEW WORLD ORDER
2169 @end quotation
2170
2171 This warning comes up whenever the compiler recognises that you've added
2172 some code that didn't exist in @icst{}.  This allows you to check
2173 whether your code is valid @icst{} (although @option{-t} (@pxref{-t}) is
2174 more useful for that); it also warns you that code might not be portable
2175 (because @icst{} is implemented by most @ical{} compilers, but more
2176 recent language features may not be).
2177
2178 @ieanchor W128
2179 @quotation
2180 SYSLIB IS OPTIMIZED FOR OBUSCATION
2181 @end quotation
2182
2183 There is an idiom used in the system library that does a right-shift by
2184 selecting alternate bits from a twospot number and then mingling them
2185 the other way round.  A rightshift can much more easily be done with a
2186 single rightshift, so this is a silly way to do it, and this warning
2187 warns that this idiom was used.  However, the present optimizer is
2188 incapable of recognising whether this problem exists or not, so the
2189 warning is not currently implemented.
2190
2191 @ieanchor W276
2192 @cindex onespot, overflow warning
2193 @cindex overflow, warning
2194 @quotation
2195 YOU CAN'T EXPECT ME TO CHECK BACK THAT FAR
2196 @end quotation
2197
2198 It's an error to assign a twospot value (a value over 65535) to a
2199 onespot variable, or to use it as an argument to a mingle.  If the
2200 optimizer can't guarantee at compile time that there won't be an
2201 overflow, it issues this warning.  (Note that this doesn't necessarily
2202 mean there's a problem --- for instance, the system library generates
2203 some of these warnings --- only that the optimiser couldn't work out for
2204 sure that there wasn't a problem.)
2205
2206 @ieanchor W239
2207 @quotation
2208 WARNING HANDLER PRINTED SNIDE REMARK
2209 @end quotation
2210
2211 Your code looks like it's trying to assign 0 to an array, giving it no
2212 dimension; this is an error.  This warning is produced at compile time
2213 if it looks like a line in your code will cause this error, but it isn't
2214 necessarily an error because that line of code might never be executed.
2215
2216 @ieanchor W278
2217 @quotation
2218 FROM A CONTRADICTION, ANYTHING FOLLOWS
2219 @end quotation
2220
2221 It's sometimes impossible to reverse an assignment (a reverse
2222 assignment can happen if the @option{-v} option (@pxref{-v}) is used
2223 and an expression is placed on the left of an assignment, or in
2224 operand overloading); if the compiler detects that a reversal failure
2225 is inevitable, it will cause this warning.  Note that this doesn't
2226 always cause an error, because the relevant code might never be
2227 executed.
2228
2229 @ieanchor W450
2230 @quotation
2231 THE DOCUMENTOR IS NOT ALWAYS RIGHT
2232 @end quotation
2233
2234 There is no way to get this warning to come up; it isn't even written
2235 anywhere in @cic{}'s source code, is not implemented by anything, and
2236 there are no circumstances in which it is even meant to come up. It is
2237 therefore not at all obvious why it is documented.
2238
2239 @ieanchor W534
2240 @cindex unary operators, portability
2241 @cindex portability, unary operators
2242 @quotation
2243 KEEP LOOKING AT THE TOP BIT
2244 @end quotation
2245
2246 @cic{} uses a slightly different typing mechanism to some other @ical{}
2247 compilers; types are calculated at compile time rather than run time.
2248 This only makes a difference in some cases involving unary operators.
2249 It's impossible to detect at compile time for certain whether such a
2250 case has come up or not, but if the compiler or optimizer thinks that
2251 such a case might have come up, it will issue this warning.
2252
2253 @ieanchor W622
2254 @quotation
2255 WARNING TYPE 622 ENCOUNTERED
2256 @end quotation
2257
2258 Your code looks like it's trying to resume by 0; this is an error.  This
2259 warning is produced at compile time if it looks like a line in your code
2260 will cause this error, but it isn't necessarily an error because that
2261 line of code might never be executed.
2262
2263 @end table
2264
2265 @node The yuk debugger
2266 @chapter The yuk debugger
2267 @cindex yuk
2268 @cindex debugging, yuk
2269 @cindex debugging, runtime
2270 @cindex runtime debugger
2271 @anchor{yuk}
2272
2273 The @cic{} distribution contains a runtime debugger called `yuk'.
2274 Unlike most other debuggers, it is stored as object code rather than as
2275 an executable, and it is compiled into the code rather than operating on
2276 it.  To debug code, add @option{-y} (@pxref{-y}) to the command line of
2277 @command{ick} when invoking it; that tells it to compile the debugger
2278 into the code and then execute the resulting combination.  (The
2279 resulting hybrid debugger/input executable is deleted afterwards; this
2280 is to prevent it being run by mistake, and to prevent spreading the
2281 debugger's licence onto the code it was compiled with.)
2282
2283 yuk can also be used as a profiler using the @option{-p} option
2284 (@pxref{-p}); this produces a file @file{yuk.out} containing information
2285 on how much time was spent running each command in your program, and
2286 does not prompt for debugger commands.
2287
2288 Note that some command line arguments are incompatible with the
2289 debugger, such as @option{-m} and @option{-f}.  In particular, this
2290 means that multithreaded programs and programs that use backtracking
2291 cannot be debugged using this method; the @option{+printflow} option
2292 (@pxref{+printflow}) to a compiled program may or may not be useful for
2293 debugging multithreaded programs.
2294
2295 When the debugger starts, it will print a copyright message and a
2296 message on how to access online help; then you can enter commands to
2297 run/debug the program.  The debugger will show a command prompt,
2298 @samp{yuk007 }, to let you know you can input a command.
2299
2300 @cindex yuk, commands
2301 Here are the commands available.  Commands are single characters
2302 followed by newlines, or followed by a line number (in decimal) and a
2303 newline or a variable name (a @code{.}, @code{,}, @code{:} or @code{;}
2304 followed by a number in decimal; note that some commands only allow
2305 onespot and twospot variables as arguments).
2306
2307 @multitable @columnfractions .15 .85
2308 @headitem Command @tab Description
2309 @item a@var{LINE}
2310 @tab
2311 All non-abstained commands on line @var{LINE} become abstained from
2312 once.
2313 @item b@var{LINE}
2314 @tab
2315 A breakpoint is set on line @var{LINE}.  The breakpoint causes execution
2316 with @samp{c} to stop when it is reached.
2317 @item c
2318 @tab
2319 The program is run until it ends (which also ends the debugger) or a
2320 breakpoint is reached.
2321 @item d@var{LINE}
2322 @tab
2323 Any breakpoint that may be on line @var{LINE} is removed.
2324 @item e@var{LINE}
2325 @tab
2326 An explanation of the main expression in each command on line @var{LINE}
2327 is printed to the screen.  The explanation is in the same format as the
2328 format produced by @option{-h} (@pxref{-h}) and shows what the optimiser
2329 optimised the expression to (or the original expression if the optimiser
2330 wasn't used).
2331 @item f@var{LINE}
2332 @tab
2333 Removes the effect of the @samp{m} command on line @var{LINE}.
2334 @item g@var{LINE}
2335 @tab
2336 Causes the current command to be the first command on @var{LINE} (if not
2337 on that line already) or the next command on @var{LINE}, as if that line
2338 was @code{NEXT}ed to and then that @code{NEXT} stack item was forgotten.
2339 @item h
2340 @tab
2341 Lists 10 lines either side of the current line; if there aren't 10 lines
2342 to one or the other side of the current line, instead more lines will be
2343 shown on the other side to compensate, if available.
2344 @item i@var{VAR}
2345 @tab
2346 Causes variable @var{VAR} to become @code{IGNORE}d, making it read-only.
2347 @item j@var{VAR}
2348 @tab
2349 Causes variable @var{VAR} to become @code{REMEMBER}ed, making it no
2350 longer read-only.
2351 @item k
2352 @tab
2353 Continues executing commands until the @command{NEXT} stack is the same
2354 size or smaller than it was before.  In other words, if the current
2355 command is not a @command{NEXT} and doesn't have a @command{NEXT FROM}
2356 aiming at it, one command is executed; but if a @command{NEXT} does
2357 happen, execution will continue until that @command{NEXT} returns or is
2358 forgotten.  A breakpoint or the end of the program also end this.
2359 @item l@var{LINE}
2360 @tab
2361 Lists 10 lines of source code either side of line @var{LINE}, the same
2362 way as with @samp{h}, but using a line stated in the command rather than
2363 the current line.
2364 @item m@var{LINE}
2365 @tab
2366 Produces a message onscreen every time a command on line @var{LINE} is
2367 executed, but without interrupting the program.
2368 @item n
2369 @tab
2370 Show the @command{NEXT} stack on the screen.
2371 @item o
2372 @tab
2373 Continue executing commands until the @command{NEXT} stack is smaller
2374 than it was before.  If you are using @command{NEXT}s like procedures,
2375 then this effectively means that the procedure will run until it
2376 returns.  A breakpoint or the end of the program also end this.
2377 @item p
2378 @tab
2379 Displays the value of all onespot and twospot variables.
2380 @item q
2381 @tab
2382 Aborts the current program and exits the debugger.
2383 @item r@var{LINE}
2384 @tab
2385 Reinstates once all abstained commands on line @var{LINE}.
2386 @item s
2387 @tab
2388 Executes one command.
2389 @item t
2390 @tab
2391 Continues execution until the end of the program or a breakpoint: each
2392 command that executes is displayed while this command is running.
2393 @item u@var{LINE}
2394 @tab
2395 Continues execution of the program until just before a command on line
2396 @var{LINE} is run (or a breakpoint or the end of the program).
2397 @item v@var{VAR}
2398 @tab
2399 Adds a `view' on variable @var{VAR} (which must be onespot or twospot),
2400 causing its value to be displayed on the screen whenever a command is
2401 printed on screen (for instance, because the command has just been
2402 stepped past, or due to the @samp{m} or @samp{t} commands).
2403 @item w
2404 @tab
2405 Displays the current line and current command onscreen.
2406 @item x@var{VAR}
2407 @tab
2408 Removes any view and any action that may be associated with it on
2409 variable @var{VAR} (which must be onespot or twospot).
2410 @item y@var{VAR}
2411 @tab
2412 Adds a view on variable @var{VAR}; also causes a break, as if a
2413 breakpoint was reached, whenever the value of that variable changes.
2414 @item z@var{VAR}
2415 @tab
2416 Adds a view on variable @var{VAR}; also causes a break, as if a
2417 breakpoint was reached, whenever that variable's value becomes 0.
2418 @item @var{VAR}
2419 @tab
2420 A onespot or twospot variable written by itself prints out the value of
2421 that variable.
2422 @item <@var{VAR}
2423 @tab
2424 @command{WRITEs IN} a new value for variable @var{VAR}.  Note that input
2425 must be in the normal @samp{ONE TWO THREE} format; input in any other
2426 format will cause error E579 (@pxref{E579}) and as that is a fatal
2427 error, the debugger and program it's debugging will end.
2428 @item *
2429 @tab
2430 Displays the license conditions under which @command{ick} is
2431 distributed.
2432 @item ?
2433 @tab
2434 Displays a summary of what each command does.  (@samp{@@} does the same
2435 thing.)
2436 @end multitable
2437
2438 While the code is executing (for instance, during a @samp{c}, @samp{k},
2439 @samp{o}, @samp{t} or @samp{u} command), it's possible to interrupt it
2440 with @kbd{@key{CTRL}-@key{C}} (on UNIX/Linux) or
2441 @kbd{@key{CTRL}-@key{BREAK}} (on Windows/DOS); this will cause the
2442 current command to finish running and the debugger prompt to come back
2443 up.
2444
2445 @ifset notsplit
2446 @partheading{PART II: THE @ical{} LANGUAGE}
2447 @end ifset
2448 @node Syntax
2449 @chapter Syntax
2450 @cindex syntax, INTERCAL
2451 @cindex INTERCAL, syntax
2452
2453 @ical{} programs consist of a list of statements.  Execution of a
2454 program starts with its first statement; generally speaking each
2455 statement runs after the previous statement, although many situations
2456 can change this.
2457
2458 Whitespace is generally insignificant in @ical{} programs; it cannot be
2459 added in the middle of a keyword (unless the keyword contains whitespace
2460 itself) or inside a decimal number, but it can be added more or less
2461 anywhere else, and it can be removed from anywhere in the program as
2462 well.
2463
2464 An @ical{} statement consists of an optional line label, a statement
2465 identifier, an optional execution chance, the statement itself
2466 (@pxref{Statements}), and optionally @code{ONCE} or @code{AGAIN}.
2467
2468 @menu
2469 * Princeton and Atari Syntax:: There are two syntaxes for @ical{}
2470 * Line Labels::                Allowing lines to be referred to
2471 * Statement Identifiers::      Marking the start of a statement
2472 * Execution Chance::           Statements that might not execute
2473 * ONCE and AGAIN::             Self-abstaining and self-reinstating statements
2474 @end menu
2475
2476 @node Princeton and Atari Syntax
2477 @section Princeton and Atari Syntax
2478 @cindex syntax, dialects
2479 @cindex dialects of syntax
2480 @cindex character sets
2481
2482 The history of @ical{} is plagued with multiple syntaxes and character
2483 sets.  The result has settled down with two versions of the syntax;
2484 the original Princeton syntax, and the Atari syntax (which is more
2485 suited to the operating systems of today).
2486
2487 @cindex syntax, Princeton
2488 @cindex Princeton syntax
2489 @subheading Princeton syntax
2490 @portability{some versions, version 0.18+, all versions, no}
2491
2492 The original @icst{} compiler was the Princeton compiler, which
2493 introduced what has become known as the Princeton syntax for @ical{};
2494 this is the syntax used in the original manual, for instance, and can
2495 be considered to be the `original' or `official' @ical{} syntax.  It
2496 is notable for containing various characters not found in some
2497 character sets; for instance, it writes the operator for mingle as a
2498 cent sign (known as `change').  The other operator that often causes
2499 problems is the bookworm operator @samp{V}, backspace, @samp{-}, which
2500 is used for exclusive-or; the backspace can cause problems on some
2501 systems (which was probably the original intention).  This syntax is
2502 also the default syntax in the @clcic{} compiler, which is the @i{de
2503 facto} standard for expanding the Princeton syntax to modern @ical{}
2504 features that are not found in @icst{}; however, it does not appear to
2505 have been used as the default syntax in any other compilers.
2506 Nowadays, there are other ways to write the required characters than
2507 using backspace; for instance, the cent sign appears in Latin-1 and
2508 UTF-8, and there are various characters that approximate bookworms
2509 (for instance, @clcic{} uses the Latin-1 yen symbol for this, which
2510 just to make things confusing, refers to a mingle in modern Atari
2511 syntax).
2512
2513 @cindex syntax, Atari
2514 @cindex Atari syntax
2515 @subheading Atari syntax
2516 @portability{some versions, yes, version 0.05+, yes}
2517
2518 The other main syntax is the Atari syntax, so called because it was
2519 originally used by the ``Atari implementation'' of @icst{}.  It is not
2520 clear why the implementation was given this name, because the authors
2521 of the implementation are not known; it is not clear whether it has
2522 any connection with Atari other than running on an Atari computer, for
2523 instance.  The syntax was designed to work better on ASCII-based
2524 systems, by avoiding the change character (although it can still be
2525 written as @samp{c}, backspace, @samp{/}, which the Atari compiler
2526 documentation claims that the Princeton compiler supported) in favour
2527 of a `big money' character (@samp{$}), and using the `what' (@samp{?})
2528 as an alternative character for exclusive-or.  This is the syntax that
2529 @cic{} and @jic{} have always used, and is the one most commonly used
2530 for communicating @ical{} programs on Usenet and other similar fora
2531 (where ASCII is one of the most reliable-to-send character sets).  It
2532 is also the syntax used for examples in this manual, for much the same
2533 reason.  The Atari syntax for constructs more modern than @icst{} is
2534 normally taken to be that used by the @cic{} compiler, because it is
2535 the only Atari-syntax-based compiler that contains non-@icst{}
2536 constructs that actually need their own notation.
2537
2538 @node Line Labels
2539 @section Line Labels
2540 @cindex line label
2541 @cindex line number
2542
2543 @portability{yes, all versions, all versions, all versions}
2544
2545 The first part of an @ical{} statement is a line label that specifies
2546 what its line number is.  This is optional; it's allowed to have a
2547 statement without a line number, although that prevents other commands
2548 referring to it by number.  Line numbers must be constants, and unique
2549 within the program.  However, they do not have to be in order; unlike
2550 some other languages with line numbers, a line with a higher number can
2551 come earlier in the program than a line with a lower number, and the
2552 numbers don't affect the order in which commands are executed.
2553
2554 A line label is a integer expressed in decimal within a wax/wane pair
2555 (@code{(} and @code{)}).  For instance, this is a valid line label:
2556
2557 @example
2558 (1000)
2559 @end example
2560
2561 Note that line numbers from 1000 to 1999 are used by the system library,
2562 so using them within your own programs may produce unexpected errors if
2563 the system library is included.  Apart from this, line numbers from 1 to
2564 65535 are allowed.
2565
2566 It has become reasonably customary for people writing @ical{} libraries
2567 to pick a range of 1000 line numbers (for instance, 3000 to 3999) and
2568 stick to that range for all line numbers used in the program (apart from
2569 when calling the system library), so if you want to write an @ical{}
2570 library, it may be a good idea to look at the existing libraries (in the
2571 @file{pit/lib} directory in the @cic{} distribution) and choose a range
2572 of numbers that nobody else has used.  If you aren't writing a library,
2573 it may be a good idea to avoid such number ranges (that is, use only
2574 line numbers below 1000 or very high numbers that are unlikely to be
2575 used by libraries in the future), so that you can easily add libraries
2576 to your program without renumbering in the future.
2577
2578 @node Statement Identifiers
2579 @section Statement Identifiers
2580 @cindex statement identifier
2581 @findex DO
2582 @findex PLEASE
2583 @findex NOT
2584 @findex N'T
2585 @cindex abstain, at program start
2586 @cindex reinstate, at program start
2587 @cindex initial abstention
2588 @cindex abstained state
2589 @cindex reinstated state
2590
2591 @portability{yes, all versions, all versions, all versions}
2592
2593 After the line label (if a statement has one) comes the statement
2594 identifier, which marks where the statement starts.  Either the label or
2595 the statement identifier, whichever one comes first, marks where the
2596 preceding statement finishes.
2597
2598 @anchor{DO}@anchor{PLEASE}
2599 The main statement identifier is @code{DO}.  It also has two synonyms,
2600 @code{PLEASE} and @code{PLEASE DO}; these synonyms are the 'polite'
2601 forms of statement identifiers.  Although the three identifiers have the
2602 same meaning, using either polite or non-polite identifiers too much can
2603 cause an error; the correct proportion is approximately 3 non-polite
2604 identifiers for every polite identifier used.  None of these identifiers
2605 actually does anything else apart from marking where the statement
2606 starts; they leave the statements in the default `reinstated' state.
2607
2608 @anchor{NOT}@anchor{N'T}
2609 Adding @code{NOT} or @code{N'T} to the end of any of these identifiers,
2610 to create a statement identifier such as @code{DO NOT} or @code{PLEASE
2611 DON'T}, also creates a valid statement identifier.  These differ in
2612 meanings from the previous set of identifiers, though; they cause the
2613 statement they precede to not be executed by default; that is, the
2614 command will be skipped during execution (this is known as the
2615 `abstained' state).  This applies even if the command in question is in
2616 fact a syntax error, thus causing this to be a useful method of writing
2617 comments.  One common idiom is to write code like this:
2618
2619 @example
2620 PLEASE NOTE: This is a comment.
2621 @end example
2622
2623 The statement identifier (@code{PLEASE NOT}) is the only part of this
2624 statement that is valid @ical{}; however, because the statement
2625 identifier is in the negated form that contains @code{NOT}, the syntax
2626 error won't be executed, and therefore this is a valid statement.  (In
2627 @ical{}, syntax errors happen at runtime, so a program containing a
2628 statement like @code{DOUBT THIS WILL WORK} will still compile, and will
2629 not end due to the syntax error unless that statement is actually
2630 executed.  @xref{E000}.)
2631
2632 The @code{ABSTAIN} and @code{REINSTATE} statements can override the
2633 @code{NOT} or otherwise on a statement identifier; see @ref{ABSTAIN}.
2634
2635 In backtracking programs, @code{MAYBE} is also a valid statement
2636 identifier; see @ref{MAYBE}.  It comes before the other keywords in the
2637 statement identifier, and an implicit @code{DO} is added if there wasn't
2638 one already in the statement identifier (so @code{MAYBE}, @code{MAYBE
2639 DO}, @code{MAYBE DON'T}, @code{MAYBE PLEASE}, and so on are all valid
2640 statement identifiers).
2641
2642 @node Execution Chance
2643 @section Execution Chance
2644 @cindex execution chance
2645 @cindex double-oh-seven
2646 @findex %
2647
2648 @portability{yes, all versions, version 0.02+, all versions}
2649
2650 It's possible to specify that a command should be run only a certain
2651 proportion of the time, at random.  This is a rarely used feature of
2652 @ical{}, although it is the only way to introduce randomness into a
2653 program.  (The @cic{} compiler approximates this with pseudorandomness.)
2654 An execution chance specification comes immediately after the statement
2655 identifier, but before the rest of the statement, and consists of a
2656 double-oh-seven (@code{%}) followed by an integer from 1 to 99
2657 inclusive, written in decimal; this gives the percentage chance of the
2658 statement running.  The execution chance only acts to prevent a
2659 statement running when it otherwise would have run; it cannot cause a
2660 statement that would otherwise not have run to run.  For instance, the
2661 statement @code{DO %40 WRITE OUT #1} has a 40% chance of writing out
2662 @samp{I}, but the statement @code{DON'T %40 WRITE OUT #1} has no chance
2663 of writing out @code{I} or anything else, because the @code{N'T}
2664 prevents it running and the double-oh-seven cannot override that.
2665
2666 @node ONCE and AGAIN
2667 @section ONCE and AGAIN
2668 @cindex ABSTAIN, self-abstaining
2669 @cindex REINSTATE, self-reinstating
2670 @cindex self-abstaining
2671 @cindex self-reinstating
2672 @findex ONCE
2673 @findex AGAIN
2674 @anchor{ONCE}@anchor{AGAIN}
2675
2676 @portability{no, version 0.25+, no, no}
2677
2678 The last part of a statement is an optional @code{ONCE} or @code{AGAIN}.
2679 @code{ONCE} specifies that the statement is self-abstaining or
2680 self-reinstating (this will be explained below); @code{AGAIN} specifies
2681 that the statement should behave like it has already self-reinstated or
2682 self-abstained.  Whether the behaviour is self-abstention or
2683 self-reinstatement depends on whether the statement was initially
2684 abstained or not; a @code{ONCE} on an initially reinstated statement or
2685 @code{AGAIN} on an initially abstained statement indicates a
2686 self-abstention, and a @code{ONCE} on an initially abstained statement
2687 or @code{AGAIN} on an initially reinstated statement indicates a
2688 self-reinstatement.
2689
2690 The first time a self-abstaining statement is encountered, it is
2691 executed as normal, but the statement is then abstained from and
2692 therefore will not run in future.  Likewise, the first time
2693 self-reinstating statement is encountered, it is not executed (as is
2694 normal for an abstained statement), but then becomes reinstated and will
2695 run in future.  In each of these cases, the @code{ONCE} effectively
2696 changes to an @code{AGAIN}; the @code{ONCE} only happens once, as might
2697 be expected.
2698
2699 @code{REINSTATING} a currently abstained self-abstaining statement or
2700 @code{ABSTAINING} (that is, with the @code{ABSTAIN} or @code{REINSTATE}
2701 commands) a currently reinstated self-reinstating statement causes the
2702 @code{AGAIN} on the statement to change back into a @code{ONCE}, so the
2703 statement will again self-abstain or self-reinstate.  Likewise,
2704 @code{REINSTATING} a currently abstained self-reinstating statement or
2705 @code{ABSTAINING} a currently reinstated self-abstaining statement
2706 causes its @code{ONCE} to turn into an @code{AGAIN}.
2707
2708 Historical note: @code{ONCE} was devised by Malcom Ryan as a method of
2709 allowing synchronisation between threads in a multithreaded program
2710 (@code{ONCE} is atomic with the statement it modifies, that is, there is
2711 no chance that threads will change between the statement and the
2712 @code{ONCE}).  @code{AGAIN} was added to Malcom Ryan's Threaded Intercal
2713 standard on the suggestion of Kyle Dean, as a method of adding extra
2714 flexibility (and to allow the @code{ONCE}s to happen multiple times,
2715 which is needed to implement some multithreaded algorithms).
2716
2717 @node Expressions
2718 @chapter Expressions
2719 @cindex expressions
2720
2721 Many @ical{} statements take expressions as arguments.  Expressions are
2722 made up out of operands and operators between them.  Note that there is
2723 no operator precedence in @ical{}; different compilers resolve
2724 ambiguities different ways, and some versions of some compilers
2725 (including the original @icst{} compiler) will cause error messages on
2726 compiling or executing an ambiguous expression, so it's safest to fully
2727 group each expression.
2728
2729 @menu
2730 * Constants and Variables::      The basic operands that make up expressions
2731 * Grouping Rules::               How to specify grouping in expressions
2732 * Operators::                    Joining operands into more complex expressions
2733 @end menu
2734
2735 @node Constants and Variables
2736 @section Constants and Variables
2737 @cindex constant
2738 @cindex variable
2739 @cindex mesh
2740 @cindex onespot
2741 @cindex twospot
2742 @cindex tail
2743 @cindex hybrid
2744 @findex #
2745 @findex .
2746 @findex :
2747 @findex ,
2748 @findex ;
2749
2750 @portability{yes, all versions, all versions, all versions}
2751
2752 The basic operands in @ical{} are constants and variables.  These
2753 together make up what in other languages are known as `lvalues', that
2754 is, operands to which values can be assigned.  (Constants can also be
2755 lvalues in @ical{}, but by default @cic{} turns this off because it
2756 carries an efficiency penalty and can be confusing; this can be turned
2757 on with the @option{-v} option (@pxref{-v}).)
2758
2759 Constants can have any integer value from 0 to 65535 inclusive; higher
2760 values (up to 4294967295) can be generated in programs, but cannot be
2761 specified literally as constants.  (The usual way to work around this
2762 limitation is to interleave two constants together; see @ref{Mingle}.) A
2763 constant is written as a mesh (@code{#}) followed by a number in
2764 decimal.  At the start of the program, all constants have the same value
2765 as the number that identifies them; for instance, @code{#100} has 100 as
2766 its value, and it's strongly advised not to change the value of a
2767 constant during the execution of a program.
2768
2769 There are four types of variable: 16-bit and 32-bit unsigned integers,
2770 and arrays of 16-bit and 32-bit unsigned integers.  These are
2771 represented with a spot, twospot, tail, and hybrid (@code{.}, @code{:},
2772 @code{,}, and @code{;}) respectively.  For this reason, integers within
2773 the range 0 to 65535 inclusive are known as `onespot numbers', and
2774 integers within the range 0 to 4294967295 inclusive are known as
2775 `twospot numbers'; variables with those ranges are known as onespot and
2776 twospot variables.  (Note that arrays did not work in @cic{} before
2777 version 0.7.)
2778
2779 Variables are represented with a character representing their data type,
2780 followed by an integer from 1 to 65535 inclusive, written in decimal.
2781 Non-array variables don't need to be declared before they are used; they
2782 automatically exist in any program that uses them.  For instance,
2783 @code{.1} and @code{.001} are the same variable, onespot number 1.
2784 Array variables need to be dimensioned before they are used, by
2785 assigning dimensions to them; see @ref{Calculate}.
2786
2787 @node Grouping Rules
2788 @section Grouping Rules
2789 @cindex grouping rules
2790 @cindex positional precedence
2791 @cindex spark
2792 @cindex rabbit-ears
2793 @cindex ears
2794 @findex '
2795 @findex "
2796
2797 Because there are no operator precedences in @ical{}, there are various
2798 solutions to specifying what precedences actually are.
2799
2800 @table @asis
2801
2802 @item The portable solution
2803
2804 All known versions of @ical{} accept the @icst{} grouping rules.  These
2805 state that it's possible to specify that an operator takes precedence by
2806 grouping it inside sparks (@code{'}) or rabbit-ears (@code{"}), the same
2807 way as wax/wane pairs (parentheses) are used in other programming
2808 languages.  @icst{} and earlier @cic{} versions demanded that
2809 expressions were grouped fully like this, and this practice is still
2810 recommended because it leads to portable programs and is easier to
2811 understand.  Whether sparks or rabbit-ears (often called just `ears' for
2812 short) are used normally doesn't matter, and programmers can use one or
2813 the other for clarity or for aesthetic appeal.  (One common technique is
2814 to use just sparks at the outermost level of grouping, just ears at the
2815 next level, just sparks at the next level, and so on; but expressions
2816 like @code{''#1~#2'~"#3~#4"'~#5} are completely unambiguous, at least to
2817 the compiler.)
2818
2819 There are, however, some complicated situations involving array
2820 subscripting where it is necessary to use sparks and ears at alternate
2821 levels, if you want to write a portable program.  This limitation is in
2822 @cic{} to simplify the parsing process; @icst{} has the same limitation,
2823 probably for the same reason.  Compare these two statements:
2824
2825 @example
2826 DO .1 <- ,3SUB",2SUB.1".2
2827 DO .1 <- ,3SUB",2SUB.1".2~.3"".4
2828 @end example
2829
2830 The problem is that in the first statement, the ears close a group, and
2831 in the second statement, the ears open a group, and it's impossible to
2832 tell the difference without unlimited lookahead in the expression.
2833 Therefore, in similar situations (to be precise, in situations where a
2834 group is opened inside an array subscript), it's necessary to use the
2835 other grouping character to the one that opened the current group if you
2836 want a portable program.
2837
2838 One final comment about sparks and rabbit-ears; if the next character
2839 in the program is a spot, as often happens because onespot variables
2840 are common choices for operands, a spark and the following spot can be
2841 combined into a wow (@code{!}).  Unfortunately, the rabbit-ear/spot
2842 combination has no one-character equivalent in any of the character
2843 sets that @cic{} accepts as input (UTF-8, Latin-1, and ASCII-7) as
2844 none of these contain the rabbit character, although the Hollerith
2845 input format that @clcic{} can use does.
2846
2847 @item Positional precedences: @clcic{} rules
2848
2849 The precedence rules used by @clcic{} for grouping when full grouping
2850 isn't used are simple to explain: the largest part of the input that
2851 looks like an expression is taken to be that expression.  The main
2852 practical upshot of this is that binary operators right-associate; that
2853 is, @code{.1~.2~.3} is equivalent to @code{.1~'.2~.3'}.  @cic{} versions
2854 0.26 and later also right-associate binary operators so as to produce
2855 the same results as @clcic{} rules in this situation, but as nobody has
2856 yet tried to work out what the other implications of @clcic{} rules are
2857 they are not emulated in @cic{}, except possibly by chance.
2858
2859 @ianchor Prefix and infix unary operators
2860 @cindex unary operator, prefix
2861 @cindex unary operator, infix
2862
2863 In @icst{} and versions of @cic{} before 0.26, unary operators were
2864 always in the `infix' position.  (If you're confused about how you can
2865 have an infix unary operator: they go one character inside a group that
2866 they apply to, or one character after the start of a constant or
2867 variable representation; so for instance, to portably apply the unary
2868 operator @code{&} to the variable @code{:1}, write @code{:&1}, and to
2869 portably apply it to the expression @code{'.1~.2'}, write
2870 @code{'&.1~.2'}.)  @clcic{}, and versions of @cic{} from 0.26 onwards,
2871 allow the `prefix' position of a unary operator, which is just before
2872 whatever it applies to (as in @code{&:1}).  This leads to ambiguities as
2873 to whether an operator is prefix or infix.  The portable solution is, of
2874 course, to use only infix operators and fully group everything, but when
2875 writing for recent versions of @cic{}, it's possible to rely on its
2876 grouping rule, which is: unary operators are interpreted as infix where
2877 possible, but at most one infix operator is allowed to apply to each
2878 variable, constant, or group, and infix operators can't apply to
2879 anything else.  So for instance, the @cic{} @code{'&&&.1~.2'} is
2880 equivalent to the portable @code{'&"&.&1"~.2'} (or the more readable
2881 version of this, @code{"&'"&.&1"~.2'"}, which is also portable).  If
2882 these rules are counter-intuitive to you, remember that this is @ical{}
2883 we're talking about; note also that this rule is unique to @cic{}, at
2884 least at the time of writing, and in particular @clcic{} is likely to
2885 interpret this expression differently.
2886
2887 @end table
2888
2889 @node Operators
2890 @section Operators
2891 @cindex operator
2892
2893 Operators are used to operate on operands, to produce more complicated
2894 expressions that actually calculate something rather than just fetch
2895 information from memory.  There are two types of operators, unary and
2896 binary operators, which operate on one and two arguments respectively.
2897 Binary operators are always written between their two operands; to
2898 portably write a unary operator, it should be in the `infix' position,
2899 one character after the start of its operand; see @ref{Prefix and infix
2900 unary operators} for the full details of how to write unary operators
2901 portably, and how else you can use them if you aren't aiming for
2902 portability.  This section only describes @icst{} operators; many
2903 @ical{} extensions add their own operators.
2904
2905 @menu
2906 * Mingle::                   Interleaving bits in two operands
2907 * Select::                   Selecting from one operand according to another
2908 * Unary Binary Logic::       Binary logic on adjacent bits of an operand
2909 * Array Subscript::          Selecting elements of arrays
2910 @end menu
2911
2912 @node Mingle
2913 @subsection Mingle
2914 @cindex mingle
2915 @cindex interleave
2916 @findex $
2917
2918 @portability {yes, all versions, all versions, all versions}
2919
2920 Mingle, or interleave, is one of the two binary operators in @icst{}.
2921 However, different @ical{} compilers represent it in different ways, so
2922 it is impossible to write a mingle in a program completely portably,
2923 because it differs between Princeton and Atari syntax, and worse, the
2924 sequence of character codes needed to represent it in each syntax has
2925 varied from compiler to compiler.
2926
2927 The original @icst{} compiler (the Princeton compiler) used the
2928 'change' (cent) character for a mingle, represented as @code{c},
2929 backspace, @code{/}.  (By the way, this is still the most portable way
2930 to write a mingle; both @cic{} and @clcic{} accept it, at least if a
2931 lowercase @code{c} is used, the Atari compiler accepted it, and its
2932 documentation claimed that the Princeton compiler also accepted it;
2933 @clcic{} also accepts a capital @code{C} before the backspace and
2934 @code{/}, and allows @code{|} rather than @code{/}.)  The Atari
2935 compiler, another @icst{} compiler, used a 'big money' character
2936 (@code{$}) as the mingle character; this character is also the only
2937 one accepted for mingle by the @jic{} compiler.  @cic{} originally
2938 also used the @code{$} character for mingle, and this character is the
2939 one most commonly seen in existing @cic{} programs, and most often
2940 used when giving examples of @ical{} on Usenet, because it exists in
2941 the ASCII-7 character set, and because it doesn't contain control
2942 characters.  From version 0.18 of @cic{} onwards, various other units
2943 of currency (change, quid, and zlotnik if Latin-1 is used as the
2944 input, and euro if Latin-9 is used as the input) are accepted; from
2945 version 0.20 onwards, in addition to the Latin-1 characters, all the
2946 currency symbols in Unicode are accepted if UTF-8 is used as the input
2947 format.  @clcic{} has always used the change character (either the
2948 Latin-1 version or the version that contains a backspace) for mingle.
2949 In this manual, mingle will be represented as @code{$}, but it's
2950 important to bear in mind that this character is not the most portable
2951 choice.
2952
2953 The mingle operator should be applied to two operands or expressions.
2954 To be portable, the operands must both be onespot expressions, that is
2955 expressions which have a 16-bit result; @cic{} relaxes this rule
2956 slightly and only requires that the result be in the onespot range.
2957 (This is because the data type of a select operator's value is meant to
2958 be determined at runtime; @cic{} determines all data types at compile
2959 time, so has to guess a 32-bit result for a select with a 32-bit type as
2960 its right operand even when the result might actually turn out to be of
2961 a 16-bit type, and so this behaviour prevents an error when a select
2962 operation returns a value with a 16-bit data type and is used as an
2963 argument to a mingle.)  The result is a 32-bit value (that is, it is of a
2964 32-bit data type, even if its value fits into the onespot range), which
2965 consists of bits alternated from the two arguments; to be precise, its
2966 most significant bit is the most significant bit of its first argument,
2967 its second most significant bit is the most significant bit of its
2968 second argument, its third most significant bit is the second most
2969 significant bit of its first argument, and so on until its least
2970 significant bit, which is the least significant bit of its second
2971 argument.
2972
2973 One of the most common uses of interleaving is to create a constant with
2974 a value greater than 65535; for instance, 65536 is @code{#0$#256}.  It
2975 is also commonly used in expressions that need to produce 32-bit
2976 results; except in some simple cases, this is usually coded by
2977 calculating separately the odd-numbered and even-numbered bits of the
2978 result, and mingling them together at the end.  It is also used in
2979 expressions that need to left-shift values or perform similar
2980 value-increasing operations, as none of the other operators can easily
2981 do this; and mingle results are commonly used as the argument to unary
2982 binary logic operators, because this causes them to behave more like the
2983 binary logic operators found in some other languages.
2984
2985 @node Select
2986 @subsection Select
2987
2988 @portability{yes, all versions, all versions, all versions}
2989
2990 The select operator is one of the two binary operators in @icst{};
2991 unlike mingle, every known implementation of @ical{} ever has used the
2992 sqiggle character (@code{~}) as the representation of the select
2993 operator, meaning that writing it portably is easy.
2994
2995 The select operator takes two arguments, which can be of either
2996 datatype (that is, 16- or 32-bit).  It returns a value made by
2997 selecting certain bits of its first operand indicated by the second
2998 operand, and right-justifying them.  What it does is that it ignores
2999 all the bits of the first operand where the second operand has a 0 as
3000 the corresponding bit, that is, deletes them from a copy of the
3001 operand's value; the bits that are left are squashed together towards
3002 the least-significant end of the number, and the result is filled with
3003 0s to make it up to 16 or 32 bits.  (In @icst{} the minimum multiple
3004 of 16 bits possible that the result fits into is chosen, although if
3005 :1 has the value 131061 (in hex, 1FFFF) the expression @code{#21~:1}
3006 produces a 32-bit result because 17 bits were selected, even though
3007 many of the leading bits were zeros; in @cic{} the data type of the
3008 result is the same as of the right operand of the select, so that it
3009 can be determined at compile time, and so using a unary binary logic
3010 operator on the result of select when the right operand has a 32-bit
3011 type is nonportable and not recommended.)  As an example,
3012 @code{#21~:1} produces 21 as its result if :1 has the value 131061, 10
3013 as its result if :1 has the value 30 (1E in hex; the least significant
3014 bit of 21 is removed because it corresponds to a 0 in :1), and 7 as
3015 its result if :1 has the value 21 (because three bits in 21 are set,
3016 and those three bits from 21 are therefore selected by 21).
3017
3018 Select is used for right-shifts, to select every second bit from a
3019 number (either to produce what will eventually become an argument to
3020 mingle, or to interpret the result of a unary binary logic operator, or
3021 occasionally both), to test if a number is zero or not (by selecting it
3022 from itself and selecting 1 from the result), in some cases as a limited
3023 version of bitwise-and (that only works if the right operand is 1 less
3024 than a power of 2), and for many other purposes.
3025
3026 @node Unary Binary Logic
3027 @subsection Unary Binary Logic
3028 @cindex unary binary logic
3029 @cindex and
3030 @cindex or
3031 @cindex xor
3032 @cindex exor
3033 @cindex exclusive or<