# CLC-INTERCAL Reference

## ... The INTERCAL calculator

Table of contents:

- Parent directory
- The INTERCAL calculator
- Command-line options
- Using the calculator

## The INTERCAL calculator

Starting from CLC-INTERCAL 1.-94.-4, a new INTERCAL calculator is included with the distribution. Apart from the obvious use as a luxury desk calculator, the calculator is useful to quickly test fragments of INTERCAL programs by just typing them in the calculator and seeing what happens. Note that some statements are by necessity not supported, for example COME FROMs have no real meaning as each statement is executed as a separate program. ABSTAIN FROM and friends, however, are supported: you can even say things line "DO ABSTAIN FROM (1)", them write out the state to a file, exit the calculator, start it up again, write the state back in, type "(1) DO .1 <- #2" and the statement will not be executed: the calculator remembers it's supposed to be ABSTAINed FROM.

intercalc requires CLC-INTERCAL 1.-94.-4 and newer. It won't work with older versions.

Starting with CLC-INTERCAL 1.-94.-2, intercalc is provided as a separate package, CLC-INTERCAL-ICALC. The various User Interfaces are also probided as separate packages, so you can install just the ones you use.

By default, if started without instructions to the contrary, intercalc uses the configuration to decide what kind of user interface to use; the default depends on which CLC-INTERCAL extensions are installed, but it will try things in the following order until one works.

- X
  Available if the UI-X extension is installed. It works when the calculator runns on a system supporting either Gtk3 or Gtk2, and requires the corresponding perl module installed (Gtk3 or Gtk2). If both perl modules are installed, Gtk3 is preferred.
- Curses
  Available if the UI-Curses extension and the Curses perl module are both installed; it requires a terminal with sufficient capabilities, like an xterm, a Linux, FreeBSD, NetBSD or OpenBSD console, a serial terminal like a VT-220, in fact almost anything except a line printer.
- Line
  Available if the UI-Line extension and the Term::ReadLine::Gnu perl module are both installed; other Term::ReadLine perl modules are currently not supported but will probably be in future; it requires a terminal with sufficient capabilities, like anything mentioned in the previous item and maybe a few more. It may even work on a line printer, although this is untested.
- Batch
  Always available as long as your program has something connected to standard input, for example a keyboard, a card reader, or redirection from a file. This mode is also referred to as "None" because it's implemented by a tiny "interface" called UI-None which is included in the Base package.

The default can be changed as described in the sickrc specification.

In the remainder of this chapter, we speak of "interactive" interface to mean "anything except batch mode" and of "windowed" interface to mean X or Curses, as opposed to Line or Batch.

The arguments on the command line are either options (in the form --name`=`value or -xvalue), or filenames. If a filename is encountered, it must be a file previously created by intercalc using the Read As or Read Out option. Specifiying a file is equivalent to selecting Write In first thing after the calculator starts up.

## Command-line options

There is a number of command-line options, which are grouped by type for easy reference.

### User interface options

If the automatic user interface selection does not give the required result, the following options can be used to control what happens:

Long option | Short | Meaning
--- | --- | ---
--graphic | -X | GTK-based graphical interface
--curses | -c | Curses-based text interface
--line |  | ReadLine-based text interface
--batch |  | Batch mode, no user interface
--interface=NAME | -iNAME | Load the specified interface

The --interface option can be used to load third-party interface modules which intercalc would not otherwise know about: it will look for them in the standard perl include path. Note however that any interface modules using the recommended extension mechanism will add itself to the list of interfaces intercalc tries if not told otherwise, so it may just work without having to say anything on the command line.

### Compiler options and operating mode

These are either the name of the compiler to use, and any extensions which you wish to load initially, or other options which control how the compiler behaves.

Long option | Short | Meaning
--- | --- | ---
--include=DIR | -ID ALIGN="left"IR | Add directory to search path for compiler objects
--language=NAME | -lNAME | Selects the compiler (default: sick)
--option=NAME | -oNAME | Selects a compiler option, may be repeated (default: none)
--mode=NAME | -mNAME | Selects operating mode (default: full)
--bug=NUMBER |  | Change the probability of the compiler bug
--ubug=NUMBER |  | Change the probability of the unexplainable compiler bug

