Call operations

This section describes operations for calling methods, functions and other callable objects such as types and bound methods.

All of these functions may raise direct or normal exceptions.

See also: The section Member operations contains operations for dealing with member variables and reading members, including bound methods.

Operations

All of these functions have a few things in common:

• They return the return value of the call, or AError if a normal uncaught exception was raised.
• The args array must point to locations in a function frame or in temporary locations allocated using AAllocTemps, i.e. they must be visible to the garbage collector.
• The args array must have space for one extra item in addition to the arguments (and self, in case of method calls). This is needed for evaluating the calls.
• The functions may modify the contents of the args array.

AValue ACall(AThread *t, const char *callable, int numArgs, AValue *args)

Call an object specified using the fully qualified name of global definition with numArgs arguments, stored in the array args. args[0] is the first argument, args[1] is the second one, and so on. See the list above for additional details.

AValue ACallVarArg(AThread *t, const char *callable, int numFixedArgs, AValue *args)

Like above, but an additional Array object must be present in the args array that contains the rest of the arguments (args[numFixedArgs]).

AValue ACallValue(AThread *t, AValue callable, int numArgs, AValue *args)

Call a callable object with numArgs arguments, stored in the array args. args[0] is the first argument, args[1] is the second one, and so on. See the list above for additional details.

AValue ACallValueVarArg(AThread *t, AValue callable, int numFixedArgs, AValue *args)

Like above, but an additional Array object must be present in the args array that contains the rest of the arguments (args[numFixedArgs]).

AValue ACallMethod(AThread *t, const char *member, int numArgs, AValue *args)

Call a method with numArgs arguments (not including the implicit self argument), stored in the array args. args[0] is the target object (self), args[1] is the first argument, and so on. See the list above for additional details.

AValue ACallMethodVarArg(AThread *t, const char *member, int numFixedArgs, AValue *args)

Like above, but an additional Array object must be present in the args array that contains the rest of the arguments (args[numFixedArgs + 1]).

Examples

This module defines two example functions, one that calls a function and one that calls a method:

#include <alore/alore.h>

AValue FunctionExample(AThread *t, AValue *frame)
{
    AValue ret; /* The return value does not need to be stored in the frame,
                   since no operation invalidates it. However, it could be
                   stored in the frame for safety and consistency. */

    /* Setup arguments. Note that frame[3] is not set, but it is allocated in
       the frame. */
    frame[1] = AMakeInt(t, 4);
    frame[2] = AMakeStr(t, "hello");

    ret = ACallValue(t, frame[0], 2, frame + 1);
    if (AIsError(ret))
        return AError; /* Normal exception */
    else
        return ret; /* Pass on the return value. */
}

AValue MethodExample(AThread *t, AValue *frame)
{
    AValue ret;

    /* Setup arguments. Note that frame[4] is not set, but it is allocated in
       the frame. */
    frame[1] = frame[0]; /* self */
    frame[2] = AMakeInt(t, 4); /* First argument */
    frame[3] = AMakeStr(t, "hello"); /* Second argument */
    
    ret = ACallMethod(t, "method", 2, frame + 1);
    if (AIsError(ret))
        return AError; /* Normal exception */
    else
        return ret; /* Pass on the return value. */
}

A_MODULE(call, "call")
    A_SUB("FunctionExample", 1, 3, FunctionExample)
    A_SUB("MethodExample", 1, 4, MethodExample)
A_END_MODULE()

This Alore code uses the above module:

import call

sub Main()
  WriteLn(FunctionExample(Func)) -- Display 9 (== 4 + 5)
  var x = MyClass()
  WriteLn(MethodExample(x))      -- Display 10 (== 4 + 5 + 1)
end

sub Func(x, y)
  return x + y.length()
end

class MyClass
  var member = 1

  sub method(x, y)
    return x + y.length() + member
  end
end