An object in ColdC is both a data type and a database record. Objects are structured with parents and children in a tree (geneology-style) hierarchy known as the object hierarchy. An object has both ColdC procedures (methods) and ColdC data (variables) bound to it. The object variables are accessed and modified by the methods defined on the object.
Referencing Objects
Objects exist within the database, and are referenced with a unique object number (objnum), which is assigned to the object upon its creation in the database. Object numbers cannot be changed after an object is created. When an object is destroyed, it's objnum is not re-used by the driver unless the database is decompiled to text and recompiled.
An object can also have an object name (objname) assigned to it, which can be changed througout the life of the object. Object names are only unique to that object while the object has the name. Once the name is changed the old name can be taken by another object. Object names exist for practical functionality, as it is easier to remember references which consist of alphabetic and numeric characters than references which are simply numeric.
In ColdC, an object number is designated with a hash mark (#) followed by the object's number. For instance #23 refers to object number 23. An object name is designated as an identifier beginning with a dollar sign ($). For instance, if the object #23 has the name object_23 assigned to it, it would be formatted in ColdC as $object_23.
A negative object number will appear if there is no object in the database with the given object number—that is, if it is an invalid object number. This is true for all cases, except #-1, which is the generic invalid object number.
Both the object number and object name are generically called database references (dbrefs). When the driver formats a database reference the object name will take precedence over an object number because the name is generally easier to remember and comprehend.
When the interpreter encounters an object name, it looks up the number associated with that name in a table. If no object has been assigned to that name, a ~namenf error is thrown; otherwise the object name is equivalent to the object number when executing functions and methods.
Methods
A method is a series of ColdC statements which are grouped together as a procedure to perform a task. Method's are given a name and bound to a specific object. Methods determine the object's behavior. Methods have a specific structure to them. The number of arguments they will accept is defined at the beginning of the method, followed by the definition of all the variables used within the method. Subsequent lines compose the actual method code (see Methods for more information on method structure).
When descendants of an object wish to change their behavior, they may define their own methods, or override a method defined on an ancestor. A method is overriden by simply giving it the same name as an existing method on an ancestor of the object. When a method is called, the interpreter looks for it first on the object, then on the object's ancestors. If this occurs, it is possible for a method overriding another to stop executing and pass back to the method on its ancestor, and then resume executing when the overriden method completes executing. It is possible for a method to disallow descendants to override a method, see Method Flags.
Variables
In ColdC there are two types of variables, local variables and object variables. An object variable is defined on the object, and can be accessed by any method defined on the same object. Object variables exist outside of the scope of methods. Local variables are defined within a method, with their scope being limited to that method. Object variables will always exist until they are explicitly removed. Local variables only exist while the method defining them is executing.
If a variable is used within the body of a method, but it is not defined as an argument or a local variable (at the top of the method), it is assumed to be an object variable. When the method is executed, the interpreter looks on the object for the variable. If the interpreter cannot find the variable on the object, the error ~varnf is thrown.
It is important to remember that object variables may only be accessed by methods defined by the same object defining the variable. No other method may reference that variable. For instance, assume two objects exist as $obj_a and $obj_b, where $obj_b is a child of $obj_a. $obj_a defines the variable text and the methods set_text and get_text:
object $obj_a: $root;
var $obj_a text;
public method $obj_a.get_text {
return text;
};
public method $obj_a.set_text {
arg new_text;
text = new_text;
};
Calling $obj_a.set_text("text") will set $obj_a's instance of the object variable text to "text". $obj_b inherits the ability to use and write to it's own instance of text (using methods defined on $obj_a), but it does not inherit values assigned to the same object variable on its ancestors. For instance, calling $obj_b.get_text() will currently return 0 (the default unset value), as it's instance of text has not yet been defined, even though $obj_a's instance of text has been defined. This is called encapsulation. Calling $obj_b.set_text("more") would set $obj_b's instance of text to "more". If, following this, $obj_b were to override the method get_text defined on $obj_a as
public method $obj_b.get_text {
return "more text: " + text;
};
calling $obj_b.get_text() would cause the error ~varnf to be thrown, rather than having "more text: more" returned. This is because the object variable text is not defined by $obj_b (where the new get_text is defined), even though it has its own instance from $obj_a.
Another way to look at this is from a C++ perspective. All object variables in ColdC are equivalent to private object variables in C++.
Special Objects
There are always two objects which exists within a ColdC database. The first object is $root (#1). The root object has no parents, and is the base for all other objects. This is a requirement in order to allow for a secure database to be created.
The second object is $sys (#0). The system object is the only object the driver directly calls methods on without previously setting up with the driver (i.e. connections). These methods include $sys.startup(), $sys.heartbeat() and $sys.signal().
The root and system objects are automatically created by the database compiler.
