1.2.2Class BOM

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
__addOverrides binary addition operand.
__callOverrides call operator "self()".
__decOverrides decrement unary prefix operand.
__decpostOverrides decrement unary postfix operand.
__divOverrides binary division operand.
__getIndexOverrides array access operator []
__incOverrides increment unary prefix operand.
__incpostOverrides increment unary postifx operand.
__modOverrides modulo operand.
__mulOverrides binary multiplication operand.
__powOverrides power operand.
__setIndexOverrides array write operator []
__subOverrides binary subtraction operand.
baseClassReturns the class item from which an object has been instantiated.
boundDetermines if an item is bound or not.
classNameReturns the name of the class an instance is instantiated from.
clonePerforms a deep copy of the item.
comparePerforms a lexicographical comparison.
derivedFromChecks if this item has a given parent.
describeReturns the deep contents of an item on a string representation.
isCallableDetermines if an item is callable.
lenRetrieves the length of a collection
metaclassReturns the metaclass associated with this item.
ptrReturns a raw memory pointer out of this data (as an integer).
serializeSerialize the item on a stream for persistent storage.
toStringCoverts the object to string.
typeIdReturns an integer indicating the type of this item.

Methods

__add

Overrides binary addition operand.

BOM.__add( operand )
operand The second operand in the expression.
ReturnThe 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.

__call

Overrides call operator "self()".

BOM.__call( ... )
... The parameters passed to the original call.
ReturnThe 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

__dec

Overrides decrement unary prefix operand.

BOM.__dec( operand )
operand The second operand in the expression.
ReturnThe 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).

__decpost

Overrides decrement unary postfix operand.

BOM.__decpost( operand )
operand The second operand in the expression.
ReturnThe 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.

__div

Overrides binary division operand.

BOM.__div( operand )
operand The second operand in the expression.
ReturnThe 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.

__getIndex

Overrides array access operator []

BOM.__getIndex( index )
index The index of the desired item.
ReturnThe 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.

__inc

Overrides increment unary prefix operand.

BOM.__inc( operand )
operand The second operand in the expression.
ReturnThe 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).

__incpost

Overrides increment unary postifx operand.

BOM.__incpost( operand )
operand The second operand in the expression.
ReturnThe 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.

__mod

Overrides modulo operand.

BOM.__mod( operand )
operand The second operand in the expression.
ReturnThe 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.

__mul

Overrides binary multiplication operand.

BOM.__mul( operand )
operand The second operand in the expression.
ReturnThe 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.

__pow

Overrides power operand.

BOM.__pow( operand )
operand The second operand in the expression.
ReturnThe 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.

__setIndex

Overrides array write operator []

BOM.__setIndex( index, value )
index The index of the desired item.
value The value that must be set.
ReturnThe 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.

__sub

Overrides binary subtraction operand.

BOM.__sub( operand )
operand The second operand in the expression.
ReturnThe 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.

baseClass

Returns the class item from which an object has been instantiated.

BOM.baseClass()
ReturnA 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.

bound

Determines if an item is bound or not.

BOM.bound()
ReturnTrue if the item is bound.

See also: isBound.

className

Returns the name of the class an instance is instantiated from.

BOM.className()
ReturnThe 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.

clone

Performs a deep copy of the item.

BOM.clone()
ReturnA copy of the item.
Raise
CloneError if the item is not cloneable.

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.

compare

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.

derivedFrom

Checks if this item has a given parent.

BOM.derivedFrom( cls )
cls A symbolic class name or a class instance.
Returntrue 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.

describe

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.

isCallable

Determines if an item is callable.

BOM.isCallable()
Returntrue 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.

len

Retrieves the length of a collection

BOM.len()
Returnthe count of items in the sequence, or 0.

The returned value represent the "size" of this item.

See also: len.

metaclass

Returns the metaclass associated with this item.

BOM.metaclass()
ReturnThe metaclass of this item.

ptr

Returns a raw memory pointer out of this data (as an integer).

BOM.ptr()
ReturnAn 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

Serialize the item on a stream for persistent storage.

BOM.serialize( stream )
stream The stream on which to perform serialization.
Raise
IoError on stream errors.

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.

toString

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.

typeId

Returns an integer indicating the type of this item.

BOM.typeId()
ReturnA constant indicating the type of the item.

See typeOf() function for details.

Made with http://www.falconpl.org