Ubuntu Manpage: sick - Compiler for CLC-INTERCAL

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.

NAME

SYNOPSIS

DESCRIPTION

BUGS

SEE ALSO