Method variables

Summary

SOUL supports method variables, variables that reference methods. They can be used to invoke varying methods with a particular, unchanging invocation. For example, to conditionally invoke the system intrinsic Right, Left, or Center method, you can do something like the following:

%justify is function (string):justify(%amount is float) is longstring ... if %x then %justify = right elseif %y then %justify = centre else %justify = left end if ... printtext {'Whatever':%justify(10)} printtext {%something:%justify(10)}

As shown in the preceding example, to use a method variable you first declare it, then assign a method to it, then invoke it. The declaration specifies the type of method to which the method variable may refer. Function and Subroutine are the two type options. A Function variable is required if the method (or class variable) you want to assign to the variable returns a value (this is always true for class variables). A Subroutine variable is used if the method to be assigned does not return a value or is Callable.

The method you assign to a method variable can be a system method, a user-defined method, (instance method, enhancement method, shared method, or local method), or a class variable. Invoking the method using the method variable employs the same syntax as invoking the method directly, except that the method variable is used.

The following example shows assignment from a user class method, class variables, and a local method:

b class junk public variable a is float variable b is string len 32 function c is float end public function c is float return %this:a:toPower(3) end function end class local function (junk):aTimesC is float return %this:a * %this:c end function %rubbish is object junk %rfunc is function (junk):whatever is float %rubbish = new %rubbish:a = 3 %rubbish:b = 'Holy cow!' %rfunc = a printText {~} = {%rubbish:%rfunc:right(20, pad='*')} %rfunc = b printText {~} = {%rubbish:%rfunc} %rfunc = c printText {~} = {%rubbish:%rfunc} %rfunc = aTimesC printText {~} = {%rubbish:%rfunc} end

The result is:

%rubbish:%rfunc:right(20, pad='*') = *******************3 %rubbish:%rfunc = Holy cow! %rubbish:%rfunc = 27 %rubbish:%rfunc = 81

Note: The second line of the result contains string output. Because of loose datatyping for intrinsics, a method variable declared as Float can return a String (or Unicode) value, if the method assigned to it returns such a value.

Notice also that class Variables are used exactly like the Functions in the examples above.

Function or Subroutine variables may not be passed between requests; they are always nullified between requests. Function or Subroutine variables may not appear inside of global objects.

Declaring a method variable

The syntax for the declaration of a method variable is shown below:

%var [Is] methodTemplate | (methodTemplate) [methvarQualifiers]

Where:

If there are any method variable qualifiers, methodTemplate must be enclosed in parentheses. For example if a method variable is Shared, that qualifier must be specified as in:

%x is (function (stringlist):stupid is float) shared

%var	The name of the method variable, which can be any name that follows the rules for SOUL %variables.
methodTemplate	The function or subroutine declaration template.
methvarQualifiers	Qualifiers for the variable being declared, such as Common or Shared.

Method template in method variable declaration

A method declaration template is used to declare the type of a method variable and is essentially the same as a normal method declaration, consisting of the method name followed by the method description.

methodType [(class):]methodName[(parms)] - [Is returnType] [methodQualifiers]

methodType	The type of method that is to be represented by the method variable. The options are Function and Subroutine. Function is required if the method (or class variable) returns a value. Subroutine is used if the method does not return a value or is Callable. Strictly speaking, Function and Subroutine are the classes of the method object that is is referenced by the method variable. There are currently no methods in the Function or Subroutine class.
class	Identifies the class of objects to which the method applies.
methodName	The method name, which can be any name that follows the rules for SOUL %variables, is preceded by its class as necessary, and is followed by its parameters, if any.
parms	The parameters that are used in invoking the method variable.
returnType	The datatype of values returned by the methods assigned to the method variable. This is only allowed for Function class method variables.
methodQualifiers	Details of method operation. Since the method operation details tend to come from the method to which the variable is set, methodQualifiers is rarely used.

Method class in method variable method template

Two method variables that are identically declared except for their class specifications are not equivalent. That is, given these declarations:

%foo is function (stringlist):hash is float %bar is function (stringlist):hash is float %junk is function (xmlDoc):hash is float

The following is valid:

%foo = %bar

But the following is not valid:

%foo = %junk

The class designation supplies context for any method assigned to the method variable. Given the declarations in the previous item, the following assignment implies the Count method in the Stringlist class:

%foo = count

Count above references the Stringlist class Count method unless you had created a local Stringlist enhancement method called "Count," in which case method %foo references the local Count method.

Omitting a class specification implies that the method referred to by the method variable does not operate on an instance of an object variable, that is, it is a shared method. Such a method variable may be assigned to a conforming shared method in any class.

For example, the following declaration specifies a method variable that does not apply to an object instance:

%debug is subroutine debug

Consequently, valid assignments could take any of the following forms:

