View source for User-Defined Functions/Operators

<ul>
  <li><p>'''User-defined Functions and Operators'''</p>
    <ul>
      <li><p>Within a user-defined function/operator header, the '''left''' and '''right''' arguments may consist of one or more names each separated by one or more blanks and enclosed in parentheses.  In this context, the caller of the function/operator must pass a scalar (which is extended to each name) or an appropriate length vector argument.  Upon invocation of the function/operator, these values are assigned one item per name.</p>

<p>For example, a function whose header looks like</p>

<p><apll>{del} Z←FOO (R<sub>1</sub> R<sub>2</sub>)</apll></p>

<p>can be called with a two-element vector (or a scalar which is extended to a two-element vector) right argument only.  If the right argument is of rank greater than one, a <apll>RANK ERROR</apll> is signaled.  If the right argument is not of the proper length, a <apll>LENGTH ERROR</apll> is signaled.</p>

<p>Note that if only one name appears within parentheses in the left or right argument, the caller must supply a value for this argument which is a scalar or one-element vector.</p></li>

      <li><p>Within a user-defined function/operator header, the '''result''' may consist of two or more names each separated by one or more blanks and enclosed in parentheses.  In this context, when the function exits, the individual names must all have a value (else a <apll>VALUE ERROR</apll> is signaled), the names are joined together in a strand, and the resulting vector is returned as the result.  If the header contains only one name for the result, it may '''not''' be enclosed in parentheses.</p></li>

      <li><p>Thanks to Dyalog APL for proposing and implementing the above features.</p></li>

      <li><p id="Shy">Within a user-defined function/operator header, the '''result''' may be marked as '''shy''' or non-displayable by enclosing it in braces, as in <apll>∇ {Z}←FOO R</apll>. If the result part of the header consists of multiple names, either<br />
<apll>∇ {Z<sub>1</sub> Z<sub>2</sub>}←FOO R</apll>,<br />
<apll>∇ ({Z<sub>1</sub> Z<sub>2</sub>})←FOO R</apll>, or<br />
<apll>∇ {(Z<sub>1</sub> Z<sub>2</sub>)}←FOO R</apll><br />
may be used to mark the result as shy.</p></li>

      <li><p>Within a user-defined function/operator header, the '''left''' argument may be marked as '''optional''' (a.k.a. '''ambivalent''') by enclosing it in braces, as in <font color=green><apll>∇ Z←{L} FOO R</apll></font>.  If the left argument part of the header consists of multiple names, either<br />
<apll>∇ Z←{L<sub>1</sub> L<sub>2</sub>} FOO R  &nbsp; &nbsp;  ⍝TWO optional left arguments</apll><br />
<apll>∇ Z←({L<sub>1</sub> L<sub>2</sub>}) FOO R</apll><br />
<apll>∇ Z←{(L<sub>1</sub> L<sub>2</sub>)} FOO R</apll><br />
<font color=green><strong>Braces {} are used to mark the left argument as optional.  System function '''[[System_Function_NC|<apll>⎕NC</apll>]]''' may be used to detect the presence/absence of a braced{noncompulsory} left argument(0=Not Used/Missing Arg, 2=Used/Yes Arg - for {ArgName} e.g. {L} by calling &nbsp; ⎕NC 'L' &nbsp; ''within the user function itself'', here FOO).</strong></font></p></li>

      <li><p>A user-defined function/operator may accept the '''axis operator''' as an additional argument, just as primitive function/operators do.  The axis operator may be specified in the header as in<br />
<apll>∇ Z←FOO[X] R</apll> for a function,<br />
<apll>∇ Z←(LO FOO[X]) R</apll> for a monadic operator, and<br />
<apll>∇ Z←(LO FOO[X] RO) R</apll> for a dyadic operator.</p></li>

      <li><p>A user-defined function/operator may define a '''separate entry point''' for when it is called on a prototype &mdash; use the line label <apll>⎕PRO:</apll>.  For example, the monadic function <apll>FOO</apll> when used in <apll>FOO¨R</apll> where <apll>R</apll> is an empty array is entered at the line labeled <apll>⎕PRO:</apll>.  If there is no such line with that label, a <apll>DOMAIN ERROR</apll> is signaled.</p></li>

      <li><p>The local names to a user-defined function/operator appear in the header to the right of the syntax part as above.  The first local name is separated from the start of the header by a single semicolon; the second and subsequent local names are separated from each other by either a single semicolon or one or more blanks depending upon your own preference.  For example</p>

<apll>∇ Z←FOO R;g1 g2 g3 g4;h1 h2 h3</apll></li>

      <li><p>Within a recursive user-defined function, a del symbol (<apll>∇</apll>) refers to the user-defined function without having to name it.  For example,</p>
<apll><pre>
    ∇ Z←fibonacci R
[1]   :if R≤1 ⋄ Z←1 ⋄ →0 ⋄ :end
[2]   Z←(∇R-1) + ∇R-2
    ∇
