# CLC-INTERCAL Reference

Table of Contents

- Introduction
- Obtaining CLC-INTERCAL
- Installing CLC-INTERCAL
- Fundamental Concepts
- Expressions
- Statements
- Belongs TO
- Classes and Lectures
- Input/Output
- Quantum INTERCAL
- INTERNET: INTERcal NETworking
- The System call interface
- Compiler extensions and optional features
- Writing compilers for CLC-INTERCAL
- The command-line compiler tool
- Embedding INTERCAL in Perl source
- The INTERCAL calculator
- Errors
- The various character sets supported by CLC-INTERCAL
- Configuration files
- Environment variables

## Introduction

CLC-INTERCAL was first released as an April fool joke on April 1st, 1999. The idea behind the release was to provide a new INTERCAL compiler which could be used as a test-bed for new language ideas, provided one could justify such ideas with the fundamental INTERCAL philosophy of "doing things differently".

Some features of C-INTERCAL or INTERCAL-72 were thought to be too "normal", so support for them was made optional. In the current version (1.-94.-2.1 at the time of writing), such optional features can be enabled by providing command-line options to the compiler tool (see the chapter about the command-line compiler tool), or by using the appropriate menus in the calculator (see the chapter about the INTERCAL calculator). The reference manual will indicate which features are optional and which option enables which feature. For example, CLC-INTERCAL has always considered NEXT to be an obsolete statement, being just a standard subroutine call, and one enables it by selecting the "next" option (or by using the ick compatibility mode, which automatically enables this option).

Other optional features are experimental language extensions, or else extensions which, it was felt, are above and beyond the call of insanity, for example the ability to use computed statement labels or the "COME FROM gerund" statement. See the chapter about compiler extensions and optional features.

## Obtaining CLC-INTERCAL

Unlike some other software projects, which have releases we try to keep the world safe by not releasing CLC-INTERCAL. However, despite our best efforts, it occasionally escapes and that makes it possible for other people to obtain it.

The latest escape will always be available at the top of the CLC-INTERCAL download page on SourceHut. In the page containing the escape, the "Bundle" package is listed first, followed by the "Base" package and then all other optional components.

The most recent escapes (since 1.-94.-2) are available as a "Base" package containing the minimum set of things needed to compile and run CLC-INTERCAL programs, and separate packages for optional components; a "Bundle" package contains the whole thing and has a method to install it at once instead of installing all the components in the required order to satisfy their dependencies. Refer to Installing below for more details.

Escapes since 1.-94.-7 are available for download using two different file formats: a tarball and a DD/SH program. These are listed in separate columns in the various download pages, and it is only necessary to obtain one of them for each package desired. When the difference between an escape and the previous one is small, there may also be a "patch" file which applies to the previous escape, which eill be the one listed in the line after the one containing the patch itself.

A development version, which may be broken and/or incomplete is now maintained in a git repository on SourceHut. Please note that although escapes are marked as "release" on the git repository, this does not in any way imply that anything has been released: these are generated automatically from git tags, and the corresponding tarball will be different from the official ones on the download page; moreover, the installation instructions may not apply to such tarballs. If you wanted something where tarballs generated automatically by git are the same as the distribution ones, you wouldn't be using INTERCAL anyway.

A Debian package for CLC-INTERCAL is provided by Mark Brown. See the Debian package description for more details. Packages for other operating systems and/or distributions may be made available in future. Watch this space. Or avoid watching it if that makes you feel safer.

## Installing CLC-INTERCAL

The procedure to install CLC-INTERCAL has varied considerably between escapes; this section applies to the latest escape; each escape also contains installation instructions appropriate for its own procedure.

### Dependencies

Since CLC-INTERCAL is written in perl, a working perl installation is a prerequisite. The Base package tries to use only modules installed by default, but if we find out that some installations do not have some of them we'll list them here.

The "INET" package needs to figure out which network interfaces are present, and their IP address(es). Starting from escape 1.-94.-2.3 the build system will check if it's possible to use its own module which requires a working C compiler and some C functions to be available in the C library. This is known to work on Linux, FreeBSD, NetBSD and OpenBSD if they have development tools installed.