%debug = (myclass):sharedSubroutine %debug = (yourclass):sharedSubroutine %debug = localMethod %debug = (object):garbageCollect

Method parameter list and other qualifiers in method variable method template

The method parameter list can contain required and optional, named and unnamed parameters, and their types. The parameter list is followed by a method result datatype (for functions) and then possibly by further qualifiers.

For example, a Calculate method in Myclass that takes a numeric value and returns a numeric value is declared as:

function (myclass):calculate(%x is float) is float

A method variable declared with a return type that is a SOUL intrinsic datatype might return another intrinsic type when invoked if you assign a method to it that returns the other type. This is because SOUL allows the assignment from one intrinsic type to another.

Most method qualifiers such as AllowNullObject or Implements are derived from the method assigned to a method variable and make no sense on the method template in a method variable declaration. In fact, there are currently no method qualifiers other than the return datatype that are allowed in the method template in a method variable declaration. This includes Throws clauses, though you may assign a method that throws exceptions to a method variable and catch exceptions thrown by that method.

Method variable declaration example

In the following example, the %stooge Function variable is declared for the Mayhem class:

class mayhem public variable moe is float property larry is float function curly is float end public end class %stooge is function (mayhem):Number is float

In this declaration, function is used for the object declaration, indicating that the method returns a value. The name Number is actually nothing but a placeholder, and the above declaration is considered identical to:

%stooge is function (mayhem):Placehold is float

Some placeholder is needed in the Function name position to make the declaration read properly, and you may want to put a meaningful name there to suggest the intent of the method. But whether the name is specified as Number or as Placehold, the following assignments are all valid:

%stooge = moe %stooge = larry %stooge = curly

The method values to which the method variable in this example refers are in fact class Variables, which fit the %stooge declaration: they are function-like, operating on a Mayhem object and returning a Float.

If the method in the declaration has parameters, as in:

%stooge is function (mayhem):meaningless(%x is float) is float

The parameter names do not get used, so the above declaration is equivalent to this one:

%stooge is function (mayhem):meaningful(%y is float) is float

Thus, if two method variables contain references to methods on a Mayhem object that take a float input parameter and return a float, they can be assigned to each other, as in the following:

%stooge is function (mayhem):meaningless(%x is float) is float %stud is function (mayhem):meaningful(%y is float)is float ... %stooge = %stud

For NameAllowed or NameRequired parameters, the parameter names are meaningful in the method object declarations.

Assigning to a method variable

You assign a method value to a method variable using the following syntax:

%var = [(+classname)]method

Where:

%var	The name of the method variable.
classname	The name of the class to which the method variable applies. This name is necesary if the method is a shared method or an enhancement method; otherwise, the method is assumed to be a member of the class specified in the method variable declaration. The plus sign is necessary for an enhancement method.
method	The name of the method to which the method variable will refer or an anonymous function. A method name can be either a SOUL method (instance method, enhancement method, shared method, or local method), a class member (Variable or read-only Property), or a method variable that fits the #method template in method variable declaration.

The source of an assignment to a method variable can even be the invocation of a function that returns a method value that fits the method description. Of course, it can also be another, compatible method variable.

You may assign a method that takes no parameters to a method variable that is declared as referring to a method with a parameter. For example, if function variable %goo is declared as:

%whynot is function (silly):whatever(%x is float) is float

The following assignment is valid if Z is a variable in class Silly:

%whynot = Z

In such a case, the parameter, %x, in the method variable declaration is ignored when the method variable is invoked. For example, if %whynot was set to Silly class variable Z, the 22 in the following invocation of %whynot would be ignored:

printText {~} = {%sillyVar:%whynot(22)}

This is allowed because methods are allowed to ignore a parameter value. Similarly, say a function in class Silly is defined as:

function stupid(%whatever is float, - %z is longstring optional) is longstring

Then Stupid may also be validly assigned to %whynot:

%whynot = stupid

And whenever Stupid is invoked via %whynot, the optional parameter %z will not be present.

Method variables follow the standard rules for NameAllowed and NameRequired parameters. If a method variable declaration specifies a method with one of these types of parameter, you may not assign to the variable a method that does not have the same parameter name type.

A method variable may be assigned to an enhancement method. The following statement assigns to %whynot the Float enhancement method in class Util called BigOnes which returns a Float object:

%whynot = (+util)bigOnes

If a method variable is declared as applying to a base class, you may not assign an extension class method to it. The method variable must be applicable to all objects of the base class, and setting it to a method of a specific extension class would violate this principle.

You may assign an overridable method to a method variable.

Method variables may be assigned to the special value This, which is an identity method that simply returns its method object.

For example, given the following code fragment:

%justify is function (string):justify(%amount is float) is longstring ... if %x then %justify = right elseif %y then %justify = centre elseif %z %justify = left else %justify = this end if ... printtext {'Whatever':%justify(10)} printtext {%something:%justify(10)}

If the Else logical path is followed, the printText statement will simply print the string to which it is applied, without justification or padding.

The This value is especially useful for sorting and finding maximum and minimum values in collections of intrinsic objects. This can also be used as an anonymous function where the anonymous function specifies processing to be applied to the method object.

Invoking a method variable

The syntax for invoking a method via a method variable that applies to objects of a class is:

objectVar:%methodVar[:moreMethods]

The syntax for invoking a method via a method variable that doesn't apply to objects of a class is:

%(Local):%methodVar[:moreMethods]

Where:

objectVar	The object variable to which the method variable, %methodVar, is applied.
%methodVar	The name of the method variable.
moreMethods	Additional methods that may be strung together, that is, applied to the result of the %methodVar method. This is no different from stringing a method to the result of a non-variable method.

Method variable invocation examples

In the following example, method variable %foo has this declaration:

%foo is function (stringlist):subset is object stringlist

This declaration indicates that %foo must contain a reference to a method that operates on a Stringlist object and returns a Stringlist object. The following local function is defined in the same scope as %foo, after which the function is assigned to %foo:

local function (stringlist):everyOther is object stringlist %outlist is object stringlist %i is float %outlist = new for %i from 1 to %this:count by 2 %outlist:add(%this(%i)) end for return %outlist end function ... %foo = everyOther

To invoke the EveryOther method against Stringlist variable %list, you apply method variable %foo:

%list = %list:%foo

To invoke the EveryOther method against %list and then print the result, you use:

%list:%foo:print

Stringing methods together can be taken further. To invoke EveryOther on %list, then apply EveryOther to the result of that, and finally print the output of those operations:

%list:%foo:%foo:print

In the following example, a method variable that is set to a Shared class variable is invoked using %(local), the syntax for invoking a local shared method. The method variable is not applied to a variable because the method, itself, doesn't apply to objects of any class.

begin class Reply public shared variable validate is float initial(1) end public shared end class Reply %rc is float %rcMeth is function rcReturner is float %rcMeth = (Reply):validate %rc = %(local):%rcmeth if %rc then printText Error else printText Success end if end

This request prints: Error.

Anonymous functions

An anonymous function, as the name suggests, is a method that has no name. Because these functions have no name, they must typically be defined in the context in which they are actually used. Hopefully, the meaning of this statement is made clear below.

Consider the case where a method variable is defined as:

%transform is function (string):transform is longstring

So, %transform can refer to a method that takes a String input and produces a String output. So, one can set %transform to the system Reverse function:

%transform = reverse

And then invoke the Reverse function via the method variable:

printText {~} = {'We are the worms':%transform}

which produces:

'We are the worms':%transform = smrow eht era eW

But, suppose you wanted %transform to be set to a method that returns the rightmost three characters of the method object string. Intuitively, it would seem that you should be able to do:

%transform = right(3)

But, formerly, this was not allowed because there is no method called Right(3), only Right. And, one couldn't do:

%transform = right

because right requires a parameter, but the method variable template for %transform has no parameters. And, even if the above were allowed, it is still missing the important bit of information about how many of the rightmost bytes %transform should return.

Now, however, this is allowed:

%transform = right(3)

It is worth understanding exactly what this means. The compiler sees right(3) and "knows" that it can't be a method invocation or variable reference because the right does not begin begin with a percent sign. If the compiler saw:

%transform = %right(3)

this might indicate a reference to an Arraylist called %right, or perhaps a local function called Right that, hopefully, returns a method variable. But, it most definitely would not be interpreted as having anything to do with the system Right method. But, in:

%transform = right(3)

The compiler knows you must be referring to a function name and so assumes that that function is intended to be part of what's literally being assigned to the method variable. When it sees the open parenthesis after the right, it decides that what's inside the parentheses are intended to be arguments to be passed in the specified invocation of the method.

Essentially, it is as if the compiler built a local method under the covers that looked like:

function (string):right3 is longstring return %this:right(3) end functions

and then assigned that local function to %transform:

%transform = right3

In fact, to get this same functionality before the introduction of anonymous functions, you would have to explicitly define such a local function and assign it to %transform. By implicitly doing this for you, the compiler saves you the trouble of having to come up with a name for the method (hence the term anonymous function), and it makes it clear at the point of assignment to %transform what the anonymous function actually does. Without the anonymous function, you'd have to find the definition of Right3 to see what's actually being assigned to %transform.

This is another case where SOUL's insistence that variables begin with a percent sign comes in handy, as it allows the compiler to distinguish an anonymous function from a variable or method reference.

