SICK(1p)

NAME
sick - Compiler for CLC-INTERCAL

SYNOPSIS
sick [options] files...

DESCRIPTION
sick is the main development environment for CLC-INTERCAL. If files are specified, they will be loaded into the compiler: if they are not objects, they are considered to be program sources and compiled using the options in effect at the point where they appear on the command line: the object produced by the compilation is then kept in memory.

After all the things found on the command line have been processed in some way, the program will then pass all the objects to one or more backends to do things with; the default backend just saves the objects to file, but other options exist, for example run the objects or produce program listings. Note that the action to be performed can be changed with command line options, and may be different for each object: the options in force at the time the object was loaded will be used to save or execute it.

A future version of sick will also include an interactive mode in which these objects can be inspected, ran, single-stepped, debugged or simply left alone in memory while you do something more productive.

Each non-object file will be compiled using a compiler selected using command line options; if nothing is selected, the compiler depends on the file suffix; the compiler considers a suffix anything from the last spot in the name (including the spot), and the suffix usually ends with i, for example program1.i has suffix .i and program2.test.case.42.mublei has suffix .mumblei.

The suffix selection rules are actually defined in the various sickrc files: the description below corresponds to the defaults set by the system.sickrc file included with the compiler but your local installation may have changed that.

CLC-INTERCAL program source
    These files must have a suffix ending in i; if the suffix also contains clc as a substring, this makes sure the source will be considered a CLC-INTERCAL program, otherwise the interaction of the many suffix rules may end up selecting a different compiler. These files will be prefixed with the compiler object sick.io.

