Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

Function set core_indirect

Functions meant to provide indirect symbol call facilities.


Function list

call Indirectly calls an item.
marshalCB Perform an event marshaling callback from inside an object.
marshalCBR Perform an event marshaling callback from inside an object.
marshalCBX Perform an event marshaling callback from inside an object.
methodCall Indirectly calls an object method.

Functions

call()

Indirectly calls an item.

call( callable, [parameters] )
callable

A callable item

parameters

An array containing optional parameters.

Returns:

The return value of the indirectly called item.

This function is meant to indirectly call a function. While pass and pass/in statements are meant to provide maximum efficiency in intercepting the functions, call is meant to provide different calling patterns (i.e. parameter mangling) in runtime.

Using this function is equivalent to use a callable array, but it spares the need to add the callable item in front of the array containing the parameters.

The following calls are equivalent:

       call( func, [1,2,3] )
       func( 1, 2, 3 )
       .[func 1 2 3]()

The callable item may be any callable Falcon item. This includes normal functions, external functions, methods, classes (in which case their constructor is called and a new instance is returned) and Sigmas (callable sequences).

The function returns the value that is returned by the called item.

If the symbol that is in the position of the item to be called is not a callable object, a ParamError is raised.

marshalCB()

Perform an event marshaling callback from inside an object.

marshalCB( message, [prefix], [when_not_found] )
message

The message to be marshalled.

prefix

An optional prefix to be applied to event handing method names.

when_not_found

Value to be returned when the event cannot be handled.

Returns:

The return value of the handler, or the value of when_not_found if the message couldn't be handled.

Raises:
AccessError

if the message couldn't be handled, and a default when_not_found value is not given.

This function performs automatic callback on objects that should receive and handle events.

The event is an array whose first element is the event name, and the other elements are the parameters for the handler. This function will search the calling object for a callable property having the same name of the event that should be handled. MarshallCB may also search the current object, if it is directly assigned to a property of an object, and not called from an object.

An optional prefix for the callback handlers may be given. If given, an handler for a certain event should be prefixed with that string to manage a certain event. In example, suppose that all the event handlers in the current object are prefixed with “on_”, so that the event “new_item” is handled by “on_new_item” handler, “item_removed” is handled by “on_item_removed” and so on. Then, it is possible to pass “on_” as the prefix parameter.

Some prefer to have handlers with a prefix and the first letter of the event capitalized. In example, it is common to have event “newFile” handled by “onNewFile” method, and so on. This convention will be acknowledged and used if the last character of the handler prefix is a single quote; in this example, to handle “newFile” (or “NewFile”) events through and “onNewFile” handler, the prefix should be set as “on'”.

The when_not_found parameter is returned in case the event handler is not found. It is a common situation not to be willing to handle some events, and that is not necessarily an error condition. The marshalCB function may return, in example, an out of band item to signal this fact, or it may just return a reasonable “not processed” value, as nil or false. If this parameter is not provided, not finding a valid handler will cause an access error to be raised.

See also oob.

marshalCBR()

Perform an event marshaling callback from inside an object.

marshalCBR( prefix, message )
prefix

An optional prefix to be applied to event handing method names.

message

The message to be marshalled.

Returns:

The return value of the handler.

Raises:
AccessError

if the message couldn't be handled.

This method works as marshalCB, but the order of the parameter is changed to make it easier to be used directly as object properties.

As the marshalled message is added as extra parameter during the marshalling method call, it is possible to assign marshalCBR directly to object properties, asin this example:

    attributes: receiver
 
    object MyReceiver
       // automatic marshalling
       receiver = [marshalCBR, "on'"]
 
       // Message handler
       function onNewMessage( data )
          > "New Message: ", data
       end
 
       has receiver
    end
 
    broadcast( receiver, ["newMessage", "data sent as a message"] )

Conversely to marshalCBX, marshalCBR will raise an access error in case the handler is not found.

marshalCBX()

Perform an event marshaling callback from inside an object.

marshalCBX( prefix, when_not_found, message )
prefix

An optional prefix to be applied to event handing method names.

when_not_found

The return value to be provided when the message cannot be marshalled.

message

The message to be marshalled.

Returns:

The return value of the handler, or the value of when_not_found if the message couldn't be handled.

This method works as marshalCB, but the order of the parameter is changed to make it easier to be used directly as object properties. Consider the following example:

       object handler
          marshaller = [marshalCBX, "on_", false ]
 
          function on_new_item( item )
             > "a new item: ", item
          end
       end
 
       event = ["new_item", 0 ]
       handler.marshaller( event )

In this way it is possible to stuff the marshaller in a simple declaration inside the object property declaration block, instead defining a marshaling method that had to call marshalCBX.

methodCall()

Indirectly calls an object method.

methodCall( object, methodName, [parameters] )
object

An object whose method is to be called.

methodName

The name of a method to be called.

parameters

An array containing optional parameters.

Returns:

The return value of the called method.

Raises:
AccessError

if the object doesn't contain desired property

TypeError

if the property exists, but is not callable.

This function is meant to indirectly call a method whose name is known. It's effect it's the same as calling getProperty to retrieve the method object and then using that item in the call function; however, the item is not repeatedly needed, this function is more efficient.

methodCall returns the same value that is returned by the method. If the object does not contain the required property, an AccessError is raised. If the property exists but it's not a callable item, a TypeError is raised.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0