User-Defined Functions/Operators/Hyperators

• User-defined Functions and Operators

  • 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 or an appropriate length vector argument. Upon invocation of the function/operator, these values are assigned one item per name.

    For example, a function whose header looks like

    ∇ Z←FOO (R₁ R₂)

    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 RANK ERROR is signaled. If the right argument is not of the proper length, a LENGTH ERROR is signaled.

    Note that if only one name appears within parentheses in the left or right argument, vector arguments must be singletons.

  • A user-defined function/operator header result may consist of two or more names each separated by one or more blanks. In this context, when the function exits, the individual names must all have a value (else a VALUE ERROR 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.

  • The result of a user-defined function/operator may be marked as non-displayable by enclosing the result part of the header in braces, as in ∇ {Z}←FOO R. If the result part of the header consists of multiple names, either ∇ {Z₁ Z₂}←FOO R, ∇ ({Z₁ Z₂})←FOO R, or ∇ {(Z₁ Z₂)}←FOO R may be used to mark the result as non-displayable.

  • A user-defined function/operator may be called with an optional left argument (ambivalent) by enclosing the left argument in braces, as in ∇ Z←{L} FOO R. If the left argument part of the header consists of multiple names, either ∇ Z←{L₁ L₂} FOO R, ∇ Z←({L₁ L₂}) FOO R, or ∇ Z←{(L₁ L₂)} FOO R may be used to mark the left argument as optional. The system function ⎕NC may be used to detect the presence/absence of the left argument.

  • Thanks to Dyalog APL for proposing and implementing the above features.

  • 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 ∇ Z←FOO[X] R for a function, ∇ Z←(LO FOO[X]) R for a monadic operator, and ∇ Z←(LO FOO[X] RO) R for a dyadic operator.

  • A user-defined function/operator may define a separate entry point for when it is called on a prototype — use the line label ⎕PROTOTYPE:. For example, the monadic function FOO when used in FOO¨R where R is an empty array is entered at the line labeled ⎕PROTOTYPE:. If no line has that label, the function/operator is entered at line 1.

• User-defined Operators

  • A user-defined operator is distinguished from a user-defined function by its header, such that in the place where the function name normally appears, it contains a left operand name, an operator name, and an optional right operand name (for dyadic operators only), all enclosed in parentheses. For example, operator part of the header for a monadic operator looks like (LO OP1), and a dyadic operator looks like (LO OP2 RO).

    Both types of user-defined operators may be called monadically or dyadically, as in

    	Monadic derived function	Dyadic derived function
    Monadic operator:	∇ Z←(LO OP1) R	∇ Z←L (LO OP1) R
    Dyadic operator:	∇ Z←(LO OP1 RO) R	∇ Z←L (LO OP1 RO) R

  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.

  A header using all these features might look like

  ∇ {(Z₁ Z₂)}←{(L₁ L₂ L₃)} (LO OP2[X] RO) (R₁ R₂ R₃ R₄)