</pre></apll>
</li>

      <li><p>Within a recursive user-defined operator, a del symbol (<apll>∇</apll>) refers to the derived function of the user-defined operator with the current operands bound to the operator name without having to name it.  For example, with a monadic operator whose header looks like</p>

<apll>∇ Z←(LO mop) R</apll>

<p>a del symbol in the body of the operator is a shorthand for <apll>(LO mop)</apll>, and for a dyadic operator whose header looks like</p>

<apll>∇ Z←(LO dop RO) R</apll>

<p>a del in the body of the operator is a shorthand for <apll>(LO dop RO)</apll>.</p></li>

      <li><p>Within a recursive user-defined operator, two del symbols (<apll>∇∇</apll>) refer to the operator name with no bound operands.  For example, in the monadic operator case above in the body of the operator, <apll>∇∇</apll> refers to <apll>mop</apll>, and in the dyadic operator case above, <apll>∇∇</apll> refers to <apll>dop</apll>, and in both cases without having to know the actual name.</p></li>
    </ul>
  </li>

  <li><p>'''User-defined Operators'''</p>
    <ul>
      <li><p>A user-defined <font color=purple><strong>operator</strong></font> is distinguished from a user-defined <u>function</u> by its <font color=purple><strong>header</strong></font>, such that in the place where the function <font color=purple><strong>name</strong></font> normally appears, it contains a left operand name, an operator name, and an optional right operand name (for dyadic operators only), all enclosed in <font color=purple><strong>a single set of parentheses</strong></font>.  For example, the operator part of the header for a monadic operator looks like <font color=purple><strong><apll>(LO MonOp)</apll></strong></font>, and a dyadic operator looks like <font color=purple><strong><apll>(LO DydOp RO)</apll></strong></font> where <apll>LO</apll> and <apll>RO</apll> are the left and right operands (a function, variable, or jot).</p>
<font color=purple><strong>
<p>Both types of user-defined operators may be called monadically or dyadically, as in</p>

<table border="1" cellpadding="5" cellspacing="0" summary="">
<tr>
  <td></td>
  <td align="center">Monadic derived function</td>
  <td align="center">Dyadic derived function</td>
</tr>
<tr>
  <td>Monadic operator</td>
  <td><apll>∇ Z←(LO MonOp) R</apll></td>
  <td><apll>∇ Z←L (LO MonOp) R</apll></td>
</tr>
<tr>
  <td>Dyadic operator</td>
  <td><apll>∇ Z←(LO DydOp RO) R</apll></td>
  <td><apll>∇ Z←L (LO DydOp RO) R</apll></td>
</tr>
</table>
</strong></font>
<p>Operators exist to modify behaviors of functions as well as operate on data.  An operator may be applied to a function to derive a ''different'' function or ''modify'' data(/\+-×÷).  An attribute of operators are their precedence '''over''' functions; operators are executed '''before''' functions.  One indication an Operator should be used instead of a function is - when a function always includes parentheses during its call.  Proper structuring of commonly used operators prevents, for instance, multiple layers of parentheses, thus clarifying code, speeding execution and increasing parallelization.  Operator usage situations: Statisticians - regression operators (power, multiple, growth, natural, cubic, cylical, etc.); Astronomers - integration and differentiation operators; Engineers - curve fitting, approximating, equation root derivations.
</p>
<p>Just like user-defined functions, user-defined operators may have multiple names in the result, left, and right arguments (but not the left and/or right operands), an optional left argument, an axis operator, and a non-displayable result.</p>

<p>A header using all these features might look like</p>

<p><apll>∇ {(Z<sub>1</sub> Z<sub>2</sub>)}←{(L<sub>1</sub> L<sub>2</sub> L<sub>3</sub>)} (LO DydOp[X] RO) (R<sub>1</sub> R<sub>2</sub> R<sub>3</sub> R<sub>4</sub>)</apll></p></li>
      <li>A jot (<apll>∘</apll>) may be used as an operand to a user-defined operator in which case the corresponding name in the header is undefined, that is <apll>⎕NC</apll> returns <apll>0</apll>.  For example,

<apll><pre>
    ∇ (Z1 Z2)←(LO DydOp RO) R
[1]   :select ⍬⍴⎕NC 'LO'
[2]   :case 0 ⋄ Z1←'LO is undefined'
[3]   :case 2 ⋄ Z1←'LO is a variable'
[4]   :case 3 ⋄ Z1←'LO is a function'
[5]   :end
[6]
[7]   :select ⍬⍴⎕NC 'RO'
[8]   :case 0 ⋄ Z2←'RO is undefined'
[9]   :case 2 ⋄ Z2←'RO is a variable'
[10]  :case 3 ⋄ Z2←'RO is a function'
[11]  :end
    ∇

      ∘DydOp⍴ 12
LO is undefined&nbsp;&nbsp;RO is a function
      ⍴DydOp∘ 12
LO is a function&nbsp;&nbsp;RO is undefined
      ∘DydOp∘ 12
LO is undefined&nbsp;&nbsp;RO is undefined
</pre></apll>
      </li>
    </ul>
  </li>
</ul>