Anonymous functions are always considered to be exposed, that is, variables in the containing context are always visible to the anonymous method. To illustrate this, consider:

b %transform is function (string):transform is longstring %nright is float %transform = right(%nright) %nright = 3 printText {~} = {'We are the worms':%transform} %nright = 7 printText {~} = {'We are the worms':%transform} end

The output is:

'We are the worms':%transform = rms 'We are the worms':%transform = e worms

Suppose, however, that you want %transform to return the reverse of the last three characters in a string. One might expect the following would do so:

%transform = right(3):reverse

However, for subtle syntactic reasons, this is not allowed.

The This method

To accomplish the above, you must use a special method called This. The This method is unusual in that:

• It can only be used via method variables
• The first argument is an arbitrary SOUL expression that can return any datatype. The datatype returned, though, must be compatible with the return value of the method template for the method variable to which it is assigned.
• The variable %this is automatically defined in the expression, and it holds the value of the object to which the method variable is applied.

Given these rules, the This method can be used to set a method variable to a function that takes the reverse of the rightmost three characters of a string:

%transform = this(%this:right(3):reverse)

After the above assignment, if you specify this:

printText {~} = {'We are the worms':%transform}

The result is:

'We are the worms':%transform = smr

The This method can be useful in cases where the anonymous function is needed to perform an operation that is not a method. For example:

%transform = this(%this with %this) printText {~} = {'We are the worms':%transform}

This outputs the following:

'We are the worms':%transform = We are the wormsWe are the worms

And this:

%transform = this(%this:left(1) with %this:right(1)) printText {~} = {'We are the worms':%transform}

Produces this result:

'We are the worms':%transform = Ws

As with other anonymous methods, the This method is exposed, so variables in the containing context are available inside the This method. Therefore, for the following:

b %transform is function (string):transform is longstring %middle is string len 8 initial('<===>') %transform = this(%this:left(1) with %middle with %this:right(1)) printText {~} = {'We are the worms':%transform} end

The results is:

'We are the worms':%transform = W<===>s

However, since %this inside the This method refers to the method object during the method variable invocation, a %this variable in the containing context would be "hidden." This could be a problem if a This method is used inside a class instance method or an enhancement method where a %this would be defined. For example, if you had:

local subroutine (string):foo %transform is function (string):transform is longstring %transform = this(%this:left(1) with %this with %this:right(1)) printText {~} = {'We are the worms':%transform} end subroutine

You might actually mean for the %this between the two Withs in the this function to be the %this for the local subroutine. Unfortunately, that will not be the case — %this will be the method object, so the above Subroutine would output:

'We are the worms':%transform = WWe are the wormss

To get around this, one can either assign the method's %this to a different local variable:

local subroutine (string):foo %fooThis is longstring %fooThis = %this %transform is function (string):transform is longstring %transform = this(%this:left(1) with %fooThis with %this:right(1)) printText {~} = {'We are the worms':%transform} end subroutine

Or, map the name %this via an InternalNames block:

local subroutine (string):foo internalNames %fooThis is %this end internalNames %transform is function (string):transform is longstring %transform = this(%this:left(1) with %fooThis with %this:right(1)) printText {~} = {'We are the worms':%transform} end subroutine

If this Subroutine is called with:

%x is string len 8 initial('++++') %x:foo

The following is the output:

'We are the worms':%transform = W++++s

The This method without any parameters is equivalent to This(%this), that is, it simply returns the method object at method variable invocation time. As such, the This method can be thought of as having a default parameter: %this.

Anonymous methods in collection methods

As with other method literals, anonymous methods can be useful in collection methods that use method variables to control processing. For example, given class Order, with public float variables price and quantity, suppose this:

%orders is arraylist of object order

You could, then, sort the Arraylist in descending order by quantity:

%orders:sort(descending(quantity))

To sort in descending order by the product of Price and Quantity, specify:

%orders:sort(descending(this(%this:price * %this:quantity)))

If given this:

%names is arraylist of longstring

The following sorts %names in ascending order of the second through fifth character:

%names:sort(ascending(substring(2,4)))

System types

Some system methods expect method parameters with a particular template. Rather than requiring parameters to be described with the full function template and for variables containing functions to be defined with the templates, system types are provided as a shorthand for those signatures. For example, the HttpRequest Get function has a CertificateCheck parameter that's a function with the following template:

Function (String):methname Is Boolean

If one wished to declare a variable with this template, one could do something like:

%myChecker is function (string):lambda is boolean

However, the CertificateChecker type is provided to simplify this so one can declare a variable as:

%myChecker is type certificateChecker

The two declarations are equivalent and interchangeable. In either case, a variable declared this way can be passed to the HttpRequest Get method:

%httpResponse = %httprequest:get(certificateCheck=%myChecker)

See also

• Object oriented programming in SOUL