Ubuntu Manpage: sick - Compiler for CLC-INTERCAL

Provided by: clc-intercal_1.00-2build1_amd64

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