The calculator currently defines three operating modes: full (the default), expr and oic.

In full mode, the full power of the selected compiler and extensions is available. One types INTERCAL statements and watches them execute. Additionally, for convenience, one can type an expression and this will be evaluated and its result displayed. It is internally implemented by pretending you typed "DO READ OUT expression".

expr mode is a restricted form of full mode, where you can only execute assignments and evaluate expressions; other statements are disallowed. Assignments are specified without the initial DO and/or PLEASE. Expressions can of course contain overloading and other side-effects, which will be remembered and will come back to cause unexpected results later. This mode is suitable for a desk calculator.

oic mode is a silly "One Instruction" desk calculator which is there because we can. This mode is currently undocumented.

### Misc options

The following options control the way intercalc operates:

Long option | Short | Meaning
--- | --- | ---
--nouserrc |  | Ignore .sickrc files found
--nosystemrrc |  | Ignore any files in /etc/sick
--rcfile=NAME | -rNAME | Uses specified file instead of searching for files
--rcskip=NAME | -RNAME | Ignores VERB when processing sickrc files
--interpreter=NAME |  | Uses an alternative CLC-INTERCAL Interpreter

## Using the calculator

Once the calculator has started, it will display its window (in windowed mode), print its prompt (in Line mode), or simply wait for input (in batch mode). In any case, you enter statements or expressions and watch them execute.

Some menus are available in windowed mode to change the current compiler, base and operating mode. These should be self-explanatory in the X interface; for the Curses interface, see below. For non-windowed interfaces, there is an alternative mechanism to access the functionality provided by menus in windowed mode, see below.

In X mode you can provide input by clicking on a key or by pressing the corresponding key on the keyboard if there is one (some symbols may not be available on all keyboards). The menus work in the obvious way. There is at present no keyboard shortcut for the menus, but it may be added in future.

In Curses mode you can press the key if it exists on the keyboard, or use the cursor keys (up, down, left, right) to highlight one of the buttons on the screen, then press Enter to activate it. Note that Enter does not terminate the line in Curses mode: to do that, press F5 (Do It) or "=" key, or navigate to the F5 button and press Enter. This may work different from other systems. To open a menu with a label starting with X, press Alt-X, for example Alt-L will open the Language menu. If the keyboard cannot produce this, the Escape and backspark ("`") keys will highlight the first menu, then the left and right cursor keys can move between menus, and Enter or down will open the menu. Another Escape or backspark will return to the main keypad. If you wanted a normal user interface, presumably you wouldn't be using an INTERCAL calculator.

If the system's curses library and the terminal both support it, the Curses module can also use the mouse. Add the statement:

    	I CAN POINT WITH THE MOUSE

To a configuration file to enable it. Clicking the first mouse button while the cursor is on any enabled key or menu will do the corresponding action and make that key or menu the current item.

In line and batch mode, access to menu functions can be achieved by starting a line with a backspark (```) and a letter. In Line mode you can see what letters make sense by pressing Tab twice after the backspark, which will give you a list. In any case, the following backsparks are available:

Backspark | Meaning
--- | ---
`a | Show the "About intercalc" text
`bBASE | Change base
`c | Save settings to .sickrc
`g | Give up (exit calculator) - you'll need to do it twice to confirm
`h | Show command history
`hNUM | Show command history, limiting to last NUM commands
`lLANGUAGE | Load a different compiler (1972, ick or sick)
`mMODE | Change operating mode (full, expr or oic)
`oOPTION | Toggle compiler option
`rFILE | Read Out: saves calculator state to file
`r | Like `rFILE but uses last filename given to `r or `w
`t | Show program trace, if enabled with `otrace
`tNUM | Same as `t, limiting to trace produced by last NUM commands
`wFILE | Write In: loads calculator state from file
`? | Help: displays the help text

If you do not provide an argument to `b, `l, `m or `o, they will show a list. Currently selected base, language, mode or options (respectively) will be marked with a splat. The Line interface will also show all possible completions if you press Tab twice, so "`l Tab Tab" shows all available languages and so on.