If it is not possible to use CLC-INTERCAL's own interface detect module, or if you are trying to build an escape prior to 1.-94.-2.3, the build system will look for the Net::Interface module and use that instead: this module is available on CPAN and all the usual mirrors. It needs at least version 1.0. On NetBSD, Net::Interface has a bug which requires fixing before using it: obtain the source from CPAN, apply this tiny patch to them, then build and install it according to the instructions in its own README. We reported the bug and the patch, so it's possible that this may not be needed by the time you read this, On all other systems, if there is a package providing Net::Interface it can be used without building it from source; if you do build it from source, it may give an error when you run Makefile.PL because perl's defaults have changed: the easiest way to fix that is to apply this tiny patch (note that the NetBSD patch already includes this one, so you do not need both!)

Speaking about Net::Interface, we are aware that there is also IO::Interface and IO::Interface::Simple, but it turns out that they didn't work at all in several of our test systems, so we preferred Net::Interface which works on all of them, with a tiny patch required in some cases.

The "UI-Curses" package needs the Curses module.

The "UI-Line" package needs Term::ReadLine::Gnu - at present, it does not work with Term::ReadLine::Perl but it may in future.

The "UI-X" package needs the Gtk3 or Gtk2 module, using Gtk3 if both are installed.

#### Debian, Ubuntu and derivatives

Runtime dependencies for the three user interfaces:

    	apt install libterm-readline-gnu-perl
    	apt install libcurses-perl
    	apt install libgtk3-perl

Required for INET 1.-94.-2.2 or older:

    	apt install libnet-interface-perl

#### Gentoo

Beginning with CLC-INTERCAL-1.-94.-2.3 we provide ebuilds which can install all parts of the compiler; see the information in this git repo. The rest of this section describes how to install without using these ebuilds.

Runtime dependencies for the three user interfaces:

    	emerge -a1 dev-perl/Term-ReadLine-Gnu
    	emerge -a1 dev-perl/Curses
    	emerge -a1 dev-perl/Gtk3

Required for INET 1.-94.-2.2 or older: obtain the sources for Net::Interface from CPAN, apply this patch, then build and install as per its instructions.

#### FreeBSD

Runtime dependencies for the three user interfaces:

    	pkg install p5-Term-ReadLine-Gnu
    	pkg install p5-Curses
    	pkg install p5-Gtk3

Required for INET 1.-94.-2.2 or older:

    	pkg install p5-Net-Interface

#### NetBSD, OpenBSD

Runtime dependencies for the three user interfaces:

    	pkg_add p5-Term-ReadLine-Gnu
    	pkg_add p5-Curses
    	pkg_add p5-Gtk3

(At the time of writing, NetBSD did not have a p5-Gtk3 or p5-Gtk2 package, but OpenBSD did).

Required for INET 1.-94.-2.2 or older: obtain the sources for Net::Interface from CPAN, apply this patch, then build and install as per its instructions.

### Unpacking the sources

There are different procedures depending on which type of sources you have obtained.

After downloading a DD/SH program, you need to run it, either uncompressing it first, or, if your shell allows it (most do) by using a pipe from the decompressor. For example:

    	gzip -dc /path/to/dowload.ddsh.gz | sh

or

    	gzip -d /path/to/dowload.ddsh.gz
    	sh /path/to/download.ddsh

The "sh" must be a Bourne-type shell, like sh, ash, bash, dash or ksh. A C-type shell like csh or zsh won't work.

After downloading a tarball, just unpack it using your system's "tar" program or any other archive extraction software which can read tarballs. If necessary, decompress the file first. For example:

    	gzip -dc /path/to/dowload.tar.gz | tar xvf -

or

    	tar xvzf /path/to/dowload.tar.gz

The git repository contains the whole bundle. Therefore to install the bundle there is no need to unpack anything once you have obtained a clone or copy of the repository. If planning to install the components separately, these will be in a subdirectory named after the component, but without the escape number, for example "CLC-INTERCAL-Base": change to that directory and follow the normal installation instruction for each component.

### Installing the bundle