CLC-INTERCAL compiler source
    These files must have suffix .iacc. These will be prefixed, by default, with the compiler object iacc.io and produce a compiler object (which can be executed as a program, but will do nothing - it's only useful as a preload before compiling from source).

C-INTERCAL program source
    These files must have a suffix ending in i and containing a c or a t somewhere, but not contain clc as substring: for example, prog1.cli and prog2.ti are understood as a C-INTERCAL source, but prog3.clci and prog4.tclci are not (they are CLC-INTERCAL sources). These files will be prefixed with the compiler object ick.io.

CLC-INTERCAL assembler source
    These have suffix .iasm and will be prefixed with the compiler object asm.io.

Traditional INTERCAL program source
    These will have suffix .1972 or .1972i and will be prefixed with the compiler object 1972.io

Compiler extensions
    Any other letters in the suffix can be used to select compiler extensions, Note that when a suffix is shown exactly in the above list, for example .1972 or .iacc, there is no space for extra letters and there are no other extensions: if this is reqlly required, the language guessing mechanism can be bypassed as described later in this document.

Personality
    By default, sick operates imitating itself. However it can imitate other compilers too by selecting a different personality. At present, imitating another compiler just means that different suffix rules apply. The main effect of the rules is that the default compiler changes from "sick" to "ick" or "1972" according to the personality; more information can be found in the online documentation or the CLC-INTERCAL-Docs package.

    Base
        Numbers between 2 and 7 change the default base by loading compiler objects 2.io to 7.io. If more than one number is present, the largest one wins, so .32i is a CLC-INTERCAL program in base 3. Also note that the suffixes .1972 and .1972i do not take options, and the 7 and 2 in these suffixes do not select a base; all INTERCAL-72 programs operate in base 2 only. These options can be used with sick or ick and can be added to iasm by specifying them as additional preloads, e.g. -Ap5

    Bitwise Divide
        Letter d in the suffix adds the compiler object bitwise-divide.io, which changes the normal unary divide operation to use bitwise, rather than arithmetic, shifts. It can be used with sick but not with ick. It can also be used with iasm by specifying the compiler object as an additional preload.

    COME FROM gerund
        Letter g in the suffix adds the compiler object come-from-gerund.io, which enables the COME FROM gerund statements; since ick does not parse such statements, this letter can only be used with sick, or with iasm by specifying it as an additional preload.

    Computed labels
        Letter l (ell, not upper-case i) in the suffix adds the compiler object computed-labels.io, which adds grammar rules to parse computed statement labels; this can be used only with sick; ick would not be able to use this, and iasm can just put computed labels in the object where it wants them.

    NEXT
        Letter n in the suffix adds the compiler object next.io, which enables the NEXT statement in sick; since ick enables this by default, and iasm programs can just put the NEXT instruction in the object, this letter can only be used with sick.

    INTERcal NETworking
        Letter r in the suffix adds the compiler object internet.io, which adds syntax for the STEAL, SMUGGLE and CASE statements; it can be used with ick or sick. It requires the INET extension to be installed. An iasm program may be able to take advantage of this by specifying it as an additional preload.

    System call
        Letter s in the suffix adds the compiler object syscall.io, which hides a "PLEASE NEXT FROM (666)" in a dark corner of your operating system. Works with any compiler, even INTERCAL-72, but for iasm and 1972 it needs to be specified as an additional preload.

    Threaded program
        Letter t in the suffix selects threaded mode by loading compiler object thick.io. This also changes the default compiler to ick if the suffix is .i: to use sick one would use something like .tclci. It also works with iasm and 1972 if specified as an additional preload.

    Wimp mode
        Letter w in the suffix adds the compiler object wimp.io, which causes the program to start in wimp mode when it is executed. An equivalent result can be obtained by passing the --wimp option to the executable program. To use this option with iasm or 1972 specify it as an additional preload.

The actual list of suffixes recognised is specified by the file system.sickrc and can be modified by a system-wide file in /etc/sick (any file name in that directory as long as it does not start with a spot) or by a per-user .sickrc file in a user's home directory. See the "Misc options" below for a discussion on how and where sick finds these files, and the online documentation for description of the file format.

If a preload file is specified on the command line, the defaults derived from the suffix are not used. It is also possible to use default preloads from a different file suffix by explicitly saying --suffix=.S - in this case, the compiler acts as if the file had name name.S; it is also possible to use the --add-preloads option to always request the suffix-based guess, and in addition to that also load any preload file specified.

In addition, compiler objects are always recognised, with whatever suffix. These bypass the first compiler pass and jump directly to the runtime (just-too-late) compiler. However, if the optimiser has been selected when these objects were compiled, and there are no postprocessor statements, the just-too-late compiler will be automatically replaced by a more traditional "compile-time" compiler. If this is confusing, wait until you see the rest.

If a file is specified without suffix, and there is a compiler object in the include path with the same name and suffix .io, the suffix is automatically added, whether you wanted it or now.

As soon as each program is written into sick, a pre-compiler will produce an internal compiler object.

It is possible to ask the compiler to produce a program listing; this may make the compiler run slower, for example because it'll have to remember a lot more information, depending on the type of listing selected.

If sick enters interactive mode, these objects will be available in memory for single-stepping, running, or just ignoring completely and getting on with the real work (note that the interactive mode has been talked about repeatedly, but so far, not implemented).

If sick loads all the required programs and objects successfully, but does not enter interactive mode, it will pass all the objects to the appropriate backends and then terminates. In the absence of a --backend option this means the single backend "Object", which reads the object back to disk using the file name specified by --output, or if that wasn't specified, using the original file name but replacing its suffix with .io; this behaviour can be modified using the options described below.

The compiler accepts more several options, some of which are documented here. Options and files can be mixed in any order, each file is loaded and compiled using whatever options precedes it on the command line. For example:

    sick --verbose --optimise prog1.i --quiet prog2.i --batch

will tell you everything about compiling prog1.i but not about prog2.i. Both programs will be optimised. On the other hand:

    sick --optimise prog1.i --nooptimise prog2.i --batch

will optimise prog1.i but not prog2.i.

All options can be "undone" (sometimes it's even clear how) except --include which applies to all objects loaded after it, and --rcfile which applies to all objects, even the ones loaded before it (just to be different). In fact, --rcfile works so differently from other options that we aren't sure what happens if it appears after any non-object file in the command line, so for simplicity always specify it first.

  User Interface Options
At present, sick does not use any user interfaces and always runs in batch mode; however there are user interface selection options in case one day we add support for them. The available interfaces depend on which optional interface modules are installed, and the operating environment decides which ones can actually be used.

-X / --graphic
    Enters X-based graphical user interface. Requires the optional UI-X package and its dependencies, and it will only work if running in a suitable environment, for example X windows.

-c / --curses
    Enters full screen, curses-based interface. Requires the optional UI-Curses package and its dependencies, and it will only work if running on a suitable terminal. These days, that means anything except a line printer.

--line
    Enters the line-mode user interface. Requires the optional UI-Line package and its dependencies, and it will only work if running on a terminal which supports it. These days, that means almost anything.

--batch
    Avoids entering interactive mode. This is the default if the standard input and output are not connected to a terminal and the X based interface cannot be started. It is also the default until we actually implement interactive mode.

-itype / --interface=type
    Selects the user interface type. Currently, only X, Curses, Line and None are defined, but more can be installed as compiler plug-ins. If the interface selected is None, sick will work in batch mode. In addition, an empty string will reinstate the default behaviour.

  Source Character Set Options

-a / --ascii
    Assumes that program source is in ASCII.

-b / --baudot
    Assumes that program source is in Baudot.

-e / --ebcdic
    Assumes that program source is in EBCDIC.

-h / --hollerith
    Assumes that program source is in Hollerith.

-g / --guess
    Does not make assumptions about the source character set. If the character set cannot be guessed, will produce an error. This is the default.

--charset=name
    Assumes that program source is in the given character sets. Valid values are currently ASCII, Baudot, EBCDIC, Hollerith but others could be installed as compiler plug-ins; an empty name is equivalent to specifying option --guess).

  Code Generation Options

-O / --optimise
    Invokes the optimiser. This is an upper case letter O, not a zero. This will cause the extra object optimise.io to be prefixed after the last compiler and before the real program. The program is then executed: when the optimiser takes control, it will force compilation of the rest of the program (thereby executing the compiler at compile-time, instead of runtime as it normally does), and the resulting object is checkpointed, so the next time it will automatically skip the initialisation and compilation stages. In addition, the "optimise" register is set, instructing the compiler to invoke the optimiser when it runs.

    If you specify both -O and -poptimise (see below), you are asking for trouble, so don't do that.

--nooptimise
    Disables automatic preloading and execution of optimise.io.

-oname / --output=name
    Selects a name for the output file. Some character sequences are recognised inside name: %p will be replaced by the source program's filename with the suffix removed; %s will be replaced by the appropriate suffix for the selected backend, without the initial spot; %o will provide the original file name specified on the command line, without suffix (this can differ from %p because %p can be prefixed with a directory from the search path); finally %% will produce a single %.

    The default is %p.%s, which produces the object name described at the beginning of this document. A suffix is not automatically added if the output name does not contain %s; this might be useful in conjunction with the Perl backend to produce a file without a suffix, for example:

        sick --output=%p --backend=Perl sourcefile.i

    will compile sourcefile.i and produce perl script sourcefile.

    The special backend "help" produces a list of all known backend names, and does not change the current list.

    If the output file is specified as an empty string, the code generation step will never be done.

-Ltypes / --listing=types
    Asks the compiler to produce a program listing; types is a comma-separated list, each element directs the compiler to produce a different program listing; at present, only "html" is supported which generates a syntax-highlighted version intended to be combined with a stylesheet. Use -Lnone to disable source listing from the next object, and -Lhelp to show a list of supported listing modules (this does not change what will run, just produces a list on standard output). It is possible to specify a single argument to a listing module by appending "=" and the argument to the name, for example the "html" module can be asked to load a stylesheet with something like "-Lhtml=clc-intercal.css"

-nname / --name=name
    Sets the program's name, if the code generator requires it (currently, no backends use a name, but some of the future ones will). The default is %o. The same %-escapes as defined for the output file name are defined.

--ddirectory / --directory=directory
    Forces all outputs to be produced in directory. This works by generating an output name as described above, then replacing the directory part.

-lnames / --backend=names
    Selects one or more compiler back ends; the short option is a lower case "L", not an upper case "I". The default is Object, which produces a compiler object (suffix .io). The distribution also includes a Perl backend, which produces an executable Perl program (suffix .pl). In addition, the pseudo backend Run will run the program instead of producing any object. In this case, the output file name is ignored. Note that the program will only run if the compiler is in batch mode. Other back ends can be provided as compiler plug ins. The distribution also contains a ListObject backend, which does not produce executables but object listings. A future version might offer the option to "uncompile" the output of the ListObject back end, but this is currently impossible because not all the internal state of the object is provided, only the part which is likely to be useful to a human reader. For example:

        sick prog1.i -lObject,ListObject prog2.i -lRun,Object prog3.i

    will compile prog1.i to prog1.io (default backend), then compile prog2.i to prog2.io and also produce a program listing in prog2.iasm, and finally compile prog3.i, run the object immediately but also save it to prog3.io.

--bug=number
    Selects a different probability for the compiler bug. The compiler bug is implemented by initialising the compiler's state with the required probability: when a statement is compiled (usually at runtime), a "BUG" instruction is emitted with the required probability. The default is 1%.

--ubug=number
    Selects a probability for the unexplainable compiler bug. This is the compiler bug which occurs when the probability of a (explainable) compiler bug is zero. Only wimps would use this option. The default is 0.01%.

-pname / --preload=name
    Selects a compiler object to prefix to the program. If this option is specified, the compiler won't automatically prefix objects as suggested by the suffix. The program 'oo, ick' included in previous version of CLC-INTERCAL used option -p to select a parser. Since the main use of preloads is to select an alternative (runtime) compiler, it is felt that it is appropriate to keep the same letter for this option.

    The file name specified does not include the suffix .io, which is always added. The file must be a compiler object, not source code.

    The special object optimise should always loaded via -O. Using -poptimise will not necessarily put the object in the correct place, and will not instruct the precompiler to do whatever magic it needs to do to bootstrap the optimiser.

    To completely disable preloading (this is only done when compiling the optimiser, which is used to compile itself) use an empty string.

--nopreload
    Resets the default behaviour of selecting preloads based on suffixes.

-A / --add-preloads
    Asks to do the normal suffix-based guess of preloads, then add to that the ones specified with --preload. This can be used for example to add a single preload to a pre-defined list.

--suffix=suffix
    Specifies a suffix to use when selecting preloads. If this option is not specified, the suffix is taken from the file name to be compiled.

--imitate=whom
    Specifies that different suffix rules apply by "imitating" another compiler; this functionality is still experimental. The value whom can be one of "sick", "ick" or "1972".

--clc-intercal
    Alias for --imitate=sick

--c-intercal
    Alias for --imitate=ick

--intercal-72 / --intercal-1972
    Alias for --imitate=1972

-Ipath / --include=path
    Adds a directory before the standard search path for compiler objects and source code. If a file is accessible from the current directory, it is never searched in any include path.

    If this option is repeated, the given paths will be searched in the order given, followed by the standard paths.

  Misc Options
In the absence of orders to the contrary, sick starts by looking for configuration files. First the system search path is scanned to find any files of the form *.sickrc; if two files with the same name are found in different directory, only the first one is considered. If this search reveals a file called system.sickrc this will be executed first: any other files found will be executed next in an implementation-defined order.

After searching the system directories, sick considers the directory /etc/sick: any files found there, where the first character is not a spot, will be executed in an implementation-defined order.

The process concludes by looking for file .sickrc in the user's home directory: if found, it will be executed too.

-rname / --rcfile=name
    Gets configuration from file name before doing anything else. This option can be repeated, in which case these files will be exectuted in the order specified. If this option is specified it also disables the search for configuration files described above, so only the files specified on the command line will be executed. Note that we use the terms "get configuration" and "execute a file" interchangeably because a configuration file is just a special program with an unusual syntax.

--nouserrc
    Prevents loading a user rcfile (.sickrc). This option is normally used during installation, to prevent interference from previous versions of CLC-INTERCAL.

--nosystemrc
    Prevents loading system rcfiles (usually in /etc/sick) if any exist. This option is normally only used during installation, to prevent interference from previous versions of CLC-INTERCAL. Also, it will limit the search for files to the current "build" directory if there is one, meaning that any installed *.sickrc files will be ignored.

-Rverb / ---rcskip=verb
    Makes the program ignore the verb in a sickrc file. This could be used, for example, to disable the automatic loading of libraries when it looks like the program needs them, using --RGLUE.

--extension=name
    Ask the program to make sure to load extension name. This is normally unnecessary as finding an extension's own sickrc file will load the extension; however during installation sick will not yet know about this sort of things so the build system adds this option to make sure.

-v / --verbose
    Tells everything it's doing (on Standard Error).

--stdverb=file
    Sends verbose output to file.

--trace
    Enables tracing; if compiling from source, the compiler is also traced; to trace a program, compile it to an object and then run it with --trace.

--stdtrace=file
    Enables tracing and selects an output file for the trace information.

--notrace
    Disables tracing; preloading trace.io has priority over this option.

--grammar-profile
    Enables grammar profiling: this will produce a summary of how the compiler's grammar was used when compiling programs; it is mostly useful for either debugging new compilers or analysing the parser's performance. The information is sent to standard error, unless a previous --stdgrammar-profile option (see next option) has selected something different.

--stdgrammar-profile=file
    Enables grammar profiling and sends the output to file.

--nostdgrammar-profile
    Disables grammar profiling (default).

--grammar-profile-max=number
    If grammar profiling is enabled, only produce the first number lines of output: the output is sorted by decreasing count, so these will be the number most "interesting" productions from the point of view of performance analysis.

--grammar-profile-count=number
    If grammar profiling is enabled, only produces output lines where the usage count is at least number.

--grammar-profile-cost=number
    If grammar profiling is enabled, only produces output lines where the estimated cost is at least number.

-q / --quiet
    Stop talking to Standard Error.

--times
    Prints a summary of the time take for each major action. This setting is independent of --verbose or --quiet.

--notimes
    Does not print execution times: this is the default.

--rclist
    Prints the names of all rcfiles found; It prevents starting interactive mode. The names will be prefixed with a "splat" symbol ("*") if they would be executed according to other command-line options like --nouserrc and --nosystemrc, and without one if they would not be executed. For example, to edit all the files which would actually be executed, and to edit them in the order they would be executed, run something like:

       sh -c '"${EDITOR:-teco}" `sick --rclist | awk '"'"'$1 == "*" { print $2 }'"'"'`'

    These weird sequences of sparks and rabbit ears are obviously there to cope with the quoting mechanisms of different shells.

--interpreter=module
    Uses an alternative CLC-INTERCAL Interpreter. The default is whichever Interpreter is considered the best at the time the program is distributed.

BUGS
There are more options than ls(1). This is construed to be a feature. Some of the options are not documented here but are documented in the Docs package; some are documented here but not there.

SEE ALSO
The INTERCAL on-line documentation, or the contents of the Docs package. If necessary, see a qualified psychiatrist.