c_cpp/etc/calc/help/define

   1 NAME
   2     define - command keyword to start a function definition
   3
   4 SYNTAX
   5     define fname([param_1 [= default_1], ...]) = [expr]
   6     define fname([param_1 [= default_1], ...]) { [statement_1 ... ] }
   7
   8 TYPES
   9     fname               identifier, not a builtin function name
  10     param_1, ...        identifiers, no two the same
  11     default_1, ...      expressions
  12     expr                expression
  13     statement_1, ...    statements
  14
  15 DESCRIPTION
  16     The intention of a function definition is that the identifier fname
  17     becomes the name of a function which may be called by an expression
  18     of the form  fname(arg_1, arg_2, ...), where arg_1, arg_2, ... are
  19     expressions (including possibly blanks, which are treated as
  20     null values).  Evaluation of the function begins with evaluation
  21     of arg_1, arg_2, ...; then, in increasing order of i, if arg_i is
  22     null-valued and  "= default_i" has been included in the definition,
  23     default_i is evaluated and its value becomes the value of arg_i.
  24     The instructions in expr or the listed statements are then executed
  25     with each occurrence of param_i replaced by the value obtained
  26     for arg_i.
  27
  28     In a call, arg_i may be preceded by a backquote (`)  to indicate that
  29     evaluation of arg_i is not to include a final evaluation of an lvalue.
  30     For example, suppose a function f and a global variable A have been
  31     defined by:
  32
  33         ; define f(x) = (x = 3);
  34         ; global mat A[3];
  35
  36     If g() is  a function that evaluates to 2:
  37
  38         ; f(A[g()]);
  39
  40     assigns the value of A[2] to the parameter x and then assigns the
  41     value 3 to x:
  42
  43         ; f(`A[g()]);
  44
  45     has essentially the effect of assigning A[2] as an lvalue to x and
  46     then assigning the value 3 to A[2].  (Very old versions of calc
  47     achieved the same result by using '&' as in  f(&A[g()]).)
  48
  49     The number of arguments arg_1, arg_2, ... in a call need not equal the
  50     number of parameters.  If there are fewer arguments than parameters,
  51     the "missing" values are assigned the null value.
  52
  53     In the definition of a function, the builtin function param(n)
  54     provides a way of referring to the parameters.  If n (which may
  55     result from evaluating an expreession) is zero, it returns the number
  56     of arguments in a call to the function, and if 1 <= n <= param(0),
  57     param(n) refers to the parameter with index n.
  58
  59     If no error occurs and no quit statement or abort statement is
  60     encountered during evaluation of the expression or the statements,
  61     the function call returns a value.  In the expression form, this is
  62     simply the value of the expression.
  63
  64     In the statement form, if a return statement is encountered,
  65     the "return" keyword is to be either immediately followed by an
  66     expression or by a statement terminator (semicolon or rightbrace);
  67     in the former case, the expression is evaluated, evaluation of
  68     the function ceases, and the value obtained for the expression is
  69     returned as the "value of the function";  in the no-expression case,
  70     evaluation ceases immediately and the null-value is returned.
  71
  72     In the expression form of definition, the end of the expression expr
  73     is to be indicated by either a semicolon or a newline not within
  74     a part enclosed by parentheses; the definition may extend over
  75     several physical lines by ending each line with a '\' character or by
  76     enclosing the expression in parentheses.  In interactive mode, that
  77     a definition has not been completed is indicated by the continuation
  78     prompt.   A ctrl-C interrupt at this stage will abort the definition.
  79
  80     If the expr is omitted from an expression definition, as in:
  81
  82         ; define h() = ;
  83
  84     any call to the function will evaluate the arguments and return the
  85     null value.
  86
  87     In the statement form, the definition ends when a matching right
  88     brace completes the "block" started by the initial left brace.
  89     Newlines within the block are treated as white space; statements
  90     within the block end with a ';' or a '}' matching an earlier '{'.
  91
  92     If a function with name fname had been defined earlier, the old
  93     definition has no effect on the new definition, but if the definition
  94     is completed successfully, the new definition replaces the old one;
  95     otherwise the old definition is retained.  The number of parameters
  96     and their names in the new definiton may be quite different from
  97     those in the old definition.
  98
  99     An attempt at a definition may fail because of scanerrors as the
 100     definition is compiled.  Common causes of these are: bad syntax,
 101     using identifiers as names of variables not yet defined.  It is
 102     not a fault to have in the definition a call to a function that has
 103     not yet been defined; it is sufficient that the function has been
 104     defined when a call is made to the function.
 105
 106     After fname has been defined, the definition may be removed by the command:
 107
 108         ; undefine fname
 109
 110     The definitions of all user-defined functions may be removed by:
 111
 112         ; undefine *
 113
 114     If bit 0 of config("resource_debug") is set and the define command is
 115     at interactive level, a message saying that fname has been defined
 116     or redefined is displayed.  The same message is displayed if bit 1
 117     of config("resource_debug") is set and the define command is read
 118     from a file.
 119
 120     The identifiers used for the parameters in a function definition do
 121     not form part of the completed definition.  For example,
 122
 123         ; define f(a,b) = a + b;
 124         ; define g(alpha, beta) = alpha + beta;
 125
 126     result in identical code for the functions f, g.
 127
 128     If config("trace") & 8 is nonzero, the opcodes of a newly defined
 129     function are displayed on completion of its definition, parameters
 130     being specified by names used in the definition.  For example:
 131
 132         ; config("trace", 8),
 133         ; define f(a,b) = a + b
 134         0: PARAMADDR a
 135         2: PARAMADDR b
 136         4: ADD
 137         5: RETURN
 138         f(a,b) defined
 139
 140     The opcodes may also be displayed later using the show opcodes command;
 141     parameters will be specified by indices instead of by names.  For example:
 142
 143         ; show opco f
 144         0: PARAMADDR 0
 145         2: PARAMADDR 1
 146         4: ADD
 147         5: RETURN
 148
 149     When a function is defined by the statement mode, the opcodes normally
 150     include DEBUG opcodes which specify statement boundaries at which
 151     SIGINT interruptions are likely to be least risky.  Inclusion of
 152     the DEBUG opcodes is disabled if config("trace") & 2 is nonzero.
 153     For details, see help interrupt.
 154
 155     While config("trace") & 1 is nonzero, the opcodes are displayed as
 156     they are being evaluated.  The current function is identified by its
 157     name, or "*" in the case of a command-line and "**" in the case of
 158     an eval(str) evaluation.
 159
 160     When a function is called, argument values may be of any type for
 161     which the operations and any functions used within the body of the
 162     definition can be executed.  For example, whatever the intention at
 163     the time they were defined, the functions f1(), f2() defined above
 164     may be called with integer, fractional, or complex-number values, or
 165     with both arguments strings, or under some compatibility conditions,
 166     matrices or objects.
 167
 168 EXAMPLE
 169     ; define f(a,b) = 2*a + b;
 170     ; define g(alpha, beta)
 171     ;; {
 172     ;;     local a, pi2;
 173     ;;
 174     ;;     pi2 = 2 * pi();
 175     ;;     a = sin(alpha % pi2);
 176     ;;     if (a > 0.0) {
 177     ;;         return a*beta;
 178     ;;     }
 179     ;;     if (beta > 0.0) {
 180     ;;         a *= cos(-beta % pi2);
 181     ;;     }
 182     ;;     return a;
 183     ;; }
 184
 185 LIMITS
 186     The number of arguments in a function-call cannot exceed 1024.
 187
 188 LIBRARY
 189     none
 190
 191 SEE ALSO
 192     param, variable, undefine, show
 193
 194 ## Copyright (C) 2000-2006  David I. Bell, Landon Curt Noll and Ernest Bowen
 195 ##
 196 ## Calc is open software; you can redistribute it and/or modify it under
 197 ## the terms of the version 2.1 of the GNU Lesser General Public License
 198 ## as published by the Free Software Foundation.
 199 ##
 200 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 201 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 202 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 203 ## Public License for more details.
 204 ##
 205 ## A copy of version 2.1 of the GNU Lesser General Public License is
 206 ## distributed with calc under the filename COPYING-LGPL.  You should have
 207 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 208 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 209 ##
 210 ## @(#) $Revision: 30.1 $
 211 ## @(#) $Id: define,v 30.1 2007/03/16 11:10:42 chongo Exp $
 212 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/define,v $
 213 ##
 214 ##
 215 ## Under source code control:   1991/07/21 04:37:18
 216 ## File existed as early as:    1991
 217 ##
 218 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 219 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/