help/COMMAND

   1 Command sequence
   2
   3     This is a sequence of any the following command formats, where
   4     each command is terminated by a semicolon or newline.  Long command
   5     lines can be extended by using a back-slash followed by a newline
   6     character.  When this is done, the prompt shows a double angle
   7     bracket to indicate that the line is still in progress.  Certain
   8     cases will automatically prompt for more input in a similar manner,
   9     even without the back-slash.  The most common case for this is when
  10     a function is being defined, but is not yet completed.
  11
  12     Each command sequence terminates only on an end of file.  In
  13     addition, commands can consist of expression sequences, which are
  14     described in the next section.
  15
  16
  17     define a function
  18     -----------------
  19     define function(params) { body }
  20     define function(params) = expression
  21             This first form defines a full function which can consist
  22             of declarations followed by many statements which implement
  23             the function.
  24
  25             The second form defines a simple function which calculates
  26             the specified expression value from the specified parameters.
  27             The expression cannot be a statement.  However, the comma
  28             and question mark operators can be useful.  Examples of
  29             simple functions are:
  30
  31                     define sumcubes(a, b) = a^3 + b^3
  32                     define pimod(a) = a % pi()
  33                     define printnum(a, n, p)
  34                     {
  35                         if (p == 0) {
  36                             print a: "^": n, "=", a^n;
  37                         } else {
  38                             print a: "^": n, "mod", p, "=", pmod(a,n,p);
  39                         }
  40                     }
  41
  42
  43     read calc commands
  44     ------------------
  45     read filename
  46     read -once filename
  47             This reads definitions from the specified calc resource filename.
  48
  49             The name can be quoted if desired.  The calculator uses the
  50             CALCPATH environment variable to search through the specified
  51             directories for the filename, similarly to the use of the
  52             PATH environment variable.  If CALCPATH is not defined,
  53             then a default path which is usually ":/usr/local/lib/calc"
  54             is used.
  55
  56             The ".cal" extension is defaulted for input files, so that
  57             if "filename" is not found, then "filename.cal" is then
  58             searched for.  The contents of the filename are command
  59             sequences which can consist of expressions to evaluate or
  60             functions to define, just like at the top level command level.
  61
  62             When -once is given, the read command acts like the regular
  63             read expect that it will ignore filename if is has been
  64             previously read.
  65
  66             The read -once form is particularly useful in a resource
  67             file that needs to read a 2nd resource file.  By using the
  68             READ -once command, one will not reread that 2nd resource
  69             file, nor will once risk entering into a infinite READ loop
  70             (where that 2nd resource file directly or indirectly does
  71             a READ of the first resource file).
  72
  73             If the -m mode disallows opening of files for reading,
  74             this command will be disabled.
  75
  76
  77     write calc commands
  78     -------------------
  79     write filename
  80             This writes the values of all global variables to the
  81             specified filename, in such a way that the file can be
  82             later read in order to recreate the variable values.
  83             For speed reasons, values are written as hex fractions.
  84             This command currently only saves simple types, so that
  85             matrices, lists, and objects are not saved.  Function
  86             definitions are also not saved.
  87
  88             If the -m mode disallows opening of files for writing,
  89             this command will be disabled.
  90
  91
  92     quit or exit
  93     ------------
  94     quit
  95     quit string
  96     exit
  97     exit string
  98             The action of these commands depends on where they are used.
  99             At the interactive level, they will cause calc it edit.
 100             This is the normal way to leave the calculator.  In any
 101             other use, they will stop the current calculation as if
 102             an error had occurred.
 103
 104             If a string is given, then the string is printed as the reason
 105             for quitting, otherwise a general quit message is printed.
 106             The routine name and line number which executed the quit is
 107             also printed in either case.
 108
 109             Exit is an alias for quit.
 110
 111             Quit is useful when a routine detects invalid arguments,
 112             in order to stop a calculation cleanly.  For example,
 113             for a square root routine, an error can be given if the
 114             supplied parameter was a negative number, as in:
 115
 116                     define mysqrt(n)
 117                     {
 118                         if (! isnum(n))
 119                             quit "non-numeric argument";
 120                         if (n < 0)
 121                             quit "Negative argument";
 122                         return sqrt(n);
 123                     }
 124
 125             See 'more information about abort and quit' below for
 126             more information.
 127
 128
 129
 130     abort
 131     -----
 132     abort
 133     abort string
 134             This command behaves like QUIT except that it will attempt
 135             to return to the interactive level if permitted, otherwise
 136             calc exit.
 137
 138             See 'more information about abort and quit' below for
 139             more information.
 140
 141
 142     change current directory
 143     ------------------------
 144     cd
 145     cd dir
 146             Change the current directory to 'dir'.  If 'dir' is ommitted,
 147             change the current directory to the home directory, if $HOME
 148             is set in the environment.
 149
 150
 151     show information
 152     ----------------
 153     show item
 154             This command displays some information where 'item' is
 155             one of the following:
 156
 157                     blocks              unfreed named blocks
 158                     builtin             built in functions
 159                     config              config parameters and values
 160                     constants           cache of numeric constants
 161                     custom              custom functions if calc -C was used
 162                     errors              new error-values created
 163                     files               open files, file position and sizes
 164                     function            user-defined functions
 165                     globaltypes         global variables
 166                     objfunctions        possible object functions
 167                     objtypes            defined objects
 168                     opcodes func        internal opcodes for function `func'
 169                     sizes               size in octets of calc value types
 170                     realglobals         numeric global variables
 171                     statics             unscoped static variables
 172                     numbers             calc number cache
 173                     redcdata            REDC data defined
 174                     strings             calc string cache
 175                     literals            calc literal cache
 176
 177             Only the first 4 characters of item are examined, so:
 178
 179                     show globals
 180                     show global
 181                     show glob
 182
 183             do the same thing.
 184
 185
 186     calc help
 187     ---------
 188     help
 189     help name
 190             This displays a help related to 'name' or general
 191             help of none is given.
 192
 193
 194     =-=
 195
 196
 197     more information about abort and quit
 198     =====================================
 199
 200     Consider the following calc file called myfile.cal:
 201
 202         print "start of myfile.cal";
 203         define q() {quit "quit from q()"; print "end of q()"}
 204         define a() {abort "abort from a()"}
 205         x = 3;
 206         {print "start #1"; if (x > 1) q()} print "after #1";
 207         {print "start #2"; if (x > 1) a()} print "after #2";
 208         {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
 209         print "end of myfile.cal";
 210
 211     The command:
 212
 213         calc read myfile
 214
 215     will produce:
 216
 217         q() defined
 218         a() defined
 219         start statment #1
 220         quit from q()
 221         after statment #1
 222         start statment #2
 223         abort from a()
 224
 225     The QUIT within the q() function prevented the ``end of q()''
 226     statement from being evaluated.  This QUIT command caused
 227     control to be returned to just after the place where q()
 228     was called.
 229
 230     Notice that unlike QUIT, the ABORT inside function a() halts
 231     the processing of statements from the input source (myfile.cal).
 232     Because calc was not interactive, ABORT causes calc to exit.
 233
 234     The command:
 235
 236         calc -i read myfile
 237
 238     will produce:
 239
 240         q() defined
 241         a() defined
 242         start statment #1
 243         quit from q()
 244         after statment #1
 245         start statment #2
 246         abort from a()
 247         >               <==== calc interactive prompt
 248
 249     because the '-i' calc causes ABORT to drop into an
 250     interactive prompt.  However typing a QUIT or ABORT
 251     at the interactive prompt level will always calc to exit,
 252     even when calc is invoked with '-i'.
 253
 254     Also observe that both of these commands:
 255
 256         cat myfile.cal | calc
 257         cat myfile.cal | calc -i
 258
 259     will produce:
 260
 261         q() defined
 262         a() defined
 263         start statment #1
 264         quit from q()
 265         after statment #1
 266         start statment #2
 267         abort from a()
 268
 269     The ABORT inside function a() halts the processing of statements
 270     from the input source (standard input).  Because standard input
 271     is not a terminal, using '-i' does not force it to drop into
 272     an interactive prompt.
 273
 274     If one were to type in the contents of myfile.cal interactively,
 275     calc will produce:
 276
 277         > print "start of myfile.cal";
 278         start of myfile.cal
 279         > define q() {quit "quit from q()"; print "end of q()"}
 280         q() defined
 281         > define a() {abort "abort from a()"}
 282         a() defined
 283         > x = 3;
 284         > {print "start #1"; if (x > 1) q()} print "after #1";
 285         start statment #1
 286         quit from q()
 287         after statment #1
 288         > {print "start #2"; if (x > 1) a()} print "after #2";
 289         start statment #2
 290         abort from a()
 291         > {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
 292         start #3
 293         quit from 3rd statement
 294
 295     The ABORT from within the a() function returned control to
 296     the interactive level.
 297
 298     The QUIT (after the if (x > 1) ...) will cause calc to exit
 299     because it was given at the interactive prompt level.
 300
 301
 302     =-=
 303
 304
 305     Also see the help topic:
 306
 307             statement       flow control and declaration statements
 308             usage           how to invoke the calc command and calc -options
 309