.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "INTERCALC 1p"
.TH INTERCALC 1p "2008-03-29" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
intercalc \- CLC\-INTERCAL desk calculator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBintercalc\fR [options]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBintercalc\fR is a simple desk calculator, allowing the user to
enter \s-1INTERCAL\s0 statements (to see what they do) and expressions
(to see what value they produce); it uses an interpreter object
from CLC-INTERCAL to provide immediate feedback.
.PP
The desk calculator accepts several options, some of which are documented here.
.SS "User Interface Options"
.IX Subsection "User Interface Options"
.IP "\fB\-X\fR / \fB\-\-graphic\fR" 4
.IX Item "-X / --graphic"
Enters X\-based graphical user interface. Requires Perl-GTK. This is the
default if Perl-GTK is installed, the environment variable \fI\f(CI$DISPLAY\fI\fR is
set and the opening of the X display succeeds.
.IP "\fB\-c\fR / \fB\-\-curses\fR" 4
.IX Item "-c / --curses"
Enters full screen, curses-based interface. This is the default if the
X based interface cannot be started, the environment variable \fI\f(CI$TERM\fI\fR
is set and the terminal name is known.
.IP "\fB\-\-line\fR" 4
.IX Item "--line"
Enters the line-mode user interface. This is the default if the X based
and the curses based interfaces do not work.
.Sp
In this mode, the program executes each line from standard input according
to the current mode and language, and prints results to standard output.
A line starting with a backspark is interpreted as a command to the
calculator. Use backspark-g to \s-1GIVE\s0 \s-1UP\s0 (you'll need to do it twice), or
backspark-h to display the ehm, help page. Things which are available
via menu entries on the Curses and X interfaces are also available via
the backspark. For now, you can refer to the source code for a list.
.Sp
Command-line editing and command history is provided by the readline
library. Command completion works if the underlying compiler supports it
(the compilers provided with the distributions do).
.IP "\fB\-\-batch\fR" 4
.IX Item "--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. This mode is very similar to the line mode except that
command-line editing and command history are not implemented. Backspark
escapes work just the same.
.IP "\fB\-i\fR\fItype\fR / \fB\-\-interface\fR=\fItype\fR" 4
.IX Item "-itype / --interface=type"
Selects the user interface \fItype\fR. Currently, only \fIX\fR, \fICurses\fR,
\&\fILine\fR and \fINone\fR are defined, but more can be installed as compiler
plug-ins. If the interface selected is \fINone\fR, \fBintercalc\fR will work in
batch mode. In addition, an empty string will reinstate the default
behaviour.
.SS "Source language and compilation options"
.IX Subsection "Source language and compilation options"
.IP "\fB\-\-bug\fR=\fInumber\fR" 4
.IX Item "--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 \*(L"\s-1BUG\s0\*(R" instruction is
emitted with the required probability. The default is 1%.
.IP "\fB\-\-ubug\fR=\fInumber\fR" 4
.IX Item "--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%.
.IP "\fB\-I\fR\fIpath\fR / \fB\-\-include\fR=\fIpath\fR" 4
.IX Item "-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.
.Sp
If this option is repeated, the given paths will be searched in the
order given, followed by the standard paths.
.IP "\fB\-l\fR\fIlanguage\fR / \fB\-\-language\fR=\fIlanguage\fR" 4
.IX Item "-llanguage / --language=language"
Selects the language to use when interpreting user input. This should
correspond to the name of a compiler, which is an \s-1INTERCAL\s0 object
which was originally built by \fIiacc\fR. Only the expression and
statement parsers are used, so it is possible to test incomplete
compilers by loading them into \fIintercalc\fR even if they don't
work with \fIsick\fR. The default is obtained from the \fIsickrc\fR
option \fI.INTERCALC.LANGUAGE\fR.
.IP "\-\fB\-o\fR\fIoption\fR \-\fB\-\-option\fR=\fIoption\fR" 4
.IX Item "--ooption ---option=option"
Adds a language option. For example, \-\fB\-o\fR\fI3\fR selects base 3 calculation,
and \-\fB\-o\fR\fIwimp\fR selects wimp mode. If no options are provided, and the
default language was taken from the \fIsickrc\fR file, the default options
are taken from the \fIsickrc\fR file. Note that if an option or a language is
specified on the command line, the \fIsickrc\fR defaults are ignored.
.Sp
Unlike previous versions of \fIintercalc\fR, this version checks that the
options make sense in the context of the calculator; for example trying
to load a compiler as an option will cause an error, but a compiler
extension will be \s-1OK\s0.
.IP "\fB\-m\fR\fImode\fR / \fB\-\-mode\fR=\fImode\fR" 4
.IX Item "-mmode / --mode=mode"
Select operation mode. Currently, the only valid modes are \fIfull\fR,
\&\fIexpr\fR and \fIone\fR. See \*(L"Operating Modes\*(R". If this is not specified,
the default is taken from the \fIsickrc\fR option \fI..INTERCALC.MODE\fR.
.SS "Misc Options"
.IX Subsection "Misc Options"
.IP "\fB\-r\fR\fIname\fR / \fB\-\-rcfile\fR=\fIname\fR" 4
.IX Item "-rname / --rcfile=name"
Executes commands from file \fIname\fR before starting to accept input.
This option can be repeated, to execute more than one file. If it is
not specified, the standard library, the current directory, and the
current user's home directory are searched for files with name
\&\fIsystem.sickrc\fR or \fI.sickrc\fR, which are then executed. The order
for this search is: specified library (\fB\-\-include\fR), system library,
home directory, current directory. This is different from the search
order used when looking for objects or source code. If a directory
contains both \fI.sickrc\fR and \fIsystem.sickrc\fR, the \fIsystem.sickrc\fR
is executed first, followed by \fI.sickrc\fR. Also note that if the
current directory or the home directory appear in the search path
and contain one of these files, they will be executed twice.
.Sp
If filenames are explicitely specified, they must be fully qualified:
the search path is not used to find them.
.IP "\fB\-\-nouserrc\fR" 4
.IX Item "--nouserrc"
Prevents loading a user rcfile (.sickrc); also limits loading of
system.sickrc to the first one found. This option is normally only
used when testing the installation, to prevent interference from
previous versions of CLC-INTERCAL.
.SH "Operating Modes"
.IX Header "Operating Modes"
The calculator can operate in the following modes:
.IP "full Fully functional \s-1INTERCAL\s0 interpreter." 5
.IX Item "full Fully functional INTERCAL interpreter."
The calculator can parse and execute any statement or expression.
.Sp
Statements are compiled as a one-statement program, and executed;
any register value etc. will be preserved between statements, so
entering a list of statements is equivalent to running a program
in which all these statements are executed in sequence.
.Sp
It is important to note that some statements will not execute in
the normal manner. For example, a \s-1COME\s0 \s-1FROM\s0 will be parsed but
have no effect, unless it is something like:
.Sp
.Vb 1
\&    (1) PLEASE COME FROM (1)
.Ve
.Sp
which causes the calculator to hang. On the other hand, an \s-1ABSTAIN\s0 \s-1FROM\s0
or a \s-1REINSTATE\s0 will work as expected, as will \s-1CREATE\s0 and \s-1DESTROY\s0.
A \s-1GIVE\s0 \s-1UP\s0 does not cause the calculator to terminate. One final
difference is that comments are not parsed, and therefore you get a
\&\*(L"Syntax Error\*(R" from the calculator rather than a splat *000 from the
\&\s-1INTERCAL\s0 interpreter.
.Sp
For expressions, the calculator READs \s-1OUT\s0 the expression's result.
Any side effects will be remembered, so if the expression contains
overloads they will remain to haunt the calculator.
.IP "expr \s-1INTERCAL\s0 expression interpreter" 5
.IX Item "expr INTERCAL expression interpreter"
The calculator can only parse expressions or assignments. In either
case, the calculated values are \s-1READ\s0 \s-1OUT\s0; assignments will also
store the value to the destination, while expressions will then
discard the result.
.IP "oic The \fBO\fRne \fBI\fRnstruction \fBC\fRalculator." 5
.IX Item "oic The One Instruction Calculator."
This is something we've made
up one early morning while discussing desk calculators (as one does).
It is not \s-1INTERCAL\s0 at all, in fact it is inspired from the One Instruction
Set Computer.
.Sp
The calculator has a number of memories (default 100 \- these can be changed
by appending a number to the operating mode, for example \fIoic10\fR will
use a 10\-memory calculator). These memories are identified by the letter
\&\fBm\fR followed by a number; in the default 100\-memory version, the first two
digits after \fBm\fR are the memory, and any subsequent digit forms part
of the next operand. At the start, all memories are initialised to 0.
.Sp
Since there is only one operation, there is no need to specify it, so an
\&\*(L"operation\*(R" is a sequence of three operands and a result. The result must
be a memory, while each operand can be a number or a memory, with the
limitation that consecutive numbers are acceptable only if the parser can
determine where one ends and the next one starts. So for example \*(L"1\-0\*(R" is
two numeric operands, 1 and \-0 (aka 0); \*(L"1.2.3\*(R" is also two operands,
1.2 and 3; \*(L"12\*(R" is a single operand, even if you intended it to be two
operands, 1 and 2, and even if you put spaces: \*(L"1 2\*(R" is still interpreted
as the single operand 12.
.Sp
The operation performed is the difference between the first two operands,
divided by the third. For example, the three operations:
.Sp
.Vb 3
\&    7 m01 2 M01
\&    1 m02 1 m02
\&    m1 .5 m2 m03
.Ve
.Sp
will produce results m01=3.5 ((7\-0)/2); m02=1 ((1\-0)/1); m03=3 ((3.5\-.5)/1).
and will produce the following output if the calculator is running in batch
mode:
.Sp
.Vb 3
\&    m01                  3.5     (7 \- m01) / 2
\&    m02                    1     (1 \- m02) / 1
\&    m03                    3     (m01 \- .5) / m02
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The \s-1INTERCAL\s0 on-line documentation, by running \fBintercalc\fR and finding the
\&\*(L"help\*(R" menu or key (X and Curses) or backspark escape (Line and None).