Basic Object Model metaclass
Class BOM
This class contains the methods that can be applied to every falcon item; the method themselves are not shown in the item list, and the provides keyword won't detectect their availability unless they have been explicitly re-declared (overloaded) by objects, instances, classes, array bindings or blessed dictionariees.
Nevertheless, the method listed in the BOM metaclass can be applied to any item, while methods defined in specific item metaclasses derived from BOM, as i.e. the Dictionary metaclass, can be applied only to items of the reflected type.
Note: The method BOM.compare is meant to overload the behavior of generic VM comparisons, including relational operators (<, >, <=, >=, ==, !=) and generic ordering criterions, for example in Dictionary insertions and arraySort.
| Methods | |
| __add | Overrides binary addition operand. |
| __call | Overrides call operator "self()". |
| __dec | Overrides decrement unary prefix operand. |
| __decpost | Overrides decrement unary postfix operand. |
| __div | Overrides binary division operand. |
| __getIndex | Overrides array access operator [] |
| __inc | Overrides increment unary prefix operand. |
| __incpost | Overrides increment unary postifx operand. |
| __mod | Overrides modulo operand. |
| __mul | Overrides binary multiplication operand. |
| __pow | Overrides power operand. |
| __setIndex | Overrides array write operator [] |
| __sub | Overrides binary subtraction operand. |
| baseClass | Returns the class item from which an object has been instantiated. |
| bound | Determines if an item is bound or not. |
| className | Returns the name of the class an instance is instantiated from. |
| clone | Performs a deep copy of the item. |
| compare | Performs a lexicographical comparison. |
| derivedFrom | Checks if this item has a given parent. |
| describe | Returns the deep contents of an item on a string representation. |
| isCallable | Determines if an item is callable. |
| len | Retrieves the length of a collection |
| metaclass | Returns the metaclass associated with this item. |
| ptr | Returns a raw memory pointer out of this data (as an integer). |
| serialize | Serialize the item on a stream for persistent storage. |
| toString | Coverts the object to string. |
| typeId | Returns an integer indicating the type of this item. |
Overrides binary addition operand.
BOM.__add( operand )
| operand | The second operand in the expression. |
| Return | The value of self + operand. |
If an object or instance re-defines this method, when a "+" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Overrides call operator "self()".
BOM.__call( ... )
| ... | The parameters passed to the original call. |
| Return | The value of self( ... ). |
If an object or instance re-defines this method, when this object is accessed through the call operator, then this method is called instead.
This allows to create functors, as in the following example:
object sum
function __call( a, b )
return a+b
end
end
> sum( 2, 2 ) // 4
Overrides decrement unary prefix operand.
BOM.__dec( operand )
| operand | The second operand in the expression. |
| Return | The value of -- self. |
If an object or instance re-defines this method, when a "--" prefix operation is performed on this object, the method gets called.
The implementation should modify the object, and return itself modified (or value representing this object after modification).
Overrides decrement unary postfix operand.
BOM.__decpost( operand )
| operand | The second operand in the expression. |
| Return | The value of self --. |
If an object or instance re-defines this method, when a "--" postfix operation is performed on this object, the method gets called.
The implementation should keep an unmodified copy of this object, modify this instance and return the previous one, or a value representing the previous status of this object.
Overrides binary division operand.
BOM.__div( operand )
| operand | The second operand in the expression. |
| Return | The value of self / operand. |
If an object or instance re-defines this method, when a "/" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Overrides array access operator []
BOM.__getIndex( index )
| index | The index of the desired item. |
| Return | The value of self [index]. |
If an object or instance re-defines this method, when a "[]" array access operator is called to read a value from a given index, this method gets called.
The index value may be of any type.
The function should return a value or throw an AccessError if the index is considered invalid.
Overrides increment unary prefix operand.
BOM.__inc( operand )
| operand | The second operand in the expression. |
| Return | The value of ++ self. |
If an object or instance re-defines this method, when a "++" prefix operation is performed on this object, the method gets called.
The implementation should modify the object, and return itself modified (or value representing this object after modification).
Overrides increment unary postifx operand.
BOM.__incpost( operand )
| operand | The second operand in the expression. |
| Return | The value of self ++. |
If an object or instance re-defines this method, when a "++" postfix operation is performed on this object, the method gets called.
The implementation should keep an unmodified copy of this object, modify this instance and return the previous one, or a value representing the previous status of this object.
Overrides modulo operand.
BOM.__mod( operand )
| operand | The second operand in the expression. |
| Return | The value of self % operand. |
If an object or instance re-defines this method, when a "%" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Overrides binary multiplication operand.
BOM.__mul( operand )
| operand | The second operand in the expression. |
| Return | The value of self * operand. |
If an object or instance re-defines this method, when a "*" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Overrides power operand.
BOM.__pow( operand )
| operand | The second operand in the expression. |
| Return | The value of self operand. |
If an object or instance re-defines this method, when a "" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Overrides array write operator []
BOM.__setIndex( index, value )
| index | The index of the desired item. |
| value | The value that must be set. |
| Return | The value of (self [index] = value). |
If an object or instance re-defines this method, when a "[]" array access operator is called to write a value to a given index, this method gets called.
The index value may be of any type.
The function should return the same value that is being assigned, but the return value can be freely changed.
Overrides binary subtraction operand.
BOM.__sub( operand )
| operand | The second operand in the expression. |
| Return | The value of self - operand. |
If an object or instance re-defines this method, when a "-" operation is performed on this object, the method gets called.
This includes self-target operations as +=, -= and so on; in this latter case, the return value of the function will also be immediately assigned to this object.
Note: There is no guarantee that the operand type is the same of this item.
Returns the class item from which an object has been instantiated.
BOM.baseClass()
| Return | A class item or nil. |
If applied on objects, returns the class item that has been used to instantiate an object. Calling the returned item is equivalent to call the class that instantiated this object.
The returned item can be used to create another instance of the same class, or for comparisons on select branches.
If the item on which this method is applied is not an object, it returns nil.
See also: baseClass.
Determines if an item is bound or not.
BOM.bound()
| Return | True if the item is bound. |
See also: isBound.
Returns the name of the class an instance is instantiated from.
BOM.className()
| Return | The class name of an object (a string) or nil. |
If applied to objects, returns the name of the class of which the object is an instance. When applied to classes, it return the class symbolic name. In all other cases, return nil.
See also: className.
Performs a deep copy of the item.
BOM.clone()
| Return | A copy of the item. | ||
| Raise |
|
Returns an item equal to the current one, but phisically separated. If the item is a sequence, only the first level of the item gets actually cloned: vectors and dictionaries gets cloned, but the items they store are just copied. This means that the new copy of the collection itself may change, and the older version will stay untouched, but if a deep item in the collection (as an object) is changed, its change will be reflected also in the original collection.
Cloning objects causes each of their properties to be cloned. If they store an internal user data which is provided by extension modules or embedding applications, that data is cloned too. Behavior of user data is beyond the control of the script, and the data may actually be just referenced or it may also refuse to be cloned. In that case, this method will raise a CloneError, which indicates that a deep user data provided by an external module or application doesn't provide a cloning feature.
Note: Cloning objects that stores other objects referencing themselves in their properties may cause an endless loop in this version. To provide a safe duplicate of objects that may be organized in circular hierarcies, overload the clone method so that it creates a new instance of the item and just performs a flat copy of the properties.
Performs a lexicographical comparison.
BOM.compare( item )
| item | The item to which this object must be compared. |
| Return | -1, 0 or 1 depending on the comparation result. |
Performs a lexicographical comparison between the self item and the item passed as a parameter. If the item is found smaller than the parameter, it returns -1; if the item is greater than the parameter, it returns 1. If the two items are equal, it returns 0.
The compare method, if overloaded, is used by the Virtual Machine to perform tests on unknown types (i.e. objects), and to sort dictionary keys.
Item different by type are ordered by their type ID, as indicated in the documentation of the typeOf core function.
By default, string comparison is performed in UNICODE character order, and objects, classes, vectors, and dictionaries are ordered by their internal pointer address.
Checks if this item has a given parent.
BOM.derivedFrom( cls )
| cls | A symbolic class name or a class instance. |
| Return | true if the given class is one of the ancestors of this item. |
If applied on objects, returns true if the given parameter is the name of the one of the classes that compose the class hierarchy of the object.
If applied on class instances, it returns true if the parameter is its name or the name of one of its ancestors.
In all the other cases, it return false.
It is also possible to use directly the class instance as a parameter, instead of a class name. In example:
object MyError from Error
//...
end
> "Is MyError derived from 'Error' (by name)?: ", \
MyError.derivedFrom( "Error" )
> "Is MyError derived from 'Error' (by class)?: ", \
MyError.derivedFrom( Error )
See also: derivedFrom.
Returns the deep contents of an item on a string representation.
BOM.describe( [depth],[maxLen] )
| depth | Maximum inspect depth. |
| maxLen | Limit the display size of possibly very long items as i.e. strings or membufs. |
This method returns a string containing a representation of this item. If the item is deep (an array, an instance, a dictionary) the contents are also passed through this function.
This method traverses arrays and items deeply; there isn't any protection against circular references, which may cause endless loop. However, the default maximum depth is 3, which is a good depth for debugging (goes deep, but doesn't dig beyond average interesting points). Set to -1 to have infinite depth.
By default, only the first 60 characters of strings and elements of membufs are displayed. You may change this default by providing a maxLen parameter.
Determines if an item is callable.
BOM.isCallable()
| Return | true if the item is callable, false otheriwse. |
If the function returns true, then the call operator can be applied. If it returns false, the item is not a callable one, and trying to call it would cause an error.
Retrieves the length of a collection
BOM.len()
| Return | the count of items in the sequence, or 0. |
The returned value represent the "size" of this item.
See also: len.
Returns the metaclass associated with this item.
BOM.metaclass()
| Return | The metaclass of this item. |
Returns a raw memory pointer out of this data (as an integer).
BOM.ptr()
| Return | An integer containing a pointer to this data. |
The default behavior of this method is to return the value of the memory location where inner data is stored, if the data is deep, and 0 otherwise. The Integer metaclass overrides this method so that it returns a dereferenced pointer, that is, the pointer value at the location indicated by the integer value, and String items overload this so that a pointer to the raw character sequence is returned.
Serialize the item on a stream for persistent storage.
BOM.serialize( stream )
| stream | The stream on which to perform serialization. | ||
| Raise |
|
The item is stored on the stream so that a deserialize() call on the same position in the stream where serialization took place will create an exact copy of the serialized item.
The application must ensure that the item does not contains circular references, or the serialization will enter an endless loop.
In case the underlying stream write causes an i/o failure, an error is raised.
Coverts the object to string.
BOM.toString( [format] )
| format | Optional object-specific format string. |
Calling this BOM method is equivalent to call toString() core function passing the item as the first parameter.
Returns a string representation of the given item. If applied on strings, it returns the string as is, while it converts numbers with default internal conversion. Ranges are represented as "[N:M:S]" where N and M are respectively lower and higher limits of the range, and S is the step. Nil values are represented as "Nil".
The format parameter is not a Falcon format specification, but a specific optional object-specific format that may be passed to objects willing to use them. In example, the TimeStamp class uses this parameter to format its string representation.
Returns an integer indicating the type of this item.
BOM.typeId()
| Return | A constant indicating the type of the item. |
See typeOf() function for details.