Unpack the source as described above, then change to the directory it created, which will be something like "CLC-INTERCAL-escape". Note that the bundle includes a different build system from the separate packages, so it cannot be installed by downloading all packages, you need to download the bundle itself. After unpacking and changing into the directory, run the following four commands:

    	perl Makefile.PL <- see notes below about XS builds
    	make
    	make test        <- see notes below about syslib tests
    	make install     <- as root or sudo if required

After that, it is safe to change out of the directory and delete its contents.

### Installing from separate packages

Installing separate packages is possible after downloading either the bundle or the required packages separately. This section describes how to install from the separate downloads, with a note about the differences when using the bundle or the git repository.

Always start with "Base"; the rest can then follow in any order. For each package to install, start by unpacking it as described above, then change to the directory it created, which will be something like "CLC-INTERCAL-component-escape", then run the following four commands:

    	perl Makefile.PL <- see notes below about XS builds for the INET package
    	make
    	make test        <- see notes below for the syslib tests in the Base package
    	make install     <- as root or sudo if required

After that, it is safe to change out of the directory and delete its contents, then repeat the process for other optional components if desired.

If you have downloaded the bundle, or start from a clone or copy of the git repository, the instructions are essentially the same, the only difference is that the directory for each component will not have the escape number, so it will be something like "CLC-INTERCAL-component".

Note that trying to install any component other than "Base" while "Base" itself is not installed will fail: the Makefile.PL actually needs some modules installed by it. Always build and install "Base" first.

When building packages for distribution, it's also possible to use the build directory for "Base" without installing it, by adding the appropriate paths to perl's search path. How you do that depends on your build environment. Another option when building packages is to build and test the whole bundle first, then go into each separate component directory and run "make install" there, which will install that component only: provide any options appropriate for your build system so that the install happens where it needs it rather than on the root filesystem!

### Special note for XS builds

The INET package includes its own network detect module, and the build system will try to build it if that looks possible. If it fails to build, that is obviously a bug, either in the module itself, or in the decision by the build system that it could be built. (Other parts of the compiler may include XS modules in future, and if so the same notes will apply).

The first thing to do is to verify that the build succeeds without the XS modules by running:

    	perl Makefile.PL --avoid-xs

then continuing the build as before. If it now succeeds, please report a bug including all relevant information such as operating system and version, system architecture, name and version of C compiler installed, version of Perl installed, and of course the error messages produced by the build.

Until we can figure out what's wrong, please continue building the system with --avoid-xs to work around the issue.

### Special note for syslib tests

The Base package includes a perl reimplementation of INTERCAL libraries which ship with C-INTERCAL, but cannot be included in CLC-INTERCAL as they have unknown licensing status; these are the system library, syslib.i and syslib3.3i to syslib7,7i, and the floating point library, floatlib.i. Two sets of tests, t/17syslib.o.t and t/19floatlib.o.i, test this reimplementaion against results obtained running C-INTERCAL with its own libraries, so we know that they are as compatible as possible. These tests always run, and take between 10 seconds and a few minutes on any reasonably modern system (by which we mean that it has been manufactured in the last 20 years).

The Base package also includes two sets of tests which can only run if these C-INTERCAL libraries are present, and which are skipped by default, just printing "skipped: read the documentation to know how to run this test". If they do run, they provide a more comprehensive comparison between CLC-INTERCAL and C-INTERCAL, but they require the user to have obtained these libraries separately and they are not necessary to verify that CLC-INTERCAL was built correctly, only that it can compile and run a large set of C-INTERCAL sources.

Another reason for not running these tests is that they are extremely slow, and could take hours to complete.

If C-INTERCAL is installed on the system it provides these libraries, normally in /usr/share/ick-VERSION or /usr/local/share/ick-VERSION. To run these extra tests it is sufficient to set environment variable $ICK_SYSLIB_DIR to a directory containing all these files and then run "make test", for example (sh-like shells):

    	    ICK_SYSLIB_DIR=/usr/share/ick-0.31 make test

Of course, if the user has obtained these files without installing C-INTERCAL the same applies, probably with a different directory in the command.