\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename ick.info
@set VERSION 0.29
@set VERSIONDASH 0-29
@settitle C-INTERCAL @value{VERSION} Revamped Instruction Manual
@paragraphindent 0
@documentlanguage en
@documentencoding ISO-8859-1

@c Command line option index.
@defcodeindex op
@c Error index
@defindex er
@c Commands and language features are in the predefined fnindex.
@c Things generally are in the predefined cpindex.

@c Combining indices.
@syncodeindex fn cp
@syncodeindex op cp
@synindex er cp

@c Adding to the main documentation tree.
@dircategory INTERCAL
@direntry
* C-INTERCAL: (ick).                 The C-INTERCAL language and compiler.
* ick: (ick) Invoking ick.           Invoking the C-INTERCAL compiler.
* convickt: (ick) convickt.          The command-line character set converter.
@end direntry

@c Some macros to ease writing and updating. (The VERSION is set above because
@c it's needed to set the title.)
@macro cic{}
@abbr{C-INTERCAL}
@end macro
@macro clcic{}
@abbr{CLC-INTERCAL}
@end macro
@macro icst{}
@abbr{INTERCAL-72}
@end macro
@macro jic{}
@abbr{J-INTERCAL}
@end macro
@macro ical{}
@acronym{INTERCAL}
@end macro

@c Part headings for unsplit output
@macro partheading{arg}
@html
<!--
@end html
@unnumbered \arg\
@html
--><h1>\arg\</h1>
@end html
@c
@end macro
@iftex
@set notsplit
@end iftex

@c 'Portability' boxes
@macro portability{st,c,clc,j}
@multitable @columnfractions .23 .23 .23 .23
@headitem @icst{} @tab @cic{} @tab @clcic{} @tab @jic{}
@item \st\ @tab \c\ @tab \clc\ @tab \j\
@end multitable
@c
@end macro

@c Generating items and anchors together is also helpful.
@macro ianchor{arg}
@item \arg\
@anchor{\arg\}
@c
@end macro
@macro ianchorc{arg}
@item \arg\
@anchor{\arg\+}
@c
@end macro
@macro ieanchor{arg}
@item \arg\
@anchor{\arg\}
@erindex \arg\
@c
@end macro
@macro ianchorpm{arg}
@item +\arg\
@itemx -\arg\
@anchor{+\arg\}
@anchor{-\arg\}
@c
@end macro

@c Some fixes for HTML.
@ifhtml
@c Examples are styled in CSS; don't do it with hardcoded whitespace!
@exampleindent 0
@end ifhtml
@c %**end of header

@copying
This manual is for @cic{} version @value{VERSION}.  It does not replace
the old groff manual, nor is it designed to be read in conjunction with
it; instead, it serves a different purpose, of providing information
useful to users of @cic{} (unlike the other manual, it is not derived
from the original @icst{} manual).

Copyright @copyright{} 2007 Alex Smith.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License.''

@end quotation
@end copying

@titlepage
@ifset notsplit
@title C-INTERCAL Revamped Instruction Manual
@subtitle (this version distributed with version @value{VERSION} of C-INTERCAL)

@page
@vskip 0pt plus 1filll
@insertcopying

@end ifset
@end titlepage

@ifset notsplit
@contents
@end ifset

@ifnottex
@node Top
@top C-INTERCAL @value{VERSION}

@insertcopying

@menu
* About this manual::               What is covered in this manual

The @cic{} compiler
* Installation::                    How to install @cic{}
* Invoking ick::                    Options to give to the compiler ick
* Errors and Warnings::             Error messages, and what to do about them
* The yuk debugger::                How to use the runtime debugger

Basic @ical{} features
* Syntax::                          Holding statements together
* Expressions::                     Operators, operands, and grouping
* Statements::                      What an @ical{} statement can do
* System Library::                  Pre-existing @ical{} routines

@ical{} dialects and extensions
* TriINTERCAL::                     @ical{} in non-binary bases
* Multithreading and Backtracking:: Running @ical{} programs in parallel
* Operand Overloading::             Where one expression stands for another
* PIC-INTERCAL::                    @ical{} on embedded systems
* CREATE::                          Creating new syntax at runtime
* External Calls::                  Linking @ical{} with other languages
* Differences to Other Compilers::  @cic{} vs. @clcic{}

Appendices and indices
* Character Sets::                  A list of character sets used by @ical{}
* convickt::                        The command-line character set converter
* Optimizer Idiom Language::        The syntax to specify optimizer idioms
* Copying::                         License information for the code and manual
* Main Index::                      An index of all the pages in this manual

@end menu
@end ifnottex

@node About this manual
@unnumbered About this manual
@cindex About this manual

This is the Revamped Instruction Manual for @cic{} (this version is
distributed with @cic{} version @value{VERSION}).  It is divided into
four parts.

The first part is about the @cic{} compiler @command{ick}, and how to
use it. It covers installing the compiler, using the compiler, what
error and warning messages are produced by the compiler, and some
information on how to use the debugger.

The second part is about the core @ical{} language, invented in 1972,
and some other commands since then which don't feel like they're
extensions.  (This is a pretty arbitrary distinction, but people who
write the documentation are entitled to arbitrary distinctions.  The
manual's licensed under a license that lets you change it
(@pxref{Copying}), so if you disagree you can move the commands from
section to section yourself.)  Mostly only commands that are
implemented in @cic{} are covered here (if you're interested in the
other commands implemented in other compilers, read @clcic{}'s
documentation).  However, a comprehensive guide to portability of
these commands between @cic{} and other @ical{} compilers is given.

The third part covers the @ical{} extensions and dialects that are
implemented by @cic{}, such as TriINTERCAL and Threaded @ical{}.
Again, extensions and dialects not implemented have been mostly left
out.

The final part contains appendices (which were known as `tonsils' in
the original @ical{} manual), such as character sets used by @ical{},
programs other than @command{ick} in the @cic{} distribution,
information on how to read and update the list of optimizer idioms
used by the compiler, and the copyright.

@ifset notsplit
@partheading{PART I: THE @cic{} COMPILER}
@end ifset
@node Installation
@chapter Installation
@cindex installation
@cindex @command{ick}, installing

The @cic{} distribution is distributed in source code form; this means
that before using it, you first have to compile it.  Don't worry: if you
have the right software, it's not at all difficult.  Most Linux-based
and UNIX-based computers are likely to have the software needed already;
the software needed to compile source-distributed packages is also
readily available for free for other operating systems.  The following
instructions will help you install the distribution in a method
appropriate for your system.

(If you happen to be using Debian or Ubuntu, you can also obtain and
install binaries with the command @samp{sudo apt-get install
intercal}, making the rest of this chapter redundant.  If you do this,
use Debian's bug tracker to report bugs, rather than reporting them
directly to the maintainers.)

@menu
* Obtaining::            How to get a @cic{} distribution to install
* Unpacking::            What to do with the distribution file
* Simple Installation::  How to install things the easy way
* Uninstalling::         If you don't want to use the software
* Reporting Bugs::       If it doesn't work or you know how to fix it
* Distributing::         How to make your own @cic{} distribution
@end menu

@node Obtaining
@section Obtaining
@cindex obtaining C-INTERCAL
@cindex C-INTERCAL, obtaining a copy

@cic{} distributions have been stored in many different places over
time; it can sometimes be hard to make sure that you are finding the
most recent version.  In order to make sure that you have the most
recent version, the easiest way is to look at the
@uref{news:alt.lang.intercal,,alt.lang.intercal newsgroup}; all releases
of the @cic{} compiler ought to be announced there.  (If you are
interested in what other @ical{} compilers are available, it may also be
worth looking there.)  If you don't have access to a newsreader, your
newsreader doesn't cover that newsgroup, or the distance between
releases has been too large for your news server to keep the message,
it's likely that you can find the announcement in an archive on the
World Wide Web; at the time of writing (2007), the archives of the
newsgroup are stored by @uref{http://groups.google.com,Google Groups},
and a search for @samp{alt.lang.intercal} there should tell you where to
find a copy.

If you're looking for the latest version, note that the number after the
dot represents the major version number; you want to maximise this in
favour of the number before the dot, which is the bugfix level within a
major version.  (Major versions are released as version 0.whatever; if a
new version comes out that fixes bugs but adds no new features, nowadays
its number will be of the form 1.whatever, with the same major number.
This has not always been the case, though.)

@node Unpacking
@section Unpacking
@cindex C-INTERCAL, unzipping
@cindex C-INTERCAL, unpacking
@cindex unzipping C-INTERCAL
@cindex unpacking C-INTERCAL
@cindex ick-@value{VERSIONDASH}.pax.*

@cic{} is distributed in compressed pax format; for instance, you may
find as a @samp{.pax.lzma} file if you have the @command{unlzma}
decompression program (this is advised, as it's the smallest);
@samp{.pax.bz2} is larger and @samp{.pax.gz} is larger still.  Most
computers can decompress files in this format, even if they don't
realise it, because pax is forwards-compatible with tar; try renaming
the extension from @samp{.pax} to @samp{.tar} after decompressing to
see if you have a progam that can decompress it.  (If you're wondering
why such an apparently non-standard format is being used, this is is
actually a case where @cic{} is being perfectly nonstandard by
conforming to the standards; tar is no longer specified by POSIX, and
pax is its replacement. It's just that pax never really caught on.)

It doesn't matter where you extract the distribution file to: it's best
if you don't put it anywhere special.  If you aren't an administrator,
you should extract the file to somewhere in your home directory (Linux
or UNIX-like systems) or to your My Documents directory (recent versions
of Windows; if you're using an older version, then you @emph{are} an
administrator, or at least have the same privileges, and can extract it
anywhere).  Some commands that you might use to extract it:

@table @asis

@item Generic UNIX/Linux

@example
unlzma ick-@value{VERSIONDASH}.pax.lzma
tar xvf ick-@value{VERSIONDASH}.pax
@end example
@i{or}
@example
bunzip2 ick-@value{VERSIONDASH}.pax.bz2
tar xvf ick-@value{VERSIONDASH}.pax
@end example
@i{or}
@example
gunzip ick-@value{VERSIONDASH}.pax.gz
tar xvf ick-@value{VERSIONDASH}.pax
@end example

On most UNIX-based and Linux-based systems, @command{tar} will be
available to unpack the installation files once they've been
uncompressed with @command{gunzip}.  (I've heard that some BSD systems
have @command{pax} itself to decompress the files, although have not
been able to verify this; some Linux distributions also have
@command{pax} in their package managers.  Both tar and pax should work
fine, though.)  @command{gunzip} is also likely to be available (and
@command{bunzip2} and @command{unlzma} are less likely, but use those
versions if you have them to save on your bandwidth); if it isn't, you
will need to download a copy from the Internet.

@item Using GNU tar

@example
tar xzvf ick-@value{VERSIONDASH}.pax.gz
@end example
@i{or}
@example
tar xqvf ick-@value{VERSIONDASH}.pax.bz2
@end example

If you are using the GNU version of @command{tar} (which is very likely
on Linux), you can combine the two steps into one as shown here,
except when using the lzma-compressed version.

@item Using DJGPP

@example
djtar -x ick-@value{VERSIONDASH}.pax.gz
@end example

On a DOS system, you will have to install DJGPP anyway to be able to
compile the distribution, and once you've done that you will be able
to use DJGPP's decompressing and unpacking utility to extract the
files needed to install the distribution.  (You will need to type this
at the command line; on Windows 95 and later, try choosing Run...@:
from the start menu then typing @command{cmd} (or @command{command} if
that fails) in the dialog box that opens to get a command prompt,
which you can exit by typing @command{exit}.  After typing any command
at a command line, press @key{RET} to tell the shell to execute that
command.)

@item On Windows

If you're running a Windows system, you could always try
double-clicking on the ick-@value{VERSIONDASH}.pax.gz file; probably
renaming it to have the extension @samp{.tgz} is likely to give the
best results.  It's quite possible that you'll have a program
installed that's capable of decompressing and unpacking it.
Unfortunately, I can't guess what program that might be, so I can't
give you any instructions for using it.

@end table

Whatever method you use, you should end up with a directory created
called @file{ick-@value{VERSION}}; this is your main installation
directory where all the processing done by the installation will be
carried out.  You will need to have that directory as the current
directory during install (at the command prompt in all the operating
systems I know, you can set the current directory by typing @command{cd
ick-@value{VERSION}}).

@node Simple Installation
@section Simple Installation
@cindex installation, simple
@cindex simple installation
@findex config.sh
@findex make
@findex make install
@cindex compiling, @command{ick} itself
@cindex installation, via autoconf and make
@cindex configuring

There are scripts included in the distribution to automate the process
of installing, in various ways.  The simplest method of installing is to
use the following routine:

@enumerate

@item
Configure @cic{}, by running @command{configure}.  Although building
in the distribution directory works; it is recommended that you build
elsewhere; create a directory to build in (using @command{mkdir} on
most operating systems), then run @command{configure} from inside that
directory (for instance, you could do this from inside the main
installation directory:
@example
mkdir build
cd build
../configure
@end example
to build in a subdirectory of the distribution called ``build'').  You
also specify where you want the files to be installed at this stage;
the default of @samp{/usr/local} is good for many people, but you may
want to install elsewhere (in particular, if you want to test out
C-INTERCAL without installing it, create a new directory somewhere you
own and specify that as the place to install it, so the install will
actually just copy the files into the right structure for use instead
of installing them).  To specify a location, give the option
@option{--prefix=@var{location}} to configure; for instance,
@command{configure --prefix=/usr} would install in /usr.

@item
Compile the source code, with the command @command{make}.  The
Makefile will be set up for your version of @command{make}, and to
automatically recompile only what needs compiling (it will even
recompile the build system if you change that).

@item
Optionally, create libraries from third-party interpreters to add
support for more languages to the @cic{} external calls system; see
@ref{Creating the Funge-98 Library}.  (This step can be skipped; you
can also do it later, but if you do so you need to run the next step
again.)

@item
Install the executables, help files, include files, and libraries,
using @command{make install}.  (This is the only step that needs
root/administrator permissions; so on a system that uses sudo to
elevate permissions, for instance, write it as @command{sudo make
install} if you're installing into a directory that you can't write to
as a non-administrative user.)

@end enumerate

On all systems, it's worth just trying this to see if it works.  This
requires a lot of software on your computer to work, but all of it is
standard on Linux and UNIX systems.  The first command is a
shell-script which will analyse your system and set settings
accordingly; it will explain what it's doing and what settings it
detected, and create several files in the installation directory to
record its results.  (This is a configure script produced by the GNU
autoconf (configure); its autoconf source code is available in the
file @file{configure.ac}.)  The second command actually compiles the
source code to produce binaries; this takes the longest of any of the
steps.  You will see all the commands that it's running as it runs
them.  The third command will copy the files it's compiled to
appropriate shared locations on your system so that anyone on the
system can just use @command{ick}.

There may be various factors that prevent this simple installation
method working.  On a system not based on UNIX or Linux, you may find
that you don't have some of the software required to run this (for
instance, you may be missing the shell @command{sh}, and don't have
the shell @command{bash} which can emulate it, and so can't run
@command{sh config.sh} that depends on one of those shells being
available) and so this method won't work for you.  In such cases, one
solution may be to install all the software required; the GNU project
has a version of all the commands required, for instance, and there
may be ports available for your operating system.  However, the only
software absolutely required is a C compiler (@cic{} was designed to
work with @command{gcc} and is tested mostly with that compiler, but
in theory it should work with other C compilers too, and this is
tested on occasion) and the associated software needed to compile C
files to object files and executables, combine object files into
libraries, etc.

Another possibility that might stop this process working is if your
version of the relevant software is incompatible with the GNU versions
that were used for testing.  For instance, I have come across
proprietary versions of @command{lex} that need directives in the source
file to say in advance how much memory the lexer-generator needs to
allocate.  In such cases, pay attention to the error messages you're
getting; normally they will suggest trivial modifications to the source
files that will cause the compilation to work again.

@cindex installation, Debian
@cindex installation, Ubuntu
@cindex Debian
@cindex Ubuntu
Some Linux and UNIX systems (notably Debian and Ubuntu) don't have the
required files for compilation installed by default.  To install them,
just download and install the required packages: for Ubuntu at the
time of writing, they are @samp{binutils}, @samp{cpp}, @samp{gcc},
@samp{libc6-dev}, @samp{make} to compile @cic{}, and if you want to
modify it, you may also need @samp{autoconf}, @samp{automake},
@samp{bison}, and @samp{flex}.  For debugging help, you may also want
@samp{gdb}, and to recompile the documentation, you may need
@samp{groff}, @samp{tetex-bin}, @samp{texinfo}, and @samp{tidy}.  Of
course, if @ical{} ever (the author of this sentence was going to
write something like ``becomes popular, someone will probably package
up a compiler for Debian or Ubuntu anyway'', but at that point on a
whim did an Ubuntu package search for 'intercal' and actually came up
with two results, which look suspiciously like @cic{} and @clcic{},
later confirming this.  The author was vaguely aware that there was a
@clcic{} package floating around, but was unaware of the @cic{}
package, and as a result was too surprised to finish the sentence.)

If you're trying to do something unusual, you probably want to set some
of the settings yourself rather than letting the compilation process
guess everything.  In this case, use @command{configure --help} to
view the options that you can set on @command{configure}; there's a wide
range of settings that you can set available there, and one of them may
be what you want.

@node Uninstalling
@section Uninstalling
@cindex uninstalling
@cindex @command{ick}, uninstalling

It may happen that you decide to uninstall @cic{} after installing it;
this may be useful if you want to test the installation system, or
change the location you install programs, or for some reason you don't
want it on your computer.  It's worth uninstalling just before you
install a new version of @cic{} because this will save some disk space;
you cannot install two versions of @cic{} at once (at least, not in
the same directory; but you can change the --prefix of one of the
installations to get two versions at once).

If you installed @cic{} using @command{make install}, you can
uninstall it by using @command{make uninstall} from the installation
directory, assuming that it still exists.  If you can't use that
method for some reason, you can uninstall it by deleting the files
@file{ick} and @file{convickt} where your computer installs binaries
(with an extension like @samp{.exe} added if that's usual for binaries
on your operating system), @file{libick.a}, @file{libickmt.a},
@file{libickec.a}, and @file{libyuk.a} where your computer installs
libraries, and the subdirectories @file{ick-@value{VERSION}} in the
places where your computer installs data files and include files, and
their contents.

You can go further than uninstalling.  Running @command{make clean}
will delete any files created by compilation; @command{make distclean}
will delete those files, and also any files created by configuring.
It's probably a wise idea to uninstall before doing a distclean,
though, as otherwise information needed to uninstall will be deleted,
as that information is generated by @command{configure}.

@node Reporting Bugs
@section Reporting Bugs
@cindex bugs, reporting
@cindex reporting bugs
@cindex patches, submitting
@cindex submitting patches

If you can't get @cic{} to install at all, or something goes wrong when
you're using it, reporting a bug is probably a good idea.  (This is
still important even if you figure out how to fix it, and the
information isn't in the manual, because the fix can be added to the
source code if possible, or at least to the manual, to benefit future
users.)  For general help, you may want to post to the
@uref{news:alt.lang.intercal,,alt.lang.intercal} news group; to report
a bug or submit a patch, email the person who released the most recent
@cic{} version (which you can determine by looking at that newsgroup).

If you do find a bug (either the compiler not behaving in the way you'd
expect, or if you find a way to cause E778 (@pxref{E778}) without
modifying the source code), it helps a lot if you can submit a bug
report explaining what causes it.  If you're not sure, say that; it
helps if you give examples of input, command line options, etc.@: that
cause the bug.  There are several debug options (@pxref{Debug Options})
that you can use to help pin down a bug if you're interested in trying
to solve the problem yourself; looking at the output C code can also
help pin down a bug if the compiler gets that far.

Information that should be given in a bug report is what you expect to
happen, what actually happens, what input and command line options you
gave to the compiler, what operating system you're using, any ideas you
might have as to what the problem is, and any appropriate debug traces
(for instance, @option{-H} (@pxref{-H+,,-H}) output if you think the bug
is in the optimizer).  Core dumps aren't portable between systems, so
don't send those; however, if you're getting an internal error and can
dump core with @option{-U} (@pxref{-U+,,-U}), it helps if you can load a
debugger (such as @command{gdb}) on the core dump, use the debugger to
produce a backtrace, and send that backtrace.

If you figure out how to solve the bug yourself, and want to submit the
patches to help other users (this also carries the advantage that your
patches will then be maintained along with the rest of the distribution,
and that you won't have to reapply them every time you upgrade to a
newer version of @cic{}), you must first agree to license your code
under the same license as the code that surrounds it (normally, that's
the GNU General Public License, but if you submit a patch to a file with
a different license, like this manual (yes, documentation patches are
useful too), you must agree to that license).  You will be credited for
the patch in the source code unless you specifically ask not to be or
you don't give your name (in both these cases, you must license the code
to the public domain so that it can be incorporated without the
attribution requirement).  Preferably, patches should be submitted in
the format created by the command @command{diff -u}; this command is
likely to be available on UNIX and Linux systems and versions are also
available for DOS and Windows (including a DJGPP port of the GNU
version).  If you can't manage that, just submit your new code with
enough lines of old code around it to show where it's meant to go, and a
description of approximately where in the file it was.  Patches should
be submitted by email to the person who most recently released a version
of @cic{}.

If you have a suggestion for a new feature, it makes sense to first
discuss it on the @uref{news:alt.lang.intercal,,alt.lang.intercal} news
group; other @ical{} compiler maintainers may also want to implement
that feature.  If you have developed code to implement that feature in
@cic{}, you can submit it the same way that you would submit a patch for
a bug.

@node Distributing
@section Distributing
@cindex C-INTERCAL, distributing
@cindex distributing C-INTERCAL
@cindex releasing C-INTERCAL

Due to the licensing conditions of @cic{}, you are allowed to release
your own version or distribution if you want to.  In such cases, it's
recommended that you follow the following guidelines:

@enumerate

@item
Make sure the new version is based on the most recent existing version.
Looking at the @uref{news:alt.lang.intercal,,alt.lang.intercal}
newsgroup will normally let you know what version is most recent.

@item
Increment the version number; if you add any new features, increment the
major version number (after the decimal point) and drop the minor version
number (before the decimal point) to 0, and otherwise increment the minor
version number.  You have to update the version number in the following
files: @file{configure.ac}, @file{configure}, and @file{doc/ick.txi}.  You
also have to rename the installation directory to reflect the new version
number.

@item
Add an entry to the @file{NEWS} file explaining what's new in the
version that you're releasing, following the same format as the other
entries.

@item
Update the @file{README} with a description of any new files you may
have added.

@item
Remove any autosave or backup files that may be littering the
installation directory or its subdirectories.

@item
Run @command{make distcheck}, which will make the distribution
paxballs, and rename them to have the correct extensions (Automake
thinks they're tarballs, so will use @samp{.tar} rather than
@samp{.pax}, and you have to fix this by hand).  @command{make
distcheck} will also perform some sanity checks on the build system of
the resulting paxball, which will help to ensure that nothing
important is missing from it.

@item
Place the new version somewhere on the Internet, and announce the
location and the fact that a new version has been released on
@uref{news:alt.lang.intercal,,alt.lang.intercal}.

@end enumerate

@node Invoking ick
@chapter Invoking ick
@cindex command line options
@cindex options, to @command{ick}
@cindex @command{ick}, command line options
@cindex @command{ick}, invoking
@cindex @command{ick}, options
@cindex compiling, @ical{} source code

All operations on @ical{} source code available in @cic{} are currently
carried out by the compiler @command{ick}.

The syntax is

@example
ick -options @var{inputfile}
@end example

@noindent
(Options can be given preceded by separate hyphens, or all in a row
after one hyphen, or a mixture; they're all single characters.)  By
default, this compiles one @ical{} program given as the input file
directly to an executable without doing anything fancy; usually you will
want to give options, which are described below.

@menu
* Language-affecting Options::       Options that specify language dialect
* Debug Options::                    Debug your code or ick itself
* Output Options::                   Specifying output format and location
* Optimizer Options::                Yes, you can optimize @ical{}!
* Other Options::                    Options not covered in other sections
* Options to Generated Programs::    Generated executables allow options too
* Environment Variables::            What environment variables affect ick
@end menu

@node Language-affecting Options
@section Language-affecting Options
@cindex options, language-affecting
@cindex language-affecting options
@cindex options, dialect
@cindex dialect options

The following command-line options to @command{ick} affect what dialect
of the @ical{} language is compiled by the compiler; you may need to set
one or more of these options if your input is not the default @cic{} but
instead some other language like @icst{} or @clcic{}, or just because
you like certainty or like being different with respect to your output.
Note that there is no command-line option corresponding to
@abbr{TriINTERCAL} (or the base 4-7 versions); instead, the numeric base
to use is determined by looking at the filename extension (@samp{.i} for
base 2, the default, or @samp{.3i} to @samp{.7i} for the base 3-7
versions.)

@table @option
@ianchor -b
@opindex -b
@cindex random bug
@cindex E774, disabling
If this option is @emph{not} given, there is a small chance that a
random bug appears in the compiler, which causes the programs it creates
to manifest a bug that causes error E774 (@pxref{E774}).  Giving the
option means that this bug will not happen.  (You may wonder why this
bug was preserved; it is in fact a bug that was carefully preserved
since the days of @icst{}, in this case, but the option to turn it off
is available as a workaround.  (There are no plans to fix this or any of
the other carefully preserved bugs any time soon, because that would
kind of defeat the point of having preserved them.)  Interestingly, the
@icst{} compiler documentation mentions a similar command-line option
that is a workaround for the same bug.)

@ianchor -m
@opindex -m
@cindex multithreading, enabling
@cindex backtracking, enabling
This option needs to be given to allow any multithreading or
backtracking commands or identifiers to be used.  (Unlike with other
language features, this is not autodetected because it's legal to have a
program with multiple COME FROM (@pxref{COME FROM}) commands aiming at
the same line even when it isn't multithreaded, in which case the
commands cause error E555 (@pxref{E555}) when that line is encountered
(with the usual caveats about both commands having to be active at the
time).)  Attempts to use non-COME FROM multithreading or backtracking
commands without this option produce error E405 (@pxref{E405}).

@ianchor -e
@opindex -e
@cindex external calls, enabling
This option makes it possible to link non-@ical{} programs with
@ical{} programs; instead of giving @ical{} programs only on the
command line, give one @ical{} program, followed by any number of
programs in other languages that have been written to be able to link
to @ical{} programs.  It also allows expansion libraries to be
specified on the command line, after the @ical{} program (expansion
libraries are given with no extension). For more information, see
@ref{External Calls}.  Also, both the @option{-a} and @option{-e}
options must be set to use CREATEd operators (regardless of whether
external calls are used or not).

@ianchorc -E
@opindex -E
@cindex system library, disabling
This option causes the system library to never be linked; this option
is only useful if your program references a line number in the range
1000 to 1999, contains no line numbers in that range, and yet still
doesn't want the system library to be linked in; therefore, it is
mostly useful with @option{-e} when adding in a custom replacement
system library written in a non-@ical{} language, especially the
expansion library @option{syslibc} (a system library replacement
written in C).

@ianchor -t
@opindex -t
@cindex INTERCAL-72 compatibility mode
@cindex compatibility, INTERCAL-72
This option tells the compiler to treat the source code as @icst{}; as a
result, any language constructs that are used but weren't available in
1972 will trigger error E111 (@pxref{E111}).

@ianchor -a
@opindex -a
@cindex CREATE, enabling
This option allows the CREATE statement (@pxref{CREATE}) to be used.
Note that enabling it carries a run-time penalty, as it means that
operand overloading code has to be generated for every variable in the
program. (This option is not necessarily needed for the external call
version of CREATE to work, but the external call version has fewer
features without it.)  Note that @option{-e} (@pxref{-e}) also needs
to be set to be able to CREATE operators.

@ianchor -v
@opindex -v
@cindex constants, assigning to
@cindex assigning to constants
It is possible to write @ical{} code sufficiently tortuous that it ends
up assigning to a constant.  Generally speaking, this isn't what you
wanted to do, so the compiler will kindly cause an error (E277;
@pxref{E277}) that stops the insanity at that point, but at the cost of a
significant amount of performance you can give this option to tell the
compiler to simply change the constant and keep on going anyway.  (Note
that unlike @clcic{}, this only changes uses of the constant preceded by
@code{#} in your program, not things like line numbers; you want
@uref{http://esolangs.org/wiki/Forte,Forte} for that.)  This option also
allows you to write arbitary expressions on the left of an assignment
statement if you wish.

@ianchorc -C
@opindex -C
@cindex clockface mode
When this option is given, the generated programs will write the number
4 as @samp{IIII} rather than @samp{IV}, in case you're writing a clock
program.

@ianchorc -P
@opindex -P
@cindex PIC-INTERCAL, command line option
@cindex E256, avoiding
@cindex E652, avoiding
This tells the compiler to treat the input as @abbr{PIC-INTERCAL}
(@pxref{PIC-INTERCAL}) rather than ordinary @cic{} input, and generate
PIC output code accordingly.  There are a lot of options that are
incompatible with this, as well as many language features, due to the
limited memory available on a PIC.  If you get error E256
(@pxref{E256}), you have this option given when it shouldn't be;
likewise, if you get error E652 (@pxref{E652}), you should be using this
option but aren't.  (A few simple programs are
@cic{}/@abbr{PIC-INTERCAL} polyglots, but such programs are incapable of
doing input or output, meaning that they aren't particularly useful.)

@ianchorc -X
@opindex -X
@cindex Princeton syntax, option
@cindex syntax, Princeton
The @cic{} and @clcic{} compilers use different notation for various
things, sometimes to the extent where the same notation is legal in both
cases but has a different meaning.  As this is the @cic{} compiler, it
rather guessably uses its own notation by default; however, the @clcic{}
notation can be used as the default instead using this option.  (In most
situations where there isn't an ambiguity about what something means,
you can use the `wrong' syntax freely.) The option causes ambiguous
characters like @code{?} to be interpreted with Princeton rather than
Atari meanings.

@ianchor -x
@opindex -x
@cindex CLC-INTERCAL compatibility mode
@cindex compatibility, CLC-INTERCAL
This option causes some constructs with different meanings in @cic{}
and @clcic{} to use the @clcic{} meaning rather than the @cic{}
meaning. At present, it affects the abstention of a GIVE UP
(@pxref{GIVE UP}) command by line number, which is possible as long as
this switch isn't given; reading through the @icst{} manual, there are
a lot of things that imply that this probably wasn't intended to be
possible, but as far as I can tell that manual doesn't actually
@emph{say} anywhere that this particular case is disallowed, even
though it rules out all other similar cases.  It also causes I/O on
array variables to be done in @clcic{}'s extended Baudot syntax,
rather than using the Turing Tape method.

@end table

@node Debug Options
@section Debug Options
@cindex options, debug
@cindex debug options

Sometimes things will go wrong with your program, or with the way
@command{ick} was installed.  There may even be unknown bugs in
@command{ick} itself (if you find one of these, please report it).  The
following options are used to debug the whole system on various levels.

@table @option

@ianchor -d
@opindex -d
@cindex debugging, parser
@cindex parser, debugging
@cindex debugging, lexical analyser
@cindex lexical analyser, debugging

If you think that something has gone wrong with the parser, or you want
to see how your program is being parsed, you can give this option on the
command line.  All the debug output produced by the parser and lexical
analyser will be output.

@ianchor -g
@opindex -g
@cindex debugging, C code
@cindex C code, debugging
@cindex C code, leaving in place

This option allows debugging of the final executable at the C code
level.  Any C code generated will be left in place, and the @option{-g}
option will be given to the C compiler that's used to compile the code,
so all the information needed for a C debugger to be used on the
executable will be present there.

@item -h
@itemx -H
@itemx -hH
@anchor{-h}
@anchor{-H+}
@anchor{-hH}
@opindex -h
@opindex -H
@opindex -hH
@cindex optimizer, debugging
@cindex debugging, optimizer
@cindex OIL, debugging
@cindex debugging, OIL

These options allow debugging of the optimiser, or produce output
helpful for understanding how your program has been summarised.
@option{-h} produces a summary of what optimiser rules were used, the
initial expression and what it was optimised to; @option{-H} produces a
more expanded view that shows each intermediate step of optimisation,
and @option{-hH} shows the same output as @option{-H}, but written
completely using C syntax (the other options output in a strange mix of
@ical{} and C).

@ianchor -l
@opindex -l
@cindex warnings, enabling

This option turns on generation of warnings (@pxref{Warnings}).  To make
sure that they aren't actually useful, or are only marginally useful,
the warning generator is far too sensitive, and there is no way to
decide which warnings are given and which ones aren't; you either get
all of them or none.

@ianchor -p
@opindex -p
@cindex profiling
@cindex yuk, profiling

This option causes the program to run immediately after being compiled,
and profiles the resulting program to identify performance bottlenecks,
etc.  The usefulness of this depends on the resolution of the timers on
the computer and operating system; DOS, in particular, is really bad
with timer resolution.  The output will be saved in a file called
@file{yuk.out} when the program finishes running.  It's legal to turn on
both the profiler and the interactive debugger at the same time, but if
you do this the profiler will also identify bottlenecks in the person
typing in commands to step through the program! The profiler will, in
fact, identify all the timings that particular commands in the program
take; so @code{WRITE IN} instructions will often show up as taking a
long time due to their need to wait for input.

@ianchor -w
@opindex -w
@cindex +printflow, enabling
@cindex printflow, enabling

This option causes the produced program to support the
@option{printflow} option fully; when this option is not given,
@option{printflow} will in most cases have partial or no support
(except in multithreaded programs, where this option is redundant),
because not all the code needed for it will be included in the program
to save space.

@ianchor -u
@opindex -u
@cindex skeleton file, directory problems
@cindex system library, directory problems
@cindex syslib, directory problems
@cindex directory problems
@cindex E999, debugging
@cindex E127, debugging

When you are getting problems with finding files -- for instance, the
compiler can't find the skeleton file (@pxref{E999}) or the system
library (@pxref{E127}) -- this option will let you know, on standard
error, where the compiler is looking for files.  This may hopefully help
you pin down where the file-finding problems are coming from, and also
offers the option of simply placing copies of the files where the
compiler is looking as a last resort.

@ianchor -y
@opindex -y
@cindex yuk, command line option

This is the main debugging option: it loads yuk, an interactive @ical{}
debugger with ability to step through the program, set breakpoints, view
and modify variables, etc.  @xref{yuk}.

@ianchorc -Y
@opindex -Y
@cindex external calls, debugging
@cindex command line, showing intermediates

This options causes the command line to be displayed for all calls to
other programs that @command{ick} makes (mostly to @command{gcc}); it
is therefore useful for debugging problems with the command lines used
when using the external calls system (@pxref{External Calls}).

@ianchorc -U
@opindex -U
@cindex internal errors, debugging
@cindex debugging, internal errors
@cindex internal errors, dumping core
@cindex dumping core on error
@cindex E778, debugging

The internal error E778 (@pxref{E778}) should never happen.  However,
there are all sorts of potential problems that may come up, and if part
of the code detects something impossible, or more usually when the
operating system detects things have got too insane and segfaults,
normally this error will just be generated and that's that.  (I most
often get this when I've been writing a new section of code and have
made a mistake; hopefully, all or at least most of these errors are
fixed before release, though.)  If you want more information as to what's
going on, you can give the @option{-U} option, which will cause the
compiler to raise an abort signal when an internal error happens.  This
can generally be caught by a debugger that's being run on @command{ick}
itself at the time; on many systems, it will also cause a core dump.

@end table

@node Output Options
@section Output Options
@cindex output options
@cindex options, output

These options allow you to control how far to compile (all the way to an
executable, or only to C, etc.@:), and where the output will be created.
Note that the output options may change depending on the other options
selected; for instance, many of the debug options will prevent the code
being compiled all the way to an executable.

@table @option

@ianchor -c
@opindex -c
@cindex code generation, stopping at C code
@cindex C, stopping after C is generated
@cindex output, C only

By default, the original @ical{} code will be compiled all the way to an
executable, and the intermediate C and object files produced will be
deleted.  Giving this option causes the compiler to stop when it has
finished producing the C file, leaving the C file there as the final
output of the compiler.  (Its filename is the same as the source file,
but with @samp{.c} as its extension/suffix rather than the source file's
extension.)  Without this option, an executable will be produced with the
extension changed to whatever's appropriate for the system you are on
(or omitted entirely if that's appropriate for the system).

This option also places verbose comments in the output C file.

@ianchor -o
@opindex -o
@cindex output, to standard output
@cindex standard output

This option causes the compiler to progress no further than producing
the C output file, but instead of writing it to a file writes it
directly to standard output.  This might occasionally be useful when
using @command{ick} as part of a pipe; it can also be useful to see how
far the compiler gets with compiling code before an error happens, when
you're trying to track down an error.

@end table

@node Optimizer Options
@section Optimizer Options
@cindex optimizer options
@cindex options, optimizer
@cindex optimization

There are various command line options that can be used to tell
@command{ick} whether and in what ways to optimize code.

@table @option

@ianchor -f
@opindex -f
@cindex flow optimization
@cindex optimization, flow
@cindex optimization, control flow

This option requests the compiler to attempt to analyse the flow of the
program and optimize accordingly; for instance, it will detect which
commands can't possibly be @code{ABSTAINED} from and refrain from
generating code to check the abstention status of those commands.

@ianchorc -F
@opindex -F
@cindex optimization, extreme
@cindex extreme optimization

This option tells the compiler to optimize the output for speed.  This
is done to crazy extremes; the compiler may take several hours/days
analysing the program in some cases and still not come up with an
improvement.  It turns on all the other optimizer options.  Note that
not all systems accept this option, because it sometimes outputs a shell
script disguised as an executable rather than an actual executable.

@ianchorc -O
@opindex -O
@cindex optimization, idioms
@cindex idiom optimization
@cindex optimization, OIL
@cindex OIL, optimizing code

This option tells the compiler to apply optimizer idioms to the
expressions in the code given, when appropriate.  The list of idioms is
stored in the file @file{src/idiotism.oil}; note that it is compiled
into the compiler, though, so you will have to rebuild and reinstall the
compiler if you change it.  For more information about changing the list
of idioms, see @ref{Optimizer Idiom Language}.

@end table

@node Other Options
@section Other Options
@cindex other options
@cindex options, other

Some options just can't be classified.

@table @option

@item -@@
@anchor{-at}
@opindex -@@
@cindex options, help
@cindex help with options
@cindex usage instructions, printing

If this option is given, the compiler doesn't run at all, but instead
prints a set of instructions for using it, explaining which options are
available on the system you're on and which options conflict with which
other options.

@end table

@node Options to Generated Programs
@section Options to Generated Programs
@cindex generated programs, options
@cindex options, to generated programs

Once the compiler runs and produces an output executable, that
executable itself will accept a range of options that control the way it
runs.  None of these options have to be used; a default value will be
assumed if they aren't.

@table @option

@ianchorpm help
@opindex +help
@opindex -help

Whether @samp{+} or @samp{-} is given at the start of this option, it
will cause the program to print out what options are available and what
state they are in.  It will then cause the program to exit via an
internal error.

@ianchorpm wimpmode
@opindex +wimpmode
@opindex -wimpmode
@cindex wimpmode
@cindex Roman numerals, disabling
@cindex Arabic numberals, enabling
@cindex input, in Arabic numerals
@cindex output, in Arabic numerals

If the @samp{+} version of this is given (rather than the default
@samp{-}), then the program will print a message explaining that you are
a wimp (the mode itself is known as wimpmode), and for the rest of
execution will input in Arabic numerals (@samp{123} rather than
@samp{ONE TWO THREE}) and likewise will output in Arabic numerals rather
than Roman numerals (such as @samp{CXXIII}).  True @ical{} programmers
should rarely have to use this mode.

@ianchorpm traditional
@opindex +traditional
@opindex -traditional

This option does not actually appear to do anything.

@ianchorpm instapipe
@opindex +instapipe
@opindex -instapipe
@cindex output, flushing
@cindex flushing

This option causes standard output to be flushed whenever any characters
are output when the @samp{+} version is used, rather than on each newline
(the default @samp{-} version).  It is most useful for more responsive
pipes when outputting binary data, and also useful for debugging very
slow programs.

@ianchorpm printflow
@opindex +printflow
@opindex -printflow
@cindex flow, printing
@cindex debugging, flow
@cindex debugging, multithreaded programs
@cindex multithreading, debugging
@cindex backtracking, debugging

The usual debugging methods don't work with multithreaded or
backtracking programs.  This option exists to give at least a slim
chance of working out what is going on with them.  It causes the
program to print the line number of the command it thinks it may be
executing next (i.e.@: the line number that would be printed if that
line had an error) immediately after executing each command, and also
an internal identifier for the thread that that command was in.  It
also prints a trace of what parts of the multithreader are being
activated; so for instance, it will tell you when a thread is being
forked into multiple threads or when a choicepoint has been deleted.
Note that the @option{-w} option (@pxref{-w}) must be given to gain
full support for flow printing in non-multithreaded non-backtracking
programs, because otherwise the required code to print this
information will not be generated.

@ianchorpm mystery
@opindex +mystery
@opindex -mystery

This option is occasionally capable of doing something, but is
deliberately undocumented.  Normally changing it will have no effect,
but changing it is not recommended.

@end table

@node Environment Variables
@section Environment Variables
@cindex environment variables

Various environment variables can be set to affect the operation of
@command{ick}.

@multitable @columnfractions .3 .7
@headitem Variable @tab Meaning
@item ICKINCLUDEDIR@*ICKLIBDIR@*ICKDATADIR
@tab
These three environment variables suggest locations in which
@command{ick} should look to find various files that it needs: the
skeleton file, system library, C header files and libraries that it
needs, constant-output optimiser, and the GNU General Public License
(which the debugger needs to be able to display on demand for legal
reasons).
@item CC
@tab
The name of a C compiler to use (defaults to gcc, which is the only
compiler with which @cic{} has been tested recently).  This option has
no effect on DJGPP, where gcc is always used.
@item ICKTEMP@*TMPDIR@*TEMP@*TMP
@tab
On DJGPP, @command{ick} creates temporary files to pass options to gcc
as a method of getting around the limit on the length of a command line
that can sometimes affect DOS programs.  These four environment
variables are tried (in this order) to determine a location for the
temporary file; if none of them are set, the current directory is used.
@end multitable

@node Errors and Warnings
@chapter Errors and Warnings
@cindex @command{ick}, errors and warnings
@cindex errors and warnings

Things may go wrong, either during the compilation or the execution of
your program.  Note that some things that would be compile-time errors
in many other languages -- such as syntax errors -- are in fact run-time
errors in @ical{}.

Errors and warnings appear as an error code starting with @samp{ICL},
followed by a three digit number, followed by @samp{I} for an error or
@samp{W} for a warning.  However, they will be notated here as
@samp{E000}, etc.@:, to save space and because consistency was never a
strong point of @ical{}.  This is followed by a text description of the
error, and a hint as to the location of the error.  This is not the line
on which the error occurred, but rather the line on which the next
command to be executed is.  To add to the fun, the calculation of the
next command to be executed is done at compile-time rather than runtime,
so it may be completely wrong due to things like abstention on
@code{COME FROM}s or computed @code{COME FROM}s.  The moral of this
story is that, if you really want to know where the error is, use a
debugger.  Note also that if the error happens at compile-time, there is
no guarantee that the line number given makes any sense at all.  Some
errors don't give next line numbers, mostly those for which it doesn't
make logical sense, such as E633 (@pxref{E633}).  After this is a
suggestion to correct (or reconsider) the source code and to resubnit
it.  (This typo has been carefully preserved for over a decade.)

@menu
* Errors::                     Error messages that might be produced
* Warnings::                   Warnings produced by the @option{-l} option
@end menu

@node Errors
@section Errors
@cindex errors
@cindex @command{ick}, errors

This is a list of the error messages that might be produced during the
compilation or execution of an @ical{} program.

@table @asis

@ieanchor E000
@cindex syntax error

This is an unusual error; it's what's printed when a syntax error is
encounted at runtime, in a situation in which it would be executed.  (An
@code{ABSTAIN}ed syntax error, for instance, would not be executed; this
is one of the mechanisms available for writing comments.)  The text of
the error message is simply the statement that couldn't be decoded.

@ieanchor E017
@cindex constant, twospot
@cindex overflow, in constant
@quotation
DO YOU EXPECT ME TO FIGURE THIS OUT?
@end quotation

This error occurs when there is an attempt to use a constant with a
value outside the onespot range; it's a compile-time error.

@ieanchor E079
@cindex politesse
@cindex @code{PLEASE}, proportion required
@quotation
PROGRAMMER IS INSUFFICIENTLY POLITE
@end quotation

The balance between various statement identifiers is important.  If less
than approximately one fifth of the statement identifiers used are the
polite versions containing @code{PLEASE}, that causes this error at
compile time.

@ieanchor E099
@quotation
PROGRAMMER IS OVERLY POLITE
@end quotation

Of course, the same problem can happen in the other direction; this
error is caused at compile time if over about one third of the statement
identifiers are the polite form.

@ieanchor E111
@quotation
COMMUNIST PLOT DETECTED, COMPILER IS SUICIDING
@end quotation

This error happens when you give the @option{-t} option (@pxref{-t}) but
you use a language construct that wasn't available in @icst{}.  If this
happens, then either there's a mistake in the program that prevents it
being @icst{} or you shouldn't be compiling it as @icst{} in the first
place.

@ieanchor E123
@cindex black lagoon
@cindex @code{NEXT}, stack overflow
@cindex stack overflow
@quotation
PROGRAM HAS DISAPPEARED INTO THE BLACK LAGOON
@end quotation

There is a hard limit of 80 @command{NEXT}s at a time; this is to
discourage excessive use of @command{NEXTING} for things like recursion.
(Recursive programs are entirely legal; you simply have to figure out
how to do it with computed @command{COME FROM} instead.  (For the
record, it is possible.  (Using lots of nested brackets when talking
about recursion is great (yay!@:).)))  Another problem with writing the
source code that can cause this error is a failure to properly
@command{FORGET} the entry on the @command{NEXT} stack created when
trying to simulate a goto.

@ieanchor E127
@cindex system library, errors
@cindex syslib, errors
@quotation
SAYING 'ABRACADABRA' WITHOUT A MAGIC WAND WON'T DO YOU ANY GOOD
@end quotation
Your program asked to include the system library (by specifying a line
number from 1000 to 1999 inclusive without including a line with that
number), but due to installation problems the compiler couldn't find the
system library to include.  You could try using the @option{-u}
(@pxref{-u}) option to see where the compiler's looking; that may give
you an idea of where you need to copy the system library so that the
compilation will work.  This error happens at compile time and doesn't
give a next command line number.

@ieanchor E129
@cindex @code{NEXT}, nonexistent target
@quotation
PROGRAM HAS GOTTEN LOST
@end quotation

This error happens at compile time when the compiler can't figure out
where a @code{NEXT} command is actually aiming (normally due to a typo
in either the line label given or the line label on the line aimed
for).  The logic behind this error means that the next line to be
executed is unknown (after all, that's the whole point of the error)
and is therefore not given.  The @option{-e} command-line option
(@pxref{-e}) makes this error into a run-time error, because it allows
@code{NEXT} commands to dynamically change targets at runtime, as well
as line labels to dynamically change values, and thus the error is
impossible to detect at compile time.

@ieanchor E139
@cindex @code{ABSTAIN}, nonexistent target
@cindex @code{REINTSTATE}, nonexistent target
@quotation
I WASN'T PLANNING TO GO THERE ANYWAY
@end quotation

This error happens at compile time when an @code{ABSTAIN} or
@code{REINSTATE} references a non-existent target line.  This generally
happens for much the same reasons as E129 (@pxref{E129}).

@ieanchor E182
@cindex line label, duplicate
@cindex duplicate line label
@quotation
YOU MUST LIKE THIS LABEL A LOT!
@end quotation

At present, it's impossible to have more than one line with the same
line number.  That would make @code{NEXT} act too much like @code{COME
FROM} in reverse to be interesting.  This error happens at compile
time.  (For inconsistency, it @i{is} possible to have multiple lines
with the same number as long as at most one of them is in an @ical{}
program (the others have to be in programs in other languages included
via the external calls system).)

@ieanchor E197
@cindex line label, illegal value
@cindex illegal line label value
@cindex invalid line label value
@quotation
SO@!  65535 LABELS AREN'T ENOUGH FOR YOU?
@end quotation

Legal values for line labels are 1 to 65535 (with values from 1000 to
1999 reserved if you want to use the system library, and 1600 to 1699
reserved if you're using other expansion libraries).  This error comes
up if you use nonpositive or twospot values for a line label.

@ieanchor E200
@cindex variable, illegal number
@cindex illegal variable number
@cindex invalid variable number
@quotation
NOTHING VENTURED, NOTHING GAINED
@end quotation

You used a variable that isn't actually in your program.  Failing that
(which would be quite impressive and is probably impossible, at least in
the present version of @cic{}), you specified an illegal number for a
variable (legal numbers are positive and onespot).  This error happens
at compile time, at least for illegal variable numbers.

@ieanchor E222
@cindex out of memory, during @code{STASH}
@quotation
BUMMER, DUDE!
@end quotation

In @ical{}, you're allowed to @code{STASH} as much as you like; this
makes the language Turing-complete and allows for unlimited recursion
when combined with computed @code{COME FROM} in the right way.
Unfortunately, real computers aren't so idealised; if you manage to
write a program so memory-intensive that the computer runs out of memory
to store stashes, it causes this error at runtime.  To fix this error,
you either have to simplify the program or upgrade your computer's
memory, and even then that will only help to some extent.

@ieanchor E240
@cindex array, invalid dimension
@cindex invalid array dimension
@cindex illegal array dimension
@quotation
ERROR HANDLER PRINTED SNIDE REMARK
@end quotation

Arrays have to be large enough to hold at least one element; you tried
to dimension an array which isn't large enough to hold any data.  This
error happens at run time.

@ieanchor E241
@cindex array, wrong dimension
@cindex wrong array dimension
@cindex array, out of bounds
@cindex out of bounds
@quotation
VARIABLES MAY NOT BE STORED IN WEST HYPERSPACE
@end quotation

This error happens at run time when the subscripts given to an array
are inconsistent with the way the array was dimensioned, either
because there were the wrong number of subscripts or because a
subscript was too large to fit in the array.  It can also happen when
a multidimensional array is given to a command, such as @code{WRITE
IN}, that expects it to be monodimensional.

@ieanchor E252
@cindex I/O, out of memory
@cindex out of memory, I/O
@quotation
I'VE FORGOTTEN WHAT I WAS ABOUT TO SAY
@end quotation

This run-time error message is caused by the compiler running out of
memory whilst trying to do I/O; at present, it can only happen during
@clcic{}-style I/O.

@ieanchor E256
@cindex PIC-INTERCAL, unsupported command
@quotation
THAT'S TOO HARD FOR MY TINY BRAIN
@end quotation

Some commands simply aren't available in @abbr{PIC-INTERCAL}.  I mean,
@acronym{PIC}s generally have less than a kilobyte of memory; you're not
going to be able to use some of the more confusing language features
with that sort of resource limitation.  The solution is to replace the
affected command, or to not give the @option{-P} option
(@pxref{-P+,,-P}) if you didn't mean to compile as @abbr{PIC-INTERCAL}
in the first place.

@ieanchor E275
@cindex overflow, over onespot
@cindex overflow, over 16 bits
@cindex onespot overflow
@cindex 16 bit overflow
@quotation
DON'T BYTE OFF MORE THAN YOU CAN CHEW
@end quotation

This error happens when there is an attempt to store a twospot value in
a onespot variable.  The actual size of the value is what matters when
counting its spots; so you can store the output of a mingle in a onespot
variable if it happens to be less than or equal to 65535, for instance.
(This is not necessarily the case in versions of @ical{} other than
@cic{}, though, so you have to be careful with portability when doing
this.)

@ieanchor E277
@cindex reverse assignment, impossible
@cindex reverse assignment, error
@cindex operand overloading, impossible
@cindex impossible reverse assignment
@quotation
YOU CAN ONLY DISTORT THE LAWS OF MATHEMATICS SO FAR
@end quotation

Reverse assignments are not always mathematically possible.  Also,
sometimes they require changing the value of a constant; this is only
legal if you specifically specified that it was legal by using the
@option{-v} option.  In the case of an impossible reverse assignment
(including a situation in which operand overloading causes a reverse
assignment to happen), this error happens at runtime.

This error can also come up when a scalar variable is overloaded to an
array (which doesn't make sense, but could happen if someone exploited
bugs in the CREATE statement (@pxref{CREATE})), and an attempt is made
to read or assign to that variable.  (Subscripting a scalar variable
is a syntax error, so there is no use for doing such an overload
anyway.)

@ieanchor E281
@cindex spark, nesting limit
@cindex ears, nesting limit
@cindex rabbit-ears, nesting limit
@cindex nesting limit
@findex SENESTMAX
@quotation
THAT MUCH QUOTATION AMOUNTS TO PLAGIARISM
@end quotation

There is a limit of 256 on the number of nested spark/ears groups
allowed.  If you somehow manage to exceed that limit, that will cause
this error.  Try breaking the expression up into smaller expressions.
(The limit is trivial to increase by changing @code{SENESTMAX} in
@file{ick.h}; if you ever actually come across a program that hits the
limit but wasn't designed to, just email the maintainer to request a
higher limit.)

@ieanchor E333
@cindex variables, limit
@quotation
YOU CAN'T HAVE EVERYTHING, WHERE WOULD YOU PUT IT?
@end quotation

Your program references so many variables that the compiler couldn't
cope.  This error is unlikely to ever happen; if it does, try reducing
the number of variables you use by combining some into arrays.  This is
a compile-time error.

@ieanchor E345
@cindex out of memory
@quotation
THAT'S TOO COMPLEX FOR ME TO GRASP
@end quotation

This is another compile-time error that's unlikely to ever happen;
this one signifies the compiler itself running out of memory trying to
compile your program.  The only solutions to this are to simplify your
program, or to make more memory available to the compiler.

@ieanchor E404
@cindex @code{GO BACK}, no choicepoint
@cindex @code{GO AHEAD}, no choicepoint
@quotation
I'M ALL OUT OF CHOICES!
@end quotation

Your program asked that a choicepoint be backtracked to or removed, but
there aren't any choicepoints at the moment.  This runtime error usually
indicates a logic mistake in your program.  In backtracking programs
translated from other backtracking languages, this indicates that the
program has failed.

@ieanchor E405
@cindex multithreading, not enabled
@cindex backtracking, not enabled
@cindex @code{WHILE}, not enabled
@cindex @code{MAYBE}, not enabled
@cindex @code{GO AHEAD}, not enabled
@cindex @code{GO BACK}, not enabled
@quotation
PROGRAM REJECTED FOR MENTAL HEALTH REASONS
@end quotation

Your program used a construct that only makes sense when multithreading
or backtracking (@code{WHILE}, @code{MAYBE}, @code{GO BACK}, or @code{GO
AHEAD}), but you didn't specify the @option{-m} option (@pxref{-m}).  If
you meant to write a multithreaded or backtracking program, just give
that option; if you didn't, be careful what words you use in comments!
This error happens at compile-time.

@ieanchor E436
@cindex @code{RETRIEVE}, without stashing
@cindex stash failure
@quotation
THROW STICK BEFORE RETRIEVING!
@end quotation

In order to @code{RETRIEVE} a variable, it has to be @code{STASH}ed
first; if it isn't, then this error happens at runtime.

@ieanchor E444
@cindex @code{COME FROM}, no target
@cindex @code{NEXT FROM}, no target
@quotation
IT CAME FROM BEYOND SPACE
@end quotation

A @code{COME FROM} aiming at a line label --- as opposed to a computed
@code{COME FROM}, which is allowed to be pointing at a nonexistent line
--- must point to a valid line label.  The same applies to @code{NEXT
FROM}.  This error happens at compile time if a nonexistent line label is
found in one of these contexts.

@ieanchor E533
@cindex overflow, over twospot
@cindex overflow, over 32 bits
@cindex twospot overflow
@cindex 32 bit overflow
@quotation
YOU WANT MAYBE WE SHOULD IMPLEMENT 64-BIT VARIABLES?
@end quotation

This error is like E275 (@pxref{E275}), but applies when an attempt is
made at runtime to store a threespot value (or even a fourspot or
morespot value) in a twospot variable, or a threespot or greater value
is produced as an intermediate during a calculation (for instance by a
mingle operation).  No values above twospot are allowed at any point
during an @ical{} program; if you want to process higher numbers, you
have to figure out a different way of storing them.

@ieanchor E553
@cindex buffer overflow
@quotation
BETTER LATE THAN NEVER
@end quotation
Oops!  The compiler just noticed that it had a buffer overflow.
(Normally programs catch buffer overflows before they happen;
C-INTERCAL catches them just afterwards instead.)  This only happens
on systems which don't have a modern C standard library. Try using
shorter or fewer filenames on the command line, to reduce the risk of
such an overflow.

@ieanchor E555
@cindex @code{COME FROM}, ambiguity
@quotation
FLOW DIAGRAM IS EXCESSIVELY CONNECTED
@end quotation

Aiming two @code{COME FROM}s at the same line only makes sense in a
multithreaded program.  In a non-multithread program, doing that will
cause this error at compile time (if neither @code{COME FROM} is
computed) or at run time (if the command that has just finished running
is simultaneously the target of two or more @code{COME FROM}s).  This
either indicates an error in your program or that you've forgotten to
use the @option{-m} option (@pxref{-m}) if you are actually trying to
split the program into two threads.

@ieanchor E562
@cindex input, EOF
@cindex EOF
@cindex end of file
@quotation
I DO NOT COMPUTE
@end quotation

The program asked for input, but for some reason it wasn't available.
(This is a runtime error, obviously.)   The error may happen because the
input is being piped in from a command or file which has reached
end-of-file, or because the user typed @kbd{@key{CTRL}-@key{D}}
(UNIX/Linux) or @kbd{@key{CTRL}-@key{Z}} (DOS/Windows) while the program
was trying to @code{WRITE IN} some data.

@ieanchor E579
@cindex input, invalid
@quotation
WHAT BASE AND/OR LANGUAGE INCLUDES @var{string}?
@end quotation

When reading spelt-out-digit input, the input didn't seem to be a valid
digit in English, Sanskrit, Basque, Tagalog, Classical Nahuatl,
Georgian, Kwakiutl, Volap@"uk, or Latin.  This seems to have languages
covered pretty well; what on earth were you using, or did you just make
a spelling mistake?

@ieanchor E621
@cindex @code{RESUME}, by 0
@quotation
ERROR TYPE 621 ENCOUNTERED
@end quotation

The compiler encountered error E621 (@pxref{E621}).  This happens at
runtime when the program requests that no entries are removed from the
@code{NEXT} stack (which is possible), but that the last entry removed
should be jumped to (which given the circumstances isn't, because no
entries were removed).

@ieanchor E632
@quotation
THE NEXT STACK RUPTURES.  ALL DIE.  OH, THE EMBARRASSMENT!
@end quotation

When an attempt is made to @code{RESUME} past the end of the @code{NEXT}
stack, the program ends; however, this cause the program to end in a
manner other than via @code{GIVE UP} or @code{DON'T TRY AGAIN}, so an
error message must be printed, and this is that error message.

@ieanchor E633
@quotation
PROGRAM FELL OFF THE EDGE
@end quotation

You can't just let execution run off the end of the program.  At least,
that is, if it doesn't end with @code{TRY AGAIN}.  An attempt to do that
causes this error at runtime.  Note that if your program references the
system library, then it counts as being appended to your program and so
the program will run into the first line of the system library rather
than cause this error.  As it happens, the first line of the system
library is a syntax error, so doing this will cause E000 (@pxref{E000})
with the error text @samp{PLEASE KNOCK BEFORE ENTERING}.  There isn't a
next statement to be executed with E633, so the next statement won't be
given in the error message.

@ieanchor E652
@cindex @code{PIN}, in a non-PIC program
@quotation
HOW DARE YOU INSULT ME!
@end quotation

The @code{PIN} command doesn't make much sense for anything bigger than
a @acronym{PIC}; using it in a non-@acronym{PIC} program causes this
error at compile-time.  Try using the normal input and output mechanisms
instead.  This error may also be a clue that you are trying to compile a
@abbr{PIC-INTERCAL} program without giving the @option{-P} option
(@pxref{-P+,,-P}).

@ieanchor E666
@cindex out of memory, during compile
@cindex too many input files
@cindex line too long
@quotation
COMPILER HAS INDIGESTION
@end quotation

There isn't a limit on the length of an input program other than your
computer's memory; if your computer does run out of memory during
compilation, it causes this error.  This error can also be caused if
too many input files are specified on the command line; if you suspect
this is the problem, split the compilation into separate compilations
if you can, or otherwise you may be able to concatenate together your
input files into larger but fewer files.  Yet another potential cause
of this error is if a line in an input program is too long; sensible
line-wrapping techniques are encouraged.

@ieanchor E774
@cindex random bug, error message
@quotation
RANDOM COMPILER BUG
@end quotation

No compiler is perfect; sometimes errors just happen at random.  In this
case, the random error is E774.  If you don't like the idea that your
program may be shot down by a random compiler bug, or you are doing
something important, you can use the @option{-b} option (@pxref{-b}) to
prevent this bug happening.  (You may wonder why this bug is in there at
all if it's so easily prevented.  The answer is that such a bug was
present in the original @icst{} compiler, which also had an option to
turn the bug off.  It's also a reward for people who actually read the
manual.)

@ieanchor E777
@cindex directory problems, source file
@cindex no source file
@quotation
A SOURCE IS A SOURCE, OF COURSE, OF COURSE
@end quotation

You specified a file to compile on the command line, but the compiler
couldn't find or couldn't open it.  This is almost certainly because you
made a typo specifying the file.

@ieanchor E778
@cindex internal errors
@quotation
UNEXPLANED COMPILER BUG
@end quotation

This should never come up, either at compile time or at run time.  It
could come up at either when an internal check by the compiler or the
runtime libraries realises that something has gone badly wrong; mistakes
happen, and in such cases the mistake will have been detected.  (If this
happens at compile time you can use the @option{-U} option
(@pxref{-U+,,-U}) to cause the compiler to send an abort signal -- which
normally causes a core dump -- when the error happens, to help debug
what's causing it.)  More often, this error comes up when the operating
system has noticed something impossible, like an attempt to free
allocated memory twice or to write to a null pointer, and tells the
compiler an error has occured, in which case the same response of
putting up this error happens.  The point is that in all cases this
error indicates a bug in the compiler (even if it happens at run time);
in such cases, it would be very helpful if you figure out what caused it
and send a bug report (@pxref{Reporting Bugs}).

@ieanchor E810
@cindex yuk, input overflow
@quotation
ARE ONE-CHARACTER COMMANDS TOO SHORT FOR YOU?
@end quotation

This is a debug-time error caused when you give too much input to the
debugger when all it wanted was to know what you wanted to do next.

@ieanchor E811
@cindex yuk, breakpoint overflow
@cindex yuk, too many breakpoints
@cindex breakpoints, too many
@quotation
PROGRAM IS TOO BADLY BROKEN TO RUN
@end quotation

There's a limit to how many breakpoints you can have in a program;
you've broken the limit and therefore broken the debugger.  This is a
debug-time error.

@ieanchor E888
@quotation
I HAVE NO FILE AND I MUST SCREAM
@end quotation
@cindex output file, failure to write

The output file couldn't be written, maybe because the disk is full or
because there's already a read-only file with the same name.  This is a
compile-time error.

@ieanchor E899
@quotation
HELLO?
CAN ANYONE GIVE ME A HAND HERE?
@end quotation
@cindex Funge, no external library
@cindex Befunge, no external library
@cindex external libraries, unavailable
@cindex .b98, no external library

This error occurs at compile-time if a file type was requested for
which the required libraries are unavailable.  (Support for Funge does
not ship with the compiler; instead, you need to generate the library
yourself from the cfunge sources.  For more information, see
@ref{Creating the Funge-98 Library}.)

@ieanchor E991
@cindex out of memory, multithreading
@cindex out of memory, backtracking
@cindex multithreading, out of memory
@cindex backtracking, out of memory
@quotation
YOU HAVE TOO MUCH ROPE TO HANG YOURSELF
@end quotation

There is no limit on the number of threads or choicepoints that you can
have in a multithreaded or backtracking program (in a program that isn't
multithreaded or backtracking, these are obviously limited to 1 and 0
respectively).  However, your computer may not be able to cope; if it
runs out of memory in the multithreader, it will cause this error at
runtime.

@ieanchor E993
@cindex @code{TRY AGAIN}, not last
@quotation
I GAVE UP LONG AGO
@end quotation

@code{TRY AGAIN} has to be the last command in a program, if it's there
at all; you can't even follow it by comments, not even if you know in
advance that they won't be @code{REINSTATE}d.  This error happens at
compile time if a command is found after a @code{TRY AGAIN}.

@ieanchor E995
@quotation
DO YOU REALLY EXPECT ME TO HAVE IMPLEMENTED THAT?
@end quotation

Some parts of the code haven't been written yet.  There ought to be no
way to cause those to actually run; however, if you do somehow find a
way to cause them to run, they will cause this error at compile time.

@ieanchor E997
@cindex whirlpool, in base 2
@cindex sharkfin, in base 2
@cindex TriINTERCAL, operators in base 2
@quotation
ILLEGAL POSSESSION OF A CONTROLLED UNARY OPERATOR
@end quotation

Some operators (such as whirlpool (@code{@@}) and sharkfin (@code{^}))
only make sense in @abbr{TriINTERCAL} programs, and some have a minimum
base in which they make sense.  This error happens at compile-time if
you try to use an operator that conflicts with the base you're in (such
as using @abbr{TriINTERCAL} operators in an @ical{} program in the
default base 2).

@ieanchor E998
@cindex unsupported file type
@cindex file type, unsupported
@quotation
EXCUSE ME,
YOU MUST HAVE ME CONFUSED WITH SOME OTHER COMPILER
@end quotation

This error occurs just before compile-time if a file is encountered on
the command line that C-INTERCAL doesn't recognise.  (If this error
occurs due to a @samp{.a}, @samp{.b98}, @samp{.c}, or @samp{.c99},
then you forgot to enable the external calls system using @option{-e}
(@pxref{-e}).)

@ieanchor E999
@cindex skeleton file, errors
@quotation
NO SKELETON IN MY CLOSET, WOE IS ME!
@end quotation

The skeleton file @file{ick-wrap.c} or @file{pickwrap.c} is needed to be
able to compile @ical{} to C.  If the compiler can't find it, it will
give this error message.  This indicates a problem with the way the
compiler has been installed; try using the @option{-u} option
(@pxref{-u}) to find out where it's looking (you may be able to place a
copy of the skeleton file in one of those places).

@end table

@node Warnings
@section Warnings
@cindex warnings
@cindex @command{ick}, warnings

This is a list of the warnings stored in the warning database.
Warnings only come up when the @option{-l} option (@pxref{-l}) is
given; even then, some of the warnings are not currently implemented
and therefore will never come up.

@table @asis

@ieanchor W016
@quotation
DON'T TYPE THAT SO HASTILY
@end quotation

The positional precedence rules for unary operators are somewhat
complicated, and it's easy to make a mistake.  This warning is meant to
detect such mistakes, but is not currently implemented.

@ieanchor W018
@quotation
THAT WAS MEANT TO BE A JOKE
@end quotation

If an @ical{} expression has been translated from another language such
as C, the optimiser is generally capable of translating it back into
something similar to the original, at least in base 2.  When after
optimisation there are still @ical{} operators left in an expression,
then this warning is produced.  (Therefore, it's likely to come up quite
a lot if optimisation isn't used@!)  The system library produces some of
these warnings (you can tell if a warning has come up in the system
library because you'll get a line number after the end of your program).

@ieanchor W112
@cindex warnings, non-INTERCAL-72
@cindex non-INTERCAL-72 warning
@quotation
THAT RELIES ON THE NEW WORLD ORDER
@end quotation

This warning comes up whenever the compiler recognises that you've added
some code that didn't exist in @icst{}.  This allows you to check
whether your code is valid @icst{} (although @option{-t} (@pxref{-t}) is
more useful for that); it also warns you that code might not be portable
(because @icst{} is implemented by most @ical{} compilers, but more
recent language features may not be).

@ieanchor W128
@quotation
SYSLIB IS OPTIMIZED FOR OBUSCATION
@end quotation

There is an idiom used in the system library that does a right-shift by
selecting alternate bits from a twospot number and then mingling them
the other way round.  A rightshift can much more easily be done with a
single rightshift, so this is a silly way to do it, and this warning
warns that this idiom was used.  However, the present optimizer is
incapable of recognising whether this problem exists or not, so the
warning is not currently implemented.

@ieanchor W276
@cindex onespot, overflow warning
@cindex overflow, warning
@quotation
YOU CAN'T EXPECT ME TO CHECK BACK THAT FAR
@end quotation

It's an error to assign a twospot value (a value over 65535) to a
onespot variable, or to use it as an argument to a mingle.  If the
optimizer can't guarantee at compile time that there won't be an
overflow, it issues this warning.  (Note that this doesn't necessarily
mean there's a problem --- for instance, the system library generates
some of these warnings --- only that the optimiser couldn't work out for
sure that there wasn't a problem.)

@ieanchor W239
@quotation
WARNING HANDLER PRINTED SNIDE REMARK
@end quotation

Your code looks like it's trying to assign 0 to an array, giving it no
dimension; this is an error.  This warning is produced at compile time
if it looks like a line in your code will cause this error, but it isn't
necessarily an error because that line of code might never be executed.

@ieanchor W278
@quotation
FROM A CONTRADICTION, ANYTHING FOLLOWS
@end quotation

It's sometimes impossible to reverse an assignment (a reverse
assignment can happen if the @option{-v} option (@pxref{-v}) is used
and an expression is placed on the left of an assignment, or in
operand overloading); if the compiler detects that a reversal failure
is inevitable, it will cause this warning.  Note that this doesn't
always cause an error, because the relevant code might never be
executed.

@ieanchor W450
@quotation
THE DOCUMENTOR IS NOT ALWAYS RIGHT
@end quotation

There is no way to get this warning to come up; it isn't even written
anywhere in @cic{}'s source code, is not implemented by anything, and
there are no circumstances in which it is even meant to come up. It is
therefore not at all obvious why it is documented.

@ieanchor W534
@cindex unary operators, portability
@cindex portability, unary operators
@quotation
KEEP LOOKING AT THE TOP BIT
@end quotation

@cic{} uses a slightly different typing mechanism to some other @ical{}
compilers; types are calculated at compile time rather than run time.
This only makes a difference in some cases involving unary operators.
It's impossible to detect at compile time for certain whether such a
case has come up or not, but if the compiler or optimizer thinks that
such a case might have come up, it will issue this warning.

@ieanchor W622
@quotation
WARNING TYPE 622 ENCOUNTERED
@end quotation

Your code looks like it's trying to resume by 0; this is an error.  This
warning is produced at compile time if it looks like a line in your code
will cause this error, but it isn't necessarily an error because that
line of code might never be executed.

@end table

@node The yuk debugger
@chapter The yuk debugger
@cindex yuk
@cindex debugging, yuk
@cindex debugging, runtime
@cindex runtime debugger
@anchor{yuk}

The @cic{} distribution contains a runtime debugger called `yuk'.
Unlike most other debuggers, it is stored as object code rather than as
an executable, and it is compiled into the code rather than operating on
it.  To debug code, add @option{-y} (@pxref{-y}) to the command line of
@command{ick} when invoking it; that tells it to compile the debugger
into the code and then execute the resulting combination.  (The
resulting hybrid debugger/input executable is deleted afterwards; this
is to prevent it being run by mistake, and to prevent spreading the
debugger's licence onto the code it was compiled with.)

yuk can also be used as a profiler using the @option{-p} option
(@pxref{-p}); this produces a file @file{yuk.out} containing information
on how much time was spent running each command in your program, and
does not prompt for debugger commands.

Note that some command line arguments are incompatible with the
debugger, such as @option{-m} and @option{-f}.  In particular, this
means that multithreaded programs and programs that use backtracking
cannot be debugged using this method; the @option{+printflow} option
(@pxref{+printflow}) to a compiled program may or may not be useful for
debugging multithreaded programs.

When the debugger starts, it will print a copyright message and a
message on how to access online help; then you can enter commands to
run/debug the program.  The debugger will show a command prompt,
@samp{yuk007 }, to let you know you can input a command.

@cindex yuk, commands
Here are the commands available.  Commands are single characters
followed by newlines, or followed by a line number (in decimal) and a
newline or a variable name (a @code{.}, @code{,}, @code{:} or @code{;}
followed by a number in decimal; note that some commands only allow
onespot and twospot variables as arguments).

@multitable @columnfractions .15 .85
@headitem Command @tab Description
@item a@var{LINE}
@tab
All non-abstained commands on line @var{LINE} become abstained from
once.
@item b@var{LINE}
@tab
A breakpoint is set on line @var{LINE}.  The breakpoint causes execution
with @samp{c} to stop when it is reached.
@item c
@tab
The program is run until it ends (which also ends the debugger) or a
breakpoint is reached.
@item d@var{LINE}
@tab
Any breakpoint that may be on line @var{LINE} is removed.
@item e@var{LINE}
@tab
An explanation of the main expression in each command on line @var{LINE}
is printed to the screen.  The explanation is in the same format as the
format produced by @option{-h} (@pxref{-h}) and shows what the optimiser
optimised the expression to (or the original expression if the optimiser
wasn't used).
@item f@var{LINE}
@tab
Removes the effect of the @samp{m} command on line @var{LINE}.
@item g@var{LINE}
@tab
Causes the current command to be the first command on @var{LINE} (if not
on that line already) or the next command on @var{LINE}, as if that line
was @code{NEXT}ed to and then that @code{NEXT} stack item was forgotten.
@item h
@tab
Lists 10 lines either side of the current line; if there aren't 10 lines
to one or the other side of the current line, instead more lines will be
shown on the other side to compensate, if available.
@item i@var{VAR}
@tab
Causes variable @var{VAR} to become @code{IGNORE}d, making it read-only.
@item j@var{VAR}
@tab
Causes variable @var{VAR} to become @code{REMEMBER}ed, making it no
longer read-only.
@item k
@tab
Continues executing commands until the @command{NEXT} stack is the same
size or smaller than it was before.  In other words, if the current
command is not a @command{NEXT} and doesn't have a @command{NEXT FROM}
aiming at it, one command is executed; but if a @command{NEXT} does
happen, execution will continue until that @command{NEXT} returns or is
forgotten.  A breakpoint or the end of the program also end this.
@item l@var{LINE}
@tab
Lists 10 lines of source code either side of line @var{LINE}, the same
way as with @samp{h}, but using a line stated in the command rather than
the current line.
@item m@var{LINE}
@tab
Produces a message onscreen every time a command on line @var{LINE} is
executed, but without interrupting the program.
@item n
@tab
Show the @command{NEXT} stack on the screen.
@item o
@tab
Continue executing commands until the @command{NEXT} stack is smaller
than it was before.  If you are using @command{NEXT}s like procedures,
then this effectively means that the procedure will run until it
returns.  A breakpoint or the end of the program also end this.
@item p
@tab
Displays the value of all onespot and twospot variables.
@item q
@tab
Aborts the current program and exits the debugger.
@item r@var{LINE}
@tab
Reinstates once all abstained commands on line @var{LINE}.
@item s
@tab
Executes one command.
@item t
@tab
Continues execution until the end of the program or a breakpoint: each
command that executes is displayed while this command is running.
@item u@var{LINE}
@tab
Continues execution of the program until just before a command on line
@var{LINE} is run (or a breakpoint or the end of the program).
@item v@var{VAR}
@tab
Adds a `view' on variable @var{VAR} (which must be onespot or twospot),
causing its value to be displayed on the screen whenever a command is
printed on screen (for instance, because the command has just been
stepped past, or due to the @samp{m} or @samp{t} commands).
@item w
@tab
Displays the current line and current command onscreen.
@item x@var{VAR}
@tab
Removes any view and any action that may be associated with it on
variable @var{VAR} (which must be onespot or twospot).
@item y@var{VAR}
@tab
Adds a view on variable @var{VAR}; also causes a break, as if a
breakpoint was reached, whenever the value of that variable changes.
@item z@var{VAR}
@tab
Adds a view on variable @var{VAR}; also causes a break, as if a
breakpoint was reached, whenever that variable's value becomes 0.
@item @var{VAR}
@tab
A onespot or twospot variable written by itself prints out the value of
that variable.
@item <@var{VAR}
@tab
@command{WRITEs IN} a new value for variable @var{VAR}.  Note that input
must be in the normal @samp{ONE TWO THREE} format; input in any other
format will cause error E579 (@pxref{E579}) and as that is a fatal
error, the debugger and program it's debugging will end.
@item *
@tab
Displays the license conditions under which @command{ick} is
distributed.
@item ?
@tab
Displays a summary of what each command does.  (@samp{@@} does the same
thing.)
@end multitable

While the code is executing (for instance, during a @samp{c}, @samp{k},
@samp{o}, @samp{t} or @samp{u} command), it's possible to interrupt it
with @kbd{@key{CTRL}-@key{C}} (on UNIX/Linux) or
@kbd{@key{CTRL}-@key{BREAK}} (on Windows/DOS); this will cause the
current command to finish running and the debugger prompt to come back
up.

@ifset notsplit
@partheading{PART II: THE @ical{} LANGUAGE}
@end ifset
@node Syntax
@chapter Syntax
@cindex syntax, INTERCAL
@cindex INTERCAL, syntax

@ical{} programs consist of a list of statements.  Execution of a
program starts with its first statement; generally speaking each
statement runs after the previous statement, although many situations
can change this.

Whitespace is generally insignificant in @ical{} programs; it cannot be
added in the middle of a keyword (unless the keyword contains whitespace
itself) or inside a decimal number, but it can be added more or less
anywhere else, and it can be removed from anywhere in the program as
well.

An @ical{} statement consists of an optional line label, a statement
identifier, an optional execution chance, the statement itself
(@pxref{Statements}), and optionally @code{ONCE} or @code{AGAIN}.

@menu
* Princeton and Atari Syntax:: There are two syntaxes for @ical{}
* Line Labels::                Allowing lines to be referred to
* Statement Identifiers::      Marking the start of a statement
* Execution Chance::           Statements that might not execute
* ONCE and AGAIN::             Self-abstaining and self-reinstating statements
@end menu

@node Princeton and Atari Syntax
@section Princeton and Atari Syntax
@cindex syntax, dialects
@cindex dialects of syntax
@cindex character sets

The history of @ical{} is plagued with multiple syntaxes and character
sets.  The result has settled down with two versions of the syntax;
the original Princeton syntax, and the Atari syntax (which is more
suited to the operating systems of today).

@cindex syntax, Princeton
@cindex Princeton syntax
@subheading Princeton syntax
@portability{some versions, version 0.18+, all versions, no}

The original @icst{} compiler was the Princeton compiler, which
introduced what has become known as the Princeton syntax for @ical{};
this is the syntax used in the original manual, for instance, and can
be considered to be the `original' or `official' @ical{} syntax.  It
is notable for containing various characters not found in some
character sets; for instance, it writes the operator for mingle as a
cent sign (known as `change').  The other operator that often causes
problems is the bookworm operator @samp{V}, backspace, @samp{-}, which
is used for exclusive-or; the backspace can cause problems on some
systems (which was probably the original intention).  This syntax is
also the default syntax in the @clcic{} compiler, which is the @i{de
facto} standard for expanding the Princeton syntax to modern @ical{}
features that are not found in @icst{}; however, it does not appear to
have been used as the default syntax in any other compilers.
Nowadays, there are other ways to write the required characters than
using backspace; for instance, the cent sign appears in Latin-1 and
UTF-8, and there are various characters that approximate bookworms
(for instance, @clcic{} uses the Latin-1 yen symbol for this, which
just to make things confusing, refers to a mingle in modern Atari
syntax).

@cindex syntax, Atari
@cindex Atari syntax
@subheading Atari syntax
@portability{some versions, yes, version 0.05+, yes}

The other main syntax is the Atari syntax, so called because it was
originally used by the ``Atari implementation'' of @icst{}.  It is not
clear why the implementation was given this name, because the authors
of the implementation are not known; it is not clear whether it has
any connection with Atari other than running on an Atari computer, for
instance.  The syntax was designed to work better on ASCII-based
systems, by avoiding the change character (although it can still be
written as @samp{c}, backspace, @samp{/}, which the Atari compiler
documentation claims that the Princeton compiler supported) in favour
of a `big money' character (@samp{$}), and using the `what' (@samp{?})
as an alternative character for exclusive-or.  This is the syntax that
@cic{} and @jic{} have always used, and is the one most commonly used
for communicating @ical{} programs on Usenet and other similar fora
(where ASCII is one of the most reliable-to-send character sets).  It
is also the syntax used for examples in this manual, for much the same
reason.  The Atari syntax for constructs more modern than @icst{} is
normally taken to be that used by the @cic{} compiler, because it is
the only Atari-syntax-based compiler that contains non-@icst{}
constructs that actually need their own notation.

@node Line Labels
@section Line Labels
@cindex line label
@cindex line number

@portability{yes, all versions, all versions, all versions}

The first part of an @ical{} statement is a line label that specifies
what its line number is.  This is optional; it's allowed to have a
statement without a line number, although that prevents other commands
referring to it by number.  Line numbers must be constants, and unique
within the program.  However, they do not have to be in order; unlike
some other languages with line numbers, a line with a higher number can
come earlier in the program than a line with a lower number, and the
numbers don't affect the order in which commands are executed.

A line label is a integer expressed in decimal within a wax/wane pair
(@code{(} and @code{)}).  For instance, this is a valid line label:

@example
(1000)
@end example

Note that line numbers from 1000 to 1999 are used by the system library,
so using them within your own programs may produce unexpected errors if
the system library is included.  Apart from this, line numbers from 1 to
65535 are allowed.

It has become reasonably customary for people writing @ical{} libraries
to pick a range of 1000 line numbers (for instance, 3000 to 3999) and
stick to that range for all line numbers used in the program (apart from
when calling the system library), so if you want to write an @ical{}
library, it may be a good idea to look at the existing libraries (in the
@file{pit/lib} directory in the @cic{} distribution) and choose a range
of numbers that nobody else has used.  If you aren't writing a library,
it may be a good idea to avoid such number ranges (that is, use only
line numbers below 1000 or very high numbers that are unlikely to be
used by libraries in the future), so that you can easily add libraries
to your program without renumbering in the future.

@node Statement Identifiers
@section Statement Identifiers
@cindex statement identifier
@findex DO
@findex PLEASE
@findex NOT
@findex N'T
@cindex abstain, at program start
@cindex reinstate, at program start
@cindex initial abstention
@cindex abstained state
@cindex reinstated state

@portability{yes, all versions, all versions, all versions}

After the line label (if a statement has one) comes the statement
identifier, which marks where the statement starts.  Either the label or
the statement identifier, whichever one comes first, marks where the
preceding statement finishes.

@anchor{DO}@anchor{PLEASE}
The main statement identifier is @code{DO}.  It also has two synonyms,
@code{PLEASE} and @code{PLEASE DO}; these synonyms are the 'polite'
forms of statement identifiers.  Although the three identifiers have the
same meaning, using either polite or non-polite identifiers too much can
cause an error; the correct proportion is approximately 3 non-polite
identifiers for every polite identifier used.  None of these identifiers
actually does anything else apart from marking where the statement
starts; they leave the statements in the default `reinstated' state.

@anchor{NOT}@anchor{N'T}
Adding @code{NOT} or @code{N'T} to the end of any of these identifiers,
to create a statement identifier such as @code{DO NOT} or @code{PLEASE
DON'T}, also creates a valid statement identifier.  These differ in
meanings from the previous set of identifiers, though; they cause the
statement they precede to not be executed by default; that is, the
command will be skipped during execution (this is known as the
`abstained' state).  This applies even if the command in question is in
fact a syntax error, thus causing this to be a useful method of writing
comments.  One common idiom is to write code like this:

@example
PLEASE NOTE: This is a comment.
@end example

The statement identifier (@code{PLEASE NOT}) is the only part of this
statement that is valid @ical{}; however, because the statement
identifier is in the negated form that contains @code{NOT}, the syntax
error won't be executed, and therefore this is a valid statement.  (In
@ical{}, syntax errors happen at runtime, so a program containing a
statement like @code{DOUBT THIS WILL WORK} will still compile, and will
not end due to the syntax error unless that statement is actually
executed.  @xref{E000}.)

The @code{ABSTAIN} and @code{REINSTATE} statements can override the
@code{NOT} or otherwise on a statement identifier; see @ref{ABSTAIN}.

In backtracking programs, @code{MAYBE} is also a valid statement
identifier; see @ref{MAYBE}.  It comes before the other keywords in the
statement identifier, and an implicit @code{DO} is added if there wasn't
one already in the statement identifier (so @code{MAYBE}, @code{MAYBE
DO}, @code{MAYBE DON'T}, @code{MAYBE PLEASE}, and so on are all valid
statement identifiers).

@node Execution Chance
@section Execution Chance
@cindex execution chance
@cindex double-oh-seven
@findex %

@portability{yes, all versions, version 0.02+, all versions}

It's possible to specify that a command should be run only a certain
proportion of the time, at random.  This is a rarely used feature of
@ical{}, although it is the only way to introduce randomness into a
program.  (The @cic{} compiler approximates this with pseudorandomness.)
An execution chance specification comes immediately after the statement
identifier, but before the rest of the statement, and consists of a
double-oh-seven (@code{%}) followed by an integer from 1 to 99
inclusive, written in decimal; this gives the percentage chance of the
statement running.  The execution chance only acts to prevent a
statement running when it otherwise would have run; it cannot cause a
statement that would otherwise not have run to run.  For instance, the
statement @code{DO %40 WRITE OUT #1} has a 40% chance of writing out
@samp{I}, but the statement @code{DON'T %40 WRITE OUT #1} has no chance
of writing out @code{I} or anything else, because the @code{N'T}
prevents it running and the double-oh-seven cannot override that.

@node ONCE and AGAIN
@section ONCE and AGAIN
@cindex ABSTAIN, self-abstaining
@cindex REINSTATE, self-reinstating
@cindex self-abstaining
@cindex self-reinstating
@findex ONCE
@findex AGAIN
@anchor{ONCE}@anchor{AGAIN}

@portability{no, version 0.25+, no, no}

The last part of a statement is an optional @code{ONCE} or @code{AGAIN}.
@code{ONCE} specifies that the statement is self-abstaining or
self-reinstating (this will be explained below); @code{AGAIN} specifies
that the statement should behave like it has already self-reinstated or
self-abstained.  Whether the behaviour is self-abstention or
self-reinstatement depends on whether the statement was initially
abstained or not; a @code{ONCE} on an initially reinstated statement or
@code{AGAIN} on an initially abstained statement indicates a
self-abstention, and a @code{ONCE} on an initially abstained statement
or @code{AGAIN} on an initially reinstated statement indicates a
self-reinstatement.

The first time a self-abstaining statement is encountered, it is
executed as normal, but the statement is then abstained from and
therefore will not run in future.  Likewise, the first time
self-reinstating statement is encountered, it is not executed (as is
normal for an abstained statement), but then becomes reinstated and will
run in future.  In each of these cases, the @code{ONCE} effectively
changes to an @code{AGAIN}; the @code{ONCE} only happens once, as might
be expected.

@code{REINSTATING} a currently abstained self-abstaining statement or
@code{ABSTAINING} (that is, with the @code{ABSTAIN} or @code{REINSTATE}
commands) a currently reinstated self-reinstating statement causes the
@code{AGAIN} on the statement to change back into a @code{ONCE}, so the
statement will again self-abstain or self-reinstate.  Likewise,
@code{REINSTATING} a currently abstained self-reinstating statement or
@code{ABSTAINING} a currently reinstated self-abstaining statement
causes its @code{ONCE} to turn into an @code{AGAIN}.

Historical note: @code{ONCE} was devised by Malcom Ryan as a method of
allowing synchronisation between threads in a multithreaded program
(@code{ONCE} is atomic with the statement it modifies, that is, there is
no chance that threads will change between the statement and the
@code{ONCE}).  @code{AGAIN} was added to Malcom Ryan's Threaded Intercal
standard on the suggestion of Kyle Dean, as a method of adding extra
flexibility (and to allow the @code{ONCE}s to happen multiple times,
which is needed to implement some multithreaded algorithms).

@node Expressions
@chapter Expressions
@cindex expressions

Many @ical{} statements take expressions as arguments.  Expressions are
made up out of operands and operators between them.  Note that there is
no operator precedence in @ical{}; different compilers resolve
ambiguities different ways, and some versions of some compilers
(including the original @icst{} compiler) will cause error messages on
compiling or executing an ambiguous expression, so it's safest to fully
group each expression.

@menu
* Constants and Variables::      The basic operands that make up expressions
* Grouping Rules::               How to specify grouping in expressions
* Operators::                    Joining operands into more complex expressions
@end menu

@node Constants and Variables
@section Constants and Variables
@cindex constant
@cindex variable
@cindex mesh
@cindex onespot
@cindex twospot
@cindex tail
@cindex hybrid
@findex #
@findex .
@findex :
@findex ,
@findex ;

@portability{yes, all versions, all versions, all versions}

The basic operands in @ical{} are constants and variables.  These
together make up what in other languages are known as `lvalues', that
is, operands to which values can be assigned.  (Constants can also be
lvalues in @ical{}, but by default @cic{} turns this off because it
carries an efficiency penalty and can be confusing; this can be turned
on with the @option{-v} option (@pxref{-v}).)

Constants can have any integer value from 0 to 65535 inclusive; higher
values (up to 4294967295) can be generated in programs, but cannot be
specified literally as constants.  (The usual way to work around this
limitation is to interleave two constants together; see @ref{Mingle}.) A
constant is written as a mesh (@code{#}) followed by a number in
decimal.  At the start of the program, all constants have the same value
as the number that identifies them; for instance, @code{#100} has 100 as
its value, and it's strongly advised not to change the value of a
constant during the execution of a program.

There are four types of variable: 16-bit and 32-bit unsigned integers,
and arrays of 16-bit and 32-bit unsigned integers.  These are
represented with a spot, twospot, tail, and hybrid (@code{.}, @code{:},
@code{,}, and @code{;}) respectively.  For this reason, integers within
the range 0 to 65535 inclusive are known as `onespot numbers', and
integers within the range 0 to 4294967295 inclusive are known as
`twospot numbers'; variables with those ranges are known as onespot and
twospot variables.  (Note that arrays did not work in @cic{} before
version 0.7.)

Variables are represented with a character representing their data type,
followed by an integer from 1 to 65535 inclusive, written in decimal.
Non-array variables don't need to be declared before they are used; they
automatically exist in any program that uses them.  For instance,
@code{.1} and @code{.001} are the same variable, onespot number 1.
Array variables need to be dimensioned before they are used, by
assigning dimensions to them; see @ref{Calculate}.

@node Grouping Rules
@section Grouping Rules
@cindex grouping rules
@cindex positional precedence
@cindex spark
@cindex rabbit-ears
@cindex ears
@findex '
@findex "

Because there are no operator precedences in @ical{}, there are various
solutions to specifying what precedences actually are.

@table @asis

@item The portable solution

All known versions of @ical{} accept the @icst{} grouping rules.  These
state that it's possible to specify that an operator takes precedence by
grouping it inside sparks (@code{'}) or rabbit-ears (@code{"}), the same
way as wax/wane pairs (parentheses) are used in other programming
languages.  @icst{} and earlier @cic{} versions demanded that
expressions were grouped fully like this, and this practice is still
recommended because it leads to portable programs and is easier to
understand.  Whether sparks or rabbit-ears (often called just `ears' for
short) are used normally doesn't matter, and programmers can use one or
the other for clarity or for aesthetic appeal.  (One common technique is
to use just sparks at the outermost level of grouping, just ears at the
next level, just sparks at the next level, and so on; but expressions
like @code{''#1~#2'~"#3~#4"'~#5} are completely unambiguous, at least to
the compiler.)

There are, however, some complicated situations involving array
subscripting where it is necessary to use sparks and ears at alternate
levels, if you want to write a portable program.  This limitation is in
@cic{} to simplify the parsing process; @icst{} has the same limitation,
probably for the same reason.  Compare these two statements:

@example
DO .1 <- ,3SUB",2SUB.1".2
DO .1 <- ,3SUB",2SUB.1".2~.3"".4
@end example

The problem is that in the first statement, the ears close a group, and
in the second statement, the ears open a group, and it's impossible to
tell the difference without unlimited lookahead in the expression.
Therefore, in similar situations (to be precise, in situations where a
group is opened inside an array subscript), it's necessary to use the
other grouping character to the one that opened the current group if you
want a portable program.

One final comment about sparks and rabbit-ears; if the next character in
the program is a spot, as often happens because onespot variables are
common choices for operands, a spark and the following spot can be
combined into a wow (@code{!}).  Unfortunately, none of the character
sets that @cic{} accepts as input (UTF-8, Latin-1, and ASCII-7) contain
the rabbit character, although the Hollerith input format that @clcic{}
can use does.

@item Positional precedences: @clcic{} rules

The precedence rules used by @clcic{} for grouping when full grouping
isn't used are simple to explain: the largest part of the input that
looks like an expression is taken to be that expression.  The main
practical upshot of this is that binary operators right-associate; that
is, @code{.1~.2~.3} is equivalent to @code{.1~'.2~.3'}.  @cic{} versions
0.26 and later also right-associate binary operators so as to produce
the same results as @clcic{} rules in this situation, but as nobody has
yet tried to work out what the other implications of @clcic{} rules are
they are not emulated in @cic{}, except possibly by chance.

@ianchor Prefix and infix unary operators
@cindex unary operator, prefix
@cindex unary operator, infix

In @icst{} and versions of @cic{} before 0.26, unary operators were
always in the `infix' position.  (If you're confused about how you can
have an infix unary operator: they go one character inside a group that
they apply to, or one character after the start of a constant or
variable representation; so for instance, to portably apply the unary
operator @code{&} to the variable @code{:1}, write @code{:&1}, and to
portably apply it to the expression @code{'.1~.2'}, write
@code{'&.1~.2'}.)  @clcic{}, and versions of @cic{} from 0.26 onwards,
allow the `prefix' position of a unary operator, which is just before
whatever it applies to (as in @code{&:1}).  This leads to ambiguities as
to whether an operator is prefix or infix.  The portable solution is, of
course, to use only infix operators and fully group everything, but when
writing for recent versions of @cic{}, it's possible to rely on its
grouping rule, which is: unary operators are interpreted as infix where
possible, but at most one infix operator is allowed to apply to each
variable, constant, or group, and infix operators can't apply to
anything else.  So for instance, the @cic{} @code{'&&&.1~.2'} is
equivalent to the portable @code{'&"&.&1"~.2'} (or the more readable
version of this, @code{"&'"&.&1"~.2'"}, which is also portable).  If
these rules are counter-intuitive to you, remember that this is @ical{}
we're talking about; note also that this rule is unique to @cic{}, at
least at the time of writing, and in particular @clcic{} is likely to
interpret this expression differently.

@end table

@node Operators
@section Operators
@cindex operator

Operators are used to operate on operands, to produce more complicated
expressions that actually calculate something rather than just fetch
information from memory.  There are two types of operators, unary and
binary operators, which operate on one and two arguments respectively.
Binary operators are always written between their two operands; to
portably write a unary operator, it should be in the `infix' position,
one character after the start of its operand; see @ref{Prefix and infix
unary operators} for the full details of how to write unary operators
portably, and how else you can use them if you aren't aiming for
portability.  This section only describes @icst{} operators; many
@ical{} extensions add their own operators.

@menu
* Mingle::                   Interleaving bits in two operands
* Select::                   Selecting from one operand according to another
* Unary Binary Logic::       Binary logic on adjacent bits of an operand
* Array Subscript::          Selecting elements of arrays
@end menu

@node Mingle
@subsection Mingle
@cindex mingle
@cindex interleave
@findex $

@portability {yes, all versions, all versions, all versions}

Mingle, or interleave, is one of the two binary operators in @icst{}.
However, different @ical{} compilers represent it in different ways, so
it is impossible to write a mingle in a program completely portably,
because it differs between Princeton and Atari syntax, and worse, the
sequence of character codes needed to represent it in each syntax has
varied from compiler to compiler.

The original @icst{} compiler (the Princeton compiler) used the
'change' (cent) character for a mingle, represented as @code{c},
backspace, @code{/}.  (By the way, this is still the most portable way
to write a mingle; both @cic{} and @clcic{} accept it, at least if a
lowercase @code{c} is used, the Atari compiler accepted it, and its
documentation claimed that the Princeton compiler also accepted it;
@clcic{} also accepts a capital @code{C} before the backspace and
@code{/}, and allows @code{|} rather than @code{/}.)  The Atari
compiler, another @icst{} compiler, used a 'big money' character
(@code{$}) as the mingle character; this character is also the only
one accepted for mingle by the @jic{} compiler.  @cic{} originally
also used the @code{$} character for mingle, and this character is the
one most commonly seen in existing @cic{} programs, and most often
used when giving examples of @ical{} on Usenet, because it exists in
the ASCII-7 character set, and because it doesn't contain control
characters.  From version 0.18 of @cic{} onwards, various other units
of currency (change, quid, and zlotnik if Latin-1 is used as the
input, and euro if Latin-9 is used as the input) are accepted; from
version 0.20 onwards, in addition to the Latin-1 characters, all the
currency symbols in Unicode are accepted if UTF-8 is used as the input
format.  @clcic{} has always used the change character (either the
Latin-1 version or the version that contains a backspace) for mingle.
In this manual, mingle will be represented as @code{$}, but it's
important to bear in mind that this character is not the most portable
choice.

The mingle operator should be applied to two operands or expressions.
To be portable, the operands must both be onespot expressions, that is
expressions which have a 16-bit result; @cic{} relaxes this rule
slightly and only requires that the result be in the onespot range.
(This is because the data type of a select operator's value is meant to
be determined at runtime; @cic{} determines all data types at compile
time, so has to guess a 32-bit result for a select with a 32-bit type as
its right operand even when the result might actually turn out to be of
a 16-bit type, and so this behaviour prevents an error when a select
operation returns a value with a 16-bit data type and is used as an
argument to a mingle.)  The result is a 32-bit value (that is, it is of a
32-bit data type, even if its value fits into the onespot range), which
consists of bits alternated from the two arguments; to be precise, its
most significant bit is the most significant bit of its first argument,
its second most significant bit is the most significant bit of its
second argument, its third most significant bit is the second most
significant bit of its first argument, and so on until its least
significant bit, which is the least significant bit of its second
argument.

One of the most common uses of interleaving is to create a constant with
a value greater than 65535; for instance, 65536 is @code{#256$#0}.  It
is also commonly used in expressions that need to produce 32-bit
results; except in some simple cases, this is usually coded by
calculating separately the odd-numbered and even-numbered bits of the
result, and mingling them together at the end.  It is also used in
expressions that need to left-shift values or perform similar
value-increasing operations, as none of the other operators can easily
do this; and mingle results are commonly used as the argument to unary
binary logic operators, because this causes them to behave more like the
binary logic operators found in some other languages.

@node Select
@subsection Select

@portability{yes, all versions, all versions, all versions}

The select operator is one of the two binary operators in @icst{};
unlike mingle, every known implementation of @ical{} ever has used the
sqiggle character (@code{~}) as the representation of the select
operator, meaning that writing it portably is easy.

The select operator takes two arguments, which can be of either
datatype (that is, 16- or 32-bit).  It returns a value made by
selecting certain bits of its first operand indicated by the second
operand, and right-justifying them.  What it does is that it ignores
all the bits of the first operand where the second operand has a 0 as
the corresponding bit, that is, deletes them from a copy of the
operand's value; the bits that are left are squashed together towards
the least-significant end of the number, and the result is filled with
0s to make it up to 16 or 32 bits.  (In @icst{} the minimum multiple
of 16 bits possible that the result fits into is chosen, although if
:1 has the value 131061 (in hex, 1FFFF) the expression @code{#21~:1}
produces a 32-bit result because 17 bits were selected, even though
many of the leading bits were zeros; in @cic{} the data type of the
result is the same as of the right operand of the select, so that it
can be determined at compile time, and so using a unary binary logic
operator on the result of select when the right operand has a 32-bit
type is nonportable and not recommended.)  As an example,
@code{#21~:1} produces 21 as its result if :1 has the value 131061, 10
as its result if :1 has the value 30 (1E in hex; the least significant
bit of 21 is removed because it corresponds to a 0 in :1), and 7 as
its result if :1 has the value 21 (because three bits in 21 are set,
and those three bits from 21 are therefore selected by 21).

Select is used for right-shifts, to select every second bit from a
number (either to produce what will eventually become an argument to
mingle, or to interpret the result of a unary binary logic operator, or
occasionally both), to test if a number is zero or not (by selecting it
from itself and selecting 1 from the result), in some cases as a limited
version of bitwise-and (that only works if the right operand is 1 less
than a power of 2), and for many other purposes.

@node Unary Binary Logic
@subsection Unary Binary Logic
@cindex unary binary logic
@cindex and
@cindex or
@cindex xor
@cindex exor
@cindex exclusive or
@findex ?
@findex &
@findex V
@cindex what
@cindex ampersand
@cindex book

@portability{yes, all versions, all versions, all versions}

There are three unary operators in @icst{}, each of which carries out
a binary logic operation on adjacent bits of the number. The operators
are and, or, and exclusive or; and and or are represented by an
ampersand (@code{&}) and book (@code{V}) respectively, and exclusive
or has the same notational problems as mingle, as it differs between
Princeton and Atari syntax.  It was represented by a bookworm, written
@code{V}, backspace, @code{-}, in the Princeton @icst{}
implementation, and this is still the most portable way to write it
(@cic{} and @clcic{} accept it).  The Atari implementation of @icst{}
wrote it with a what (@code{?}), and this is the representation
originally used by @cic{} (and still accepted), the only
representation accepted by @jic{}, the one most commonly used on
Usenet, and the one used in this manual (although again, it's worth
pointing out that this isn't portable).  @clcic{} approximates a
bookworm with the yen character, which being a currency character is
one of the possible representations for mingle in @cic{}; @cic{} uses
the rather confusing method of interpreting a yen character as
exclusive-or if input in Latin-1 but as mingle if input in UTF-8.
(This usually does the right thing, because @clcic{} doesn't support
UTF-8.)  In the same way, @clcic{} has a @cic{} compatibility option
to allow the use of @code{?} for exclusive-or.

The operators take each pair of consecutive bits in their arguments
(that is, the least significant with the second least significant, the
second least significant with the third least significant, the third
least significant with the fourth least significant, and so on, with the
pair consisting of the most significant and least significant being used
to calculate the most significant bit of the result), and perform an
appropriate logic operation on them; and sets a bit of the result if and
only if both bits in the pair were set, or sets each bit corresponding to
each pair where either bit was set, and exclusive or sets if and only if
the bits in the pair had different values (that is, one was set, but not
both).  So for instance, @code{#&26} is 16 (26 is 1A in hexadecimal or
11010 in binary); @code{#V26} is 31 (11111 in binary), and @code{#?26}
is 23 (10111 in binary).

The most commonly seen use for these operators is to carry out bitwise
ands, ors, and exclusive ors between two different 16-bit expressions,
by mingling them together, applying a unary binary logic operator, and
selecting every second bit of the result; such code often results due to
people thinking in terms of some other language when writing @ical{},
but is still often useful.  (Historically, the first idiom added to the
optimizer, apart from constant folding, was the mingle/unary/select
sequence.)  There are more imaginative uses; one impressive example is
the exclusive or in the test for greater-than from the original @icst{}
system library:

@example
DO :5 <- "'?":1~'#65535$#0'"$":2~'#65535$#0'"'
     ~'#0$#65535'"$"'?":1~'#0$#65535'"$":2~'#0$
     #65535'"'~'#0$#65535'"
DO .5 <- '?"'&"':2~:5'~'"'?"'?":5~:5"~"#65535~
     #65535"'~'#65535$#0'"$#32768'~'#0$#65535'"
     $"'?":5~:5"~"#65535$#65535"'~'#0$#65535'"'
     "$"':5~:5'~#1"'~#1"$#2'~#3
@end example

The first statement works out the value of :1 bitwise exclusive or :2;
the second statement then works out whether the most significant set bit
in :5 (that is, the most significant bit that differs between :1 and :2)
corresponds to a set bit in :2 or not.  In case that's a bit too
confusing to read, here's the corresponding optimizer idiom (in OIL):

@example
((_1~:2)~((?32(:2~:2))^#2147483648))->(_1>(:2^_1))
@end example

(Here, the ^ refers to a bitwise exclusive or, an operation found in OIL
but not in @ical{}, which is why the @ical{} version is so much longer.)
The @ical{} version also has some extra code to check for equality and
to produce 1 or 2 as the output rather than 0 or 1.

@node Array Subscript
@subsection Array Subscript
@cindex arrays, subscripting
@cindex subscripts
@findex SUB

@portability{yes, version 0.7+, all versions, all versions}

In order to access the elements of an array, either to read or write
the array, it is necessary to use the array subscript operator
@code{SUB}.  Note that an array element is not a variable, so it is
not accepted as an acceptable argument to statements like
@code{IGNORE}; however, it can be assigned to.

The syntax for an array element is the array, followed by the keyword
@code{SUB}, followed by an expression for the element number in the
array.  In the case of a multidimensional array, more than one
expression is given after the keyword @code{SUB} to give the location
of the element in each of the array's dimensions.  The first element
in an array or array dimension is numbered 1.

For instance, this is a legal (but not particularly useful) @ical{}
program with no syntax errors that shows some of the syntaxes possible
with array subscripting:

@example
PLEASE ,1 <- #2
DO .1 <- #2
DO ,1 SUB .1 <- #1
DO ,1 SUB #1 <- ,1 SUB #2
PLEASE ;1 <- #2 BY #2
DO ;1 SUB #1 #2 <- ,1 SUB ,1 SUB .1
DO READ OUT ;1SUB#1.1
DO GIVE UP
@end example

Grouping can get complicated when nested array subscripting is used,
particularly with multiple subscripts.  It is the programmer's job to
write an unambiguous statement, and also obey the extra grouping rules
that apply to array subscripts; see @ref{Grouping Rules}.

@node Statements
@chapter Statements
@cindex statements
@cindex statements, INTERCAL

There is a wide range of statements available to @ical{} programs;
some identifiably belong to a particular variant or dialect (such as
Backtracking @ical{}), but others can be considered to be part of the
'core language'.  The statements listed here are those that the @cic{}
compiler will accept with no compiler switches to turn on particular
dialect options.  Note that many statements have slightly different
effects in different implementations of @ical{}; known
incompatibilities are listed here, but it's important to check your
program on multiple compilers when attempting to write a portable
program.

@menu
* Syntax Error::              Why use a deliberate syntax error?
* Calculate::                 Assigning to variables and arrays
* NEXT FORGET and RESUME::    @icst{}-style flow control
* STASH and RETRIEVE::        Value stacks and scoping
* IGNORE and REMEMBER::       Creating read-only variables
* ABSTAIN and REINSTATE::     Dynamic DOs and DON'Ts
* READ OUT and WRITE IN::     @ical{} input and output
* GIVE UP::                   How to end a program
* TRY AGAIN::                 Control flow without loops
* COME FROM and NEXT FROM::   Time-reversed GOTO
@end menu

@node Syntax Error
@section Syntax Error
@cindex syntax error
@cindex comment
@findex COMMENT
@findex COMMENTS
@findex COMMENTING
@portability{yes,version 0.15+,all versions,all versions}

One of the more commonly-used commands in @ical{} is the syntax error.
A properly-written syntax error looks nothing like any known @ical{}
command; a syntax error that looks vaguely like a command but isn't
may confuse @cic{} before version 0.28, and possibly other compilers,
into bailing out at compile time in some situations (this is known as
a `serious syntax error'), and so is not portable.  For other syntax
errors, though, the semantics are easily explained: there is a
run-time error whenever the syntax error is actually executed, and the
line containing the syntax error is used as the error message.

One purpose of this is to allow your programs to produce their own
custom errors at run time; however, it's very important to make sure
that they start and end in the right place, by manipulating where
statement identifiers appear.  Here's a correct example from the
system library:

@example
DOUBLE OR SINGLE PRECISION ARITHMETIC OVERFLOW
@end example

This is a valid @ical{} command, that produces an error when run (note
the @code{DO} at the start).  An even more common use is to produce an
initially abstained syntax error by using an appropriate statement
identifier, for instance

@example
PLEASE NOTE THAT THIS IS A COMMENT
@end example

This would produce an error if reinstated somehow, but assuming that
this isn't done, this is a line of code that does nothing, which is
therefore equivalent to a comment in other programming languages.
(The initial abstention is achieved with the statement identifier
@code{PLEASE NOT}; the extra @code{E} causes the command to be a
syntax error, and this particular construction is idiomatic.)

Referring to the set of all syntax errors in a program (or the set of
all commands of any other given type) is achieved with a special
keyword known as a `gerund'; gerund support for syntax errors is
resonably recent, and only exists in @clcic{} (version 1.-94.-3 and
later, with @code{COMMENT}, @code{COMMENTS}, or @code{COMMENTING}),
and @cic{} (@code{COMMENT} in version 0.26 and later, and also
@code{COMMENTS} and @code{COMMENTING} in version 0.27 and later).
Therefore, it is not portable to refer to the set of all syntax errors
by gerund; using a line label is a more portable way to refer to an
individual syntax-error command.

@node Calculate
@section Calculate
@findex CALCULATING
@cindex calculate
@cindex assignment
@cindex arrays, dimensioning
@cindex dimensioning arrays
@cindex variables, assignment
@portability{yes, all versions, all versions, all versions}

At present, the only @ical{} command that contains no keywords (apart
from the statement identifier and possibly @code{ONCE} or
@code{AGAIN}) is what is known as the `calculate' command.  It is used
to assign values to variables, array elements, and arrays; assigning a
value to an array changes the number of elements that that array can
hold, and causes the values of all elements previously in that array
to be lost.  The syntax of a calculate command is as follows:

@example
DO .1 <- ':2~:3'~#55
@end example

That is, the command is written as a variable or array element, then
the @code{<-} operator (known as an `angle-worm' and pronounced
`gets'), then an expression to assign to it.  In the special case when
an array is being dimensioned by assigning a value to it, the
expression can contain the keyword @code{BY} to cause the array to
become multidimensional; so for a 3 by 4 by 5 array, it would be
possible to write

@example
DO ,1 <- #3 BY #4 BY #5
@end example

The calculate command always evaluates the expression, even if for
some reason the assignment can't be done (for instance, if the
variable being assigned to is read-only); this is important if the
expression has side-effects (for instance, giving an overflow error).
If the variable does happen to be read-only, there is not an error;
the expression being assigned to it is just evaluated, with the
resulting value being discarded.

The gerund to refer to calculations is @code{CALCULATING}; however, if
you are planning to use this, note that a bug in older versions of
@cic{} means that assignments to arrays are not affected by this
gerund before version 0.27.

@clcic{} from 1.-94.-4 onwards, and @cic{} from 0.26 onwards, allow
arbitrary expressions on the left hand side of an assignment (@cic{}
only if the @code{-v} option is used); for more information on how
such `reverse assignments' work, see @ref{Operand Overloading}.

@node NEXT FORGET and RESUME
@section NEXT, FORGET and RESUME
@findex NEXT
@findex FORGET
@findex RESUME
@findex NEXTING
@findex FORGETTING
@findex RESUMING
@cindex NEXT stack
@cindex flow control, INTERCAL-72
@cindex stack, NEXT
@cindex stack, instruction pointer
@anchor{NEXT}
@anchor{FORGET}
@anchor{RESUME}
@portability{yes, all versions, see text, all versions}

The only flow-control commands in @icst{} were @code{NEXT},
@code{RESUME}, and @code{FORGET}; together these manipulate a stack of
locations in the program known as the `NEXT stack'.  Although all
@ical{} compilers have implemented these, from @clcic{} version 0.05
onwards @clcic{} has considered them obsolete, and therefore a special
command-line switch needs to be used to enable them.  (They are still
the most portable flow-control commands currently available, though,
precisely because @icst{} implements nothing else.)  Note that there
is a strict limit of 80 locations on the NEXT stack, enforced by all
known @ical{} compilers; this helps to enforce good programming style,
by discouraging NEXT-stack leaks (which are otherwise quite easy to
write).

Here are examples to show the syntax of these three statements:

@example
DO (1000) NEXT
DO FORGET '.1~.1'~#1
DO RESUME .5
@end example

The @code{NEXT} command takes a line label as its argument (unlike
most other @ical{} commands, it comes after its argument rather than
before); both @code{FORGET} and @code{RESUME} take expressions.
(@clcic{} from version 0.05 onwards also allows an expression in
@code{NEXT}, rather than a label, to give a computed @code{NEXT}, but
this behaviour was not implemented in other compilers, and is
deprecated in @clcic{} along with noncomputed @code{NEXT}; if computed
@code{NEXT} is ever implemented in @cic{}, it will likely likewise be
deprecated upon introduction).  (Update: it was implemented in @cic{}
version 0.28, but only as part of the external calls system, so it
cannot be used in ordinary programs; a sample expansion library gives
in-program access to a limited form of computed @code{NEXT}, but
should probably not be used.)  Running a @code{NEXT} causes the
program control to transfer to the command whose line label is
referenced, and also saves the location in the program immediately
after the @code{NEXT} command on the top of the NEXT stack.

In order to remove items from the @code{NEXT} stack, to prevent it
filling up (which is what happens with a naive attempt to use the
@code{NEXT} command as an equivalent to what some other languages call
GOTO), it is possible to use the @code{FORGET} or @code{RESUME}
commands.  They each remove a number of items from the NEXT stack
equal to their argument; @code{RESUME} also transfers control flow to
the last location removed from the @code{NEXT} stack this way.  Trying
to remove no items, or more items than there are in the stack, does
not cause an error when @code{FORGET} is used (no items or all the
items are removed respectively); however, both of these cases are
errors in a @code{RESUME} statement.

Traditionally, boolean values in @ical{} programs have been stored
using #1 and #2 as the two logic levels.  This is because the easiest
way to implement an if-like construct in @icst{} is by @code{NEXTING},
then @code{NEXTING} again, then @code{RESUMING} either by 1 or 2
according to an expression, and then if the expression evaluated to 1
@code{FORGETTING} the remaining NEXT stack entry.  By the way, the
previous sentence also explained what the appropriate gerunds are for
@code{NEXT}, @code{RESUME}, and @code{FORGET}.

@node STASH and RETRIEVE
@section STASH and RETRIEVE
@anchor{STASH}
@anchor{RETRIEVE}
@findex STASH
@findex RETRIEVE
@findex STASHING
@findex RETRIEVING
@cindex stack, variable
@cindex stashes
@cindex variables, stashes
@portability{yes, all versions, all versions, all versions}

The NEXT stack is not the only stack available in an @ical{} program;
each variable used in the program also has its own stack, which holds
values of the same type as the variable.  The @code{STASH} command
pushes a variable's value onto that variable's stack; @code{RETRIEVE}
can be used in the same way to pop the top element of a variable's
stack to replace that variable's value.  The syntax is the same as
most other @ical{} commands, with the word @code{STASH} or
@code{RETRIEVE} followed by the variable or variables to stash or
retrieve:

@example
DO STASH .1 + ;2
DO RETRIEVE ,3
@end example

Note that it is possible to stash or retrieve multiple variables at
once, by listing their names separated by intersections (@code{+});
it's even possible to stash or retrieve a variable twice in the same
statement.

It is not entirely clear how @code{RETRIEVE} interacts with
@code{IGNORE} in historical @icst{} compilers; the three modern
@ical{} compilers all use different rules for the interaction (and the
@cic{} maintainers recommend that if anyone decides to write their own
compiler, they choose yet another different rule so that looking at
the interaction (the so-called `ignorret test') can be used as a
method of determining which compiler is running):

@cindex @code{IGNORE}/@code{RETRIEVE} interaction
@cindex @code{RETRIEVE}/@code{IGNORE} interaction
@cindex ignorret test
@itemize
@item
@cic{} treats a retrieval just like an assignment.  That is, a
read-only variable will not be changed by a retrieval, and will remain
read-only, but the side-effect of popping that variable's stash will
still happen.

@item
@jic{} ignores the read-only status of a variable when retrieving it
from a stash; the value of the variable changes despite being
read-only.  The variable remains read-only; the @code{RETRIEVE} simply
allows a change to its value despite the read-only status.

@item
@clcic{} is the most complicated; it stores read-only status or
otherwise in the stash, along with the variable's value.  This means
that if a variable was stashed when read-only, retrieving it will
retrieve its value and set it to read-only regardless of its previous
read-only status; likewise, if a variable was stashed when read-write,
retrieving it will retrieve its value and set it to read-write even if
it was previously read-only.

@end itemize

The appropriate gerunds for @code{STASH} and @code{RETRIEVE} are
@code{STASHING} and @code{RETRIEVING} respectively.

@node IGNORE and REMEMBER
@section IGNORE and REMEMBER
@anchor{IGNORE}
@anchor{REMEMBER}
@findex IGNORE
@findex IGNORING
@findex REMEMBER
@findex REMEMBERING
@cindex variables, read-only
@cindex variables, read-write
@cindex read-only variables
@cindex read-write variables
@cindex variables, ignoring
@cindex variables, remembering
@portability{yes, all versions, all versions, all versions}

Variables in @ical{} can be either read-write or read-only.  At the
start of a program, all variables are read-write, but this status can
be changed dynamically during execution of a program using the
@code{IGNORE} and @code{REMEMBER} statements (whose gerunds are
@code{IGNORING} and @code{REMEMBERING} respectively).  The syntax is
the same as for @code{STASH} and @code{RETRIEVE}: the command's name
followed by an intersection-separated list of variables.  For
instance:

@example
DO IGNORE .4
DO REMEMBER ,4 + ;5
@end example

Using the @code{IGNORE} statement sets a variable to be read-only (or
does nothing if it's read-only already); @code{REMEMBER} sets it to be
read-write.  Any attempt to assign to a read-only variable silently
fails.  One place that this is used is in the system library; instead
of not assigning to a variable in certain control flow paths, it
instead sets it to be read-only so that subsequent assignments don't
change its value (and sets it to be read-write at the end, which
succeeds even if it was never set read-only in the first place); the
advantage of this is that it doesn't need to remember what flow path
it's on except in the variable's ignorance status.

The interaction between @code{IGNORE} and @code{RETRIEVE} was never
defined very clearly, and is in fact different in @cic{}, @clcic{} and
@jic{}; for more details, see @ref{RETRIEVE}.

@node ABSTAIN and REINSTATE
@section ABSTAIN and REINSTATE
@anchor{ABSTAIN}
@anchor{REINSTATE}
@findex ABSTAIN
@findex ABSTAINING
@findex REINSTATE
@findex REINSTATING
@cindex abstain, during execution
@cindex reinstate, during execution
@portability{yes, all versions, all versions, all versions}

The statement identifier of a statement determines whether it's
in an abstained or reinstated state at the start of a program; these
states determine whether the statement runs at all when it's
encountered.  It is, however, possible to change this state
dynamically during a program's execution, and the statements to do
this are rather appropriately named @code{ABSTAIN} and
@code{REINSTATE}.  There are two forms of each, one which takes a
single line label (which must be constant in most compilers, but can
instead be an expression in recent @clcic{} versions), and one which
takes an intersection-delimited list of gerunds.  They look like this:

@example
DO ABSTAIN FROM ABSTAINING + REINSTATING
DO ABSTAIN FROM (10)
DO REINSTATE CALCULATING
DO REINSTATE (22)
@end example

(This also illustrates the gerunds used for these commands; note that
@code{ABSTAINING} from @code{REINSTATING} is generally a bad idea@!)
The line referenced, or every command represented by any gerund
referenced, are reinstated or abstained as appropriate (effectively
changing the DO to DON'T (or PLEASE to PLEASE DON'T, etc.@:), or vice
versa).  Using these forms of @code{ABSTAIN} and/or @code{REINSTATE}
won't abstain from a command that's already abstained, or reinstate a
command that's already reinstated.

There is a strange set of restrictions on @code{ABSTAIN} and
@code{REINSTATE} that has existed since @icst{}; historically such
restrictions have not always been implemented, or have not been
implemented properly.  They together define an unusual interaction of
@code{ABSTAIN} and @code{GIVE UP} (note, for instance, that there
isn't a gerund for @code{GIVE UP}).  The wording used in the @icst{}
manual is:

@quotation
[...] the statement DO ABSTAIN FROM GIVING UP is not accepted, even
though DON'T GIVE UP is. [...] DO REINSTATE GIVING UP is invalid, and
attempting to REINSTATE a GIVE UP statement by line label will have no
effect.  Note that this insures that DON'T GIVE UP will always be a
"do-nothing" statement.
@end quotation

This restriction was not implemented at all in the only @clcic{}
version before 0.02 (i.e.@: version 0.01), or in @cic{} versions
before 1.26.  The restriction was implemented in @cic{} version 1.26
and @clcic{} versions 0.02 and later as ``@code{GIVE UP} cannot be
@code{REINSTATED} or @code{ABSTAINED FROM}''; however, this is not
strictly the same as the definition used by @icst{} (@cic{} still uses
this definition in @clcic{} compatibility mode).  The @jic{}
implementation of this restriction is to make @code{REINSTATING} or
@code{ABSTAINING} from a line label that refers to a @code{GIVE UP}
statement a compile-time error, but this does not fit the @icst{}
definition either.  The definition adopted with version 0.27 and
later of @cic{}, which is hopefully correct, is to allow abstaining
from a @code{GIVE UP} statement by line number but to rule out the
other three cases (reinstating by line number silently fails,
reinstating or abstaining by gerund is impossible because there is no
gerund).

As well as @clcic{}'s extension to abstain/reinstate by computed line
number, there is also (since version 0.25) a @cic{}-specific extension
to @code{ABSTAIN}, also known as `computed abstain', but with a
different syntax and different semantics.  It's written like an
ordinary @code{ABSTAIN}, but with an expression between the words
@code{ABSTAIN} and @code{FROM}, for instance:

@example
DO ABSTAIN #1 FROM (1000)
DO ABSTAIN .2 FROM WRITING IN
@end example

Unlike non-computed @code{ABSTAIN}, this form allows a command to be
abstained from even if it's already been abstained from; so if the
first example command is run and line (1000) is already abstained, it
becomes `double-abstained'.  The number of times the statement is
abstained from is equal to the number of times it was already
abstained from, plus the expression (whereas with non-computed
abstain, it ends up abstained once if it wasn't abstained at all, and
otherwise stays at the same abstention status).  Reinstating a
statement always de-abstains it exactly once; so double-abstaining
from a statement, for instance, means it needs to be reinstated twice
before it will actually execute.

There are many uses for @code{ABSTAIN} (both the computed and
non-computed versions) and @code{REINSTATE}, especially when
interacting with @code{ONCE} and @code{AGAIN} (@pxref{ONCE and
AGAIN}); the computed version, in particular, is a major part of a
particular concise way to write conditionals and certain kinds of
loops.  They also play an important role in multithreaded programs.

@node READ OUT and WRITE IN
@section READ OUT and WRITE IN
@anchor{READ OUT}
@anchor{WRITE IN}
@findex READ OUT
@findex READING OUT
@findex WRITE IN
@findex WRITING IN
@cindex I/O
@cindex input
@cindex output

The @code{READ OUT} and @code{WRITE IN} commands are the output and
input commands in @ical{}; they allow communication between the
program and its user.  There was a numeric I/O mechanism implemented
in @icst{}, and it (or trivial variants) have been likewise
implemented in all more modern variants.  However, it had some obvious
deficiences (such as not being able to read its own output) which
meant that other methods of I/O were implemented in @cic{} and
@clcic{}.

The syntax of @code{READ OUT} and @code{WRITE IN} is the same in all
cases: the name of the command followed by an intersection-separated
list of items; the form of each item, the compiler you are using, and
its command line arguments together determine what sort of I/O is
used, which can be different for different elements in the list.

@menu
* INTERCAL-72 I/O::        Spelt-out numbers and Roman numerals
* C-INTERCAL I/O::         The Turing Tape I/O system
* CLC-INTERCAL I/O::       Baudot and mingled binary
@end menu

@node INTERCAL-72 I/O
@subsection INTERCAL-72 I/O
@cindex I/O, INTERCAL-72
@cindex input, INTERCAL-72
@cindex output, INTERCAL-72
@cindex INTERCAL-72, I/O
@cindex Roman numerals

@portability{yes, all versions, see text, all versions}

@icst{} had its own versions of I/O commands; these commands are
available in all modern @ical{} compilers as well (but @clcic{}
implements output slightly differently).  To distinguish @icst{} input
and output from the other more modern types of I/O, the @code{READ
OUT} and @code{WRITE IN} commands must take one of the following
values: a onespot or twospot variable, a single element of a tail or
hybrid array, or (in the case of @code{READ OUT}) a constant, meaning
that these are some examples of the possible forms:

@example
READ OUT .1
READ OUT ;2 SUB .3:4
READ OUT #3
WRITE IN :4
WRITE IN ,5 SUB #6
@end example

The statements do what you would expect; @code{READ OUT} outputs its
argument to the user, and @code{WRITE IN} inputs a number from the
user and assigns it to the variable or array element referenced.  (If
the variable, or the array that contains the array element, happens to
be read-only, the input or output still happens but in the case of
@code{WRITE IN} silently skips the assignment, instead throwing away
the input.)  The formats used for input and output are, however,
different from each other and from the formats used by most mainstream
languages.

Input is achieved by writing a number in decimal, one digit at a time,
with each digit written out as a word; so to input the number 12345, a
user would have to type @code{ONE TWO THREE FOUR FIVE} as input (if
they were using English, the most portable choice of language).  In
@icst{} only English is accepted as a language, but other compilers
accept other languages in addition.  @cic{} from version 0.10 onwards
accepts English, Sanskrit, Basque, Tagalog, Classical Nahuatl,
Georgian, and Kwakiutl; also Volap@"uk from version 0.11 onwards, and
Latin from version 0.20 onwards.  @jic{} accepts the same languages,
except with Esperanto instead of Latin; from version 0.05 of @clcic{}
onwards, the same list of languages as @cic{} is supported (apart from
Latin, which was added in version 1.-94.-8), plus Scottish Gaelic.

The format that output can be read in is a modified form of Roman
numerals, known as `butchered' Roman numerals.  @icst{}, @cic{} and
@jic{} do this the same way; @clcic{} is somewhat different. The
characters @samp{I}, @samp{V}, @samp{X}, @samp{L}, @samp{C}, @samp{D},
and @samp{M} mean 1, 5, 10, 50, 100, 500 and 1000 respectively,
placing a lower-valued letter after a higher-valued letter adds them,
and placing a lower-valued letter before a higher-valued letter
subtracts it from the value; so @samp{XI} is 11 and @samp{IX} is 9,
for instance.  In @icst{}, @cic{}, and @jic{}, a bar over a numeral
multiplies its value by 1000, and writing a letter in lowercase
multiplies its value by 1000000; however, @clcic{} uses lowercase to
represent multiplication by 1000 and for multiplication by 1000000
writes a backslash before the relevant numeral.

@node C-INTERCAL I/O
@subsection C-INTERCAL I/O
@cindex I/O, C-INTERCAL
@cindex input, C-INTERCAL
@cindex output, C-INTERCAL
@cindex C-INTERCAL, I/O
@cindex Turing Tape

@portability{no, version 0.07+, version 0.05+, no}

@cic{}'s method of character-based (rather than numeric) input and
output is known as the Turing Tape method; it is a binary
(character-set-agnostic) input/output mechanism.  To specify that
@cic{}-style I/O is being used, an array must be used as the argument
to @code{READ OUT} or @code{WRITE IN}; as the syntax is the same as
for @clcic{}'s I/O, command-line arguments and the capabilities of the
version of the compiler being used serve to distinguish the two
mechanisms.

The character-based input writes as many characters into a tail or
hybrid array as will fit, one character in each element.  The number
that's written into the array is not the character code, though, but
the difference between the character code and the previous character
code, modulo 256.  (To be precise, the code is the new character minus
the previous character, or 256 minus (the previous character minus the
new character) if the previous character had a higher character code;
the 'previous character' is the previous character from the input, not
the previous character written into the array.)  End-of-file causes
256 to be written into the array.  The concept is that of a circular
tape containing all the characters, where the program measures how
many spaces it needs to move along the tape to reach the next
character.  The 'previous character' starts at 0, but is preserved
throughout the entire program, even from one @code{WRITE IN} to the
next.

Character-based output uses a similar model, but conceptually the
output device moves on the inside of the tape, rather than on the
outside.  Therefore, the character is that is actually output is the
bit-reversal of the difference between the last character output
before it was bit-reversed and the number found in the array
(subtracting in that order, and adding 256 if the result is
negative).  (Rather than trying to parse the previous sentence, you
may find it easier to look either at the source code to the compiler
if you have it (the relevant part is binout in @file{src/cesspool.c})
or at some example @cic{} programs that do text-based I/O.)

@node CLC-INTERCAL I/O
@subsection CLC-INTERCAL I/O
@cindex Baudot
@cindex I/O, Baudot
@cindex I/O, CLC-INTERCAL
@cindex CLC-INTERCAL I/O
@cindex input, CLC-INTERCAL
@cindex output, CLC-INTERCAL

@portability{no, see text, all versions, no}

There are also two @clcic{}-specific I/O mechanisms.  These are
Baudot-based text I/O (which is also implemented from @cic{} version
0.27 onwards), and @clcic{} generalised binary I/O (not implemented in
@cic{}).

Baudot text-based I/O is specified by using a tail array as an
argument to @code{WRITE IN} or @code{READ OUT}.  (A tail array can
also be used to specify @cic{}-style Turing Tape I/O.  In order to
determine which is used: both @cic{} and @clcic{} use their own sort
of I/O unless a command-line argument instructs them to use the
other.)  In the case of @code{WRITE IN}, one line of input is
requested from the user (@cic{} requires this to be input in Latin-1,
and will then automatically convert it; @clcic{} gives the option of
various character sets for this input as command-line options); the
final newline is removed from this line, then it is converted to
extended Baudot and stored in the tail array specified (causing an
error if the array is too small).  Because Baudot is only a 5-bit
character set, each element is padded to 16 bits; @clcic{} pads with
zeros, @cic{} pads with random bits.  Trying to input at end-of-file
will act as if the input were a blank line.  @code{READ OUT} is the
reverse; it interprets the array as extended Baudot and converts it to
an appropriate character set (Latin-1 for @cic{}, or whatever was
specified on the command line for @clcic{}), which is output to the
user, followed by a newline.  Note that the Baudot is often longer
than the corresponding character in other character sets due to the
need to insert shift codes; for information on the extended Baudot
character set, @ref{Character Sets}.

Generalised binary I/O is specified using a hybrid array as an
argument to @code{WRITE IN} or @code{READ OUT}.  Input works by
reading in a number of bytes equal to the length of the array (without
trying to interpret them or translating them to a different character
set), prepending a byte with 172 to the start, padding each byte to 16
bits with random data, then replacing each pair of consecutive bytes
(that is, the first and second, the second and third, the third and
fourth, and so on) with (the first element selected from the second
element) mingled with (the complement of the first element selected from
the complement of the second element).  Output is the exact opposite
of this process.  End-of-file reads a 0, which is padded with 0s
rather than random data; if a non-end-of-file 0 comes in from the
data, its padding will contain at least one 1.  Any
all-bits-0-even-the-padding being read out will be skipped.

@node GIVE UP
@section GIVE UP
@findex GIVE UP
@cindex quitting
@cindex exiting

@portability{yes, all versions, all versions, all versions}

The @code{GIVE UP} command causes the program to end (or, in a
multithreaded program, causes the current thread to end).  It is
written simply as @code{GIVE UP}.  There is not much else to say about
it, except to mention that it is the only way to end the program
without an error unless the last line of the program is @code{TRY
AGAIN}, and that it has an unusual interaction with @code{ABSTAIN};
for details of this, see @ref{ABSTAIN}.  (Going past the last command
in the program is an error.)

There is no gerund for @code{GIVE UP}; in particular, @code{GIVING UP}
is a syntax error.

@node TRY AGAIN
@section TRY AGAIN
@findex TRY AGAIN
@cindex loops, entire program

@portability{no, version 0.25+, no, no}

The @code{TRY AGAIN} command is a very simple command with many
limitations; its effect is to place the entire program in a loop.  If
it exists, it must be the very last command in the program (it cannot
even be followed by syntax errors), and it causes execution of the
program to go back to the first command.  If the @code{TRY AGAIN}
command is abstained or for some other reason doesn't execute when
reached, it exits the program without the error that would usually be
caused by going past the last line of code.

The gerund for @code{TRY AGAIN} is @code{TRYING AGAIN}.

@node COME FROM and NEXT FROM
@section COME FROM and NEXT FROM
@anchor{COME FROM}
@anchor{NEXT FROM}
@findex COME FROM
@findex NEXT FROM
@cindex reverse goto
@cindex goto, time-reversed
@cindex time-reversed goto

@portability{no, see text, see text, see text}

The @code{COME FROM} statement (incidentally also invented in 1972,
but not in connection with @ical{}) is the main control-flow command
in @clcic{} (which deprecates @code{NEXT}), and one of two main
control flow structures in other modern @ical{} compilers.  It takes
either a label or an expression as its argument; these forms are
noncomputed @code{COME FROM} and computed @code{COME FROM}.

Noncomputed @code{COME FROM} was implemented in version 0.5 of @cic{},
but did not conform to modern-day semantics until version 0.7; it is
available in every version of @clcic{} and @jic{}.  Computed
@code{COME FROM} support is available in every version of @clcic{} and
in @cic{} from version 0.25 onwards, but not in @jic{}; the variant
@code{NEXT FROM} of @code{COME FROM} is available from @clcic{}
version 1.-94.-8 and @cic{} version 0.26 (both computed and
noncomputed).  @cic{} and @clcic{} also have a from-gerund form of
@code{COME FROM} and @code{NEXT FROM}, which was also implemented from
@clcic{} version 1.-94.-8 and @cic{} version 0.26.

The basic rule of @code{COME FROM} is that if a @code{COME FROM}
statement references another statement, whenever that statement is
reached, control flow will be transferred to the @code{COME FROM}
after that statement finishes executing.  (@code{NEXT FROM} is
identical except that in addition to the @code{COME FROM} behaviour,
the location immediately after the statement that was nexted from is
saved on the NEXT stack, in much the same way as if the statement
being nexted from was itself a @code{NEXT}.)

Here are examples of noncomputed, computed, and from-gerund @code{COME
FROM}:

@example
DO COME FROM (10)
DO COME FROM #2$'.1~#1'
DO COME FROM COMING FROM
@end example

(The last example is an infinite loop.  If it said @code{DO NEXT FROM
NEXTING FROM}, it would not be an infinite loop because the NEXT stack
would overflow and cause an error.  This also establishes the gerunds
used for @code{COME FROM} and @code{NEXT FROM}.)

There are some things to be careful with involving @code{COME FROM}
and @code{NEXT FROM}.  First, if the statement come from or nexted
from happens to be a @code{NEXT}, the @code{NEXT} doesn't count as
'finishing executing' until the NEXT stack entry created by the
@code{NEXT} is @code{RESUME}d to.  In particular, this means that if
@code{FORGET} is used to remove the entry, or a @code{RESUME} with a
large argument resumes a lower entry, the @code{COME FROM} doesn't
steal execution at all.

Second, you may be wondering what happens if two @code{COME FROM}s or
@code{NEXT FROM}s aim at the same line.  In a non-multithreaded
program (whether a program is multithreaded or not is determined by a
compiler option for those compilers that support it), this is an
error; but it is only an error if the statement that they both point
to finishes running, and both @code{COME FROM}s or @code{NEXT FROM}s
try to execute as a result (they might not if, for instance, one is
abstained or has a double-oh-seven causing it not to run some of the
time).  If both @code{COME FROM}s or @code{NEXT FROM}s are
noncomputed, however, a compiler can (but does not have to) give a
compile time error if two @code{COME FROM}s or @code{NEXT FROM}s share
a label, and so that situation should be avoided in portable code.
(If it is wanted, one solution that works for @cic{} and @clcic{} is
to use computed @code{COME FROM}s or @code{NEXT FROM}s with a constant
expression.)

@node System Library
@chapter System Library
@cindex system libary
@cindex syslib

@portability{yes, all versions, no, all versions}

@ical{} has a system library, called @samp{syslib}.  It is included
automatically at the end of your program by the compiler whenever your
program refers to a line from (1000) to (1999) without defining any
line in that range in the program.  (Although it is not added
automatically by the compiler in @clcic{}, it is trivial to
concatenate a copy onto the end of the program; copies of the system
library are available from many sources on the Internet, including a
version in the example code that comes with @cic{}.)

The intention of the system library is to provide a range of useful
capabilities, like multiplication, that can otherwise be hard to write
in @ical{}.  System library routines are used by @code{NEXTING} to
their line number (@pxref{NEXT}), where they will make changes to
certain variables depending on certain other variables (depending on
which routine is called), and @code{RESUME} back to the original
program.  As the system library is itself written in @ical{}, there
are some restrictions that need to be obeyed for calls to it to be
guaranteed to work; none of the variables it uses (@code{.1} to
@code{.6} and @code{:1} to @code{:5}) should be read-only or
overloaded (although the value of any variables that aren't mentioned
in the routine's description will be preserved by the routine), and
none of the lines in it should have their abstention status changed by
lines outside it (this can happen with blatant infractions like
@code{DO ABSTAIN FROM (1500)} or more subtle problems like
gerund-abstention) or have @code{COME FROM}s or @code{NEXT FROM}s
aiming at them.

The system library is currently available in all bases from 2 to 7
(@pxref{TriINTERCAL}), but not every command is available in every
base, and @cic{} is the only one of the three compilers listed above
that use the system library to ship with a version in bases other than
2.  (This table was originally based on the @icst{} manual, but has
had extra information added for bases other than 2.) Here, ``overflow
checked'' means that #1 is assigned to .4 if there is not an overflow,
and #2 is assigned to .4 if there is; ``overflow captured'' means that
if there is overflow, the digit that overflowed is stored in the
variable referenced.  In all cases, division by 0 returns 0.

@multitable @columnfractions .1 .7 .15
@headitem Line @tab Description @tab Bases
@item (1000) @tab
.3 <- .1 plus .2, error exit on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1009) @tab
.3 <- .1 plus .2, overflow checked
@tab 2, 3, 4, 5, 6, 7
@item (1010) @tab
.3 <- .1 minus .2, no action on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1020) @tab
.1 <- .1 plus #1, no action on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1030) @tab
.3 <- .1 times .2, error exit on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1039) @tab
.3 <- .1 times .2, overflow checked
@tab 2, 3, 4, 5, 6, 7
@item (1040) @tab
.3 <- .1 divided by .2
@tab 2, 3, 4, 5, 6, 7
@item (1050) @tab
.2 <- :1 divided by .1, error exit on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1200) @tab
.2 <- .1 times #2, overflow captured in .3
@tab 4, 6
@item (1210) @tab
.2 <- .1 divided by #2, one digit after the quartic or sextic point
stored in .3
@tab 4, 6
@item (1500) @tab
:3 <- :1 plus :2, error exit on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1509) @tab
:3 <- :1 plus :2, overflow checked
@tab 2, 3, 4, 5, 6, 7
@item (1510) @tab
:3 <- :1 minus :2, no action on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1520) @tab
:1 <- .1 concatenated with .2
@tab 2, 3, 4, 5, 6, 7
@item (1530) @tab
:1 <- .1 times .2
@tab 2, 3, 4, 5, 6, 7
@item (1540) @tab
:3 <- :1 times :2, error exit on overflow
@tab 2, 3, 4, 5, 6, 7
@item (1549) @tab
:3 <- :1 times :2, overflow checked
@tab 2, 3, 4, 5, 6, 7
@item (1550) @tab
:3 <- :1 divided by :2
@tab 2, 3, 4, 5, 6, 7
@item (1700) @tab
:2 <- :1 times #2, overflow captured in .1
@tab 4, 6
@item (1710) @tab
:2 <- :1 divided by #2, one digit after the quartic or sextic point
stored in .1
@tab 4, 6
@item (1720) @tab
:2 <- :1 times the least significant digit of .1, overflow captured in
.2
@tab 5, 7
@item (1900) @tab
.1 <- uniform random number from #0 to #65535
@tab 2, 3, 4, 5, 6, 7
@item (1910) @tab
.2 <- normal random number from #0 to .1, with standard deviation .1
divided by #12
@tab 2, 3, 4, 5, 6, 7
@end multitable

If you happen to be using base 2, and are either using the external
call system (@pxref{External Calls}) or are willing to use it, it is
possible to use a version of the system library written in C for
speed, rather than the default version (which is written in @ical{}).
To do this, use the command line options @option{-eE} (before the
@ical{} file), and @option{syslibc} (at the end of the command line).

@ifset notsplit
@partheading{PART III: @ical{} DIALECTS AND EXTENSIONS}
@end ifset
@node TriINTERCAL
@chapter TriINTERCAL
@cindex TriINTERCAL
@cindex ternary
@cindex whirlpool
@cindex sharkfin
@cindex BUT
@cindex add-without-carry
@cindex subtract-without-borrow
@cindex controlled unary operator
@findex ^
@findex @@

@portability{no, version 0.7+, version 1.-94.-8+, no}

One extension to @ical{} that is implemented by both @cic{} and
@clcic{} is known as TriINTERCAL, and extends @ical{} to bases other
than binary.  Unlike ordinary @ical{} programs, which have the
extension @samp{.i}, TriINTERCAL programs in bases from 3 to 7 (the
only allowed bases) have extensions from @samp{.3i} to @samp{.7i}
respectively.

The change of numeric base only affects expressions, and in particular
the behaviour of operators, and the range of variables.  (The onespot
and twospot ranges become the highest number of trits or other digits
in the base required that fit inside the binary ranges, so for
instance, the maximum value of a onespot variable in ternary is 59048,
or 3 to the power 10 minus 1.) Interleave/mingle is the simplest to
explain; it alternates digits just as it alternated bits in binary.
The other operators all change, as follows:

@itemize

@item
Exclusive-or becomes two operators, known either as
subtract-without-borrow and add-without-carry due to their
mathematical interpretations, or what and sharkfin after their Atari
syntax representations (@code{?} and @code{^}).  (In Princeton syntax,
these are the bookworm or yen sign, and a spike (@code{|}).)  The two
operators do the same thing in binary, but differ in higher bases.
(Nevertheless, it is an error to use a sharkfin in binary, because it
is a so-called `controlled unary operator', as are the rest of the
new operators defined in this section, which has a lower limit on
which base it is allowed in.)  Instead of doing the exclusive-or
operation, the bits being combined are either subtracted or added; if
the result is out of range for the base being used, the base is added
or subtracted from the result until it is in range.  (For the
subtraction, the bit that was less significant is subtracted from the
bit that was more significant in any given pair of bits, except for
the subtraction between the most and least significant bits, where the
most significant bit is subtracted from the least.)

@item
The AND and OR operators are generalised into an entire sequence of
operators; the number of operators available is the same as the base
that is being used.  In base 3, the third operator is known as BUT; in
other bases, there are no commonly accepted names for the extra
operators, so names that reflect the notation are used here.

The way to think of it is this: in base 2, an AND gives the result 0
if either argument is a 0, and otherwise a 1, and likewise, an OR
gives the result 1 if either argument is a 1, and otherwise a 0; they
could be said to favour 0 over 1 and 1 over 0 respectively.  In base
3, AND favours 0 over 2 over 1, OR favours 2 over 1 over 0, and BUT
favours 1 over 0 over 2.  (The symbol for BUT is @code{@@} (a
`whirlpool', which is another name for the BUT operation) in Atari
syntax, and @code{?} in Princeton syntax.)  The pattern continues: in
base 4, AND favours 0 over 3 over 2 over 1, BUT favours 1 over 0 over
3 over 2, 2BUT (written @code{2@@} or @code{2?}) favours 2 over 1 over
0 over 3, and OR favours 3 over 2 over 1 over 0.  (This can be
extended to higher bases following the same pattern, introducing
operators @code{3@@} or @code{3?}, etc., to favour 3, etc., when
neither AND (which always favours 0) nor OR (which favours the highest
digit in the base) are available.)  All the whirlpool operators are
controlled unary operators, which are only legal when both the base
contains the favoured digit, and they aren't redundant to AND nor OR.

@item
Select has its semantics modified to deal with more than one nonzero
digit in the base.  It starts off by doing an AND (in whatever base is
being used) between the two numbers being selected; then the bits of
the result are sorted by the bits of the right-hand argument to the
select, with bits corresponding to 0s in the right-hand argument
ending up more significant than bits corresponding to high digits in
the right-hand argument.  In base 2, this has the same effect as a
traditional-style select.

@end itemize

Note that the base doesn't affect anything other than variable ranges
and expressions; in particular, it doesn't affect the bit-reversal
used by Turing Tape I/O.  (The tape still has characters written on it
in binary, even though the program uses a different base.)

@node Multithreading and Backtracking
@chapter Multithreading and Backtracking
@cindex multithreading
@cindex threading
@cindex Threaded INTERCAL
@cindex Backtracking INTERCAL

The multithreading and backtracking extensions to @ical{} were
originally invented by Malcom Ryan, who implemented @code{COME
FROM}-based multithreading as a modified version of @cic{}, known as
Threaded @ical{}, but did not implement backtracking.  (The same
functionality is implemented in @cic{} today, but with different code.
Most likely, this means that the original code was better.)  He also
invented the original version of Backtracking @ical{}, but did not
implement it; the only known implementation is the @cic{} one.  A
different version of multithreading, using @code{WHILE}, was
implemented as part of @clcic{} (like all extensions first available
in @clcic{}, it is most likely due to Claudio Calvelli) and then added
to @cic{}, although its implications were not noticed for some time
afterwards.

So nowadays, three freely-mixable threading-like extensions to @ical{}
exist, all of which are implemented in @cic{}.  (A fourth, Quantum
@ical{}, is implemented in @clcic{} but not @cic{}, and so will not be
discussed further here.)  If you're wondering about the description of
backtracking as a threading-like extension, it's implemented with much
of the same code as multithreading in @cic{}, because the @ical{}
version can be seen as roughly equivalent to multithreading where the
threads run one after another rather than simultaneously.  (This
conceptualisation is probably more confusing than useful, though, and
is also not strictly correct.  The same could probably be said about
@ical{} as a whole, for that matter.)

@menu
* Multithreading using COME FROM::  Creating separate threads.
* Multithreading using WHILE::      Creating connected threads.
* Backtracking::                    Multithreading in series, not parallel.
@end menu

@node Multithreading using COME FROM
@section Multithreading using COME FROM
@cindex @code{COME FROM}, multithreading
@cindex @code{NEXT FROM}, multithreading
@cindex multithreading, separate threads
@cindex threading, separate
@cindex threading, unwoven
@cindex separate threads
@cindex unwoven threads

@portability{no, version 0.25+, version 0.05+, no}

The original multithreading implementation worked by giving a new
meaning to what was previously an error condition.  If in a
multithreaded program (a program is marked as multithreaded using
options to a compiler) two or more @code{COME FROM}s or @code{NEXT
FROM}s (or a mixture of the these) attempt to steal control
simultaneously, the original thread splits into multiple threads, one
for each of the commands trying to take control, and a different
command gains control of the program in each case.

From then on, all the threads run simultaneously.  The only thing
shared between threads (apart from the environment in which they run)
is the abstained/reinstated status of each command; everything else is
separate.  This means, for instance, that it's possible to change the
value of a variable in one thread, and it will not affect the
corresponding variable in other threads created this way.  Likewise,
there is a separate NEXT stack in each thread; if both a @code{COME
FROM} and a @code{NEXT FROM} aim at the same line, for instance, the
@code{NEXT FROM} thread will end up with a NEXT stack entry that isn't
in the @code{COME FROM} thread, created by the @code{NEXT FROM}
itself.  This is known as unwoven thread creation; none of the threads
created this way are `woven' with any of the other threads created
this way.  (Whether threads are woven depends on how they were
created.)  If the thread being split was itself woven with other
threads, exactly one of the resulting threads after the split is woven
with the threads that the original thread was woven to, but the rest
will not be woven to anything.  (If that seems a somewhat unusual
rule: well, this is @ical{}.)

In @cic{}, there are other guarantees that can be made about unwoven
threads (that is, threads not woven to any other thread).  In
particular, they can all be guaranteed to run at approximately the
same speed; to be more precise, the number of commands that have been
given the chance to execute in any given thread will not differ by
more than 2 from the number of commands that have been given the
chance to execute in any other thread that was created at the same
time.  (However, @code{COME FROM}s and @code{NEXT FROM}s can make this
relationship less precise; it is unspecified (in the technical sense
that means the compiler can choose any option it likes and change its
mind on a whim without telling anyone) whether a @code{COME FROM} or
@code{NEXT FROM} aiming at the current command counts towards the
command total or not, thus causing the relationship to become weaker
the more of them have the chance to execute.  In versions of @cic{}
from 0.27 onwards, there is a third guarantee; that if a @code{COME
FROM} comes from itself, it will actually give other threads at least
some chance to run, at some speed, by counting itself as a command
every now and then; previously this requirement didn't exist, meaning
that a @code{COME FROM} could block all threads if it aimed for itself
due to the speed restrictions and the fact that @code{COME FROM}s need
not count towards the total command count.)  Also, all commands,
including any @code{ONCE} or @code{AGAIN} attached to the command, are
atomic; this means that it's impossible for another thread to conflict
with what the command is doing.  (In a departure from the usual
@ical{} status quo, these guarantees are somewhat @emph{better} than
in most other languages that implement threading, amusingly continuing
to leave @ical{} with the status of being unlike any other mainstream
language.)

The only way to communicate between unwoven threads is by changing the
abstention status of commands; this always affects all threads in the
program, whether woven or not.  (The combination of @code{ABSTAIN} and
@code{ONCE} is one way to communicate atomically, due to the atomic
nature of @code{ONCE}.)

If there are at least two threads, the @code{GIVE UP} command ends the
current thread, rather than the current program.

@node Multithreading using WHILE
@section Multithreading using WHILE
@findex WHILE
@anchor{WHILE}
@cindex multithreading, connected threads
@cindex threading, connected
@cindex threading, woven
@cindex connected threads
@cindex woven threads

@portability{no, version 0.27+, version 0.05+, no}

The @code{WHILE} command (which is not strictly speaking a command,
but more a sort of metacommand that joins commands) is a second method
of achieving multithreading.  (In @clcic{}, there are at least two
other meanings for @code{WHILE}, but only the one implemented in
@cic{} is discussed here.)  The syntax is somewhat unusual, and
consists of two commands separated by the @code{WHILE} keyword, but
sharing the statement identifier, execution chance, and any
@code{ONCE}/@code{AGAIN} keyword that may be present.  For instance:

@example
(1) DO COME FROM ".2~.2"~#1 WHILE :1 <-
      "'?.1$.2'~'"':1/.1$.2'~#0"$#65535'"$
      "'"'&.1$.2'~'#0$#65535'"$#0'~#32767$#1"
@end example

(OK, maybe that's an unnecessarily complicated example, and maybe it
shouldn't have included the @code{/} operator which is part of another
@ical{} extension (@pxref{Operand Overloading}).  Still, I thought
that maybe you'd want to see how addition can be implemented in @ical{}.)

A @code{WHILE} command starts two threads (the original thread that
ran that command and a new one), one of which runs the command to the
left of the @code{WHILE} and one of which runs the command to the
right.  Any line number applies to the left-hand command, not the
WHILE as a whole, which is a metalanguage construct.  @code{NEXTING
FROM}, @code{ABSTAINING FROM} or similar behaviour with respect to the
@code{WHILE} itself is impossible, although it's certainly possible to
abstain from either of its operands (and abstaining from the left
operand has much the same effect as abstaining from the @code{WHILE}
itself; the right-hand thread deliberately takes a bit of time to get
started just so that this behaviour happens).  The right-command
thread starts just before the left command is run (so @code{NEXTING},
etc.@:, directly to the left command will not start that loop in the
first place); if that command finishes (which may be almost
immediately for something like a calculate command, or take a long
time for something like @code{NEXT}), that thread loops and reruns
that command as long as the left command has not finished;
@code{COMING FROM} that command, or a @code{NEXT}/@code{NEXT FROM}
from/aiming at that command, doesn't count as finishing that command
until it is @code{RESUME}d back to (if possible; if it's come from,
that command can never end and the right-hand loop will continue
forever, or until it @code{GIVE}s @code{UP} or the loop ends due to
the command ending later in another thread).  A @code{WHILE} command
itself exists across all threads of a multithreaded program in a way;
for each left-hand command that ends (in any thread), the next time a
right-hand command of the same @code{WHILE} ends it will cause the
thread it's looping in to end, regardless of whether that thread
corresponds to the thread in which the left-hand command ended.  (As
well as a right-hand command ending, there's also the possibility that
it never got started; there is a delay before the right-hand command
runs during which a left-hand command ending can prevent the
right-hand thread starting in the first place; this counts as the same
sort of event as terminating a right-hand loop, and can substitute for
it anywhere a right-hand command ending is mentioned.)  There is one
exception, in that if two or more left-hand commands end in a space of
time in which no right-hand commands for that @code{WHILE} ends, they
together only cause one right-hand command to end.  (What, did you
expect the logical and orthogonal behaviour?)

The two threads produced by a @code{WHILE} (the original thread and a
new copy of it) have more in common than ordinary @ical{} threads
created by @code{COME FROM}; ordinary threads share only
@code{ABSTAIN}/@code{REINSTATE} information, whereas the
@code{WHILE}-produced threads count as `woven' threads which also
share variables and stashes.  (They still have separate instruction
pointers, separate instruction pointer stacks, such as the NEXT stack,
and separate choicepoint lists.  Overloading information is shared,
though.)  Being woven is a relationship between two or more threads,
rather than an attribute of a thread, although a thread can be
referred to as being unwoven if it is not woven to any other thread.

Ordinary multithreading cannot create woven threads. When threads are
created by multiple @code{COME FROM}s from an original thread, which
was woven with at least one other thread, one of the resulting threads
counts as the `original' thread and remains woven; the rest are `new'
threads which initially start out with the same data as the original,
but are not woven with anything.  Backtracking in a thread
(@pxref{Backtracking}) causes it to unweave with any threads it may be
woven with at the time (so the data in the thread that backtracks is
set back to the data it, and the threads it was woven with at the
time, had at the time of the @code{MAYBE}, but the other threads
continue with the same data as before).  The only way to cause three
or more threads to become woven is with a new @code{WHILE} inside one
of the threads that is already woven, which causes all the new threads
to be woven together (the weaving relationship is transitive).

@node Backtracking
@section Backtracking
@cindex backtracking
@cindex choicepoints
@cindex dormant thread
@cindex threading, in series
@cindex threading, dormant

@portability{no, version 0.25+, no, no}

A somewhat unusual threading construct that's available is
backtracking.  In case you haven't come across it before (the concept
exists in other languages but is implemented differently and usually
in a less general way), the basic idea is that instead of executing or
not executing a command, you can @code{MAYBE} execute a command.  This
causes the command to be executed, but also creates a dormant thread
in which the command wasn't executed; at any time later, the program
can either decide that it liked the consequences of the command and
@code{GO AHEAD} and get rid of the dormant thread, or decide that it
didn't like the consquences of the command and @code{GO BACK} to the
dormant thread, discarding the current one.  The dormant thread is
more commonly called a `choicepoint', that is, a point at which a
choice was made but a different choice can still be made, and is
generally not thought of as a thread at all by most programmers.  (In
case you're wondering: dormant threads are always unwoven.)

@anchor{MAYBE}
@findex MAYBE
@cindex choicepoints, creating
To create a choicepoint, the statement identifier @code{MAYBE} is
used, rather than the more usual @code{DO} or @code{PLEASE}.
(Combination statement identifiers are still allowed, but must be in
the order @code{MAYBE PLEASE DO NOT} with optionally some parts
omitted, or different versions of @code{NOT} used, or both.) Here's an
example:

@example
MAYBE DON'T GIVE UP
@end example

When a command whose statement identifer contains @code{MAYBE} is
reached, it is executed or not executed as normal, but in addition a
choicepoint is created containing the program as it is at that time.
Only @code{ABSTAIN} and @code{REINSTATE}, which always affect all
threads in a program (even choicepoints), can alter the values stored
in the choicepoint; so in this way, a choicepoint is also somewhat
similar to the concept of a continuation in other languages.  The
choicepoint is placed on a choicepoint stack, which is maintained
separately for each thread in much the same way that stashes and the
@code{NEXT} stack are.

@anchor{GO BACK}
@findex GO BACK
@cindex choicepoints, activating
The choicepoint does not actually do anything immediately, but if the
program doesn't like the look of where it's ended up, or it decides to
change its mind, or just wants to try all the possibilities, it can
call the @code{GO BACK} command (which has no arguments, and is just
the statement identifier, optional execution chance, @code{GO BACK},
and optional @code{ONCE} or @code{AGAIN}).  This causes the current
thread to unweave from all other threads and then replace itself with
the thread created by the choicepoint on top of the choicepoint stack.
The difference is that this time, the abstention or reinstatement
status of the command that was modified with @code{MAYBE} is
temporarily reversed for determining whether it runs or not (this
reversal only lasts immediately after the @code{GO BACK}, and does not
affect uses of the command in other threads or later in the same
thread), so unless it has been @code{ABSTAIN}ed or @code{REINSTATE}d
in the meantime it will run if and only if it wasn't run the first
time.  The choicepoint stack's top entry is replaced by a `stale'
choicepoint that definitely isn't a thread; attempting to @code{GO
BACK} to a stale choicepoint instead causes the stale choicepoint to
be deleted and the program to continue executing.  (This is what gives
@ical{}'s backtracking greater flexibility in some ways than some
other languages; to get backtracking without the stale choicepoints
having an effect, simply run @code{COME FROM} the @code{GO BACK} as
the previous statement.)

Note that, though, when a thread splits into separate threads (whether
woven or unwoven), the choicepoint stack doesn't split completely, but
remains joined at the old top of stack.  The two choicepoint stacks
can add and remove items independently, but an attempt to @code{GO
BACK} to before the current thread split off from any other threads
that are still running instead causes the current thread to end,
although it will @code{GO BACK} as normal if all other threads that
split off from it or that it split off from since the top choicepoint
of the stack was created have ended since.  This means that it's
possible to backtrack past a thread splitting and get the effect of
the thread unsplitting, as long as both resulting threads backtrack;
this is another way in which @ical{}'s backtracking is more flexible
than that of some other languages.

@anchor{GO AHEAD}
@findex GO AHEAD
@cindex choicepoints, discarding
If, on the other hand, a program decides that it likes where it is and
doesn't need to @code{GO BACK}, or it wants to @code{GO BACK} to a
choicepoint lower down the stack while skipping some of the ones
nearer the top of the stack, it can run the @code{GO AHEAD} command,
which removes the top choicepoint on the stack, whether it's a genuine
choicepoint or just a stale one.

Both @code{GO AHEAD} and @code{GO BACK} cause errors if an attempt is
made to use them when the choicepoint stack is empty.

@node Operand Overloading
@chapter Operand Overloading
@cindex operand overloading
@findex /
@cindex slat
@cindex reverse assignment

@portability{no, version 0.26+, version 0.05+, no}

(Operand overloading in @cic{} is nowhere near as advanced as it is in
@clcic{}.  This chapter only explains the partial implementation used
by @cic{}; for a full implementation, see @clcic{} and its
documentation.)

Operand overloading is a method of using a onespot or twospot variable
as a substitute for an expression.  When a variable is overloaded to
an expression (which could be another variable, or something more
complex), any uses of that variable cause the expression to be
substituted instead.

At the beginning of the program, all variables stand for themselves;
so @code{.1} really does mean @code{.1}, for instance.  The meaning of
a variable can be overloaded using the slat operator (@code{/}), which
is the same in both Princeton and Atari syntax: it is a binary
operator whose left argument must be a onespot or twospot variable and
whose right argument can be any expression.  The slat operator returns
the true value of its left argument, but as a side effect, changes the
meaning of its left argument to be its right argument.  Here is an
example:

@example
DO .1 <- .2/'.3~.4'
@end example

The example causes @code{.2}'s true value to be assigned to @code{.1}
(unless of course @code{.1} is read-only), but also causes @code{.2}
from then on to actually mean @code{'.3~.4'}, except when it's the
left operand of a slat operator.  So for instance, @code{DO .1 <- .2}
would actually assign @code{'.3~.4'} to @code{.1}.  Somewhat
confusingly, this also works in the other direction; @code{DO .2 <-
.1} would assign @code{.1} to @code{'.3~.4'}, which would have the
effect of changing the values of @code{.3} and @code{.4} so that
@code{'.3~.4'} had the correct value, or throw an error if it couldn't
manage this.  (The general rule in this case is that any variable or
constant in the expression that overloads the variable is at risk of
being changed; this is known as a `reverse assignment'.  Code like
@code{DO .1 <- .1/#1} is entirely capable of changing the value of
@code{#1}, although to protect new @ical{} users @cic{} will refuse to
carry out operations that change the value of constants unless a
command-line switch (@pxref{-v}) is used to give it permission.  In
@cic{}, changing the value of a constant only changes meshes with that
value, but in @clcic{} it can also change non-mesh uses of that
constant, so doing so is not portable anyway.)

When multiple overloading rules are in effect, they are all applied;
overloading @code{.1} to @code{'.2~.3'} and @code{.2} to
@code{'.3$.4'} will cause @code{.1} to refer to @code{''.3$.4'~.3'}.
However, this expansion stops if this would cause a loop; to be
precise, overloading is not expanded if the expansion is nested within
the same expansion at a higher level (so @code{.1/.2} and @code{.2/.1}
together cause @code{.1} to expand to @code{.2}, which expands to
@code{.1}, which cannot expand any further).  In @cic{}, the
expression on the right hand side of a slat is not evaluated and not
expanded by operand overloading.

@code{STASHING} a variable causes its overloading information to be
stashed too; @code{RETRIEVING} it causes its overload rule to also be
retrieved from the stash (or any overload rule on the variable to be
removed if there wasn't one when the variable was stashed).

Overloading a onespot variable to a twospot variable or vice versa is
possible, but the results are unlikely to be predictable, especially
if a onespot variable is used to handle a twospot value.  Possible
outcomes include truncating the value down to the right bitwidth,
throwing an error if a value outside the onespot range is used, and
even temporarily handling the entire twospot value as long as it
doesn't end up eventually being assigned a value greater than twospot.

Note that reverse assignments can cause unpredictable behaviour if an
attempt is made to reverse-assign the same variable twice in the same
expression.  In particular, sequences of commands like @code{DO .1 <-
.2/'.3$.3' DO .2 <- #6} are liable to succeed assigning garbage to
@code{.3} rather than failing as they ought to do, and likewise any
situation where a variable is reverse-assigned twice in the same
expression may assign garbage to it.  This behaviour is seen as
unsatisfactory, though, and plans exist to improve it for future
versions.

@node PIC-INTERCAL
@chapter PIC-INTERCAL
@cindex PIC-INTERCAL
@cindex embedded systems
@cindex microcontrollers

@portability{no, version 0.26+, no, no}

PIC-INTERCAL is a simplified version of @ical{} designed especially
for embedded systems, designed to minimise code and data usage by
@ical{} programs so that they can fit on devices whose memory is
measured in bytes rather than megabytes.  (It is named after the first
microcontroller for which code was successfully generated, and which
influenced the choices of commands, the PIC16F628 manufactured by
Microchip, and is most likely to be portable to other microcontrollers
in the same range.)  @cic{} only compilers as far as C code when
producing PIC-INTERCAL; it is up to the user to find the appropriate
cross-compiler to translate this C into the relevant dialect of
machine code.  (Two header files in the distribution,
@file{src/pick1.h} and @file{src/pick2.h}, don't have any affect on
the compiler but are referenced by the generated code, and the intent
is for the user to change them to suit the behaviour of the PIC
compiler used, because these are not as standardised as C compilers
for everyday systems.)

There are several restrictions on PIC-INTERCAL programs:

@itemize

@item
It's impossible to store more than one item in the STASH for any given
variable.

@item
Many errors are not checked at runtime; it is the programmer's job to
ensure that runtime errors are avoided.  (The few errors that are
detected will send the program into an infinite loop, as there is no
sensible way to exit from a PIC program.)

@item
Double-oh-sevens are not randomised, but instead depend merely on
whether the probability given is greater than 50% or not.

@item
The NEXT stack is limited to 16 entries rather than the usual 80.

@item
@code{ABSTAIN} and @code{REINSTATE} still work, but cannot be computed
@code{ABSTAIN}s, and will not necessarily work when used to affect the
system library or calls to it.

@item
@code{READ OUT} and @code{WRITE IN} don't work.  (See below for a
replacement.)

@item
@code{COME FROM} and @code{NEXT FROM} must aim at a label, not an
expression or gerund.

@item
Multithreading and TriINTERCAL cannot be used on PICs.  (Operand
overloading can be used, but only if your PIC cross-compiler supports
function pointers; some don't.)

@end itemize

@anchor{PIN}
@findex PIN
@cindex I/O, PIC-INTERCAL
In order to provide I/O capabilities, a new command @code{PIN} is
available. It controls up to 16 I/O pins on the PIC or other embedded
system; an I/O pin is capable of receiving or sending voltages to an
electrical or electronic circuit.  This explanation assumes that the
device being controlled is a PIC16F628A, and therefore has its pins in
two blocks of 8 named @samp{PORTA} and @samp{PORTB}; for other
microcontrollers, adapting the code in @file{src/pick1.h} is likely to
be necessary to tell the compiler how to control the I/O pins, and the
way in which this done will affect which I/O pins it is that the
program will end up being able to communicate with.

The @code{PIN} command takes one twospot variable as its argument,
like this:

@example
DO PIN :2
@end example

The twospot variable is conceptually divided into 4 blocks of 8 bits.
The highest two blocks control the directions of the pins in
@code{PORTB} (most significant block) and @code{PORTA} (second most
significant block); a 1 on any bit means that the corresponding I/O
pin should be set to send data, and a 0 means that it should be set to
receive data.  The lower two blocks control the values on the pins
that are sending (and are ignored for receiving pins); the second
least significant block controls @code{PORTB} and the least
significant block controls @code{PORTA}, with a 1 causing the program
to set the output voltage to that of the microcontroller's negative
voltage supply rail, and a 0 causing the program to set the output
voltage to that of the microcontroller's positive voltage supply
rail.  (These voltages may vary on other systems; consult your
system's datasheet and the changes you made to the header files.)
After setting the pins, the @code{PIN} command then reads them as part
of the same operation, this time setting the values of the lower
blocks that are receiving, rather than setting the pins from the lower
blocks that are sending.  However, 1 and 0 bits on all bits of the
twospot variable have the opposite meaning when doing this, so that 1
means receiving/positive voltage rail and 0 means sending/negative
voltage rail.  There is no way to input without output, or vice versa,
but it's trivial to just send the same output again (which has no
effect, because the voltage on sending pins is maintained at the same
level until it is changed), or to ignore the input received.

@node CREATE
@chapter CREATE
@findex CREATE
@cindex creating syntax
@cindex syntax, creating

@portability{no, version 0.28+, see text, no}

The @code{CREATE} command allows the creation of new syntax at
runtime.  @clcic{} has had such a command since 1.-94.-8, but its
syntax is completely different and incompatible with the @cic{}
version, and so is not documented here (see the @clcic{} documentation
for more details).  The @cic{} version is only defined if the
@code{-a} option is used on the command line (and a runtime error E000
otherwise), because it forces the operand overloading code to be
introduced and so slows down every variable access in the program.

The syntax of the @code{CREATE} command is to write @code{CREATE},
then a line label, then anything.  OK, well not quite anything; you're
restricted to syntax that is supported by the `just-in-case' compiler
that runs on comments at compile time just in case they gain a meaning
later (see below).  The anything provides an example statement to
@code{CREATE}; statements which look the same (but may differ in
details) are created. Typical syntax for a @code{CREATE} statement
would therefore look something like this:

@example
DO CREATE (5) SWITCH .1 WITH .2
@end example

There is also computed @code{CREATE}, working identically to ordinary
@code{CREATE} except that the line number is taken from an expression
and the created command must start with a letter (to avoid an
ambiguity if the expression giving the line label happens to be an
array reference), with a syntax like this:

@example
DO CREATE .5 SWITCH .1 WITH .2
@end example

Here, a new @code{SWITCH WITH} statement (there is no such statement
in @ical{} normally) is being created.  This command makes it possible
to do this:

@example
DO SWITCH .3 WITH .4
@end example

Normally that line would be an error (E000) due to being unrecognised,
but having been @code{CREATE}d, it's now a real statement.  (The
gerund to affect created statements is @code{COMMENT}, just like
before they were created; the gerund to affect @code{CREATE} itself is
@code{CREATION} (@code{CREATING} is also allowed, but not as
elegant).)  When the created statement is encountered, it @code{NEXT}s
to line (5), the line number specified in the @code{CREATE} statement.
In order for the code there to be able to affect the variables
mentioned in the statement, the variables @code{:1601} (for the first
variable or expression mentioned), @code{:1602} (for the second
variable or expression mentioned), and so on, are @code{STASH}ed and
then overloaded to the respective expressions or variables mentioned
in the created command; so @code{:1601} has been overloaded to mean
@code{.3} and @code{:1602} has been overloaded to mean @code{.4} at
this point.  Then, the code at (5) runs; if it returns via a
@code{RESUME #1}, @code{:1601} and @code{:1602} will be
@code{RETRIEVE}d automatically and the program will continue from
after the created statement.  (If you do not resume to that point, say
if you're creating a flow control statement, you'll have to deal with
the stashes for the 1600-range variables yourself.)

So what syntax is available in created statements@?  All the capital
letters except @samp{V} (which is an operator in @ical{}) are
available and can be used freely and as many times as desired; they
match themselves literally.  However, they are not allowed to spell an
@ical{} keyword at any point (so watch out for @code{DO} and
@code{FROM}, for instance).  Whitespace is allowed, but is ignored
(both in the @code{CREATE} template statement, and in the code being
created; so @code{DO SW ITCH :8 WITH :50} will also have been
created).  Then, there are three groups of matchable data: scalar
variables (onespot or twospot variables, as used in the examples
above) match other scalar variables, array elements (like @code{,4 SUB
'.5~.6'}) match other array elements, and other expressions match
other other expressions.  Two matchable data may not appear
consecutively in a created command, but must be separated by at least
one capital letter (to prevent array-subscript-related ambiguities;
remember that the just-in-case compiler has to compile these
statements at compile time without knowing what they are).  The actual
expressions used in the @code{CREATE} statement don't matter; they're
just examples for the runtime to match against.

@cindex CREATE, operators
It is also possible (from @cic{} version 0.29 onwards) to create new
operators.  Such operators are always binary operators (that is, they
take two arguments and parse like mingle or select), and always return
32-bit results.  There are three types of legal names for such
operators, all of which are treated equivalently: lowercase letters,
punctuation marks otherwise unused in @ical{}, and overstrikes
consisting of a character, a backspace, and another character (apart
from overstrikes already used for built-in @ical{} operators).  The
syntax for creating an operator looks like one of these:

@example
DO CREATE (5) x
DO CREATE .5 =
@end example

The arguments to the operator will be overloaded onto :1601 and :1602
(which are, like with @code{CREATE}d statements, stashed before the
overloading happens), and the return value is read from :1603 (which
is stashed, then overloaded to itself).  All these three variables are
retrieved again after the operator finishes evaluating.

Note that it is a very unwise idea to use a @code{CREATE}d operator in
the expression for a computed @code{COME FROM} or @code{NEXT FROM},
because this always leads to an infinite regress; whenever any line
label is reached (including the line label that the @code{CREATE}
statement pointed at), the expression needs to be evaluated in order
to determine whether to @code{COME FROM} that point, which in turn
involves evaluating lines which have labels.

Some other points: a newer @code{CREATE} statement supercedes an older
@code{CREATE} statement if they give equivalent templates, multiple
@code{CREATE} statements may aim at the same line (this is the
recommended technique for creating a statement that can handle
expressions even if they're array elements or variables; you do this
by specifying multiple templates in multiple @code{CREATE}
statements), and strange things happen if a twospot variable in the
1600-range is used as an argument to a created statement itself
(because of the stash/retrieve, such a variable can usually be read,
but may not always be able to be written without the data being lost).

@node External Calls
@chapter External Calls
@cindex external calls
@cindex other languages
@cindex foreign functions
@cindex calls, external

@portability{no, version 0.28+, no, no}

@cic{} has a feature allowing @ical{} and non-@ical{} code to be
mixed.  This is achieved by causing the non-@ical{} programs to
participate in the @ical{} line-numbering model.  The same feature
allows expansion libraries to be linked into the code.

To create a combined program containing @ical{} and non-@ical{} code,
use @command{ick} as the compiler as normal, but specify both the
@ical{} and non-@ical{} source files on the command line, and use the
@option{-e} command-line option.  @command{ick} will invoke other
compilers as necessary, after modifying the source files accordingly.
At present, external calls are only supported to and from C.

In each case, it will be the @ical{} program that is invoked first.
(This means that it is impossible to link together more than one
@ical{} program, but you probably don't want to, because concatenating
the programs is likely to have a similar effect.)  You can get the
@ical{} program to @code{NEXT} to the non-@ical{} program immediately,
or the non-@ical{} program to @code{COME FROM} or @code{NEXT FROM} the
@ical{} program immediately, to obtain the effect of running the
non-@ical{} program first.

Note that external calls are incompatible with PIC-INTERCAL and with
multithreading; note also that you must use @command{gcc} as your
compiler, and @acronym{GNU} cpp and ld, for them to work in the
current version of @cic{}.

@menu
* External Calls to C::          How to put @ical{} calls in C.
* External Calls to Funge-98::   Linking Befunge-98 and @ical{}.
* Miscellaneous External Calls:: Other things you can link in.
* Using External Calls::         What happens when you use -e.
* Expansion Libraries::          Expanding the compiler's capabilities.
@end menu

@node External Calls to C
@section External Calls to C
@cindex C
@cindex other languages, C
@cindex external calls, to C

@portability{no, version 0.28+, no, no}

Linking C and @ical{} programs is achieved by placing various
constructs into the C programs that are equivalent to various @ical{}
constructs.  It is possible to simulate a line with a label and a
dummy command (which serves as a @code{COME FROM} suckpoint and
@code{NEXT} target), a command with a line label, @code{NEXT},
@code{RESUME}, and @code{FORGET}, and @code{COME FROM} and @code{NEXT
FROM}.  Onespot and twospot variables are accessible from inside the C
program, where they can be read and written; however, the @ical{}
program cannot access any variables inside the C program that weren't
part of the @ical{} program originally.

To prevent various logical impossibilities, there are restrictions on
where these can be used and what preparation is needed before they are
used.  Also, the semantics are not always exactly what you might
expect for technical reasons.

It should be observed that the @ical{} link intrudes on the user
namespace.  To prevent possible namespace clashes, no identifiers
starting with @code{ick_} or @code{ICK_} should be used anywhere in
the linked C program for any reason, except where specified in this
manual.

@menu
* External C Call Infrastructure:: Enabling a C program for external calls
* ick_startup::                    Doing things at startup
* ick_linelabel::                  Labelling lines...
* ick_labeledblock::               ...and labelling blocks
* ick_comefrom and ick_nextfrom::  Stealing control from elsewhere
* ick_next::                       The INTERCAL answer to subroutine calls
* ick_resume::                     Going back to before a NEXT
* ick_forget::                     Discarding NEXT stack entries
* ick_get/setone/twospot::         Accessing INTERCAL variables from C
* ick_create::                     CREATE statements via external calls
* External Calls and auto::        Considerations for auto variables
@end menu

@node External C Call Infrastructure
@subsection External C Call Infrastructure
@cindex C, external call infrastructure
@cindex external calls, C infrastructure

For a C program to be connected to an @ical{} program, it needs to be
marked with the correct header file, and needs to have functions marked
for communication with the @ical{} program.

@table @code

@item #include <ick_ec.h>
@cindex ick_ec.h
The header file @file{ick_ec.h} must be included using the
preprocessor in any file which uses any of the @ical{} external call
functions, variables, or macros.  (Note that this file may not
necessarily exist, or exist in the usual place; @command{ick} will
deal with making sure the correct header file is included.)  This will
include @file{stdint.h} (a standard C header file, which must exist on
your system), so that you can access @ical{} variables (the @ical{}
types onespot, twospot, tail, hybrid correspond to the C types
uint16_t, uint32_t, uint16_t*, uint32_t* respectively); also, it will
provide the prototypes for all the functions and definitions for all
the macros needed to use the external calls system with C.

@item ICK_EC_FUNC_START
@itemx ICK_EC_FUNC_END
@findex ICK_EC_FUNC_START
@findex ICK_EC_FUNC_END
Many of the @ical{} interface macros (@code{ick_linelabel},
@code{ick_comefrom}, and @code{ick_nextfrom}) make it possible to
jump from an @ical{} program to a C program.  Because C doesn't allow
jumping into the middle of a function, there has to be some way to
create a block of code which @emph{can} be jumped into. This is what
these two macros achieve.

This declaration and definition:

@example
ICK_EC_FUNC_START(identifier)
@{
  /* code goes here */
@}
ICK_EC_FUNC_END
@end example

is equivalent to this:

@example
void identifier(void)
@{
  /* code goes here */
@}
@end example

except that it is possible to jump from an @ical{} program into the
declared and defined program.  (If you need to write a prototype for
the function early, @code{void identifier(void);} is perfectly
acceptable, but an early prototype is not required unless you call the
function from earlier within the C code.)  Of course, you can
substitute any identifier that's legal as a function name for
@code{identifier} (as long as it doesn't start with @code{ick_} or
@code{ICK_}).  The resulting function is a function (for instance, you
can take its address or call it in the usual ways); the only
differences are that it can be jumped into from @ical{} code and that
it is constrained to take no arguments and return no data.  (It can
still access global and @ical{} variables.)  If the function is jumped
into from @ical{} code, but then control flow reaches the end of the
function, or the function @code{return;}s but was not called from C,
the resulting behaviour is undefined; @cic{} will attempt to continue
by some means at that point, but may fail.  If a function is unsure
whether it gained control from C or from INTERCAL code, it may use
@code{ick_return_or_resume} (described below).

Because you are not allowed to declare two C functions with the same
name (even in different modules), all functions declared with
@code{ICK_EC_FUNC_START} must have unique names across the entire
compilation.

@end table

@node ick_startup
@subsection ick_startup
@findex ick_startup
@cindex startup code, C

It is sometimes necessary for a C program to do its own initialisation
before the INTERCAL program starts running.  To do so, it can use the
@code{ick_startup} macro inside a function declared with
@code{ICK_EC_FUNC_START}; the syntax is @code{ick_startup(block)},
where the argument is an expression, statement, or compound statement
to run.  The argument itself must not contain any ick_-prefixed macros
or functions except possibly ick_create, may have side effects, and
must fit the C preprocessor's idea of what a macro argument should
look like (it's more used to parsing expressions than blocks; the
general rule is to avoid commas except when they're directly or
indirectly inside parentheses or strings).

@node ick_linelabel
@subsection ick_linelabel
@findex ick_linelabel
@cindex line labels, C

A line label is something that can be @code{NEXT}ed to and @code{COME
FROM}.  Unlike an @ical{} line label, it does not label a statement,
and therefore attempts to @code{ABSTAIN} or @code{REINSTATE} it may be
errors, or may be ignored (it's unspecified which, which means that
either may happen for any or no reason, but exactly one will happen in
any given case, although the choice might not be consistent).

The macro @code{ick_linelabel(expression);} may appear anywhere a
compound statement would normally be able to appear.  (That is, it
looks like a function call being used as a standalone expression, but
in fact the places where it can appear are more limited.)  In contrast
to ordinary line labels, an expression can be used rather than just a
constant; however, the behaviour is undefined if the expression has
side-effects.  Upon encountering the line label, any @code{COME FROM}s
or @code{NEXT FROM}s aiming at the line label (including
@code{ick_comefrom}s and @code{ick_nextfrom}s) will steal control from
the program; @code{RESUMING} after a @code{NEXT FROM} will work, but
suffers from the same caveats as setjmp/longjmp do (any auto variables
that change their value between the @code{NEXT FROM} and @code{RESUME}
will have their value clobbered (i.e. their value is no longer
reliable and should not be accessed)).  Note that the @ical{}
variables are immune to this problem.  You can also avoid the problem
by marking variables as @code{volatile} in the C program.

It is possible to @code{NEXT} or @code{ick_next} to a
@code{ick_linelabel}, which has the same effect as saving the
@code{NEXT} stack, calling the function containing the
@code{ick_linelabel} and then immediately doing a C @code{goto} to an
imaginary label preceding it.  Due to this possibility, an
@code{ick_linelabel} is only allowed within a function defined with
@code{ICK_EC_FUNC_START}.

@node ick_labeledblock
@subsection ick_labeledblock
@findex ick_labeledblock
@cindex labeled blocks
@cindex blocks, labeled

In @ical{} programs, labels don't stand on their own, but instead
label a statement.  The difference between a standalone line label and
a line label that labels a statement is that @code{COME FROM}s will
come from the @emph{label itself} (which is before the next statement)
when aiming at a standalone line label, but the @emph{end of the
statement} when aiming at a labeled statement.  To achieve the same
effect in C, the macro @code{ick_labeledblock} is available; it can be
used as @code{ick_labeledblock(expression,expression)} or
@code{ick_labeledblock(expression,statement)}; the first argument is
the label, and the second argument is an expression or statement to
label (if an expression is labeled, it will be converted to a
statement that evaluates it for its side effects and discards the
result).  It is even permitted to label a block statement in this way.
Note, however, that you have to contend with the C preprocessor's
ideas of where macro arguments begin and end when doing this.  Other
than the position of the @code{COME FROM} target created by the label,
this behaves the same way as @code{ick_linelabel} (so for instance,
computed line labels are allowed, but the expression that computes
them must not have side effects, and it is only allowed within a
function defined with @code{ICK_EC_FUNC_START}).

@node ick_comefrom and ick_nextfrom
@subsection ick_comefrom and ick_nextfrom
@findex ick_comefrom
@findex ick_nextfrom
@cindex COME FROM, in C
@cindex NEXT FROM, in C

The @code{ick_comefrom} and @code{ick_nextfrom} macros are, like the
other @ical{} flow control macros (as opposed to functions), only
allowed within a function defined with @code{ICK_EC_FUNC_START}.  They
act almost exactly like the @ical{} statements of the same name
(although note that C statements cannot be @code{ABSTAIN}ed
@code{FROM} even if they act the same way as @ical{} statements);
they are written as @code{ick_comefrom(expression);} and
@code{ick_nextfrom(expression);} respectively (note that they must be
called as statements, and cannot be used as part of an expression).
Whenever a standalone line label is encountered whose expression
evaluates to the same number as the expression inside the
@code{ick_comefrom} or @code{ick_nextfrom}, and that number is at most
65535, then control will be transferred to the @code{ick_comefrom} or
@code{ick_nextfrom}, leaving a @code{NEXT} stack entry behind in the
case of @code{ick_nextfrom}; likewise, if the end of a labeled
statement, expression or block is reached and the label has the right
number.  Some caveats: the expression need not be constant, but must
not have side effects, must not be negative, and must fit into the
range of an @code{unsigned long} in the C program (and the statement
will do nothing if the expression evaluates to a value larger than
65535).  In keeping with the best C traditions, these caveats are not
checked, but instead result in undefined behaviour if breached.

@findex ick_comefromif
@findex ick_nextfromif
There are also versions @code{ick_comefromif} and @code{ick_nextfromif},
which take a second parameter, which is a condition that specifies
whether control is actually stolen from the target.  The condition may
have side effects, and is only run when the line numbers match; it should
return 0 or NULL to leave control flow alone, or nonzero to steal
control, and should be either an integral type or a pointer type.
Although side effects are allowed, the condition must not look at or
alter @code{auto} or @code{register} variables in the enclosing function,
not even if they are also marked @code{volatile}.  (Global and
@code{static} variables are fine, though.)

@node ick_next
@subsection ick_next
@findex ick_next
@cindex NEXT, in C

@code{ick_next} is a macro that acts like the @ical{} statement
@code{NEXT}.  Contrary to the other @ical{}-like macros, it can be used
in any function regardless of whether it was defined with
@code{ICK_EC_FUNC_START}; however, it must still be used as a statement
by itself, and a call to it looks like @code{ick_next(expression);}.  The
expression is the label to @code{NEXT} to, and works under the same rules
as the expressions for @code{ick_comefrom}; it need not be constant
(unlike in @cic{}!), but must not have side effects, must not be
negative, must fit into the range of an unsigned long, and is ignored if
it is over 65535.  If there happen to be multiple labels with the correct
value at the time, the compiler will @code{NEXT} to one of them.  Bear in
mind that there is a limit of 80 entries to the @code{NEXT} stack, and
that this limit is enforced.

If the resulting @code{NEXT} stack entry is @code{RESUME}d to, the
program will continue after the @code{ick_next} as if via @code{setjmp},
with all the usual restrictions that that entails; if the resulting
@code{NEXT} stack entry is forgotten, then the @code{ick_next} call will
never return.  (Notice the 'as if via setjmp' condition allows you to
preserve the vales of @code{auto} and @code{alloca}-allocated storage as
long as its value has not changed since the @code{ick_next} was called,
which is a significantly more lenient condition than that normally
imposed on such variables (@pxref{External Calls and auto}).

@node ick_resume
@subsection ick_resume
@findex ick_resume
@cindex RESUME, in C

@code{ick_resume} is a macro, but there are few restrictions on its use;
it is permitted to use it inside an expression (but it returns void,
making this not particularly useful), and acts like a function which
takes an unsigned short argument, returns void, and has a prototype (but
you cannot take its address; if you need to be able to do that, write a
wrapper function for it).  It can be used within any function regardless
of how it was declared, and never returns; instead, it pops the specified
number of @code{NEXT} stack entries and resumes execution at the last one
popped, just as the @ical{} statement does.  This causes the same errors
as the @ical{} statement if the number of entries popped is zero or
larger than the @code{NEXT} stack.

@findex ick_return_or_resume
There is also a macro @code{ick_return_or_resume();}; it can only be used
inside a function defined with @code{ICK_EC_FUNC_START}, and is
equivalent to @code{return;} if the function was called from C, or
@code{ick_resume(1);} if the function was called from @ical{}.  It's
therefore a safe way to return from such a C function if you don't know
how control reached it in the first place.

@node ick_forget
@subsection ick_forget
@findex ick_forget
@cindex FORGET, in C

The @code{ick_forget} macro removes @code{NEXT} stack entries, and the
corresponding C stack entries. It must be called as a statement by
itself, and its invocation looks like this: @code{ick_forget(expr);},
where the expression is the number of @code{NEXT} stack entries to forget
(all of them will be forgotten if the number is higher than the number of
entries).  The expression will be casted to an @code{unsigned short}.

@code{ick_forget} can only be used inside a function declared with
@code{ICK_EC_FUNC_START}.  As it is removing stack entries both in
@ical{} and in C, it will clobber the value of all @code{auto} variables
created since the highest remaining @code{NEXT} stack entry came into
being (or since the start of the program, if the @code{NEXT} stack is
emptied by the command) and also deallocate all @code{alloca} storage
allocated since then.  It also causes the return address of the current
function to become undefined, so that function must not return; control
may leave it via @code{RESUME}, or via @code{COME FROM}, or via
@code{NEXT} or @code{NEXT FROM} followed by the relevant @code{NEXT}
stack entry being forgotten (the function is still 'running' but
suspended while the @code{NEXT} stack entry still exists).  (Note that
these restrictions are stronger than those on @code{RESUME}; this is
because @code{RESUME} preserves most of the stack, but @code{FORGET}
destroys parts of the stack and therefore cannot avoid destroying the
data stored there.  It could be much worse; a previous (never released)
version of the code didn't remove those parts of the stack in many
circumstances, leading to a stack leak that caused programs to segfault
after a while.)

@node ick_get/setone/twospot
@subsection ick_get/setone/twospot
@findex ick_getonespot
@findex ick_setonespot
@findex ick_gettwospot
@findex ick_settwospot
@cindex variables, from C

This class of four functions make it possible to get and set @ical{}
scalar variables from C code.  Their prototypes are as follows:

@example
uint16_t ick_getonespot(unsigned short varnumber);
void ick_setonespot(unsigned short varnumber, uint16_t newvalue);
uint32_t ick_gettwospot(unsigned short varnumber);
void ick_settwospot(unsigned short varnumber, uint32_t newvalue);
@end example

The program will error out with a fatal error (@pxref{E200}) if the
variable you request is mentioned nowhere in the @ical{} program; if
you attempt to set an @code{IGNORE}d variable, the attempt will
silently fail (just as if you assigned to it in an @ical{} program).
The get functions are safe to use in a computed line label, so you can
use them to produce computed line labels that depend on @ical{}
variables.  (@code{uint16_t} and @code{uint32_t} are standard C data
types; if your system doesn't provide them, get better system header
files.)

If you care about speed, note that .1 is the fastest variable of all
to access, and otherwise variables first mentioned near the top of the
@ical{} program will be faster to access than variables mentioned
lower down.

@node ick_create
@subsection ick_create
@cindex CREATE, in C
@cindex C, CREATE

The @code{ick_create} function (prototype: @code{void
ick_create(char*, unsigned long)}) allows the external calls system to
be used to create new @ical{} syntax; to do this, you give a
`signature' representing the syntax you want to define and a line
number to the function (which are its two arguments, respectively).
The signature defines the syntax that you are defining; whenever that
syntax is encountered within the @ical{} program, it will @code{NEXT}
to the line number you specify, which can do various clever things and
then @code{RESUME} back to the @ical{} program (or if you're defining
a flow-control operation, you might want to leave the @code{NEXT}
stack entry there and do other things).  However, note that the
overloading of @code{:1601}, etc.@:, will still take place as in the
@ical{} version of @code{CREATE} if the @option{-a} option is used
(@pxref{-a}), so care is needed when writing flow control statements
that they work both with and without the option and don't cause
@code{STASH} leaks (which means no @code{FORGET}ting the relevant
@code{NEXT} stack entry, and no looking at 1600-range variables).
This allows the external calls system to define whole new @ical{}
commands, with the same power as any other programming language.

There are various restrictions on what syntax you can @code{CREATE}
with this method, which are best explained by an explanation of the
relevant @cic{} compiler internals.  When an @ical{} program is
compiled by @cic{}, any unrecognised statements it comes across are
compiled by a `just-in-case' compiler that attempts to compile them
anyway with no knowledge of their syntax, just in case the syntax
becomes defined later.  (E000 (@pxref{E000}) will be thrown when such
statements are encountered at runtime, unless the syntax has been
@code{CREATE}d since to give a statement a meaning.)  For the
just-in-case compiler to run, the resulting statement must be
completely unrecognised; this means that it may contain no keywords
(not even a sequence of letters that forms a keyword, such as
@code{FROM} or @code{DO}), it must consist only of variable names,
expressions, and capital letters other than @samp{V} (because @samp{V}
is a unary operator, so otherwise there would be ambiguity), and in
which any two variable names or expressions are separated by at least
one capital letter.  The compiler will produce a `signature' for the
unknown command that can be defined.

@cindex signatures
@cindex CREATE, signatures
A signature consists of a sequence of characters (and is represented
as a null-terminated string; the runtime makes a shallow copy of the
string and keeps it until the end of the program, so arrangements must
be made to ensure that the storage in which the string is allocated
stays around that long, but this opens up interesting possibilities in
which the signature that was actually @code{CREATE}d can be modified
retroactively); whitespace is not allowed in a signature.  Capital
letters can be used (apart from @samp{V}), and match the same capital
letters literally in the @ical{} syntax being created; also available
are the special characters @samp{.,;~}, which match respectively a
scalar variable (a onespot or twospot variable such as @code{:1}), an
array variable (such as @code{;2}), an array element (such as @code{,3
SUB #4 #5}), and an expression that isn't a variable name and isn't an
array element (such as @code{.4$.5}).  If you want to be able to match
other things (say, to be able to match all expressions), you will need
to submit multiple signatures using multiple calls to
@code{ick_create}; maybe you could write a library to do that
automatically.

@code{CREATE}d operators also have signatures, but of quite a
different form.  The signature for a single-character operator is a
lowercase u, followed by its character code in hexadecimal (no leading
zeros, and in lowercase); the signature for an overstrike is a
lowercase o, followed by the lower relevant character code in
hexadecimal, followed by a lowercase x, followed by the higher
relevant character code in hexadecimal.

The routine that is @code{NEXT}ed to will presumably want to be able
to see what in the @ical{} program was matched by the signature, so a
range of function-like macros is provided to access that.  They must
be run from within the invocation of the function which was
@code{NEXT}ed into by the created syntax (@pxref{External Calls and
auto} for when a function invocation ends, which could be sooner than
you think when the @cic{} external calls system is used), and are
undefined behaviour when that invocation did not gain control from a
@code{CREATE}d statement.  Here are their effective prototypes:

@example
int ick_c_width(int);
int ick_c_isarray(int);
unsigned short ick_c_varnumber(int);
uint32_t ick_c_value(int);
/* These require -a to work */
uint32_t ick_c_getvalue(int);
void ick_c_setvalue(int, uint32_t);
@end example

The first argument to all these macros is the position of the match in
the signature (0 for the first non-capital-letter match in the
signature, 1 for the second, and so on until no more items are left in
the signature to match); specifying a position that isn't in the
signature is undefined behaviour.

@code{ick_c_width} returns the data type, as a width in bits, of the
expression (or the width in bits of an element of the passed in
array), and @code{ick_c_isarray} returns 1 if the argument was an
array variable or 0 if it was an expression (array elements and scalar
variables are expressions).  @code{ick_c_varnumber} returns the
variable's number (for instance 123 for @code{.123}), or 0 if the
corresponding argument was not a variable; in the cases where the
argument was a variable, these three functions together provide enough
information to figure out which variable (which is useful if you're
writing an extension which takes a variable name as an argument).

@code{ick_c_value} returns the value of the corresponding expression
at the time the @code{CREATE}d command was called;
@code{ick_c_getvalue} is almost equivalent, but only works if the
@option{-a} option (@pxref{-a}) was used during compilation, and
returns the value of the corresponding expression now.  (The uint32_t
return type is large enough to hold either a onespot or twospot value,
and will be zero-extended if the corresponding expression had onespot
type.)  @code{ick_c_setvalue} also depends on @option{-a}, and will
assign to the corresponding expression (be careful not to provide a
value that is too large for it!@:).  In the case that the corresponding
expression is not a variable, this will attempt to perform a reverse
assignment to the expression, and can produce ordinary @ical{} errors
if it fails.  It is not possible to redimension an array this way, as
this is assignment, not a calculate operation.

@node External Calls and auto
@subsection External Calls and auto
@cindex auto
@cindex alloca
@cindex external calls, and auto
@cindex C, auto/alloca

Because the external calls system merges the @ical{} @code{NEXT} stack
with the C return value and data storage stack (note for pedants: the C
standards nowhere mandate the existence of such a stack, or even mention
one, but the restrictions stated in them imply that implementations have
to act as if such a stack existed, because of the way the scoping rules
and recursion work), the external calls system therefore has severe
effects on data that happens to be stored there.  (In @ical{} terms,
imagine what would happen if data could be stored on the @code{NEXT}
stack; if C used the more sensible system of having a @code{STASH} for
each variable, these problems would never occur in the first place,
instead causing an entirely different set of problems.)  Similar
considerations apply to the common nonstandard C extension @code{alloca},
which dynamically alters the size of the stack; also, in what goes below,
@code{register} variables should be considered to be @code{auto}, because
the compiler may choose to allocate them on the stack.  Theoretical
considerations would lead one to conclude that variable-length arrays
should obey most of the same restrictions; in practice, though, it's
unwise to attempt to mix those with @ical{} code at all, except by
separating them into separate functions which aren't flagged with
@code{ICK_EC_FUNC_START} and use no @code{ick_}-prefixed identifiers,
even indirectly.  (They may cause a compile to fail completely because
they don't mix well with @code{goto}.)

In the description below, @ical{} commands should be taken to include the
equivalent C macros.

@code{NEXT}/@code{NEXT FROM} paired with @code{RESUME} have the least
effect, and the most obvious effect, on @code{auto} variables in the
function that was @code{NEXT}ed from, which is the same effect that the
standard C function @code{longjmp} has.  That is, @code{alloca} storage
stays intact, and @code{auto} variables have their values `clobbered'
(that is, their value is no longer reliable and should not be used) if
they changed since the corresponding @code{NEXT} and are not marked as
@code{volatile}.  (This is a very easy restriction to get around, because
changing the values of such variables is quite difficult without using
statically-allocated pointers to point to them (a dubious practice in any
case), and @code{volatile} is trivial to add to the declaration.)

@code{COME FROM} has more restrictions; it deallocates all @code{alloca}
storage in the function that was @code{COME FROM}, and functions that
called it or that called functions that called it, etc.@:, using C calls
(as opposed to @code{NEXT}), and those invocations of the functions will
cease to exist (thus destroying any @code{auto} variables in them), even
in the case of @code{COMING FROM} a function into the same function.
@code{auto} variables in the function that is come into will start
uninitialised, even if initialisers are given in their declaration, and
it will be a `new' invocation of that function.  (It is quite possible
that the uninitialised values in the @code{auto} variables will happen by
chance to have the values they had in some previous invocation of the
function, though, because they are likely to be stored in much the same
region of memory; but it is highly unwise to rely on this.)  Note that
@code{volatile} will not help here.  Observant or source-code-reading
readers may note that there is a mention of an @code{ick_goto} in the
source code to @cic{}; this is undocumented and this manual does not
officially claim that such a macro exists (after all, if it did, what in
@ical{} could it possibly correspond to?), but if such a macro does exist
it obeys the same restrictions as @code{COME FROM}.

@code{FORGET} is the worst of all in terms of preserving data on the
stack; it deallocates @code{alloca} data and clobbers or deletes
@code{auto} variables in all function invocations that have come into
existence since the @code{NEXT} that created the topmost remaining
@code{NEXT} stack entry was called, or since the start of the program if
the @code{NEXT} stack is emptied, and the current function will continue
in a new invocation.  @code{volatile} is useless in preventing this,
because the relevant parts of the stack where the data were stored are
deleted by the command (that's what @code{FORGET} does, remove stack).
If any of these data are required, they have to be backed up into static
storage (variables declared with @code{static} or global variables), or
into heap storage (as in with @code{malloc}), or other types of storage
(such as temporary files) which are not on the stack.  (Incidentally,
suddenly deleting parts of the stack is excellent at confusing C
debuggers; but even @code{RESUME} and @code{COME FROM} tend to be
sufficient to confuse such debuggers.  More worrying is probably the fact
that the C standard provides a portable method for deleting the stack
like that, and in fact the external calls runtime library is written in
standard freestanding-legal C89 (with the exception of
@option{+printflow} debug output which requires a hosted implementation),
meaning that in theory it would be possible to split it out to create an
implementation of a C-plus-COME-FROM-and-NEXT language, and doing so
would not be particularly difficult.)

Note that @ical{} variables are not stored on the C stack, nor are any of
the metadata surrounding them, and so are not affected unduly by control
flow operations.

@node External Calls to Funge-98
@section External Calls to Funge-98
@cindex .b98
@cindex external calls, Funge
@cindex external calls, Befunge
@cindex Funge
@cindex Befunge

@portability{no, version 0.29+, no, no}

@cic{} supports linking @ical{} programs with Funge-98 programs (to be
precise, only Befunge-98 programs are currently supported).  However,
it does not ship with a Funge-98 interpreter, and such an interpreter
needs to be linked to the resulting program in order to run the
Befunge program.  Therefore, you need to convert a third-party
Funge-98 interpreter to a library usable by @cic{} before you can use
this part of the external calls system (@pxref{Creating the Funge-98
Library}); however, this only has to be done once.

Once the library has been created, you can link an @ical{} program
with a Befunge-98 program by invoking @command{ick} like this:

@example
ick -e intercalprogram.i befungeprogram.b98
@end example

You can link no more than one Befunge-98 program at once (just like
you can link no more than one @ical{} program at once).  Also, the
@ical{} program must come first on the command line.

It is legal to link @ical{}, C, and Befunge-98 simultaneously;
however, the identifiers used in the third-party Funge-98 interpreter
have not been mangled to avoid collisions, and therefore problems may
be caused if the C program uses the same identifiers as the Funge-98
interpreter.

@menu
* Creating the Funge-98 Library:: How to create the Funge-98 library.
* The IFFI Fingerprint::          External calls from Funge's view.
@end menu

@node Creating the Funge-98 Library
@subsection Creating the Funge-98 Library
@cindex libick_ecto_b98.a
@cindex Funge, installing
@cindex Befunge, installing
@cindex libraries, Funge
@cindex libraries, Befunge

Before external calls to Funge-98 can be used, the relevant library
must be compiled.  (After the library has been compiled, then you will
need to reinstall @cic{}; however, you will not need to recompile
@cic{}.)

At present, only the cfunge Funge-98 interpreter can be converted into
a library suitable for use by @cic{}; also, doing this is only
supported on POSIX systems (although if someone gets it to work on
DOS/Windows, the author of this manual would be interested to hear
about it.)  Also, a source-code distribution (rather than a binary
distribution) is needed.  One way to obtain the latest cfunge sources
is via the bzr version-control system, using the following command
(correct as of the time of writing, but as always, links can become
dead):

@example
bzr branch http://rage.kuonet.org/~anmaster/bzr/cfunge
@end example

(As a licensing note, note that cfunge is licensed under the GNU
General Public licence version 3, whereas @cic{} is licensed under
version 2 and all later versions of that licence; although these terms
are obviously compatible with each other, you must ensure yourself
that your program has appropriate licensing terms to allow a GPLv3
library to be linked to it.)

Once you have downloaded the cfunge sources, you need to compile them
into a library suitable for use with @cic{} (note that this is a
somewhat different process to compiling them into a standalone
Funge-98 interpreter).  There is a script provided in the @cic{}
distribution to do this, @file{etc/cftoec.sh}.  It must be run in the
@file{etc} subdirectory of the @cic{} distribution (i.e. the directory
the script itself is in), and must be given the path to the root
directory of the cfunge source distribution (that is, the directory
that contains the @file{src}, @file{lib} and @file{tools}
subdirectories of that distribution) as its only argument.  Note that
it may give some compiler warnings on compilation; my experience is
that warnings about C99 inlining can be safely ignored (they reflect a
deficiency in @command{gcc} itself that luckily seems to be irrelevant
in this case), but other warnings may indicate problems in the exact
versions of the sources that you downloaded (and errors definitely
indicate such problems).

Once the library has been created, it will appear as the new file
@file{lib/libick_ecto_b98.a} in the @cic{} distribution (the cfunge
distribution will be left unchanged); reinstalling @cic{} will install
this file to its proper location.  (It is also in a valid location to
be able to be run if you aren't installing @cic{} but instead just
running it from the distribution's directory.)

@node The IFFI Fingerprint
@subsection The IFFI Fingerprint
@cindex IFFI
@cindex fingerprint
@cindex external calls, from Funge's view
@cindex Funge, fingerprint
@cindex Befunge, fingerprint

@i{This section will not make much sense to a non-Funge programmer;
therefore, if you are not used to Funge, you probably want to skip it.}

To a Funge program, the external calls interface is accessed via a
Funge-98 'fingerprint' defined by the interpreter.  The name of the
fingerprint is 0x49464649, or as text, @samp{IFFI}.

When a program formed by linking @ical{} and Befunge-98 is run, the
first thing that happens is some internal @ical{} initialisation which
is not visible to either program, and then initialisation routines
specified in the Befunge-98 program run (if an initialisation routine
is also specified in a linked C program using ick_startup, it is
unspecified whether the C or Befunge-98 initialisation happens first.)
In the Befunge program, the initialisation routine consists of
everything that happens until the @samp{Y} command in the @samp{IFFI}
fingerprint is run; the author of the Funge-98 must load the
@samp{IFFI} fingerprint themselves during this initialisation to
access that command.  (This is so that the Befunge program ends up
complying with the Funge-98 standard; commands not defined in that
standard cannot be used until a fingerprint is loaded.)  During
initialisation, no commands from the @samp{IFFI} fingerprint may be
used except @samp{Y} and @samp{A}.  (If a different command is used,
@samp{C}, @samp{M}, and @samp{X} remove the arguments they would use
from the stack (if any) but otherwise do nothing, and the other
commands in the @samp{IFFI} fingerprint reflect.)

After the @samp{Y} command is called, the @ical{} program starts
running; in order for the Befunge program to regain control, it has to
be @code{NEXT}ed to from the @ical{} program, or @code{COME} or
@code{NEXT FROM} the @ical{} program, or contain the line label to
which syntax in the @ical{} program was @code{CREATE}d.  (In other
words, the normal @ical{} ways of transferring information between
parts of a program.)  In order to do this, therefore, line labels and
@ical{} control flow statements must be placed into the Befunge
program.

@cindex marker
@cindex Funge, marker
@cindex Befunge, marker
Code like @code{COME FROM (100)} is a single statement in @ical{}, but
several statements in Funge-98; therefore, some method of telling the
interpreter where to start executing to look for @code{COME FROM}s,
@code{NEXT FROM}s, and line labels is needed.  The method used by
@cic{} is that of the 'marker'; a marker is represented by character
0xB7 (a mid-dot in Latin-1) in the input Funge-98 program, but is
transformed to a capital @samp{M} by @command{ick}.  (The reason for
using a special character for a marker and transforming it rather than
just using @samp{M} is to prevent occurences of @samp{M} in comments
and string literals, etc.@:, having an effect on the control flow of
the program.)  Whenever a @code{NEXT} or line label is encountered (in
the @ical{} program, the Funge program or elsewhere), the Funge
program is executed starting from each marker in each cardinal
direction to look for line labels or @code{COME}/@code{NEXT FROM}s
respectively.  Therefore, @code{COME FROM (100)} is written in
Funge-98 as @code{Maa*C} (where the M is a marker in the source code),
and likewise the line label @code{(100)} would be written as
@code{Maa*L}.  (This code can be written in any cardinal direction,
that is left to right, top to bottom, right to left, or bottom to top,
but not diagonally or flying.)  There are likely to be unused
directions from markers, which will be evaluated too; you can (and
must) close these off by reflecting code execution back into that
marker, another marker, or a non-marker @code{M}.  Note also that a
marker remains in Funge-space even if the @code{M} on the same square
is deleted (the marker itself is not visible to the @code{g} command,
though).

Here are the commands in the @samp{IFFI} fingerprint:
@cindex IFFI, commands
@table @code
@item A
@cindex CREATE, in Funge
This command pops a line number and then an 0"gnirts"-format string
from the stack; they are used as the line number and signature to
@code{CREATE} syntax in the @ical{} program; for details of the format
of the signature, see @ref{ick_create}.  Although using this command
during speculative execution works, doing so is not recommended; if
the target line number for @code{CREATE}d syntax is changed during
speculative execution to find the line that that syntax corresponds
to, its effect is delayed until after the original line is found and
execution continues from that point.  (Side effects during speculative
execution are never recommended, because they might or might not be
optimised away.)
@item C
@cindex COME FROM, in Funge
During speculative execution to find @code{COME FROM}s and @code{NEXT
FROM}s, pops a line label off the top of the stack and does a
@code{COME FROM} that location.  During speculative excution to find
line labels, pops the top of the stack and ends that particular
speculative execution as a failure.  When not doing speculative
execution, pops and discards the top element of the stack.
@item D
This command must only be used when the Funge program is executing a
@code{CREATE}d command, and allows access to the arguments that
command has.  It pops an integer off the top of the stack, and treats
it as an argument position (0-based, so 0 refers to the first
argument, 1 refers to the second, and so on).  Note that providing an
invalid argument number, or running this command when not implementing
a @code{CREATE}d command, leads to undefined behaviour (possibly a
reflection, possibly a segfault, possibly worse).

The command pushes information about the argument chosen onto the
stack; the following information is pushed from bottom to top:
@itemize
@item
The data type of the argument, in bits (16 if the argument was a
onespot variable or expression of onespot type, and 32 if the argument
was a twospot variable or expression of twospot type).  Note that this
is under the @cic{} typing rules, rather than the @icst{} typing rules
(that is, select's type is always that of its right argument no matter
how many bits are actually selected).
@item
1 if the argument is an array variable, 0 if it is a scalar value.
@item
0 if the argument is not a variable, or the variable's number if it is
(e.g.@: @code{.123} would push 123 here, but @code{.1~.2} would push
0).
@item
The argument's value at the time that the @code{CREATE}d instruction
was called.
@item
The argument's value now, or alternatively a repeat of the previous
stack element if @option{-a} (@pxref{-a}) was not used.  (Without
@option{-a}, the information needed to re-evaluate the expression is
not available.)
@end itemize
@item F
@cindex FORGET, in Funge
During speculative execution, this command reflects; otherwise, this
command pops an integer from the top of stack, and @code{FORGET}s that
many @code{NEXT} stack entries (or all of them if the argument given
is negative).
@item G
@cindex variables, Funge, accessing
This command pops an integer from the top of stack.  If it is
positive, the value of the onespot variable whose name is the popped
integer is pushed onto the stack; if it is negative, the value of the
twospot variable whose name is minus the popped integer is pushed onto
the stack; and if it is zero, the command reflects.  If the referenced
variable is not in the @ical{} program at all, this causes an @ical{}
error due to referencing a nonexistent variable.
@item L
@cindex line label, in Funge
During speculative execution to find @code{COME FROM}s and @code{NEXT
FROM}s, this command pops and discards the top stack element, then
ends that speculative execution.  During speculative execution to find
a line label, this command pops an integer from the top of stack and
succeeds with that integer as the line label (that is, it is possible
to @code{NEXT} to an @code{L} in the Funge program if a marker,
followed by code to push the correct line number onto the stack,
precedes that @code{L}).  When not doing speculative execution, the
integer on the top of the stack is used as a line label (assuming it
is in the range 1--65535, otherwise it is popped and discarded), and
a search is made for @code{COME FROM}s and @code{NEXT FROM}s aiming
for that line label (including in the @ical{} program and the Befunge
program itself, as well as programs in any other language which may be
linked in).  Note that just as in @ical{}, it is possible to
@code{NEXT} to a line label which has a @code{COME FROM} aiming for
it, in which case the @code{COME FROM} will come from that line label
as soon as the @code{NEXT} transfers control to it.
@item M
Does nothing if not in speculative execution, or ends the current
speculative execution with failure.  (This is so that code like
@example
 v
>M5C
 ^
@end example
does exactly the same thing as @code{COME FROM (5)}, even when, for
instance, it is entered from the left in the Funge program, rather
than gaining control from the line label @code{(5)}.)
@item N
@cindex NEXT, in Funge
During speculative execution, reflects.  Otherwise, pops the top stack
element, interprets it as a line label, and @code{NEXT}s to that line
label (this may start speculative execution to look for line labels,
but might not if it isn't needed, for instance if the line label in
question is in the @ical{} program or in a C program linked to the
Befunge program).
@item R
@cindex RESUME, in Funge
During speculative execution, reflects.  Otherwise, pops the top stack
element, removes that many items from the @code{NEXT} stack, and
@code{RESUME}s at the last item removed.  (If the top stack element
was zero, negative, or too large, this will cause a fatal error in the
@ical{} program.)
@item S
@cindex variables, Funge, setting
Pops a variable number (interpreted as onespot if positive, or minus
the number of a twospot variable if negative) and an integer from the
stack, and sets the referenced variable to the integer.  This reflects
if an attempt is made to set the nonexistent variable 0, causes a
fatal error in the @ical{} program if an attempt is made to set a
variable that doesn't exist there, and does not set read-only
variables (but pops the stack anyway).  If the integer is too high for
the variable it is being stored in, only the least significant 16 or
32 bits from it will be used; and likewise, if it is negative, it will
be treated as the two's complement of the number given.
@item V
Pops a @code{CREATE}d argument index and an integer from the top of
stack.  (This is undefined behaviour if not in the implementation of a
@code{CREATE}d statement, or if the referenced argument does not
exist; as with the @code{D} instruction, 0 refers to the first
argument, 1 to the second, and so on.)  If the @option{-a} option is
not used, this command does nothing; otherwise, the value of the
argument will be set to the integer.  (This involves doing a reverse
assignment if the argument is a non-variable expression, as usual, and
causes a fatal error in the @ical{} program if the reverse assignment
is impossible or an attempt is made to assign a scalar to an array.)
@item X
@cindex NEXT FROM, in Funge
This is identical to @code{C}, except that it does a @code{NEXT FROM}
rather than a @code{COME FROM}.
@end table

As with external calls to C, terminating any program involved (whether
the @ical{} program with @code{GIVE UP}, the Befunge program with
@code{@@} or @code{q}, or a C program with @code{exit()}) causes all
programs involved to terminate, and likewise a fatal error will end
all programs with an error.

One final point which is probably worth mentioning is that flow
control instructions only record the IP's position and direction,
nothing else; so for instance, if the stack is modified in one part of
the code, those modifications will remain even after a @code{RESUME},
for instance.

@node Miscellaneous External Calls
@section Miscellaneous External Calls
@cindex external calls, miscellaneous
@cindex miscellaneous external calls
@cindex libraries, external calls
@cindex external calls, libraries
@cindex C99
@cindex external calls, C99

@portability{no, version 0.29+, no, no}

It is possible to specify other information to the external calls
system by using the filename list after all the options are given.  To
be precise, certain filename patterns are recognised and used to
change the options that are used to compile the externally-called
files.

The @samp{.c99} extension is treated identically to @samp{.c}, except
that it causes the file with that extension to be preprocessed as C99
(the more modern version of the C standard, the older C89 is more
common), and that all C files involved will be compiled and linked as
C99. (This corresponds to @option{-std=c99} in @command{gcc}.)

The @samp{.a} extension indicates that an object-code library should
be linked in to the final program.  This is most commonly used to link
in the maths library @file{libm.a} and other such system libraries.
If the filename is of the form @samp{lib*.a}, then the file will be
searched for in the standard directories for libraries on your system,
and also where the @cic{} libraries are stored (which may be the same
place); otherwise, the current directory will be searched.
(Specifying @file{libm.a} on the command line corresponds to passing
@option{-lm} to @command{gcc}.)

@node Using External Calls
@section Using External Calls
@cindex using external calls
@cindex external calls, using

Whatever language your source files are written in, when @option{-e}
is used (@pxref{-e}), the compiler will go through much the same
steps.

First, the @ical{} program specified is compiled into a C program that
uses the @ical{} external call conventions for its control flow
operations.  The resulting @samp{.c} file will be left behind in the
same directory (even if @option{-g} isn't used); if you look at it,
you'll see the @code{#include <ick_ec.h>} line, and the other
hallmarks of an external call program (for instance, @ical{}
@code{NEXT}s will translate into slightly modified @code{ick_next}s;
the modification is simply to allow the correct line number to be
displayed in case of error).

After that, the resulting files are preprocessed twice.  First, the C
preprocessor is run on the files; then, a special @cic{}
`preprocessor' is run on the files.  (`Preprocessor' is a bit of a
misnomer here, as it's near the end of the compilation process;
`postprocessor' would likely be more accurate, or maybe
`interprocessor'.)  Its job is to fix line labels between the gotos
that are used to implement jumping into the middle of a C function, to
assign unique numbers to things that need them, and to keep track of
which functions need to be checked for line labels and for @code{COME
FROM}s and @code{NEXT FROM}s.  The resulting file will have the
extension @samp{.cio}; it is almost human-readable, especially if you
run it through a C code indenter, and consists of C code (or code in
whatever language is being linked to the @ical{} code, but so far only
C is accepted) and instructions to @command{gcc}.  The @samp{.cio}
file will be left behind for you to look at, if you like.

Once the @samp{.cio} files have been produced, @command{gcc} is used
to compile all the @samp{.cio} files and link them together into an
executable; the executable will have the same name as the @ical{}
source, minus any extension (and on DJGPP, assuming that its version
of @command{gcc} could handle the resulting command line (not
necessarily guaranteed), a @samp{.exe} extension is added), and will
consist of all the C files linked together with the @ical{}.  Any
functions named @code{main} in the C files will be deleted; likewise,
if there is a name clash between any two functions, the one in the
file named earlier on the command line will be used.  There is
presumably some use for this feature, although I haven't figured out
what it is yet.

Extending this to other compiled languages is mostly a problem of
determining how they fit into the @ical{} control structure, which is
not a trivial task, and of figuring out how to link them to C code,
which in some cases is trivial (especially if the language is one that
@command{gcc} can compile!) and in other cases is very difficult.  If
anyone has any ideas of new languages that could be added to the
external calls system, feel free to contact the current @cic{}
maintainer with suggestions or patches.

@node Expansion Libraries
@section Expansion Libraries
@cindex expansion libraries
@cindex libraries

@portability{no, version 0.28+, no, no}

The @cic{} distribution comes with libraries that can be used to
extend its capabilities; they are implemented using the external call
mechanism, and are in effect standard files to include using that
mechanism.  To use an expansion library, give the @option{-e} option
to @command{ick} (note that this means you cannot use them with the
debugger or profiler, nor with multithreaded or backtracking
programs), and specify the expansion library's name at the end of the
command line (or to be precise, anywhere after the initial @ical{}
file).  The libraries themselves are written in C and have a @samp{.c}
extension, and are human-readable; @cic{} will look for them in the
same places as it looks for the system library (including in the
current directory, so you can test your own expansion libraries
without having to install them).

Expansion libraries use C identifiers which start with the string
@samp{ick_my_} (this is not used by the compiler, and is explicitly
not affected by the prohibition on identifiers starting @samp{ick_}
when writing an expansion library), and use line labels in the range
(1600) to (1699).  (Most programs will be avoiding this range anyway,
because it's inside the (1000) to (1999) range reserved for the system
library, but the system library doesn't use it, in much the same way
that the identifiers used are inside the range reserved for the
compiler, but the compiler doesn't use them.)

Expansion libraries are available from @cic{} version 0.28; @clcic{}
has a similar concept (that of `preloads'), but implemented a
completely different way.

@subheading syslibc
@findex syslibc
@cindex system library, in C
@cindex C, system library

@option{syslibc} is an implementation of the base-2 @ical{} system
library in C (@pxref{System Library}); using it in programs running in
other bases is accepted by the compiler, but likely to produce
unpredictable results.  When using this expansion library, you also
need to give the @option{-E} option (@pxref{-E+,,-E}) so that the main
system library is not included, or it will be used in preference to
the expansion library.  All documented features of the @ical{} base-2
system library are implemented, but most undocumented features are
not, so @ical{} programs which relied on them (dubious behaviour in
any case) will not work with @option{syslibc}.  The main reason to use
this library is to increase the speed of an @ical{} program; however,
note that the speed gains in arithmetic will be accompanied by the
performance penalty of using the external calls infrastructure, unless
you were already using it.

@subheading compunex
@findex compunex
@cindex computed NEXT
@cindex NEXT, computed

As an example of using @code{ick_create}, a very simple expansion
library is provided to enable a computed NEXT capability, by defining
a new command @code{COMPUNEX}.  It is used as @code{DO .1 COMPUNEX}
(allowing any expression in place of the .1), and is similar to an
ordinary @code{NEXT}, but has two limitations: it takes up two
@code{NEXT} stack entries, and the top one should not be
@code{RESUMEd} past or forgotten (thus it isn't a particularly useful
command, except maybe to produce the equivalent of something like
function pointers).  By the way, note that @cic{} avoids computed
@code{NEXT} mainstream for much the same way that @clcic{} avoids
@code{NEXT} altogether; it makes things too easy.  This example is
provided mostly just to demonstrate the syntax, and the care that
needs to be taken with implementing flow control operators.

@samp{compunex} is double-deprecated; an alternative is the following
sequence of commands involving computed @command{CREATE}:

@example
DO CREATE .1 ABC
DO ABC
@end example

This sequence emulates all features of @code{NEXT} (although it has
different gerunds and is two statements, not one), making it much more
useful for simulating computed @code{NEXT} than @code{COMPUNEX}
is. (There's no need to avoid forgetting the return value; although
this skips the @code{CREATE} cleanup, none is required because the
created statement @code{ABC} (any other statement would do just as
well) takes no arguments.)

@node Differences to Other Compilers
@chapter Differences to Other Compilers
@cindex INTERCAL compilers

The @cic{} compiler exists in a world of several other compilers.

@subheading Differences to the Princeton compiler
@cindex Princeton compiler
The Princeton compiler was the first @ical{} compiler available, and
compiled @icst{}.  Using @command{convickt} (@pxref{convickt}) to
translate its programs from the original EBCDIC to Latin-1 or
Atari-syntax ASCII is required to run them under the @cic{} compiler,
but apart from that there should be no problems; everything that that
compiler can do can be reproduced by @cic{}, even including some of
its bugs.  The only potential problems may be where constructs were
nonportable or dubious to begin with (such as the
@code{IGNORE}/@code{RETRIEVE} interaction), or where commands intended
to be syntax errors were used in the program but have a meaning in
@cic{}.  For extra portability, it's possible to use the @code{-t}
compiler option to @command{ick} (@pxref{-t}) to tell it to interpret
the program as @icst{}, but as @cic{}'s dialect of @ical{} is
basically backward-compatible anyway this mostly serves to check newer
programs for compatibility with older compilers.

@subheading Differences to the Atari compiler
@cindex Atari compiler
The Atari compiler was another implementation of @icst{}, which was
basically identical to the Princeton compiler apart from its use of
ASCII and Atari syntax.  Everything said under the previous section
applies, except that as it uses the same syntax as @cic{} anyway
(@cic{}'s syntax was based on the Atari compiler's), there is no need
to use @command{convickt}.

@subheading Differences to @jic{}
@cindex J-INTERCAL
The @jic{} compiler is an implementation of @ical{} written in Java
that compiles @ical{} into Java (and so has a similar relationship
with Java to that of the @cic{} compiler (which is written in C and
compiles into C) with C).  @jic{} has much the same feature set as
older versions of @cic{}, with a few changes (such as the addition of
Esperanto and error messages coming up in different situations).
@jic{} programs should run fine on @cic{} without trouble (as it is
also an Atari syntax compiler), except in nonportable cases such as
@code{IGNORE}/@code{RETRIEVE} interaction.

@subheading Differences to @clcic{}
@cindex CLC-INTERCAL
The @clcic{} compiler is the most modern @ical{} compiler apart from
@cic{} (both compilers are maintained and updated every now and then
as of the time of writing, so which is more modern is normally a
matter of when you happen to check).  Unlike the other three compilers
mentioned above, it has a quite significant feature set, including
many features not implemented or only partially implemented in @cic{},
and is responsible for the origin of many of the features added in
more recent versions of @cic{}.  Generally speaking, a @clcic{}
program that uses its advanced features is unlikely to run on @cic{},
or vice versa, whatever you do (apart from completely rewriting the
more advanced parts of the program.)

However, there are certain steps that can be taken to transfer less
advanced programs from one compiler to the other.  First, translate
the program to Latin-1 Princeton syntax (if translating from @clcic{}
to @cic{}) or Atari syntax (if translating from @cic{} to @clcic{}),
maybe using @command{convickt}, if necessary.  (Note that here the
program is being translated to the syntax that is not default for the
target compiler.)  Then use command-line arguments to switch the
compiler into the correct emulation mode for the other compiler;
@cic{} uses the options @option{-xX}, and on @clcic{} this is done by
selecting the appropriate preloads, or by changing the program's file
extension to @samp{.ci}.  In each case other options may be needed to
turn on various extensions (maybe @option{-m} or @option{-v} if
translating to @cic{}, maybe the preload for gerund-based @code{COME
FROM} if translating to @clcic{}), and if translating to @clcic{} you
need to append the system library to your program yourself because
@clcic{} doesn't load it automatically.

In the case of very simple programs, or if you want to spend the
effort in translating compiler-specific code from one compiler to
another, you may be able to work without emulation options.  (This is
a good target to aim for, in any case.)  In such a case, you would do
nothing other than possibly edit the program to be more portable and a
possible character set and syntax change using @command{convickt}.  If
you need compiler-specific code, you may be able to detect the
compiler in the code itself and adapt accordingly; making use of the
@code{IGNORE}/@code{RETRIEVE} interaction is one way to do this, as it
differs between @cic{}, @jic{}, and @clcic{}.  The other things to
watch out for when doing this are that @clcic{} needs an explicit
option to enable the use of @code{NEXT}, that @clcic{} doesn't load
the system library itself (you need to manually append it to the end
of the program) and that you probably shouldn't number a line (666)
unless you know what you're doing, because that line number has a
special meaning in @clcic{}.

@ifset notsplit
@partheading{PART IV: APPENDICES AND INDICES}
@end ifset
@node Character Sets
@appendix Character Sets
@cindex character sets
@cindex Atari, character set
@cindex Baudot
@cindex EBCDIC
@cindex Latin-1

The following table explains the equivalences between the various
character sets used for @ical{}: 7-bit ASCII Atari syntax, 5-bit
Baudot Princeton syntax, 8-bit EBCDIC Princeton syntax, and 8-bit
Latin-1 Princeton syntax.  (The Baudot and EBCDIC are the @clcic{}
versions, which are used by @ical{} compilers but basically nowhere
else.)  The characters themselves are not shown in the table below,
because they would have to be shown in some syntax, which would be
misleading.  (Atari syntax is used throughout this manual; you could
convert from that, assuming you have an ASCII table handy.)  You can
also use the @command{convickt} command-line tool to translate @ical{}
programs from one format to another (@pxref{convickt}).  Note that
Baudot has more than one 'shift state'; the shift state (1, 2, 3, or
4) is written before the hexadecimal code for each character, and *
represents a character available in every shift state.  To change from
one shift state to another, use character 1f to change from shift
states 3 or 4 to 1, or from 1 or 2 to 2, and character 1b to change
from shift states 1 or 2 to 3, or from 3 or 4 to 4.

@multitable {@b{Atari}}{@b{Baudot}}{@b{EBCDIC}}{@b{Latin-1}}
@headitem Atari @tab Baudot @tab EBCDIC @tab Latin-1
@item 09 @tab N/A @tab 09 @tab 09
@item 0a @tab * 02 @tab 0a @tab 0a
@item 0d @tab * 08 @tab 0d @tab 0d
@item 20 @tab * 04 @tab 40 @tab 20
@item 21 @tab 3 0d @tab 4f @tab 21
@item 22 @tab 3 11 @tab 7f @tab 22
@item 23 @tab 4 06 @tab 7b @tab 23
@item 24 @tab 4 01 @tab 4a @tab a2
@item 25 @tab 4 1c @tab 6c @tab 25
@item 26 @tab 3 1a @tab 50 @tab 26
@item 27 @tab 3 0b @tab 7d @tab 27
@item 28 @tab 3 0f @tab 4d @tab 28
@item 29 @tab 3 12 @tab 5d @tab 29
@item 2a @tab 4 09 @tab 5c @tab 2a
@item 2b @tab 4 03 @tab 4e @tab 2b
@item 2c @tab 3 0c @tab 6b @tab 2c
@item 2d @tab 3 03 @tab 60 @tab 2d
@item 2e @tab 3 1c @tab 4b @tab 2e
@item 2f @tab 3 1d @tab 61 @tab 2f
@item 30 @tab 3 16 @tab f0 @tab 30
@item 31 @tab 3 17 @tab f1 @tab 31
@item 32 @tab 3 13 @tab f2 @tab 32
@item 33 @tab 3 01 @tab f3 @tab 33
@item 34 @tab 3 0a @tab f4 @tab 34
@item 35 @tab 3 10 @tab f5 @tab 35
@item 36 @tab 3 15 @tab f6 @tab 36
@item 37 @tab 3 07 @tab f7 @tab 37
@item 38 @tab 3 06 @tab f8 @tab 38
@item 39 @tab 3 18 @tab f9 @tab 39
@item 3a @tab 3 0e @tab 7a @tab 3a
@item 3b @tab 3 1e @tab 5e @tab 3b
@item 3c @tab 4 0f @tab 4c @tab 3c
@item 3d @tab 4 07 @tab 7e @tab 3d
@item 3e @tab 4 12 @tab 6e @tab 3e
@item 3f @tab 4 0c @tab 65 @tab a5
@item 40 @tab 3 19 @tab 6f @tab 3f
@item 41 @tab 1 03 @tab c1 @tab 41
@item 42 @tab 1 19 @tab c2 @tab 42
@item 43 @tab 1 0e @tab c3 @tab 43
@item 44 @tab 1 09 @tab c4 @tab 44
@item 45 @tab 1 01 @tab c5 @tab 45
@item 46 @tab 1 0d @tab c6 @tab 46
@item 47 @tab 1 1a @tab c7 @tab 47
@item 48 @tab 1 14 @tab c8 @tab 48
@item 49 @tab 1 06 @tab c9 @tab 49
@item 4a @tab 1 0b @tab d1 @tab 4a
@item 4b @tab 1 0f @tab d2 @tab 4b
@item 4c @tab 1 13 @tab d3 @tab 4c
@item 4d @tab 1 1c @tab d4 @tab 4d
@item 4e @tab 1 0c @tab d5 @tab 4e
@item 4f @tab 1 18 @tab d6 @tab 4f
@item 50 @tab 1 16 @tab d7 @tab 50
@item 51 @tab 1 17 @tab d8 @tab 51
@item 52 @tab 1 0a @tab d9 @tab 52
@item 53 @tab 1 05 @tab e2 @tab 53
@item 54 @tab 1 10 @tab e3 @tab 54
@item 55 @tab 1 07 @tab e4 @tab 55
@item 56 @tab 1 1e @tab e5 @tab 56
@item 57 @tab 1 12 @tab e6 @tab 57
@item 58 @tab 1 1d @tab e7 @tab 58
@item 59 @tab 1 15 @tab e8 @tab 59
@item 5a @tab 1 11 @tab e9 @tab 5a
@item 5b @tab 4 10 @tab 9e @tab 5b
@item 5c @tab 4 05 @tab N/A @tab 5c
@item 5d @tab 4 13 @tab 5a @tab 5d
@item 5e @tab 4 0d @tab 6a @tab 7c
@item 5f @tab 4 15 @tab 7c @tab 40
@item 60 @tab N/A @tab N/A @tab 60
@item 61 @tab 2 03 @tab 81 @tab 61
@item 62 @tab 2 19 @tab 82 @tab 62
@item 63 @tab 2 0e @tab 83 @tab 63
@item 64 @tab 2 09 @tab 84 @tab 64
@item 65 @tab 2 01 @tab 85 @tab 65
@item 66 @tab 2 0d @tab 86 @tab 66
@item 67 @tab 2 1a @tab 87 @tab 67
@item 68 @tab 2 14 @tab 88 @tab 68
@item 69 @tab 2 06 @tab 89 @tab 69
@item 6a @tab 2 0b @tab 91 @tab 6a
@item 6b @tab 2 0f @tab 92 @tab 6b
@item 6c @tab 2 13 @tab 93 @tab 6c
@item 6d @tab 2 1c @tab 94 @tab 6d
@item 6e @tab 2 0c @tab 95 @tab 6e
@item 6f @tab 2 18 @tab 96 @tab 6f
@item 70 @tab 2 16 @tab 97 @tab 70
@item 71 @tab 2 17 @tab 98 @tab 71
@item 72 @tab 2 0a @tab 99 @tab 72
@item 73 @tab 2 05 @tab a2 @tab 73
@item 74 @tab 2 10 @tab a3 @tab 74
@item 75 @tab 2 07 @tab a4 @tab 75
@item 76 @tab 2 1e @tab a5 @tab 76
@item 77 @tab 2 12 @tab a6 @tab 77
@item 78 @tab 2 1d @tab a7 @tab 78
@item 79 @tab 2 15 @tab a8 @tab 79
@item 7a @tab 2 11 @tab a9 @tab 7a
@item 7b @tab 4 0a @tab 9c @tab 7b
@item 7c @tab 4 1e @tab fe @tab N/A
@item 7d @tab 4 11 @tab dc @tab 7d
@item 7e @tab 4 0b @tab a1 @tab 7e
@end multitable

@node convickt
@appendix convickt
@cindex convickt
@cindex character sets, converting
@cindex converting between character sets

A variety of character sets have historically been used to represent
@ical{} programs.  Atari syntax was designed specifically for use with
ASCII-7, and all Atari-syntax-based @ical{} compilers accept that
character set as possible input.  (@cic{} also accepts Latin-1 and
UTF-8.)  However, the story is more complicated with Princeton syntax;
the original Princeton compiler was designed to work with EBCDIC, but
because modern computers are often not designed to work with this
character set other character sets are often used to represent it,
particularly Latin-1.  The @clcic{} compiler accepts Latin-1, a custom
dialect of EBCDIC, Baudot, and a punched-card format as input; @cic{}
can cope with Latin-1 Princeton syntax, but for the other character
sets, for other compilers, or just for getting something
human-readable, it's useful to have a conversion program.
@command{convickt} is an @ical{} character set conversion program
designed with these needs in mind.

The syntax for using @command{convickt} is

@example
convickt @var{inputset} @var{outputset} [@var{padding}]
@end example

(that is, the input and output character sets are compulsory, but the
parameter specifying what sort of padding to use is optional).

The following values for @var{inputset} and @var{outputset} are
permissible:

@table @samp
@item latin1
Latin-1, or to give it its official name ISO-8859-1, is the character
set most commonly used for transmitting @clcic{} programs, and
therefore nowadays the most popular character set for Princeton syntax
programs.  Because it is identical to ASCII-7 in all codepoints that
don't have the high bit set, most of the characters in it can be read
by most modern editors and terminals.  It is also far more likely to
be supported by modern editors than EBCDIC, Baudot, or punched cards,
all of which have fallen into relative disuse since 1972.  It is also
the only input character set that @cic{} supports for Princeton syntax
programs.  It uses 8 bit characters.

@item ebcdic
EBCDIC is an 8-bit character set that was an alternative to ASCII in
1972, and is the character set used by the original Princeton
compiler.  Unfortunately, there is no single standard version; the
version of EBCDIC used by @command{convickt} is the one that @clcic{}
uses.  It is the default input character set that @clcic{} uses
(although more recent versions of @clcic{} instead try to guess the
input character set based on the input program.)

@item baudot
Baudot is a 5-bit character set with shift codes; therefore when
storing it in a file on an 8-bit computer, padding is needed to fill
in the remaining three bits.  The standard Baudot character set does
not contain all the characters needed by @ical{}; therefore, @clcic{}
uses repeated shift codes to add two more sets of characters.
@command{convickt} uses the @clcic{} version of Baudot, so as to be
able to translate programs designed for that compiler; however,
standard Baudot is also accepted in input if it contains no redundant
shift codes, and if the input contains no characters not in standard
Baudot, the output will be written so that it is both correct standard
Baudot and correct @clcic{} Baudot for those characters.

@item atari
This option causes @command{convickt} to attempt a limited conversion
to or from Atari syntax; this uses ASCII-7 as the character set, but
also tries to translate between Atari and Princeton syntax at the
character level, which is sometimes but not always effective.  For
instance, @code{?} is translated from Atari to Princeton as a yen
sign, and from Princeton to Atari as a whirlpool (@code{@@}); this
sort of behaviour is often capable of translating expressions
automatically, but will fail when characters outside ASCII-7 (Atari)
or Latin-1 (Princeton) are used, and will not, for instance, translate
a Princeton @code{V}, backspace, @code{-} into Atari @code{?}, but
instead leave it untouched.  ASCII-7 is a 7-bit character set, so on
an 8 bit computer, there is one bit of padding that needs to be
generated; note, however, that it is usual nowadays to clear the top
bit when transmitting ASCII-7, which the `printable' and `zero'
padding styles will do, but the `random' style may not do.

@end table

When using a character set where not all bits in each byte are
specified, a third argument can be given to specify what sort of
padding to use for the top bits of each character. There are three
options for this:

@multitable {printable}{Keep the output in the range 32-126 where possible}
@headitem Option @tab Meaning
@item printable
@tab Keep the output in the range 32-126 where possible
@item zero
@tab Zero the high bits in the output
@item random
@tab Pad with random bits (avoiding all-zero bytes)
@end multitable

Note that not all conversions are possible.  If a character cannot be
converted, it will normally be converted to a NUL byte (which is
invalid in every character set); note that this will prevent
round-tripping, because NUL is interpreted as end-of-input if given in
the input.  There is one exception; if the character that could not be
converted is a tab character, it will be converted to the other
character set's representation of a space character, if possible,
because the two characters have the same meaning in @ical{} (the only
difference is if the command is a syntax error that's printed as an
error message).  (The exception exists to make it possible to
translate existing @ical{} source code into Baudot.)

@node Optimizer Idiom Language
@appendix Optimizer Idiom Language
@cindex Optimizer Idiom Language
@cindex OIL

One file in the @cic{} distribution (@file{src/idiotism.oil}) is written
in Optimizer Idiom Language, a programming language designed especially
for expressing optimizer idioms for @ical{} in an easily editable form
(well, at least it's easier than the unmaintainable set of idioms
hard-coded in C that were used in previous versions of the @ical{}
compiler).

@menu
* Basics: OIL Basics.               The basics of how an OIL program works.
* Syntax: OIL Syntax.               How to write comments, idioms, and groups.
* Expressions: OIL Expressions.     Expressions are the basis of idioms.
* Patterns: OIL Patterns.           Filling in the left hand side of an idiom.
* Replacements: OIL Replacements.   Syntax for the right hand side.
* Loops: OIL Loops.                 Simplifying and shortening programs.
* Tips: OIL Tips.                   Some tips about using OIL.
* Example: OIL Example.             An example of how OIL can work.
@end menu

@node OIL Basics
@appendixsec OIL Basics
@cindex OIL, basics
@cindex @file{src/idiotism.oil}
@cindex @file{idiotism.oil}
@cindex OIL, execution

The structure of an @acronym{OIL} file consists of a sequence of idioms.
An optimizer idiom looks for a certain pattern in an expression (which
could be an @ical{} expression, or an expression that has already been
partly optimized and therefore contains some non-@ical{} operators), and
replaces it with a replacement that's `simpler' in some sense (in the
case of @cic{}, `simpler' is interpreted to mean `compiles into a faster
or smaller executable when run through a C compiler').  When an
@acronym{OIL} program acts on an input @ical{} file, it keeps on
matching idioms to simplify expressions, until none of the idioms act
any more (and if a situation occurs where idioms can keep matching
indefinitely, the compiler goes into an infinite loop; so don't allow
that to happen); at present, the idioms are tried from left to right,
from the leaves of an expression to its root, and from the start of the
OIL file to the end; but don't rely on that, because it's subject to
change (and gets confusing when you think about what happens when the
program actually does a replacement).  Anyway, the point is that if an
idiom can match an expression, and another idiom doesn't change it
first, then the idiom will be matched against that part of the
expression eventually, and the program won't end until there are no
idioms that match the optimized expression.

At present, the only place that @acronym{OIL} is used in the @cic{}
compiler is when the @option{-O} option (@pxref{-O+,,-O}) is used in
base 2.  (Syntax is planned to extend @acronym{OIL} to higher bases, and
some of this is documented and even implemented, but there's no way to
use it.)  The idioms are read from the file @file{src/idiotism.oil}
during the compilation of the @cic{} from sources; you can change the
idioms, but you will then have to recompile the distribution (and if you
are using the @command{config.sh} method, also reinstall, but that will
be pretty fast.)

@node OIL Syntax
@appendixsec OIL Syntax
@cindex OIL, syntax
@cindex syntax, of OIL

An @acronym{OIL} file is encoded as an @acronym{ASCII} text file using
no codepoints outside the range 0-127; using 10 for newline (as on a
UNIX or Linux system) is always acceptable, but using 13 then 10 (as is
common on Windows or DOS) for newline is acceptable only if your C
compiler recognizes that as a newline.  I have no idea what happens if
you use just 13 on an Apple computer on which that is the common newline
convention.

@cindex OIL, comments
@cindex comments, OIL
Comments can be given anywhere in the file by writing lines starting
with semicolons (known as hybrids to @ical{} programmers).  It's also
possible to write a semicolon after part of a line to comment out the
rest of the line.  Inside braced C expressions, comments can be given
anywhere whitespace would be allowed by placing them between @code{/*}
and @code{*/} (in such cases, the comments will be copied verbatim to
the C temporary files used when building the @cic{} compiler, where your
C compiler will ignore them).  Whitespace is ignored nearly everywhere;
the only places it isn't ignored are in the middle of a decimal
constant, inside square brackets, immediately after one of the
characters @samp{.:#_@}}, and anywhere that C doesn't allow it in quoted
C code.  (This means that you can even place it inside operators like &&
if you like, as long as they're part of OIL code and not C code,
although doing this is not recommended.)  If you use whitespace in a
situation where it isn't ignored, that's almost certainly an error.

@cindex OIL, idiom groups
Idioms are grouped into groups of idioms by placing an identifier in
square brackets before the group; this follows the rules for C
identifiers, except that there's a maximum length of 30 characters.
This identifier is the `name' of the group, which has no effect except
on optimizer debug output; for that matter, the only effect a group has
is that all idioms in the group look the same in optimizer debug output,
because they have the same name.  It's recommended that idioms only have
the same name if they are the same idiom, possibly written in several
ways.  For example, a shift by 0 has no effect and may as well be
removed from the output; the way to express this in OIL is:

@example
[nullshift]
(_1 >> #0)->(_1)
(_1 << #0)->(_1)
@end example

Here, nullshift is the name of the group of idioms, and two idioms are
given; one which removes a null rightshift, and one which removes a null
leftshift.

@cindex OIL, idioms
@cindex idiom
As the example above shows, the syntax of an idiom itself is

@example
(pattern)->(replacement)
@end example

The parentheses here are actually part of the pattern and/or
replacement, and as such sparks (apostrophes) or rabbit-ears (double
quotes) can be used instead; they're shown in the syntax because the
outer layer of parenthesising is always required.  Both the pattern and
replacement are @acronym{OIL} expressions, although they both have their
own special syntax elements as well.

@node OIL Expressions
@appendixsec OIL Expressions
@cindex expressions, OIL
@cindex OIL, expressions

An @acronym{OIL} expression is built around subexpressions connected by
infix binary operators and/or preceded by prefix unary operators, the
same way as in C or @ical{} (although unary operators must be entirely
before their argument; the one character later position is not allowed.)
As in @ical{}, there is no operator precedence; expressions must be very
fully bracketed to show unambiguously what the precedences must be, and
then more so; for instance, bracketing marks must be placed around the
argument of a unary operator in most circumstances.  Bracketing of
expressions can be done with parentheses, sparks (apostrophes) or
rabbit-ears (double-quotes).

The following unary and binary operators are allowed in OIL expressions:

@cindex OIL, operators
@cindex operators, OIL
@multitable {@code{@@216..@@516}}{@ical{} unary generalised whirlpool (16-bit)}
@item @code{$} @tab INTERCAL mingle
@item @code{~} @tab INTERCAL select
@item @code{&16} @tab INTERCAL unary AND (16-bit)
@item @code{V16} @tab INTERCAL unary OR (16-bit)
@item @code{?16} @tab INTERCAL unary XOR (16-bit)
@item @code{^16} @tab INTERCAL unary sharkfin (16-bit)
@item @code{@@16} @tab INTERCAL unary whirlpool (16-bit)
@item @code{@@216..@@516} @tab INTERCAL unary generalised whirlpool (16-bit)
@item @code{&32} @tab INTERCAL unary AND (32-bit)
@item @code{V32} @tab INTERCAL unary OR (32-bit)
@item @code{?32} @tab INTERCAL unary XOR (32-bit)
@item @code{^32} @tab INTERCAL unary sharkfin (32-bit)
@item @code{@@32} @tab INTERCAL unary whirlpool (32-bit)
@item @code{@@232..@@532} @tab INTERCAL unary generalised whirlpool (32-bit)
@item @code{&} @tab C binary bitwise AND
@item @code{|} @tab C binary bitwise OR
@item @code{^} @tab C binary bitwise XOR
@item @code{+} @tab C addition
@item @code{-} @tab C subtraction
@item @code{*} @tab C multiplication
@item @code{/} @tab C integer division
@item @code{%} @tab C modulus
@item @code{>} @tab C greater than
@item @code{<} @tab C less than
@item @code{~} @tab C unary bitwise complement
@item @code{!=} @tab C not equals operator
@item @code{==} @tab C equals operator
@item @code{&&} @tab C logical AND
@item @code{||} @tab C logical OR
@item @code{>>} @tab C bitwise rightshift
@item @code{<<} @tab C bitwise leftshift
@item @code{!} @tab C unary logical NOT
@end multitable

(Note that in some cases two operators are expressed the same way, but
that this doesn't matter because one is unary and the other is binary so
that there can't be any ambiguity, only confusion.  Also note that
unlike @ical{} unary logic operators, OIL unary logic operators must
have a bitwidth stated.)

It hasn't yet been explained what operands these operators have to
operate on; the syntax for those depends on whether it's a pattern or
replacement that the expression is representing.

@node OIL Patterns
@appendixsec OIL Patterns
@cindex patterns
@cindex OIL, patterns

Patterns are simply @acronym{OIL} expressions; the expressions match
either original @ical{} input or expressions produced by earlier idioms.
Each operator must match the same operator in the (possibly
partially-optimised) input; the operands themselves are pattern
templates specifying what operands in the input they can match.

One special simple form of match is possible: @code{#@var{NUMBER}},
where @var{NUMBER} is in decimal, matches a constant with that value.
(Unlike in @ical{}, this constant is not limited to being a onespot
value; it is, however, limited to being at most twospot, as are all
operands and intermediate values in @acronym{OIL}.)

Otherwise, an operand consists of the following parts, written in order:

@cindex operands, OIL, in patterns
@cindex patterns, operands
@enumerate

@item
A character to specify the data type of what's being matched.  Usually,
this will be @code{_} to specify that any data type can be matched.  In
a few cases, you may want to use @code{.} or @code{:} to specify that
you only want to match a onespot or twospot value respectively (that is,
16- or 32-bit).  You can also use @code{#}; this specifies a value that
can be any width, but must be known to be a constant with a known value
at optimize time (either because it was hardcoded as a constant
originally or because a constant was produced there by the optimizer,
for instance via a constant folding optimization).

@item
Optionally, an expression in braces (@code{@{} and @code{@}}).  This
expression is written in C, not @acronym{OIL} (as are all expressions in
braces), and puts an extra condition on whether the pattern matches.
The exact meaning of this will be explained later.

@item
A reference number, which must be one decimal digit long.  A reference
number of 0 causes the operand to be discarded immediately after
matching; normally, you will want to specify a positive reference
number.  Two operands with the same reference number must be exactly the
same for the pattern to match (for instance, both references to the same
variable, or identical subexpressions).  The reference number also
allows the operand to be referenced by C expressions on other operands
and by replacements.  Reference numbers must be unique within the idiom
(unless two or reference numbers are deliberately the same so that the
operands they reference have to be identical to produce a match), and
they are scoped only as far as the containing idiom; they don't carry
from one idiom to another.

@end enumerate

Note that syntax like @code{#2} is ambiguous given what comes so far;
the first interpretation is the one that is taken in practice, and if
the second interpretation is wanted the operand should be expressed as
@code{#@{1@}2}, using a no-op braced expression to tell them apart.
This particular no-op is recommended because it's detected and optimized
by the @code{OIL} compiler.

Braced expressions, which must be written purely in C, add extra
conditions; they must return nonzero to allow a possible match or zero
to prevent one.  They can reference the following variables and
functions:

@cindex functions, OIL in C
@cindex OIL, functions in C
@cindex C, within OIL
@anchor{C functions in OIL}
@table @code

@item c
@itemx c@var{NUMBER}
@findex c
@findex c1--c9

This accesses a calculation made automatically by the compiled
@acronym{OIL} program to identify which bits of the operand can possibly
be set, and which ones cannot be.  @code{c} by itself refers to the
operand to which the braced expression is attached; if a number is
given, it refers to another node (the number is interpreted as a
reference number).  The actual value of @code{c} is a 32-bit unsigned
integer, each bit of which is true, or 1, if there is any chance that
the corresponding bit of the operand might be 1, and false, or 0, if
it's known for certain that the corresponding bit of the operand is 0.

For instance:

@example
_@{!(c&4294901760LU)@}1
@end example

The constant given here is FFFF0000 when expressed in hexadecimal; the
point is that the expression matches any operand that is known to have a
value no greater than 65535.  Unless the operand is the argument to a
unary AND, this check generally makes more sense than explicitly
specifying @code{.} rather than @code{_}, because it will identify both
16- and 32-bit values as long as they're small enough to fit into a
onespot variable.  This code could, for instance, be used to check that
an argument to a mingle must be small enough before optimising it (this
is important because an optimisation shouldn't optimise an error -- in
this case, an overflowing mingle -- into a non-error).

@item x
@itemx x@var{NUMBER}
@findex x
@findex x1--x9

@code{x} is like @code{c}, and refers to operands in the same way,
except that it can only refer to an operand marked with @code{#}.  It
holds the value of that constant (a 32-bit unsigned integer), which will
be known to the optimizer at optimize time.  One common use of this is
to detect whether a constant happens to be a power of 2, although there
are many other possibilities that may be useful.

@item r
@findex r

When inside a loop, @code{r} is the value of the loop counter.  (It's
almost certainly a mistake if you have a loop but don't reference the
loop counter at least once, and usually at least twice, within the
loop.)  @xref{OIL Loops}.

@item and16
@itemx and32
@itemx or16
@itemx or32
@itemx xor16
@itemx xor32
@itemx iselect
@itemx mingle
@findex and16
@findex and32
@findex or16
@findex or32
@findex xor16
@findex xor32
@findex iselect
@findex mingle

These are all functions with one argument (apart from iselect and
mingle, which each take two arguments); they exist so that @ical{}
operators can be used by C expressions.  They all take unsigned longs as
input and output, even if they are onespot operators.  Note that it's
entirely possible for these to cause a compile-time error if used on
invalid arguments (such as mingling with an operand over 65535), or to
silently truncate an invalid argument down to the right number of bits;
both of these should be avoided if possible, so the optimiser should
check first to make sure that it doesn't use any of these functions on
invalid arguments.

@item xselx
@findex xselx

This function returns its argument selected with itself; so
@code{xselx(c)} is shorthand for @code{iselect(c,c)}.  When the argument
is very complicated, this can save a lot of space in the original
@acronym{OIL} program.

@item setbitcount
@findex setbitcount

This function simply returns the number of bits with value 1 in its
argument.  This is sometimes useful with respect to various
select-related optimisations, and can be a useful alternative to having
to take logarithms in various situations.

@item smudgeright
@itemx smudgeleft
@findex smudgeright
@findex smudgeleft

The @code{smudgeright} function returns its argument but with all the
bits less significant than the most significant bit with value 1 set to
1; likewise, @code{smudgeleft} returns its argument with all the bits
more significant than the least significant bit with value 1 set to 1.

@end table

Note that all @acronym{OIL} character is done internally using unsigned
32-bit numbers, and C expressions you write should do the same.  The
practical upshot of this is that you should write @code{LU} after any
constant you write in C code; if you don't do this, you are reasonably
likely to get compiler warnings, and the resulting program may not work
reliably, although the @acronym{OIL} compiler itself will not complain.

Here's a more complicated example of an optimizer operand:

@example
#@{!(x&2863311530LU)&&iselect(x,1431655765LU)==
  xselx(iselect(x,1431655765LU))@}3
@end example

It helps to understand this if you know that 2863311530 in hexadecimal
is AAAAAAAA and 1431655765 in hexadecimal is 55555555.  (It's worth
putting a comment with some frequently-used decimal constants in an
@acronym{OIL} input file to help explain what these numbers mean and
make the code more maintainable.)  The operand matches any constant
integer which has no bits in common with AAAAAAAA, and for which if any
bit in common with 55555555 is set, all less significant bits in common
with that number are also set.

@node OIL Replacements
@appendixsec OIL Replacements
@cindex OIL, replacements
@cindex replacements

Replacements have much the same syntax as patterns.  The expressions are
parsed in much the same way; however, one peculiarity of replacements is
that bitwidths must be specified.  @ical{} has a typecaster that figures
out whether each expression is 16 bits or 32 bits wide, but it runs
before the optimizer, and as the optimizer can produce expressions whose
bitwidths don't obey @ical{}'s rules, this information needs to be
inserted somehow in a replacement.  In @cic{}, it usually doesn't matter
what the bitwidth is, and in cases where it doesn't matter the normal
operators (@code{$}, @code{~}, and so on) can be used.  (Note that the
bit width of the entire replacement is always set to the same bit width
as the bit width of the expression matched by the pattern; so you don't
have to worry about the effect on unary logical operators that might be
operating on the expression being optimized.  This is an exception to
the normal bitwidth rules for a replacement.)  In cases where it does
matter (due to @cic{}'s lenient interpretation of bitwidth on mingle
inputs, the only place it matters is in the input to @ical{} unary
logical operators), both the bitwidth of the operator and the argument
on which it operates must be explicitly given, and given as the same
value; to set the bitwidth of an operator's result, simply write the
bitwidth (16 or 32 for onespot and twospot respectively) immediately
after the operator; for instance, @code{!=32} will generate a not-equals
operation with a 32-bit bitwidth.  If an operator's width is set to 16,
and during the course of execution of the optimized program, a value
that doesn't fit into 16 bits is encountered, that's undefined behaviour
and anything might happen (most likely, though, the program will just
act as though its width had been set to 32 bits instead); this error
condition is not detected.  Also note that operators like @code{&32}
already have a bitwidth specified, so specifying @code{&3232} (or worse,
@code{&3216}) is not allowed.

@cindex operands, OIL, in replacements
@cindex replacements, operands
Replacement operands are simpler than pattern operands, because there
are only a few forms they can take.

@table @code
@item _@var{NUMBER}
@itemx .@var{NUMBER}
@itemx :@var{NUMBER}

This tells the optimiser to copy the operand or expression with
reference number @var{NUMBER} to this point in the replacement used for
the expression matched by the pattern.  The three forms are identical;
the last two are provided for aesthetic reasons (it can look better and
be clearer to match @code{.1} in the pattern with @code{.1} in the
replacement, for instance).  You cannot use @code{#@var{NUMBER}} here to
copy in a constant from the left-hand side, though, nor
@code{#@{1@}@var{NUMBER}}, because the first means something else and
the second is undefined behaviour (that is, no behaviour for the second
case has been specifically implemented in the compiler and therefore its
behaviour is unpredictable and subject to change in future versions);
use @code{_@var{NUMBER}} to copy over a constant with an unknown at
optimizer compile time (but known at optimize time) value from the left
hand side, as you can do with any other operand being copied.

@item #@var{NUMBER}

Insert a constant with the literal value @var{NUMBER} here.

@item #@{@var{EXPRESSION}@}0

Calculate the value of @var{EXPRESSION} (a C expression, which can
reference the same variables and functions as a C expression in a
pattern can; see @ref{C functions in OIL}) and insert a constant with
the calculated value here.  (That is, a value is calculated at
optimise-time and the resulting value is therefore constant at
runtime.)

@end table

As an example, here's an idiom that moves C bitwise AND operations
inside leftshifts.  (This is useful because if the optimizer has
generated a large sequence of mixed ANDs and bitshifts, moving all the
ANDs to one end allows them to be clumped together and optimized down to
one AND, whilst the shifts can all be combined into one large shift.)

@example
((_1 << #@{1@}2) & #@{1@}3)->((_1 & #@{x3>>x2@}0) << _2)
@end example

@node OIL Loops
@appendixsec OIL Loops
@cindex loops, OIL
@cindex OIL, loops

When writing idioms, sometimes instead of using very complicated
expressions to try to match multiple situations at once it's easier to
have a separate idiom for each possible situation; for instance, it's
easier to write idioms for right-shift by 1, right-shift by 2,
right-shift by 3, etc.@:, rather than a general idiom to rightshift by any
amount.  When the idioms follow a pattern, as they will do in basically
every case of this sort, it's possible to automatically generate them
using a loop.  For instance, idioms to optimize a one-bit rightshift
and a two-bit rightshift are:

@example
(_1~#@{xselx(x)<<1==x&&x@}2)->((_1&_2)>>#1)
(_1~#@{xselx(x)<<2==x&&x@}2)->((_1&_2)>>#2)
@end example

Adding a loop to automatically generate the idioms, and placing a name
for the group of idioms at the start, produces the following code:

@example
[rshift]
<#1-#31
(_1~#@{xselx(x)<<r==x&&x@}2)->((_1&_2)>>#@{r@}0)
>
@end example

That's 31 different idioms, generated with a loop.  As the above example
shows, a loop starts with @code{<#@var{NUMBER}-#@var{NUMBER}} and ends
with @code{>}; a different idiom is generated for each possible value of
the loop counter @code{r} in the range given by the opening line of the
loop.  Loops must be placed around idioms, but inside a group of
idioms.  Note the use of @code{#@{r@}0} to generate a constant whose
value is equal to the value of the loop counter.

@node OIL Tips
@appendixsec OIL Tips
@cindex tips, OIL
@cindex OIL, tips

Here are some tips for the best use of @acronym{OIL}:

@itemize

@item
@findex MAXTOFREE
The @acronym{OIL} compiler has a few deficiencies, such as error
messages that don't give you much of an idea of what you did wrong (to
compensate for this, it does give a reasonably accurate line and
character number where the error happened), limits on things like how
deep expressions can be nested and how many idioms are allowed (if you
hit the first, you should really break it up into smaller idioms if
possible, and if you hit the second, increase @code{MAXTOFREE} in oil.y;
this isn't a limit on the number of idioms but on the number of strings
that are allocated internally to process the idioms), and lack of error
checking (invalid @acronym{OIL} may produce errors in the @acronym{OIL}
compiler, or cause the output C code to contain errors or warnings, or
may even appear to work).

@item
When you have symmetrical operators in an idiom (like C binary logical
operators), you need to write the idiom both ways round (in the same
group of idioms, preferably), or write another idiom to standardise the
format first; the first method can get very tedious when there are many
symmetrical operators in an idiom, and the second is prone to optimizer
loops and subtle errors (both methods have been used in the provided
@file{idiotism.oil} file.)

@item
Idioms should preferably be as general as possible, broken down into
many separate idioms rather than all as one big idiom, and match the
smallest part of the expression being optimized that is necessary for
the idiom to be correct in all circumstances; all of these help to
improve the performance of the optimizer in terms of what it can
optimize.

@item
If a program's optimizing incorrectly, or you just want to see how the
optimizer deals with a particular program, it's possible to debug the
optimizer by giving the @option{-h}, @option{-H}, or @option{-hH}
(@pxref{-h}) switch to the @cic{} compiler, which will cause debug
information to be output on stderr.  @option{-h} will show the initial
and final expressions for each expression that was given as input to the
optimizer, as well as a list of all optimizations used, in a language
that's a sort of mix of C, @ical{}, and @acronym{OIL}; @option{-H} will
do the same, and also show the intermediate stages in the optimization.
@option{-hH} is like @option{-H}, but produces its output entirely in C,
so that the various intermediate stages can be tried with a C compiler,
or for people who are fed up of reading @ical{}.  @option{-H} can be a
useful learning resource for people who want to understand how a
particular @ical{} expression works.

@item
Make sure that the optimizer doesn't change a statement from a run-time
error into something that silently succeeds@!  Checking which bits can
and can't be 1 is one good way to avoid this, especially with mingles.
(At present, there are some idioms that can turn run-time errors into
compile-time errors, such as with the expression
@code{''#65535$#65535'$#0'}; this could be avoided, but for the time
being it isn't.)

@item
You can help@!  If you find an idiom that the optimizer isn't optimizing
correctly, feel free to add it, or multiple idioms that come to the same
thing, to @file{idiotism.oil}.  In such a case, it would help other
users if you would submit your new optimizer idiom to the project
(@pxref{Reporting Bugs}); this will help other users and future releases
of @ical{}, and also has a chance of allowing other users to check your
new idioms to see if they cause problems or could be written better.

@end itemize

@node OIL Example
@appendixsec OIL Example
@cindex OIL, example
@cindex examples, OIL

To finish off this appendix, here's an example of the power of
@acronym{OIL}; this is the optimization of an idiom from the @icst{}
system library, as shown with @option{-H}; this should give a good idea
of how @acronym{OIL} programs work.  (All the relevant idioms are in
@file{idiotism.oil} as of the time of writing.)  Note how the expression
is reduced one small step at a time; the smallness of the steps makes
the optimizer more general, because if the original expression had been
slightly different, the optimizer wouldn't have come to the same result
but could have optimized it quite a bit of the way, up to the point
where the optimizations were no longer valid; in an older version of
@ical{}, this idiom was simply hardcoded as a special case and so slight
variations of it weren't optimized at all.  If you look at the idioms
themselves, it'll also be apparent how @code{c} (the record of which
bits of an expression can be 1 and which bits can't be) is important
information in being able to apply an optimization more aggressively.

@ifhtml
@smallexample
.3 <- ((((((((.3 $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[minglefold]
.3 <- ((((((((.3 $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[lshift16]
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[noopor]
.3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[minglefold]
.3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[lshift16]
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[noopor]
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))
[minglefold]
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0xaaaaaaf) $ 0x0) ~ (0xfff $ 0xf))
[lshift16]
.3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) | 0x0) $ 0x0) ~ (0xfff $ 0xf))
[noopor]
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ (0xfff $ 0xf))
[minglefold]
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ 0xaaaaff)
[lshift16]
.3 <- (((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7) | 0x0)
[noopor]
.3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[nullshift]
.3 <- (((((((((((.3 & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[combinelrshift]
.3 <- ((((((((((.3 & 0x7fff) << 0x1) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[andintolshift]
.3 <- ((((((((((.3 & 0x7fff) & 0x3fff) << 0x1) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[combinellshift]
.3 <- (((((((((.3 & 0x7fff) & 0x3fff) << 0x2) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[combinelrshift]
.3 <- ((((((((.3 & 0x7fff) & 0x3fff) << 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[andintolshift]
.3 <- ((((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) << 0x3) >> 0x3) & 0x1ff) << 0x7)
[combinellshift]
.3 <- (((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x4) >> 0x3) & 0x1ff) << 0x7)
[combinelrshift]
.3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) & 0x1ff) << 0x7)
[andintolshift]
.3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x1) << 0x7)
[combinellshift]
.3 <- (((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x8)
[combineand]
.3 <- ((((.3 & 0x3fff) & 0xfff) & 0xff) << 0x8)
[combineand]
.3 <- (((.3 & 0xfff) & 0xff) << 0x8)
[combineand]
.3 <- ((.3 & 0xff) << 0x8)
@end smallexample
@end ifhtml
@ifnothtml
@quotation
.3 <- ((((((((.3 $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[minglefold]@*
.3 <- ((((((((.3 $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[lshift16]@*
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[noopor]@*
.3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x7fff $ 0x1)) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[minglefold]@*
.3 <- (((((((((.3 >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0x2aaaaaab) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[lshift16]@*
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) | 0x0) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[noopor]@*
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ (0x3fff $ 0x3)) $ 0x0) ~ (0xfff $ 0xf))@*
[minglefold]@*
.3 <- ((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) $ 0x0) ~ 0xaaaaaaf) $ 0x0) ~ (0xfff $ 0xf))@*
[lshift16]@*
.3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) | 0x0) $ 0x0) ~ (0xfff $ 0xf))@*
[noopor]@*
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ (0xfff $ 0xf))@*
[minglefold]@*
.3 <- (((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) $ 0x0) ~ 0xaaaaff)@*
[lshift16]@*
.3 <- (((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7) | 0x0)@*
[noopor]@*
.3 <- ((((((((((((.3 >> 0x0) & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[nullshift]@*
.3 <- (((((((((((.3 & 0x7fff) << 0x1) >> 0x0) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[combinelrshift]@*
.3 <- ((((((((((.3 & 0x7fff) << 0x1) & 0x7fff) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[andintolshift]@*
.3 <- ((((((((((.3 & 0x7fff) & 0x3fff) << 0x1) << 0x1) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[combinellshift]@*
.3 <- (((((((((.3 & 0x7fff) & 0x3fff) << 0x2) >> 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[combinelrshift]@*
.3 <- ((((((((.3 & 0x7fff) & 0x3fff) << 0x1) & 0x1fff) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[andintolshift]@*
.3 <- ((((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) << 0x3) >> 0x3) & 0x1ff) << 0x7)@*
[combinellshift]@*
.3 <- (((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x4) >> 0x3) & 0x1ff) << 0x7)@*
[combinelrshift]@*
.3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) << 0x1) & 0x1ff) << 0x7)@*
[andintolshift]@*
.3 <- ((((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x1) << 0x7)@*
[combinellshift]@*
.3 <- (((((.3 & 0x7fff) & 0x3fff) & 0xfff) & 0xff) << 0x8)@*
[combineand]@*
.3 <- ((((.3 & 0x3fff) & 0xfff) & 0xff) << 0x8)@*
[combineand]@*
.3 <- (((.3 & 0xfff) & 0xff) << 0x8)@*
[combineand]@*
.3 <- ((.3 & 0xff) << 0x8)@*
@end quotation
@end ifnothtml

@node Copying
@appendix Copying
@cindex copyright
@cindex copying conditions

The majority of the files in the @cic{} distribution are licensed
under the GNU General Public License (version 2 or later), but with
some exceptions.  The files @file{ick-wrap.c} and @file{pickwrap.c}
are licensed under a license that allows them to be used for any
purpose and redistributed at will, and are explicitly not GPL'd.  This
means that C source code generated by the compiler has the same
copyright conditions as the original @ical{} source.  (Note that the
libraries @file{libick.a} and @file{libickmt.a} are GPL, though, so
you cannot redistribute an executable produced by @command{ick} or by
linking a C file to either of those libraries unless the original
@ical{} source was GPL.)  For similar reasons, the expansion libraries
@file{syslibc.c} and @file{compunex.c} (currently the only ones in the
distribution) is explicitly public domain.  Also, this manual, and the
files that are the source code for creating it, are licensed under the
GNU Free Documentation License rather than the GPL, and the licenses
themselves (@file{fdl-1-2.txi} and @file{COPYING.txt}) are licensed
under a license that allows verbatim redistribution but not creation
of derivative works.  All other files, though (including the
@command{man} pages, which are not part of @emph{this} manual), are
licensed under the GPL.  For the full text of the GPL, see the file
@file{COPYING.txt} in the distribution.

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@node GNU Free Documentation License
@appendixsec GNU Free Documentation License
@cindex GFDL
@cindex FDL
@cindex GNU Free Documentation License
@cindex Free Documentation License

@include fdl-1-2.txi

@node Main Index
@unnumbered Index

This is the index of everything in this manual.  (Note that in some
versions of the manual this is called @samp{Main Index} to prevent it
transforming into a page called @file{index.html} in the HTML version of
the manual.  The complications that that caused were really odd.)

@printindex cp

@bye