1.1 Obtaining

C-INTERCAL 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 alt.lang.intercal newsgroup; all releases of the C-INTERCAL compiler ought to be announced there. (If you are interested in what other INTERCAL 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 Google Groups, and a search for ‘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.)

1.2 Unpacking

C-INTERCAL is distributed in compressed pax format; for instance, you may find it as a ‘.pax.lzma’ file if you have the unlzma decompression program (this is advised, as it’s the smallest); ‘.pax.bz2’ is larger and ‘.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 ‘.pax’ to ‘.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 C-INTERCAL 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 are an administrator, or at least have the same privileges, and can extract it anywhere). Some commands that you might use to extract it:

Generic UNIX/Linux

unlzma ick-0-29.pax.lzma
tar xvf ick-0-29.pax

or

bunzip2 ick-0-29.pax.bz2
tar xvf ick-0-29.pax

or

gunzip ick-0-29.pax.gz
tar xvf ick-0-29.pax

On most UNIX-based and Linux-based systems, tar will be available to unpack the installation files once they’ve been uncompressed with gunzip. (I’ve heard that some BSD systems have pax itself to decompress the files, although have not been able to verify this; some Linux distributions also have pax in their package managers. Both tar and pax should work fine, though.) gunzip is also likely to be available (and bunzip2 and 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.

Using GNU tar

tar xzvf ick-0-29.pax.gz

or

tar xqvf ick-0-29.pax.bz2

If you are using the GNU version of 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.

Using DJGPP

djtar -x ick-0-29.pax.gz

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 cmd (or command if that fails) in the dialog box that opens to get a command prompt, which you can exit by typing exit. After typing any command at a command line, press RET to tell the shell to execute that command.)

On Windows

If you’re running a Windows system, you could always try double-clicking on the ick-0-29.pax.gz file; probably renaming it to have the extension ‘.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.

Whatever method you use, you should end up with a directory created called ick-0.29; 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 cd ick-0.29).

1.3 Simple Installation

There are scripts included in the distribution to automate the process of installing, in various ways. The simplest method of installing on most operating systems (on DOS, see Installation on DOS) is to use the following routine:

1. Configure C-INTERCAL, by running configure. Although building in the distribution directory works, it is recommended that you build elsewhere; create a directory to build in (using mkdir on most operating systems), then run configure from inside that directory (for instance, you could do this from inside the main installation directory:

   mkdir build
   cd build
   ../configure
   

   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 ‘/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 --prefix=location to configure; for instance, configure --prefix=/usr would install in /usr.

2. Compile the source code, with the command make. The Makefile will be set up for your version of make, and to automatically recompile only what needs compiling (it will even recompile the build system if you change that).
3. Optionally, create libraries from third-party interpreters to add support for more languages to the C-INTERCAL external calls system; see 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.)
4. Install the executables, help files, include files, and libraries, using 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 sudo make install if you’re installing into a directory that you can’t write to as a non-administrative user.) This step is optional; if you do not install C-INTERCAL, you can still run it by directly referencing the exact location of the ick command.

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 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 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 sh, and don’t have the shell bash which can emulate it, and so can’t run configure 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 (C-INTERCAL was designed to work with 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.; but this requires trying to do the build by hand, so it’s generally easier just to install a UNIX-like shell and associated tools.

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 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.

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 ‘binutils’, ‘cpp’, ‘gcc’, ‘libc6-dev’, ‘make’ to compile C-INTERCAL, and if you want to modify it, you may also need ‘autoconf’, ‘automake’, ‘bison’, and ‘flex’. For debugging help, you may also want ‘gdb’, and to recompile the documentation, you may need ‘groff’, ‘texlive’, ‘texinfo’, and ‘tidy’.

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 configure --help to view the options that you can set on configure; there’s a wide range of settings that you can set available there, and one of them may be what you want.

1.4 Installation on DOS

On DOS-based systems, it’s possible to install C-INTERCAL via compiling it using DJGPP, a free DOS development system. (You can obtain DJGPP via its homepage, at http://www.delorie.com/djgpp/.) The process for installing it works like this:

1. To start with, you will need to install DJGPP and various utilities (especially many of the GNU utilities) that come with it. To do this, see the instructions on DJGPP’s website, and download and unpack any additional packages on this list that you did not install as part of those instructions (a filename by which the package can be found on DJGPP mirrors is given, and a version number with which C-INTERCAL was tested is given as part of the filename, but other versions are likely to work as well):
   • Unzip32 (‘unzip32.exe’) — to unpack the other packages
   • DJGPP development kit (‘v2/djdev203.zip’) — needed for all DJGPP compiles
   • CS’s DPMI Provider (‘v2misc/csdpmi7b.zip’) — you need some DPMI provider to run C-INTERCAL on a plain DOS system, although this is not needed on systems such as Microsoft Windows’ emulation of DOS which already include a DPMI provider
   • GNU Binutils (‘v2gnu/bnu219b.zip’) — needed to produce executables
   • gcc (‘v2gnu/gcc444b.zip’) — used to compile C code
   • GNU make (‘v2gnu/mak3791b.zip’) — used to resolve dependencies within the build system
   • GNU bash (‘v2gnu/bsh204b.zip’) — used to interpret build scripts
   • GNU Diffutils (‘v2gnu/dif20b.zip’) — used by the build scripts
   • GNU Fileutils (‘v2gnu/fil41b.zip’) — used by the build scripts
   • GNU Findutils (‘v2gnu/find41b.zip’) — used by the build scripts
   • GNU awk (‘v2gnu/gwk318b.zip’) — used by the build scripts
   • GNU sed (‘v2gnu/sed421b.zip’) — used by the build scripts
   • GNU Shellutils (‘v2gnu/shl2011b.zip’) — used by the build scripts
   • GNU Textutils (‘v2gnu/txt20b.zip’) — used by the build scripts, and sometimes by C-INTERCAL itself too

   You might want to install other packages, particularly GNU Bison and GNU Flex, in order to be able to rebuild certain parts of the compiler if you change them. This is not necessary to simply be able to run C-INTERCAL without changing it, though.

2. Test your DJGPP install to ensure it works, and make sure you have environment variables set up correctly. In addition to the ‘DJGPP’ variable that points to your ‘DJGPP.ENV’ file, and the ‘PATH’ variable that needs to contain DJGPP’s binaries directory, you also need to set the ‘DJDIR’ environment variable to point to the main DJGPP installation directory.
3. Unpack a copy of C-INTERCAL in its own directory, if you haven’t already (see Unpacking).
4. Load up a bash session, change to the ‘buildaux’ subdirectory of your main C-INTERCAL directory, and run the command build-dj.sh. This will run the entire C-INTERCAL build system, and hopefully end up with executables you can run in the ‘build’ subdirectory that will be created in your main C-INTERCAL directory.
5. If you wish, you can install C-INTERCAL by using the command make install from the new ‘build’ subdirectory. It will run just fine in-place without a need to install, though, if you prefer.

1.5 Uninstalling

It may happen that you decide to uninstall C-INTERCAL 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 C-INTERCAL because this will save some disk space; you cannot install two versions of C-INTERCAL 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 C-INTERCAL using make install, you can uninstall it by using 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 ick and convickt where your computer installs binaries (with an extension like ‘.exe’ added if that’s usual for binaries on your operating system), libick.a, libickmt.a, libickec.a, and libyuk.a where your computer installs libraries, and the subdirectories ick-0.29 in the places where your computer installs data files and include files, and their contents.

You can go further than uninstalling. Running make clean will delete any files created by compilation; 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 configure. You can go even further and use make veryclean which will delete not only files created by configuring, but the entire build system; doing so is not recommended unless you have some method of rebuilding the build system from its original sources (a script to do this is provided in repository versions of C-INTERCAL, because the generated part of the build system is not stored in the repository).

1.6 Reporting Bugs

If you can’t get C-INTERCAL 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 alt.lang.intercal news group; to report a bug or submit a patch, email the person who released the most recent C-INTERCAL 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 (see 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 (see 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, -H (see -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 -U (see -U), it helps if you can load a debugger (such as 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 C-INTERCAL), 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 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 C-INTERCAL.

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

1.7 Distributing

Due to the licensing conditions of C-INTERCAL, 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:

1. Make sure the new version is based on the most recent existing version. Looking at the alt.lang.intercal newsgroup will normally let you know what version is most recent.
2. 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: configure.ac, configure, and doc/ick.texi. You also have to rename the installation directory to reflect the new version number.
3. Add an entry to the NEWS file explaining what’s new in the version that you’re releasing, following the same format as the other entries.
4. Update the README with a description of any new files you may have added.
5. Remove any autosave or backup files that may be littering the installation directory or its subdirectories.
6. Run make distcheck, which will make the distribution paxballs, and rename them to have the correct extensions (Automake thinks they’re tarballs, so will use ‘.tar’ rather than ‘.pax’, and you have to fix this by hand). 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; and some regression tests on a version of C-INTERCAL built from the distribution tarball itself, to prove that it runs correctly and produces plausible output. (A failure of the regression checks will not stop the build, but should stop you distributing the resulting compiler.)
7. Place the new version somewhere on the Internet, and announce the location and the fact that a new version has been released on alt.lang.intercal.

2.1 Language-affecting Options

The following command-line options to ick affect what dialect of the INTERCAL language is compiled by the compiler; you may need to set one or more of these options if your input is not the default C-INTERCAL but instead some other language like INTERCAL-72 or CLC-INTERCAL, 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 TriINTERCAL (or the base 4-7 versions); instead, the numeric base to use is determined by looking at the filename extension (‘.i’ for base 2, the default, or ‘.3i’ to ‘.7i’ for the base 3-7 versions.)

-b

If this option is 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 (see 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 INTERCAL-72, 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 INTERCAL-72 compiler documentation mentions a similar command-line option that is a workaround for the same bug.)

-m

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 (see COME FROM) commands aiming at the same line even when it isn’t multithreaded, in which case the commands cause error E555 (see 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 (see E405).

-e

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

-E

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 -e when adding in a custom replacement system library written in a non-INTERCAL language, especially the expansion library syslibc (a system library replacement written in C).

-t

This option tells the compiler to treat the source code as INTERCAL-72; as a result, any language constructs that are used but weren’t available in 1972 will trigger error E111 (see E111).

-a

This option allows the CREATE statement (see 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 -e (see -e) also needs to be set to be able to CREATE operators.

-v

It is possible to write INTERCAL 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; see 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 CLC-INTERCAL, this only changes uses of the constant preceded by # in your program, not things like line numbers; you want Forte for that.) This option also allows you to write arbitary expressions on the left of an assignment statement if you wish.

-C

When this option is given, the generated programs will write the number 4 as ‘IIII’ rather than ‘IV’, in case you’re writing a clock program.

-P

This tells the compiler to treat the input as PIC-INTERCAL (see PIC-INTERCAL) rather than ordinary C-INTERCAL 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 (see E256), you have this option given when it shouldn’t be; likewise, if you get error E652 (see E652), you should be using this option but aren’t. (A few simple programs are C-INTERCAL/PIC-INTERCAL polyglots, but such programs are incapable of doing input or output, meaning that they aren’t particularly useful.)

-X

The C-INTERCAL and CLC-INTERCAL 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 C-INTERCAL compiler, it rather guessably uses its own notation by default; however, the CLC-INTERCAL 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 ? to be interpreted with Princeton rather than Atari meanings.

-x

This option causes some constructs with different meanings in C-INTERCAL and CLC-INTERCAL to use the CLC-INTERCAL meaning rather than the C-INTERCAL meaning. At present, it affects the abstention of a GIVE UP (see GIVE UP) command by line number, which is possible as long as this switch isn’t given; reading through the INTERCAL-72 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 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 CLC-INTERCAL’s extended Baudot syntax, rather than using the Turing Tape method.

2.2 Debug Options

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

-d

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.

-g

This option allows debugging of the final executable at the C code level. Any C code generated will be left in place, and the -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.

-h

-H

-hH

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

-l

This option turns on generation of warnings (see 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.

-p

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 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 WRITE IN instructions will often show up as taking a long time due to their need to wait for input.

-w

This option causes the produced program to support the printflow option fully; when this option is not given, 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.

-u

When you are getting problems with finding files – for instance, the compiler can’t find the skeleton file (see E999) or the system library (see 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.

-y

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

-Y

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

-U

The internal error E778 (see 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 -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 ick itself at the time; on many systems, it will also cause a core dump.

2.3 Output Options

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.

-c

By default, the original INTERCAL 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 ‘.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.

-o

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 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.

2.4 Optimizer Options

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

-f

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 ABSTAINED from and refrain from generating code to check the abstention status of those commands.

-F

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.

-O

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 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 Optimizer Idiom Language.

2.5 Other Options

Some options just can’t be classified.

-@

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.

2.6 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.

+help

-help

Whether ‘+’ or ‘-’ 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.

+wimpmode

-wimpmode

If the ‘+’ version of this is given (rather than the default ‘-’), 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 (‘123’ rather than ‘ONE TWO THREE’) and likewise will output in Arabic numerals rather than Roman numerals (such as ‘CXXIII’). True INTERCAL programmers should rarely have to use this mode.

+traditional

-traditional

This option does not actually appear to do anything.

+instapipe

-instapipe

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

+printflow

-printflow

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 -w option (see -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.

+mystery

-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.

2.7 Environment Variables

Various environment variables can be set to affect the operation of ick.

3.1 Errors

This is a list of the error messages that might be produced during the compilation or execution of an INTERCAL program.

E000

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 ABSTAINed 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.

E017

DO YOU EXPECT ME TO FIGURE THIS OUT?

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.

E079

PROGRAMMER IS INSUFFICIENTLY POLITE

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

E099

PROGRAMMER IS OVERLY POLITE

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

E111

COMMUNIST PLOT DETECTED, COMPILER IS SUICIDING

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

E123

PROGRAM HAS DISAPPEARED INTO THE BLACK LAGOON

There is a hard limit of 80 NEXTs at a time; this is to discourage excessive use of NEXTING for things like recursion. (Recursive programs are entirely legal; you simply have to figure out how to do it with computed 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 FORGET the entry on the NEXT stack created when trying to simulate a goto.

E127

SAYING ’ABRACADABRA’ WITHOUT A MAGIC WAND WON’T DO YOU ANY GOOD

Your program asked to include a system library (by specifying a line number in a magic range 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 -u (see -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.

E129

PROGRAM HAS GOTTEN LOST

This error happens at compile time when the compiler can’t figure out where a 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 -e command-line option (see -e) makes this error into a run-time error, because it allows 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.

E139

I WASN’T PLANNING TO GO THERE ANYWAY

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

E182

YOU MUST LIKE THIS LABEL A LOT!

At present, it’s impossible to have more than one line with the same line number. That would make NEXT act too much like COME FROM in reverse to be interesting. This error happens at compile time. (For inconsistency, it is possible to have multiple lines with the same number as long as at most one of them is in an INTERCAL program (the others have to be in programs in other languages included via the external calls system). The resulting behaviour is entirely inconsistent with the rest of the language, though, for what I hope are obvious reasons.)

E197

SO! 65535 LABELS AREN’T ENOUGH FOR YOU?

Legal values for line labels are 1 to 65535 (certain subranges are reserved for system and expansion libraries). This error comes up if you use nonpositive or twospot values for a line label.

E200

NOTHING VENTURED, NOTHING GAINED

You used a variable that isn’t actually in your program. Failing that (which, contrary to previous versions of this manual, is indeed possible in the present version of C-INTERCAL, although I’m not telling how; a hint: what mechanism in C-INTERCAL allows for a computed variable number?), 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.

E222

BUMMER, DUDE!

In INTERCAL, you’re allowed to STASH as much as you like; this makes the language Turing-complete and allows for unlimited recursion when combined with computed 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.

E240

ERROR HANDLER PRINTED SNIDE REMARK

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.

E241

VARIABLES MAY NOT BE STORED IN WEST HYPERSPACE

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 WRITE IN, that expects it to be monodimensional.

E252

I’VE FORGOTTEN WHAT I WAS ABOUT TO SAY

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 CLC-INTERCAL-style I/O.

E256

THAT’S TOO HARD FOR MY TINY BRAIN

Some commands simply aren’t available in PIC-INTERCAL. I mean, PICs 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 -P option (see -P) if you didn’t mean to compile as PIC-INTERCAL in the first place.

E275

DON’T BYTE OFF MORE THAN YOU CAN CHEW

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 INTERCAL other than C-INTERCAL, though, so you have to be careful with portability when doing this.)

E277

YOU CAN ONLY DISTORT THE LAWS OF MATHEMATICS SO FAR

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 -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 (see 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.)

E281

THAT MUCH QUOTATION AMOUNTS TO PLAGIARISM

There is a limit of 3200 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 SENESTMAX in 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.)

E333

YOU CAN’T HAVE EVERYTHING, WHERE WOULD YOU PUT IT?

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.

E345

THAT’S TOO COMPLEX FOR ME TO GRASP

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.

E404

I’M ALL OUT OF CHOICES!

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.

E405

PROGRAM REJECTED FOR MENTAL HEALTH REASONS

Your program used a construct that only makes sense when multithreading or backtracking (WHILE, MAYBE, GO BACK, or GO AHEAD), but you didn’t specify the -m option (see -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.

E436

THROW STICK BEFORE RETRIEVING!

In order to RETRIEVE a variable, it has to be STASHed first; if it isn’t, then this error happens at runtime.

E444

IT CAME FROM BEYOND SPACE

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

E533

YOU WANT MAYBE WE SHOULD IMPLEMENT 64-BIT VARIABLES?

This error is like E275 (see 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 INTERCAL program; if you want to process higher numbers, you have to figure out a different way of storing them.

E553

BETTER LATE THAN NEVER

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.

E555

FLOW DIAGRAM IS EXCESSIVELY CONNECTED

Aiming two COME FROMs 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 COME FROM is computed) or at run time (if the command that has just finished running is simultaneously the target of two or more COME FROMs). This either indicates an error in your program or that you’ve forgotten to use the -m option (see -m) if you are actually trying to split the program into two threads.

E562

I DO NOT COMPUTE

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 CTRL-D (UNIX/Linux) or CTRL-Z (DOS/Windows) while the program was trying to WRITE IN some data.

E579

WHAT BASE AND/OR LANGUAGE INCLUDES string?

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ük, or Latin. This seems to have languages covered pretty well; what on earth were you using, or did you just make a spelling mistake?

E621

ERROR TYPE 621 ENCOUNTERED

The compiler encountered error E621 (see E621). This happens at runtime when the program requests that no entries are removed from the 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).

E632

THE NEXT STACK RUPTURES. ALL DIE. OH, THE EMBARRASSMENT!

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

E633

PROGRAM FELL OFF THE EDGE

You can’t just let execution run off the end of the program. At least, that is, if it doesn’t end with 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 (see E000) with the error text ‘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.

E652

HOW DARE YOU INSULT ME!

The PIN command doesn’t make much sense for anything bigger than a PIC; using it in a non-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 PIC-INTERCAL program without giving the -P option (see -P).

E666

COMPILER HAS INDIGESTION

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.

E774

RANDOM COMPILER BUG

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 -b option (see -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 INTERCAL-72 compiler, which also had an option to turn the bug off. It’s also a reward for people who actually read the manual.)

E777

A SOURCE IS A SOURCE, OF COURSE, OF COURSE

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.

E778

UNEXPLAINED COMPILER BUG

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 -U option (see -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 (see Reporting Bugs).

E810

ARE ONE-CHARACTER COMMANDS TOO SHORT FOR YOU?

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.

E811

PROGRAM IS TOO BADLY BROKEN TO RUN

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.

E888

I HAVE NO FILE AND I MUST SCREAM

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.

E899

HELLO? CAN ANYONE GIVE ME A HAND HERE?

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 Creating the Funge-98 Library.)

E990

FLAG ETIQUETTE FAILURE BAD SCOUT NO BISCUIT

This error occurs at runtime if an INTERCAL program was passed an unknown option flag.

E991

YOU HAVE TOO MUCH ROPE TO HANG YOURSELF

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.

E993

I GAVE UP LONG AGO

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 REINSTATEd. This error happens at compile time if a command is found after a TRY AGAIN.

E994

NOCTURNAL EMISSION, PLEASE LAUNDER SHEETS IMMEDIATELY

This error should never happen, and if it does indicates a compiler bug. It means the emitter function in the code degenerator has encountered an unknown opcode. Please send a copy of the program that triggered it to the INTERCAL maintainers.

E995

DO YOU REALLY EXPECT ME TO HAVE IMPLEMENTED THAT?

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.

E997

ILLEGAL POSSESSION OF A CONTROLLED UNARY OPERATOR

Some operators (such as whirlpool (@) and sharkfin (^)) only make sense in 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 TriINTERCAL operators in an INTERCAL program in the default base 2).

E998

EXCUSE ME, YOU MUST HAVE ME CONFUSED WITH SOME OTHER COMPILER

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 ‘.a’, ‘.b98’, ‘.c’, ‘.c99’, or ‘.c11’ file, then you forgot to enable the external calls system using -e (see -e).)

E999

NO SKELETON IN MY CLOSET, WOE IS ME!

The skeleton file ick-wrap.c or pickwrap.c is needed to be able to compile INTERCAL 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 -u option (see -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).

3.2 Warnings

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

W016

DON’T TYPE THAT SO HASTILY

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.

W018

THAT WAS MEANT TO BE A JOKE

If an INTERCAL 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 INTERCAL 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).

W112

THAT RELIES ON THE NEW WORLD ORDER

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

W128

SYSLIB IS OPTIMIZED FOR OBUSCATION

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.

W276

YOU CAN’T EXPECT ME TO CHECK BACK THAT FAR

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.)

W239

WARNING HANDLER PRINTED SNIDE REMARK

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.

W278

FROM A CONTRADICTION, ANYTHING FOLLOWS

It’s sometimes impossible to reverse an assignment (a reverse assignment can happen if the -v option (see -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.

W450

THE DOCUMENTOR IS NOT ALWAYS RIGHT

There is no way to get this warning to come up; it isn’t even written anywhere in C-INTERCAL’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.

W534

KEEP LOOKING AT THE TOP BIT

C-INTERCAL uses a slightly different typing mechanism to some other INTERCAL 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.

W622

WARNING TYPE 622 ENCOUNTERED

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.

5.1 Princeton and Atari Syntax

The history of INTERCAL 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).

Princeton syntax

The original INTERCAL-72 compiler was the Princeton compiler, which introduced what has become known as the Princeton syntax for INTERCAL; this is the syntax used in the original manual, for instance, and can be considered to be the ‘original’ or ‘official’ INTERCAL 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 ‘V’, backspace, ‘-’, 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 CLC-INTERCAL compiler, which is the de facto standard for expanding the Princeton syntax to modern INTERCAL features that are not found in INTERCAL-72; 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, CLC-INTERCAL uses the Latin-1 yen symbol for this, which just to make things confusing, refers to a mingle in modern Atari syntax).

Atari syntax

The other main syntax is the Atari syntax, so called because it was originally described in notes about an “Atari implementation” added to the paper INTERCAL-72 manual when it was softcopied in 1982. These notes describe a never-completed compiler implementation for 6502 by Mike Albaugh and Karlina Ott; it was meant to use the Atari 800 cartrtidge and screen editor, but that portion was never written. The syntax was designed to work better on ASCII-based systems, by avoiding the change character (although it can still be written as ‘c’, backspace, ‘/’, which the Atari compiler documentation claims that the Princeton compiler supported) in favour of a ‘big money’ character (‘$’), and using the ‘what’ (‘?’) as an alternative character for exclusive-or. This is the syntax that C-INTERCAL and J-INTERCAL have always used, and is the one most commonly used for communicating INTERCAL 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 INTERCAL-72 is normally taken to be that used by the C-INTERCAL compiler, because it is the only Atari-syntax-based compiler that contains non-INTERCAL-72 constructs that actually need their own notation.

5.2 Line Labels

The first part of an INTERCAL statement is a line label that specifies what its line number is. This is optional; it’s legal 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 (( and )). For instance, this is a valid line label:

(1000)

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 INTERCAL 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 INTERCAL library, it may be a good idea to look at the existing libraries (in the pit/lib directory in the C-INTERCAL 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.

5.3 Statement Identifiers

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.

The main statement identifier is DO. It also has two synonyms, PLEASE and 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.

Adding NOT or N'T to the end of any of these identifiers, to create a statement identifier such as DO NOT or 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:

PLEASE NOTE: This is a comment.

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

The ABSTAIN and REINSTATE statements can override the NOT or otherwise on a statement identifier; see ABSTAIN.

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

5.4 Execution Chance

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 INTERCAL, although it is the only way to introduce randomness into a program. (The C-INTERCAL 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 (%) 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 DO %40 WRITE OUT #1 has a 40% chance of writing out ‘I’, but the statement DON'T %40 WRITE OUT #1 has no chance of writing out I or anything else, because the N'T prevents it running and the double-oh-seven cannot override that.

5.5 ONCE and AGAIN

The last part of a statement is an optional ONCE or AGAIN. ONCE specifies that the statement is self-abstaining or self-reinstating (this will be explained below); 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 ONCE on an initially reinstated statement or AGAIN on an initially abstained statement indicates a self-abstention, and a ONCE on an initially abstained statement or 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 a 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 ONCE effectively changes to an AGAIN; the ONCE only happens once, as might be expected.

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

Historical note: ONCE was devised by Malcom Ryan as a method of allowing synchronisation between threads in a multithreaded program (ONCE is atomic with the statement it modifies, that is, there is no chance that threads will change between the statement and the ONCE). 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 ONCEs to happen multiple times, which is needed to implement some multithreaded algorithms).

6.1 Constants and Variables

The basic operands in INTERCAL 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 INTERCAL, but by default C-INTERCAL turns this off because it carries an efficiency penalty and can be confusing; this can be turned on with the -v option (see -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 Mingle.) A constant is written as a mesh (#) 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, #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 (., :, ,, and ;) 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 C-INTERCAL 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, .1 and .001 are the same variable, onespot number 1. Array variables need to be dimensioned before they are used, by assigning dimensions to them; see Calculate.

6.2 Grouping Rules

Because there are no operator precedences in INTERCAL, there are various solutions to specifying what precedences actually are.

The portable solution

All known versions of INTERCAL accept the INTERCAL-72 grouping rules. These state that it’s possible to specify that an operator takes precedence by grouping it inside sparks (') or rabbit-ears ("), the same way as wax/wane pairs (parentheses) are used in other programming languages. INTERCAL-72 and earlier C-INTERCAL 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 ''#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 C-INTERCAL to simplify the parsing process; INTERCAL-72 has the same limitation, probably for the same reason. Compare these two statements:

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

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 (!). Unfortunately, the rabbit-ear/spot combination has no one-character equivalent in any of the character sets that C-INTERCAL accepts as input (UTF-8, Latin-1, and ASCII-7) as none of these contain the rabbit character, although the Hollerith input format that CLC-INTERCAL can use does.

Positional precedences: CLC-INTERCAL rules

The precedence rules used by CLC-INTERCAL 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, .1~.2~.3 is equivalent to .1~'.2~.3'. C-INTERCAL versions 0.26 and later also right-associate binary operators so as to produce the same results as CLC-INTERCAL rules in this situation, but as nobody has yet tried to work out what the other implications of CLC-INTERCAL rules are they are not emulated in C-INTERCAL, except possibly by chance.

Prefix and infix unary operators

In INTERCAL-72 and versions of C-INTERCAL 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 & to the variable :1, write :&1, and to portably apply it to the expression '.1~.2', write '&.1~.2'.) CLC-INTERCAL, and versions of C-INTERCAL from 0.26 onwards, allow the ‘prefix’ position of a unary operator, which is just before whatever it applies to (as in &: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 C-INTERCAL, 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 C-INTERCAL '&&&.1~.2' is equivalent to the portable '&"&.&1"~.2' (or the more readable version of this, "&'"&.&1"~.2'", which is also portable). If these rules are counter-intuitive to you, remember that this is INTERCAL we’re talking about; note also that this rule is unique to C-INTERCAL, at least at the time of writing, and in particular CLC-INTERCAL is likely to interpret this expression differently.

6.3 Operators

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 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 INTERCAL-72 operators; many INTERCAL extensions add their own operators.

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

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

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

7.1 Syntax Error

One of the more commonly-used commands in INTERCAL is the syntax error. A properly-written syntax error looks nothing like any known INTERCAL command; a syntax error that looks vaguely like a command but isn’t may confuse C-INTERCAL 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:

DOUBLE OR SINGLE PRECISION ARITHMETIC OVERFLOW

This is a valid INTERCAL command, that produces an error when run (note the 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

PLEASE NOTE THAT THIS IS A COMMENT

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 PLEASE NOT; the extra 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 CLC-INTERCAL (version 1.-94.-3 and later, with COMMENT, COMMENTS, or COMMENTING), and C-INTERCAL (COMMENT in version 0.26 and later, and also COMMENTS and 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.

7.2 Calculate

At present, the only INTERCAL command that contains no keywords (apart from the statement identifier and possibly ONCE or 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:

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

That is, the command is written as a variable or array element, then the <- 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 BY to cause the array to become multidimensional; so for a 3 by 4 by 5 array, it would be possible to write

DO ,1 <- #3 BY #4 BY #5

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 CALCULATING; however, if you are planning to use this, note that a bug in older versions of C-INTERCAL means that assignments to arrays are not affected by this gerund before version 0.27.

CLC-INTERCAL from 1.-94.-4 onwards, and C-INTERCAL from 0.26 onwards, allow arbitrary expressions on the left hand side of an assignment (C-INTERCAL only if the -v option is used); for more information on how such ‘reverse assignments’ work, see Operand Overloading.

7.3 NEXT, FORGET and RESUME

The only flow-control commands in INTERCAL-72 were NEXT, RESUME, and FORGET; together these manipulate a stack of locations in the program known as the ‘NEXT stack’. Although all INTERCAL compilers have implemented these, from CLC-INTERCAL version 0.05 onwards CLC-INTERCAL 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 INTERCAL-72 implements nothing else.) Note that there is a strict limit of 80 locations on the NEXT stack, enforced by all known INTERCAL 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:

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

The NEXT command takes a line label as its argument (unlike most other INTERCAL commands, it comes after its argument rather than before); both FORGET and RESUME take expressions. (CLC-INTERCAL from version 0.05 onwards also allows an expression in NEXT, rather than a label, to give a computed NEXT, but this behaviour was not implemented in other compilers, and is deprecated in CLC-INTERCAL along with noncomputed NEXT; if computed NEXT is ever implemented in C-INTERCAL, it will likely likewise be deprecated upon introduction). (Update: it was implemented in C-INTERCAL 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 NEXT, but should probably not be used.) Running a 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 NEXT command on the top of the NEXT stack.

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

Traditionally, boolean values in INTERCAL 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 INTERCAL-72 is by NEXTING, then NEXTING again, then RESUMING either by 1 or 2 according to an expression, and then if the expression evaluated to 1 FORGETTING the remaining NEXT stack entry. By the way, the previous sentence also explained what the appropriate gerunds are for NEXT, RESUME, and FORGET.

7.4 STASH and RETRIEVE

The NEXT stack is not the only stack available in an INTERCAL program; each variable used in the program also has its own stack, which holds values of the same type as the variable. The STASH command pushes a variable’s value onto that variable’s stack; 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 INTERCAL commands, with the word STASH or RETRIEVE followed by the variable or variables to stash or retrieve:

DO STASH .1 + ;2
DO RETRIEVE ,3

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

It is not entirely clear how RETRIEVE interacts with IGNORE in historical INTERCAL-72 compilers; the three modern INTERCAL compilers all use different rules for the interaction (and the C-INTERCAL 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):

• C-INTERCAL 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.
• J-INTERCAL 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 RETRIEVE simply allows a change to its value despite the read-only status.
• CLC-INTERCAL 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.

The appropriate gerunds for STASH and RETRIEVE are STASHING and RETRIEVING respectively.

7.5 IGNORE and REMEMBER

Variables in INTERCAL 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 IGNORE and REMEMBER statements (whose gerunds are IGNORING and REMEMBERING respectively). The syntax is the same as for STASH and RETRIEVE: the command’s name followed by an intersection-separated list of variables. For instance:

DO IGNORE .4
DO REMEMBER ,4 + ;5

Using the IGNORE statement sets a variable to be read-only (or does nothing if it’s read-only already); 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 IGNORE and RETRIEVE was never defined very clearly, and is in fact different in C-INTERCAL, CLC-INTERCAL and J-INTERCAL; for more details, see RETRIEVE.

7.6 ABSTAIN and REINSTATE

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 ABSTAIN and 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 CLC-INTERCAL versions), and one which takes an intersection-delimited list of gerunds. They look like this:

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

(This also illustrates the gerunds used for these commands; note that ABSTAINING from 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 ABSTAIN and/or 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 ABSTAIN and REINSTATE that has existed since INTERCAL-72; historically such restrictions have not always been implemented, or have not been implemented properly. They together define an unusual interaction of ABSTAIN and GIVE UP (note, for instance, that there isn’t a gerund for GIVE UP). The wording used in the INTERCAL-72 manual is:

[...] 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.

This restriction was not implemented at all in the only CLC-INTERCAL version before 0.02 (i.e. version 0.01), or in C-INTERCAL versions before 1.26. The restriction was implemented in C-INTERCAL version 1.26 and CLC-INTERCAL versions 0.02 and later as “GIVE UP cannot be REINSTATED or ABSTAINED FROM”; however, this is not strictly the same as the definition used by INTERCAL-72 (C-INTERCAL still uses this definition in CLC-INTERCAL compatibility mode). The J-INTERCAL implementation of this restriction is to make REINSTATING or ABSTAINING from a line label that refers to a GIVE UP statement a compile-time error, but this does not fit the INTERCAL-72 definition either. The definition adopted with version 0.27 and later of C-INTERCAL, which is hopefully correct, is to allow abstaining from a 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 CLC-INTERCAL’s extension to abstain/reinstate by computed line number, there is also (since version 0.25) a C-INTERCAL-specific extension to ABSTAIN, also known as ‘computed abstain’, but with a different syntax and different semantics. It’s written like an ordinary ABSTAIN, but with an expression between the words ABSTAIN and FROM, for instance:

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

Unlike non-computed 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 ABSTAIN (both the computed and non-computed versions) and REINSTATE, especially when interacting with ONCE and AGAIN (see 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.

7.7 READ OUT and WRITE IN

The READ OUT and WRITE IN commands are the output and input commands in INTERCAL; they allow communication between the program and its user. There was a numeric I/O mechanism implemented in INTERCAL-72, 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 C-INTERCAL and CLC-INTERCAL.

The syntax of READ OUT and 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.

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

7.8 GIVE UP

The GIVE UP command causes the program to end (or, in a multithreaded program, causes the current thread to end). It is written simply as 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 TRY AGAIN, and that it has an unusual interaction with ABSTAIN; for details of this, see ABSTAIN. (Going past the last command in the program is an error.)

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

7.9 TRY AGAIN

The 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 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 TRY AGAIN is TRYING AGAIN.

7.10 COME FROM and NEXT FROM

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

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

The basic rule of COME FROM is that if a COME FROM statement references another statement, whenever that statement is reached, control flow will be transferred to the COME FROM after that statement finishes executing. (NEXT FROM is identical except that in addition to the 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 NEXT.)

Here are examples of noncomputed, computed, and from-gerund COME FROM:

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

(The last example is an infinite loop. If it said 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 COME FROM and NEXT FROM.)

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

Second, you may be wondering what happens if two COME FROMs or NEXT FROMs 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 COME FROMs or NEXT FROMs 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 COME FROMs or NEXT FROMs are noncomputed, however, a compiler can (but does not have to) give a compile time error if two COME FROMs or NEXT FROMs share a label, and so that situation should be avoided in portable code. (If it is wanted, one solution that works for C-INTERCAL and CLC-INTERCAL is to use computed COME FROMs or NEXT FROMs with a constant expression.)

8.1 syslib

INTERCAL has a system library, called ‘syslib’ (versions for bases other than 2 will have a numeric suffix on the name).

The intention of the system library is to provide a range of useful capabilities, like multiplication, that can otherwise be hard to write in INTERCAL. System library routines are used by NEXTING to their line number (see NEXT), where they will make changes to certain variables depending on certain other variables (depending on which routine is called), and RESUME back to the original program. As the system library is itself written in INTERCAL, there are some restrictions that need to be obeyed for calls to it to be guaranteed to work; none of the variables it uses (.1 to .6 and :1 to :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 DO ABSTAIN FROM (1500) or more subtle problems like gerund-abstention) or have COME FROMs or NEXT FROMs aiming at them.

The system library is currently available in all bases from 2 to 7 (see TriINTERCAL), but not every command is available in every base, and C-INTERCAL is the only one of the three compilers listed above that has the system library to ship with a version in bases other than 2. (This table was originally based on the INTERCAL-72 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.

If you happen to be using base 2, and are either using the external call system (see 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 INTERCAL). To do this, use the command line options -eE (before the INTERCAL file), and syslibc (at the end of the command line).

8.2 floatlib

INTERCAL also has a floating-point library, called ‘floatlib’, presently available only in base 2. It is used by several of the demonstration programs shipped with the distribution. In versions after 0.28 it is included automatically at the end of your program by the compiler whenever your program refers to a line from (5000) to (5999) without defining any line in that range in the program.

Here is a summary of routines in floatlib.i:

Note: All of the above routines except (5020), (5060), (5080), (5200), (5210), and (5400) also modify .5 as follows: .5 will contain #3 if the result overflowed or if the arguments were out of domain, #2 if the result underflowed, #1 otherwise. (See below.)

The INTERCAL floating-point library uses the IEEE format for 32-bit floating-point numbers, which uses bit 31 as a sign bit (1 being negative), bits 30 through 23 hold the exponent with a bias of 127, and bits 22 through 0 contain the fractional part of the mantissa with an implied leading 1. In mathematical notation:

‘N = (1.0 + fraction) * 2^(exponent - 127) * -1^sign’

Thus the range of floating-point magnitudes is, roughly, from 5.877472*10^-39 up to 6.805647*10^38, positive and negative. Zero is specially defined as all bits 0. (Actually, to be precise, zero is defined as bits 30 through 0 as being 0. Bit 31 can be 1 to represent negative zero, which the library generally treats as equivalent to zero, though don’t hold me to that.)

Note that, contrary to the IEEE standard, exponents 0 and 255 are not given special treatment (besides the representation for zero). Thus there is no representation for infinity or not-a-numbers, and there is no gradual underflow capability. Conformance with widely-accepted standards was not considered to be a priority for an INTERCAL library. (The fact that the general format conforms to IEEE at all is due to sheer pragmatism.)

PART III: INTERCAL DIALECTS AND EXTENSIONS