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

Function set attrib_model

Functions supporting attributes. more...


Function list

attributeByName Returns an attribute registered with the VM as by symbolic name.
broadcast Send a message to every object having an attribute.
giveTo Gives a certain attribute to a certain object.
having Returns an array containing all the items having a certain attribute.
removeFrom Removes a certain attribute from a certain object.
removeFromAll Removes a certain attribute from all the objects currently having it.
testAttribute Checks if an object is currently given a certain attribute.

Detailed description

Attributes define dynamic boolean characteristics that instances may have at a certain moment. An attributed can be given or removed from a certain object, or automatically given to new instances through class declaration has statement. The VM keeps track of instances having attributes, so it is possible to iterate on, or send a message to, all the objects having a certain attribute. In this section, the functions that allow to access this functionalities are explained.

Attribute can be treated as collections in for/in loops and iterators can be extracted from them with the first() BOM method and with the Iterator class constructor.


Functions

attributeByName()

Returns an attribute registered with the VM as by symbolic name.

attributeByName( name, [raiseIfNotFound] )
name

The attribute name that has been registered with the VM.

raiseIfNotFound

if given and true, the function will raise an error in case the attribute with the given name is not found.

Returns:

The attribute having the given name, if found, or nil.

Raises:
AccessError

if the attribute is not found and the raise is required.

Attributes registered with the VM through a local export are made available in a special index which can be accessed by name. In example the b give statement can refer symbols containing attributes or globally visible attribute names.

This function returns an attribute which is globally visible. In this way it is possible to query the VM for attributes to be fed in the other core functions working with attributes.

broadcast()

Send a message to every object having an attribute.

broadcast( signaling, ... )
signaling

An attribute or an array of attributes to be broadcast.

...

Zero or more data to be broadcaset.

Returns:

Value returned by a message handler or nil.

This function iterates over all the items having a certain attribute; if those objects provide a method named exactly as the attribute, then that method is called. A method can declare that it has “consumed” the message (i.e. done what is expected to be done) by returning true. In this case, the call chain is interrupted and broadcast returns. A method not wishing to prevent other methods to receive the incoming message must return false. Returning true means “yes, I have handled this message, no further processing is needed”.

It is also possible to have the caller of broadcast to receive a return value created by the handler; If the handler returns an out of band item (using (undefined) oob) propagation of the message is stopped and the value is returned directly to the caller of the broadcast function.

The order in which the objects receive the message is random; there isn't any priority across a single attribute message. For this reason, the second form of broadcast function is provided. To implement priority processing, it is possible to broadcast a sequence of attributes. In that case, all the objects having the first attribute will receive the message, and will have a chance to stop further processing, before any item having the second attribute is called and so on.

The broadcast function can receive other parameters; in that case the remaining parameters are passed as-is to the handlers.

Items having a certain attribute and receiving a broadcast over it need not to implement an handler. If they don't provide a method having the same name of the broadcast attribute, they are simply skipped. The same happens if they provide a property which is not callable; setting an handler to a non-callable item is a valid operation to disable temporarily message processing.

An item may be called more than once in a single chained broadcast call if it has more than one of the attributes being broadcast and if it provides methods to handle the messages.

It is possible to receive more than one broadcast in the same handler using the “same handler idiom”: setting a property to a method of the same item in the init block or in the property initialization. In example:

       attributes: attr_one, attr_two
 
       object handler
          attr_two = attr_one
          function attr_one( param )
             // do something
             return false
          end
          has attr_one, attr_two
       end

giveTo()

Gives a certain attribute to a certain object.

giveTo( attrib, obj )
attrib

The attribute to be given

obj

The object that will receive the attribute

This function is equivalent to the give statement, and is provided to allow functional processing of attributes. In example:

    attributes: opened
    dolist( [giveTo, opened], [obj1, obj2, obj3] )

If the target object had already the attribute, nothing is done. If the first parameter is not an attribute or the second parameter is not an object, a ParamError is rasied.

See also dolist.

having()

Returns an array containing all the items having a certain attribute.

having( attrib )
attrib

The attribute that will be inspected

Returns:

An array with all the items currently having that attribute.

If the attribute isn't currently given to any item, this function will return an empty array. Notice that it is not strictly necessary to call having function just to iterate over the items i.e. in a for/in loop, as attributes can be directly iterated:

    attributes: opened
    //....
    for item in opened
       > "Item ", item.name, " has opened"
    end

Also, attributes support iterators; an Iterator instance can be built passing an attribute as the parameter of the constructor, and first() BOM method can be called on an attribute to create an iterator which can be used to inspect all the objects having a certain attribute.

However, having function is still useful when a snapshot of the items currently having a certain attribute is needed. In example, it is possible to save in a variable the array, change the status of some objects by removing the attribute from them and finally re-giving the attribute.

removeFrom()

Removes a certain attribute from a certain object.

removeFrom( attrib, obj )
attrib

The attribute to be removed

obj

The object from which the attribute must be removed

This function is equivalent to the give statement using to remove an attribute, and is provided to allow functional processing of attributes. In example:

    attributes: opened
    dolist( [removeFrom, opened], [obj1, obj2, obj3] )

If the target object didn't have the attribute, nothing is done. If the first parameter is not an attribute or the second parameter is not an object, a ParamError is rasied.

removeFromAll()

Removes a certain attribute from all the objects currently having it.

removeFromAll( attrib )
attrib

The attribute to be removed

After this function is called, the target attribute will not be found in any object anymore.

testAttribute()

Checks if an object is currently given a certain attribute.

testAttribute( item, attrib )
item

An object that may have an attribute.

attrib

The attribute to be tested.

Returns:

true if the attribute has been given to the object.


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