Index | | | Related pages | | | Classes | | | Functions | | | Entities | | | Function Sets | | | Groups |
Functions supporting attributes. more...
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. |
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.
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: |
|
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.
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
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.
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.
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.
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.
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 |