command

Command sequence

    This is a sequence of any the following command formats, where
    each command is terminated by a semicolon or newline.  Long command
    lines can be extended by using a back-slash followed by a newline
    character.  When this is done, the prompt shows a double angle
    bracket to indicate that the line is still in progress.  Certain
    cases will automatically prompt for more input in a similar manner,
    even without the back-slash.  The most common case for this is when
    a function is being defined, but is not yet completed.

    Each command sequence terminates only on an end of file.  In
    addition, commands can consist of expression sequences, which are
    described in the next section.


    define a function
    -----------------
    define function(params) { body }
    define function(params) = expression

        This first form defines a full function which can consist
        of declarations followed by many statements which implement
        the function.

        The second form defines a simple function which calculates
        the specified expression value from the specified parameters.
        The expression cannot be a statement.  However, the comma
        and question mark operators can be useful.      Examples of
        simple functions are:

                define sumcubes(a, b) = a^3 + b^3
                define pimod(a) = a % pi()
                define printnum(a, n, p)
                {
                    if (p == 0) {
                        print a: "^": n, "=", a^n;
                    } else {
                        print a: "^": n, "mod", p, "=", pmod(a,n,p);
                    }
                }


    read calc commands
    ------------------
    read $var
    read -once $var
    read filename
    read -once filename

        This reads definitions from the specified calc resource filename.

        In the 1st and 2nd forms, if var is a global variable string
        value, then the value of that variable is used as a filename.

        The following is equivalent to read lucas.cal or read "lucas.cal":

            global var = "lucas.cal";
            read $var;

        In the 3rd or 4th forms, the filename argument is treated
        as a literal string, not a variable.  In these forms, the
        name can be quoted if desired.

        The calculator uses the CALCPATH environment variable to
        search through the specified directories for the filename,
        similarly to the use of the PATH environment variable.
        If CALCPATH is not defined, then a default path which is
        usually ":/usr/local/lib/calc" is used.

        The ".cal" extension is defaulted for input files, so that
        if "filename" is not found, then "filename.cal" is then
        searched for.  The contents of the filename are command
        sequences which can consist of expressions to evaluate or
        functions to define, just like at the top level command level.

        When -once is given, the read command acts like the regular
        read expect that it will ignore filename if is has been
        previously read.

        The read -once form is particularly useful in a resource
        file that needs to read a 2nd resource file.  By using the
        READ -once command, one will not reread that 2nd resource
        file, nor will once risk entering into a infinite READ loop
        (where that 2nd resource file directly or indirectly does
        a READ of the first resource file).

        If the -m mode disallows opening of files for reading,
        this command will be disabled.

        To read a calc resource file without printing various
        messages about defined functions, the "resource_debug"
        config should be set to zero.  For example:

            read lucas;

        will, by default, print messages such as:

            lucas(h,n) defined
            gen_u2(h,n,v1) defined
            gen_u0(h,n,v1) defined
            rodseth_xhn(x,h,n) defined
            gen_v1(h,n) defined
            ldebug(funct,str) defined
            legacy_gen_v1(h,n) defined

        When "resource_debug" is zero, such messages are silenced.

            config("resource_debug", 0),;
            read lucas;

        To silence such messages on the calc command line, try:

            calc -p -D :0 'read -once lucas; lucas(1, 23209);'


    write calc commands
    -------------------
    write $var
    write filename

        This writes the values of all global variables to the
        specified filename, in such a way that the file can be
        later read in order to recreate the variable values.
        For speed reasons, values are written as hex fractions.
        This command currently only saves simple types, so that
        matrices, lists, and objects are not saved.      Function
        definitions are also not saved.

        In the 1st form, if var is a global variable string
        value, then the value of that variable is used as a filename.

        The following is equivalent to write dump.out or
        write "dump.out":

            global var = "dump.out";
            write $var;

        In the 2nd form, the filename argument is treated as a literal
        string, not a variable.  In this form, the name can be quoted
        if desired.

        If the -m mode disallows opening of files for writing,
        this command will be disabled.


    quit or exit
    ------------
    quit
    quit string
    exit
    exit string

        The action of these commands depends on where they are used.
        At the interactive level, they will cause calc to exit.
        This is the normal way to leave the calculator.  In any
        other use, they will stop the current calculation as if
        an error had occurred.

        If a string is given, then the string is printed as the reason
        for quitting, otherwise a general quit message is printed.
        The routine name and line number which executed the quit is
        also printed in either case.

        Exit is an alias for quit.

        Quit is useful when a routine detects invalid arguments,
        in order to stop a calculation cleanly.  For example,
        for a square root routine, an error can be given if the
        supplied parameter was a negative number, as in:

                define mysqrt(n)
                {
                    if (! isnum(n))
                        quit "non-numeric argument";
                    if (n < 0)
                        quit "Negative argument";
                    return sqrt(n);
                }

        See 'more information about abort and quit' below for
        more information.


    abort
    -----
    abort
    abort string

        This command behaves like QUIT except that it will attempt
        to return to the interactive level if permitted, otherwise
        calc exit.

        See 'more information about abort and quit' below for
        more information.


    change current directory
    ------------------------
    cd
    cd dir

        Change the current directory to 'dir'.  If 'dir' is omitted,
        change the current directory to the home directory, if $HOME
        is set in the environment.


    show information
    ----------------
    show item

        This command displays some information where 'item' is
        one of the following:

                blocks          unfreed named blocks
                builtin         built in functions
                config          config parameters and values
                constants       cache of numeric constants
                custom          custom functions if calc -C was used
                errors          new error-values created
                files           open files, file position and sizes
                function        user-defined functions
                globaltypes     global variables
                objfunctions    possible object functions
                objtypes        defined objects
                opcodes         internal opcodes for function `func'
                sizes           size in octets of calc value types
                realglobals     numeric global variables
                statics         un-scoped static variables
                numbers         calc number cache
                redcdata        REDC data defined
                strings         calc string cache
                literals        calc literal cache

        Only the first 4 characters of item are examined, so:

                show globals
                show global
                show glob

        do the same thing.


    calc help
    ---------
    help $var
    help name

        This displays a help related to 'name' or general
        help of none is given.

        In the 1st form, if var is a global variable string
        value, then the value of that variable is used as a name.

        The following is equivalent to help command or help "command":

            global var = "command";
            help $var;

        In the 2nd form, the filename argument is treated as a literal
        string, not a variable.  In this form, the name can be quoted
        if desired.


    =-=

    more information about abort and quit
    =====================================

    Consider the following calc file called myfile.cal:

        print "start of myfile.cal";
        define q() {quit "quit from q()"; print "end of q()"}
        define a() {abort "abort from a()"}
        x = 3;
        {print "start #1"; if (x > 1) q()} print "after #1";
        {print "start #2"; if (x > 1) a()} print "after #2";
        {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
        print "end of myfile.cal";

    The command:

        calc read myfile

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()

    The QUIT within the q() function prevented the ``end of q()''
    statement from being evaluated.  This QUIT command caused
    control to be returned to just after the place where q()
    was called.

    Notice that unlike QUIT, the ABORT inside function a() halts
    the processing of statements from the input source (myfile.cal).
    Because calc was not interactive, ABORT causes calc to exit.

    The command:

        calc -i read myfile

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()
        ;               <==== calc interactive prompt

    because the '-i' calc causes ABORT to drop into an
    interactive prompt.  However typing a QUIT or ABORT
    at the interactive prompt level will always calc to exit,
    even when calc is invoked with '-i'.

    Also observe that both of these commands:

        cat myfile.cal | calc
        cat myfile.cal | calc -i

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()

    The ABORT inside function a() halts the processing of statements
    from the input source (standard input).  Because standard input
    is not a terminal, using '-i' does not force it to drop into
    an interactive prompt.

    If one were to type in the contents of myfile.cal interactively,
    calc will produce:

        ; print "start of myfile.cal";
        start of myfile.cal
        ; define q() {quit "quit from q()"; print "end of q()"}
        q() defined
        ; define a() {abort "abort from a()"}
        a() defined
        ; x = 3;
        ; {print "start #1"; if (x > 1) q()} print "after #1";
        start statement #1
        quit from q()
        after statement #1
        ; {print "start #2"; if (x > 1) a()} print "after #2";
        start statement #2
        abort from a()
        ; {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
        start #3
        quit from 3rd statement

    The ABORT from within the a() function returned control to
    the interactive level.

    The QUIT (after the if (x > 1) ...) will cause calc to exit
    because it was given at the interactive prompt level.

    =-=

    Also see the help topic:

        statement   flow control and declaration statements
        usage       how to invoke the calc command and calc -options

## Copyright (C) 1999-2006,2018,2021  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:   1991/07/21 04:37:17
## File existed as early as:    1991
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/