Provided by: clc-intercal_1.0~4pre1.-94.-2-3_all bug

NAME

       intercalc - CLC-INTERCAL desk calculator

SYNOPSIS

       intercalc [options]

DESCRIPTION

       intercalc is a simple desk calculator, allowing the user to enter INTERCAL 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.

       The desk calculator accepts several options, some of which are documented here.

   User Interface Options
       -X / --graphic
           Enters X-based graphical user interface. Requires Perl-GTK. This is the default if
           Perl-GTK is installed, the environment variable $DISPLAY is set and the opening of the
           X display succeeds.

       -c / --curses
           Enters full screen, curses-based interface. This is the default if the X based
           interface cannot be started, the environment variable $TERM is set and the terminal
           name is known.

       --line
           Enters the line-mode user interface. This is the default if the X based and the curses
           based interfaces do not work.

           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
           GIVE UP (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.

           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).

       --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.

       -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,
           intercalc will work in batch mode. In addition, an empty string will reinstate the
           default behaviour.

   Source language and compilation options
       --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%.

       -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.

       -llanguage / --language=language
           Selects the language to use when interpreting user input. This should correspond to
           the name of a compiler, which is an INTERCAL object which was originally built by
           iacc. Only the expression and statement parsers are used, so it is possible to test
           incomplete compilers by loading them into intercalc even if they don't work with sick.
           The default is obtained from the sickrc option .INTERCALC.LANGUAGE.

       --ooption ---option=option
           Adds a language option. For example, --o3 selects base 3 calculation, and --owimp
           selects wimp mode. If no options are provided, and the default language was taken from
           the sickrc file, the default options are taken from the sickrc file. Note that if an
           option or a language is specified on the command line, the sickrc defaults are
           ignored.

           Unlike previous versions of intercalc, 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 OK.

       -mmode / --mode=mode
           Select operation mode. Currently, the only valid modes are full, expr and one. See
           "Operating Modes". If this is not specified, the default is taken from the sickrc
           option ..INTERCALC.MODE.

   Misc Options
       -rname / --rcfile=name
           Executes commands from file name 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 system.sickrc or .sickrc, which are then executed. The order for this search
           is: specified library (--include), 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 .sickrc and system.sickrc, the system.sickrc is executed
           first, followed by .sickrc. 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.

           If filenames are explicitely specified, they must be fully qualified: the search path
           is not used to find them.

       --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.

Operating Modes

       The calculator can operate in the following modes:

       full Fully functional INTERCAL interpreter.
            The calculator can parse and execute any statement or expression.

            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.

            It is important to note that some statements will not execute in the normal manner.
            For example, a COME FROM will be parsed but have no effect, unless it is something
            like:

                (1) PLEASE COME FROM (1)

            which causes the calculator to hang. On the other hand, an ABSTAIN FROM or a
            REINSTATE will work as expected, as will CREATE and DESTROY.  A GIVE UP does not
            cause the calculator to terminate. One final difference is that comments are not
            parsed, and therefore you get a "Syntax Error" from the calculator rather than a
            splat *000 from the INTERCAL interpreter.

            For expressions, the calculator READs OUT the expression's result.  Any side effects
            will be remembered, so if the expression contains overloads they will remain to haunt
            the calculator.

       expr INTERCAL expression interpreter
            The calculator can only parse expressions or assignments. In either case, the
            calculated values are READ OUT; assignments will also store the value to the
            destination, while expressions will then discard the result.

       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 INTERCAL at all, in fact it is inspired from the One
            Instruction Set Computer.

            The calculator has a number of memories (default 100 - these can be changed by
            appending a number to the operating mode, for example oic10 will use a 10-memory
            calculator). These memories are identified by the letter m followed by a number; in
            the default 100-memory version, the first two digits after m are the memory, and any
            subsequent digit forms part of the next operand. At the start, all memories are
            initialised to 0.

            Since there is only one operation, there is no need to specify it, so an "operation"
            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 "1-0" is two numeric operands, 1 and -0 (aka 0); "1.2.3" is also two
            operands, 1.2 and 3; "12" is a single operand, even if you intended it to be two
            operands, 1 and 2, and even if you put spaces: "1 2" is still interpreted as the
            single operand 12.

            The operation performed is the difference between the first two operands, divided by
            the third. For example, the three operations:

                7 m01 2 M01
                1 m02 1 m02
                m1 .5 m2 m03

            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:

                m01                  3.5     (7 - m01) / 2
                m02                    1     (1 - m02) / 1
                m03                    3     (m01 - .5) / m02

SEE ALSO

       The INTERCAL on-line documentation, by running intercalc and finding the "help" menu or
       key (X and Curses) or backspark escape (Line and None).