c_cpp/etc/calc/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
  22         This first form defines a full function which can consist
  23         of declarations followed by many statements which implement
  24         the function.
  25
  26         The second form defines a simple function which calculates
  27         the specified expression value from the specified parameters.
  28         The expression cannot be a statement.  However, the comma
  29         and question mark operators can be useful.      Examples of
  30         simple functions are:
  31
  32                 define sumcubes(a, b) = a^3 + b^3
  33                 define pimod(a) = a % pi()
  34                 define printnum(a, n, p)
  35                 {
  36                     if (p == 0) {
  37                         print a: "^": n, "=", a^n;
  38                     } else {
  39                         print a: "^": n, "mod", p, "=", pmod(a,n,p);
  40                     }
  41                 }
  42
  43
  44     read calc commands
  45     ------------------
  46     read $var
  47     read -once $var
  48     read filename
  49     read -once filename
  50
  51         This reads definitions from the specified calc resource filename.
  52
  53         In the 1st and 2nd forms, if var is a global variable string
  54         value, then the value of that variable is used as a filename.
  55
  56         The following is equivalent to read lucas.cal or read "lucas.cal":
  57
  58             global var = "lucas.cal";
  59             read $var;
  60
  61         In the 3rd or 4th forms, the filename argument is treated
  62         as a literal string, not a variable.  In these forms, the
  63         name can be quoted if desired.
  64
  65         The calculator uses the CALCPATH environment variable to
  66         search through the specified directories for the filename,
  67         similarly to the use of the PATH environment variable.
  68         If CALCPATH is not defined, then a default path which is
  69         usually ":/usr/local/lib/calc" is used.
  70
  71         The ".cal" extension is defaulted for input files, so that
  72         if "filename" is not found, then "filename.cal" is then
  73         searched for.  The contents of the filename are command
  74         sequences which can consist of expressions to evaluate or
  75         functions to define, just like at the top level command level.
  76
  77         When -once is given, the read command acts like the regular
  78         read expect that it will ignore filename if is has been
  79         previously read.
  80
  81         The read -once form is particularly useful in a resource
  82         file that needs to read a 2nd resource file.  By using the
  83         READ -once command, one will not reread that 2nd resource
  84         file, nor will once risk entering into a infinite READ loop
  85         (where that 2nd resource file directly or indirectly does
  86         a READ of the first resource file).
  87
  88         If the -m mode disallows opening of files for reading,
  89         this command will be disabled.
  90
  91
  92     write calc commands
  93     -------------------
  94     write $var
  95     write filename
  96
  97         This writes the values of all global variables to the
  98         specified filename, in such a way that the file can be
  99         later read in order to recreate the variable values.
 100         For speed reasons, values are written as hex fractions.
 101         This command currently only saves simple types, so that
 102         matrices, lists, and objects are not saved.      Function
 103         definitions are also not saved.
 104
 105         In the 1st form, if var is a global variable string
 106         value, then the value of that variable is used as a filename.
 107
 108         The following is equivalent to write dump.out or
 109         write "dump.out":
 110
 111             global var = "dump.out";
 112             write $var;
 113
 114         In the 2nd form, the filename argument is treated as a literal
 115         string, not a variable.  In this form, the name can be quoted
 116         if desired.
 117
 118         If the -m mode disallows opening of files for writing,
 119         this command will be disabled.
 120
 121
 122     quit or exit
 123     ------------
 124     quit
 125     quit string
 126     exit
 127     exit string
 128
 129         The action of these commands depends on where they are used.
 130         At the interactive level, they will cause calc it edit.
 131         This is the normal way to leave the calculator.  In any
 132         other use, they will stop the current calculation as if
 133         an error had occurred.
 134
 135         If a string is given, then the string is printed as the reason
 136         for quitting, otherwise a general quit message is printed.
 137         The routine name and line number which executed the quit is
 138         also printed in either case.
 139
 140         Exit is an alias for quit.
 141
 142         Quit is useful when a routine detects invalid arguments,
 143         in order to stop a calculation cleanly.  For example,
 144         for a square root routine, an error can be given if the
 145         supplied parameter was a negative number, as in:
 146
 147                 define mysqrt(n)
 148                 {
 149                     if (! isnum(n))
 150                         quit "non-numeric argument";
 151                     if (n < 0)
 152                         quit "Negative argument";
 153                     return sqrt(n);
 154                 }
 155
 156         See 'more information about abort and quit' below for
 157         more information.
 158
 159
 160     abort
 161     -----
 162     abort
 163     abort string
 164
 165         This command behaves like QUIT except that it will attempt
 166         to return to the interactive level if permitted, otherwise
 167         calc exit.
 168
 169         See 'more information about abort and quit' below for
 170         more information.
 171
 172
 173     change current directory
 174     ------------------------
 175     cd
 176     cd dir
 177
 178         Change the current directory to 'dir'.  If 'dir' is ommitted,
 179         change the current directory to the home directory, if $HOME
 180         is set in the environment.
 181
 182
 183     show information
 184     ----------------
 185     show item
 186
 187         This command displays some information where 'item' is
 188         one of the following:
 189
 190                 blocks          unfreed named blocks
 191                 builtin         built in functions
 192                 config          config parameters and values
 193                 constants               cache of numeric constants
 194                 custom          custom functions if calc -C was used
 195                 errors          new error-values created
 196                 files           open files, file position and sizes
 197                 function                user-defined functions
 198                 globaltypes             global variables
 199                 objfunctions    possible object functions
 200                 objtypes                defined objects
 201                 opcodes func    internal opcodes for function `func'
 202                 sizes           size in octets of calc value types
 203                 realglobals             numeric global variables
 204                 statics         unscoped static variables
 205                 numbers         calc number cache
 206                 redcdata                REDC data defined
 207                 strings         calc string cache
 208                 literals                calc literal cache
 209
 210         Only the first 4 characters of item are examined, so:
 211
 212                 show globals
 213                 show global
 214                 show glob
 215
 216         do the same thing.
 217
 218
 219     calc help
 220     ---------
 221     help $var
 222     help name
 223
 224         This displays a help related to 'name' or general
 225         help of none is given.
 226
 227         In the 1st form, if var is a global variable string
 228         value, then the value of that variable is used as a name.
 229
 230         The following is equivalent to help command or help "command":
 231
 232             global var = "command";
 233             help $var;
 234
 235         In the 2nd form, the filename argument is treated as a literal
 236         string, not a variable.  In this form, the name can be quoted
 237         if desired.
 238
 239
 240     =-=
 241
 242     more information about abort and quit
 243     =====================================
 244
 245     Consider the following calc file called myfile.cal:
 246
 247         print "start of myfile.cal";
 248         define q() {quit "quit from q()"; print "end of q()"}
 249         define a() {abort "abort from a()"}
 250         x = 3;
 251         {print "start #1"; if (x > 1) q()} print "after #1";
 252         {print "start #2"; if (x > 1) a()} print "after #2";
 253         {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
 254         print "end of myfile.cal";
 255
 256     The command:
 257
 258         calc read myfile
 259
 260     will produce:
 261
 262         q() defined
 263         a() defined
 264         start statment #1
 265         quit from q()
 266         after statment #1
 267         start statment #2
 268         abort from a()
 269
 270     The QUIT within the q() function prevented the ``end of q()''
 271     statement from being evaluated.  This QUIT command caused
 272     control to be returned to just after the place where q()
 273     was called.
 274
 275     Notice that unlike QUIT, the ABORT inside function a() halts
 276     the processing of statements from the input source (myfile.cal).
 277     Because calc was not interactive, ABORT causes calc to exit.
 278
 279     The command:
 280
 281         calc -i read myfile
 282
 283     will produce:
 284
 285         q() defined
 286         a() defined
 287         start statment #1
 288         quit from q()
 289         after statment #1
 290         start statment #2
 291         abort from a()
 292         ;               <==== calc interactive prompt
 293
 294     because the '-i' calc causes ABORT to drop into an
 295     interactive prompt.  However typing a QUIT or ABORT
 296     at the interactive prompt level will always calc to exit,
 297     even when calc is invoked with '-i'.
 298
 299     Also observe that both of these commands:
 300
 301         cat myfile.cal | calc
 302         cat myfile.cal | calc -i
 303
 304     will produce:
 305
 306         q() defined
 307         a() defined
 308         start statment #1
 309         quit from q()
 310         after statment #1
 311         start statment #2
 312         abort from a()
 313
 314     The ABORT inside function a() halts the processing of statements
 315     from the input source (standard input).  Because standard input
 316     is not a terminal, using '-i' does not force it to drop into
 317     an interactive prompt.
 318
 319     If one were to type in the contents of myfile.cal interactively,
 320     calc will produce:
 321
 322         ; print "start of myfile.cal";
 323         start of myfile.cal
 324         ; define q() {quit "quit from q()"; print "end of q()"}
 325         q() defined
 326         ; define a() {abort "abort from a()"}
 327         a() defined
 328         ; x = 3;
 329         ; {print "start #1"; if (x > 1) q()} print "after #1";
 330         start statment #1
 331         quit from q()
 332         after statment #1
 333         ; {print "start #2"; if (x > 1) a()} print "after #2";
 334         start statment #2
 335         abort from a()
 336         ; {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
 337         start #3
 338         quit from 3rd statement
 339
 340     The ABORT from within the a() function returned control to
 341     the interactive level.
 342
 343     The QUIT (after the if (x > 1) ...) will cause calc to exit
 344     because it was given at the interactive prompt level.
 345
 346     =-=
 347
 348     Also see the help topic:
 349
 350         statement   flow control and declaration statements
 351         usage       how to invoke the calc command and calc -options
 352
 353 ## Copyright (C) 1999-2006  Landon Curt Noll
 354 ##
 355 ## Calc is open software; you can redistribute it and/or modify it under
 356 ## the terms of the version 2.1 of the GNU Lesser General Public License
 357 ## as published by the Free Software Foundation.
 358 ##
 359 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 360 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 361 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 362 ## Public License for more details.
 363 ##
 364 ## A copy of version 2.1 of the GNU Lesser General Public License is
 365 ## distributed with calc under the filename COPYING-LGPL.  You should have
 366 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 367 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 368 ##
 369 ## @(#) $Revision: 30.1 $
 370 ## @(#) $Id: command,v 30.1 2007/03/16 11:10:42 chongo Exp $
 371 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/command,v $
 372 ##
 373 ## Under source code control:   1991/07/21 04:37:17
 374 ## File existed as early as:    1991
 375 ##
 376 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 377 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/