User-Defined Functions/Operators/Hyperators

• User-defined Functions, Operators, and Hyperators

  • Within a user-defined function/operator/hyperator 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 anappropriate length vector argument. Upon invocation of the function/operator/hyperator, 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, the caller must supply a value for this argument which is a scalar or one-element vector.

  • Within a user-defined function/operator/hyperator 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 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.

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

  • Within a user-defined function/operator/hyperator header, the result may be marked as shy or non-displayable by enclosing it 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 shy.

  • Within a user-defined function/operator/hyperator header, the left argument may be marked as optional (a.k.a. ambivalent) by enclosing it 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     ⍝TWO optional left arguments
    ∇ Z←({L₁ L₂}) FOO R
    ∇ Z←{(L₁ L₂)} FOO R
    Braces {} are used to mark the left argument as optional. System function ⎕NC may be used to detect the presence/absence of a left argument(0=Not Used/Missing Arg, 2=Used/Yes Arg - for {ArgName} e.g. {L} by calling   ⎕NC 'L'   within the user function itself, here FOO).

  • A user-defined function/operator/hyperator may accept the axis operator as an additional argument, just as primitive function/operator/hyperators 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, etc.

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

  • 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

    ∇ Z←FOO R;g1 g2 g3 g4;h1 h2 h3

  • Within a recursive user-defined function, a del symbol (∇) refers to the user-defined function without having to name it. For example,

        ∇ Z←fibonacci R
    [1]   :if R≤1 ⋄ Z←1 ⋄ →0 ⋄ :end
    [2]   Z←(∇R-1) + ∇R-2
        ∇
    

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

    ∇ Z←(LO mop) R

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

    ∇ Z←(LO dop RO) R

    a del in the body of the operator is a shorthand for (LO dop RO), etc.

  • Within a recursive user-defined operator/hyperator, two del symbols (∇∇) refer to the operator/hyperator name with bound hyperand(s), but no bound operands. For example, in the monadic operator case above in the body of the operator, ∇∇ refers to mop, and in the dyadic operator case above, ∇∇ refers to dop, and in both cases without having to know the actual name.

  • Within a recursive user-defined hyperator, three del symbols (∇∇∇) refer to the hyperator name with no bound operands/hyperands.

• 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 a single set of parentheses. For example, the operator part of the header for a monadic operator looks like (LO MonOp), and a dyadic operator looks like (LO DydOp RO) where LO and RO are the left and right operands (a function, variable, or jot).

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

    	Monadic derived function	Dyadic derived function
    Monadic operator	∇ Z←(LO MonOp) R	∇ Z←L (LO MonOp) R
    Dyadic operator	∇ Z←(LO DydOp RO) R	∇ Z←L (LO DydOp RO) R

    Operators exist to modify behaviors of functions as well as operate on data. An operator may be applied to a function or data to derive a different function. 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.

    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 DydOp[X] RO) (R₁ R₂ R₃ R₄)

  • A jot (∘) may be used as an operand to a user-defined operator in which case the corresponding name in the header is undefined, that is ⎕NC returns 0. For example,

        ∇ (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  RO is a function
          ⍴DydOp∘ 12
    LO is a function  RO is undefined
          ∘DydOp∘ 12
    LO is undefined  RO is undefined
    

• User-defined Hyperators

  • A user-defined hyperator is distinguished from a user-defined operator by its header, such that in the place where the operator name normally appears, it contains a left hyperand name, a hyperator name, and an optional right hyperand name (for dyadic hyperators only), all enclosed in a single set of parentheses. For example, the hyperator part of the header for a monadic hyperator looks like (LO (LH MonHyp)) or (LO (LH MonHyp) RO), and a dyadic hyperator looks like (LO (LH DydHyp RH)) or (LO (LH DydHyp RH) RO) where LO and RO are the left and right operands (a function, variable, or jot) and LH and RH are the left and right hyperands (an operator, function, variable, or jot).

    All four types of user-defined hyperators may be called monadically or dyadically, as in

    	Monadic derived function	Dyadic derived function
    Monadic Hyperator, Monadic Operator	∇ Z←(LO (LH MonHypMonOpr)) R	∇ Z←L (LO (LH MonHypMonOpr)) R
    Monadic Hyperator, Dyadic Operator	∇ Z←(LO (LH MonHypDydOpr) RO) R	∇ Z←L (LO (LH MonHypDydOpr) RO) R
    Dyadic Hyperator, Monadic Operator	∇ Z←(LO (LH DydHypMonOpR RH)) R	∇ Z←L (LO (LH DydHypMonOpr RH)) R
    Dyadic Hyperator, Dyadic Operator	∇ Z←(LO (LH DydHypDydOpR RH) RO) R	∇ Z←L (LO (LH DydHypDydOpr RH) RO) R

    Hyperators exist to modify behaviors of operators as well as functions and data. An hyperator may be applied to an operator, function, or data to derive a different operator or function. An attribute of hyperators are their precedence over operators and functions; hyperators are executed before operators and functions. Like operators, hyperators have short right scope, but unlike operators they have short left scope so as to allow an operator to be passed as a left hyperand.

    Just like user-defined functions and operators, user-defined hyperators may have multiple names in the result, left, and right arguments (but not the left and/or right hyperands/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 DydOp[X] RO) (R₁ R₂ R₃ R₄)

  • A jot (∘) may be used as a hyperand to a user-defined hyperator in which case the corresponding name in the header is undefined, that is ⎕NC returns 0. For example,

        ∇ (Z1 Z2 Z3)←(LO (LH H2O1 RH)) 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]   :else ⋄ ⎕ERROR 'Left Operand Unknown'
    [6]   :end
    [7]   
    [8]   :select ⍬⍴⎕NC 'LH'
    [9]   :case 0 ⋄ Z2←'LH is undefined'
    [10]  :case 2 ⋄ Z2←'LH is a variable'
    [11]  :case 3 ⋄ Z2←'LH is a function'
    [12]  :case 4 ⋄ Z2←'LH is an operator'
    [13]  :else ⋄ ⎕ERROR 'Left Hyperand Unknown'
    [14]  :end
    [15]  
    [16]  :select ⍬⍴⎕NC 'RH'
    [17]  :case 0 ⋄ Z3←'RH is undefined'
    [18]  :case 2 ⋄ Z3←'RH is a variable'
    [19]  :case 3 ⋄ Z3←'RH is a function'
    [20]  :case 4 ⋄ Z3←'RH is an operator'
    [21]  :else ⋄ ⎕ERROR 'Right Hyperand Unknown'
    [22]  :end
        ∇
    
         ⍪ -(¨¨)H2O1⍤5 6
     LO is a function  
     LH is an operator 
     RH is an operator
          ⍪ -(¨¨)H2O1∘5 6
     LO is a function  
     LH is an operator 
     RH is undefined