Class Index | File Index

Classes


Class $class

This class encapsulates information about a class, but its constructor is used as a function (without the "new" keyword) to create a class. It is used as a constructor for private implementation purposes only. Each class created by $class has a static property named "$class" that is an instance of $class. $class instances can also be obtained by calling #getClass.
Defined in: class-debug.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
$class(name, descriptor)

Creates a class with the specified name and properties.

Method Summary
Method Attributes Method Name and Description
<static>  
$class.adapt(ctor, name)

Adapts a pre-existing class into the $class library framework.

<static>  
$class.getClass(obj)

Gets the $class object that represents the class of the specified object.

 
Gets the constructor for the class.
 
Gets the full name of the class.
 
Returns the prototype object of this class.
 
Gets the $class object of this class's parent class.
<static>  
$class.implementationOf(obj, iface)

Tests if an object is an implementation of an $interface.

 
Tests if this class implements a specific interface.
<static>  
$class.instanceOf(obj, type)

Tests if an object is an instance of a class or an implementation of an interface.

<static>  
$class.instantiate(ctor, args)

Creates a new instance of a specified class using an array of arguments.

 
Tests if an object is an instance of this class.
 
Returns true if this class is one of the standard JavaScript classes (Number, Function, etc).
<static>  
$class.resolve(name)

Gets the value of a fully qualified name, possibly nested within one or more $namespaces or namespace-like objects.

 
Overridden to return a string that identifies this $class object.
<static>  
$class.typeOf(obj)

Gets the name of the class of the specified object.

Class Detail
$class(name, descriptor)

Creates a class with the specified name and properties. Note that this documentation describes the behavior of $class when used as a method (without the "new" keyword). This should only be called as a method rather than as a constructor. Instances of $class are created as a private implementation detail of $class being called as a method.

$class supports many features, such as abstract methods, implementing interfaces, easily calling an overridden implementation of a method, and much more. See $class.descriptor for details.

The new class will have a static property named "$class" that is an instance of $class and can provide information about the class that was created by $class. Should I say "class" a few more times?

Example:

$class("Sample", {
  $constructor: function(arg) {
    this._property = arg;
  },
  
  getProperty: function() {
    return this._property;
  }
});

var sample = new Sample("Hello World!");

alert(sample.getProperty()); // alerts "Hello World"

alert(sample instanceof Sample); // alerts "true"

Parameters:
{String} name
The name of the class. The name may describe a path of multiple nested namespace/class/object names separated by a period (.). The entire path to the class name is expected to exist already. See $namespace for details about creating namespaces.
{$class.descriptor} descriptor
An object containing the properties of the class, which can describe methods, static methods, static properties, and more.
Returns:
{Function} The constructor for the newly created class.
Method Detail: adapt
<static> {Boolean} $class.adapt(ctor, name)

Adapts a pre-existing class into the $class library framework. Use this to give a pre-existing class a $class object so that it can fully participate in $class library features. For example, retroactively applied interfaces ($interface#applyInterface) will be automatically applied to all descendents of a class only if that class was defined by the $class function, or if the class was adapted with this method.

If the specified class extends another class that does not exist within the $class framework, then that parent class will be automatically adapted, but with a name that is simply the specified name with "$base" appended (there's no way for me to know the actual name of the parent class). If you want each class in the heirarchy to have the correct name, then you must adapt each class, starting from the base class.

Note that it is not necessary to adapt a class if you simply want to extend it using the $class library. When extending a class, it will be automatically adapted with a name made up of the child class's name with "$base" appended.

If any $interfaces had been applied ($interface#applyInterface) to the class or its prototype before being adapted, it will be detected when adapting the class so that the adapted class and all of its decendents will be considered to implement the interfaces.

Example:

var MyNamespace = {};

MyNamespace.Sample = function(param) {
  this._param = param;
}

MyNamespace.Sample.prototype = {
  getParam: function() {
    return 
  }
};

$class.adapt(MyNamespace.Sample, "MyNamespace.Sample");

alert(MyNamespace.Sample.$class.getName()); // alerts "MyNamespace.Sample"

Debug version warnings:

Parameters:
{Function} ctor
The constructor function of the class to be adapted.
{String} name
(optional) The full name of the class. If not specified, an anonymous name will be generated.
Returns:
{Boolean} true if the class was adapted, false if the class is already within the $class library framework at the time this method was called.
Method Detail: getClass
<static> {$class} $class.getClass(obj)

Gets the $class object that represents the class of the specified object. If the object is not an instance of a class that was created by $class or adapted with $class#adapt, then Object's $class object will be returned.

For JavaScript primitive valuesthe $class objects of of their corresponding classes will be returned.

For null and undefined, the $class objects for the dummy classes Null and Undefined will be returned (respectively).

Parameters:
{mixed} obj
any object or primitive.
Returns:
{$class} The object's class's $class object.
Method Detail: getConstructor
{Function} getConstructor()
Gets the constructor for the class.
Returns:
{Function} the constructor for the class.
Method Detail: getName
{String} getName()
Gets the full name of the class.
Returns:
{String} the full name of the class.
Method Detail: getPrototype
{Object} getPrototype()
Returns the prototype object of this class.
Returns:
{Object} The class's prototype object.
Method Detail: getSuperclass
{$class} getSuperclass()
Gets the $class object of this class's parent class.
Returns:
{$class} The $class object for this class's parent class. Returns null if this class is Object.
Method Detail: implementationOf
<static> {Boolean} $class.implementationOf(obj, iface)

Tests if an object is an implementation of an $interface. This method only tests if the object has already been marked as being an implementation of the interface; it does not actually analyze the object to determine if all interface methods are implemented. See $class.descriptor#$implements and $interface#applyInterface for performing the work of marking an object as implementing an interface.

Parameters:
{mixed} obj
any object or primitive.
{$interface} iface
any interface.
Returns:
{Boolean} true if the object implements the interface.
Method Detail: implementsInterface
{Boolean} implementsInterface(iface)
Tests if this class implements a specific interface.
Parameters:
{$interface} iface
Returns:
{Boolean} true if this class implements the interface.
Method Detail: instanceOf
<static> {Boolean} $class.instanceOf(obj, type)

Tests if an object is an instance of a class or an implementation of an interface.

This method has special handling of primitive JavaScript values to consider them to be instances of their corresponding classes. For example, var x = 5; $class.instanceOf(x, Number) will return true, but var x = 5; x instanceof Number will return false.

The $class library supplies dummy classes Null and Undefined. This method will identify null and undefined as "instances" of those classes (respectively).

If you do not need the special handling of primitive values, and the type is never going to be an interface, then you can simply use the JavaScript instanceof operator for any classes created by $class.

Parameters:
{mixed} obj
any object or primitive.
{Function|$interface} type
A constructor function of some class, or an interface.
Returns:
{Boolean} true if the object is an instance of the specified class (or implementation of the specified interface).
Method Detail: instantiate
<static> {mixed} $class.instantiate(ctor, args)

Creates a new instance of a specified class using an array of arguments.

For "native" JavaScript classes (those defined by the ECMAScript spec, such as Number, RegExp, etc), the result of calling the constructor as a function will be returned. For classes that have corresponding primitive types (Number, Boolean, String), this means that a primitive value will be returned instead of an instance of the class. This is usually preferred for reasons such as instances of Strings, Boolean and Number always evaluating to a boolean value of true even if their values are false-like.

Example:

$class("Person", {
  $constructor: function(firstName, lastName) {
    this._firstName = firstName;
    this._lastName) = lastName);
  },
  
  getFullName: function() {
    return this._firstName + " " + this._lastName;
  }
});

var person = $class.instantiate(Person, ["John", "Doe"]);
alert(person.getFullName()) // alerts "John Doe"

var number = $class.instantiate(Number, ["123"]);
alert(number) // alerts "123"
alert(typeof number) // alerts "number"
alert(number instanceof Number) // alerts "false"

Parameters:
{Function} ctor
The constructor function for some class.
{Array} args
An array of argument values to be passed to the constructor.
Returns:
{mixed} A new instance of the specified class (or a primitive value).
Method Detail: isInstance
{Boolean} isInstance(obj)
Tests if an object is an instance of this class.
Parameters:
{Object} obj
Returns:
{Boolean} true if the object is an instance of this class, or any of its child classes.
Method Detail: isNative
{Boolean} isNative()
Returns true if this class is one of the standard JavaScript classes (Number, Function, etc).
Returns:
{Boolean} true if this class is one of the standard JavaScript classes.
Method Detail: resolve
<static> {mixed} $class.resolve(name)

Gets the value of a fully qualified name, possibly nested within one or more $namespaces or namespace-like objects. Does not cause an error if any object along the path is undefined/null. Simply returns undefined of the specified name could not be reached.

Example:

$namespace("nested.namespace");

nested.namespaces.SOME_VALUE = 10;

alert($class.resolve("nested.namespace.SOME_VALUE")) // alerts "10"

alert($class.resolve("nonexistant.namespace.SOME_VALUE")) // alerts "undefined"

Parameters:
{String} name
The fully qualified name of some object/value.
Returns:
{mixed} the value found at the specified name, or undefined if it could not be reached.
Method Detail: toString
{String} toString()
Overridden to return a string that identifies this $class object.
Returns:
{String} a string in the form "[$class _name_]", where _name_ is the full name of this class.
Method Detail: typeOf
<static> {String} $class.typeOf(obj)

Gets the name of the class of the specified object. If the object is not an instance of a class that was created by $class or adapted with $class#adapt, then it will be identified generically as "Object".

JavaScript primitive values will be reported as being instances of their corresponding classes.

The $class library supplies dummy classes Null and Undefined. This method will identify null and undefined as "Null" and "Undefined" (respectively).

Example:

$namespace("nested.namespace");

$class("nested.namespace.Example", {});

var example = new Example();

alert($class.typeOf(example)) // alerts "nested.namespace.Example"
alert($class.typeOf(5)) // alerts "5"
alert($class.typeOf(null)) // alerts "Null"

Parameters:
{mixed} obj
any object or primitive.
Returns:
{String} the name of the class of the object.

Documentation generated by JsDoc Toolkit 2.3.2 on Sat Nov 13 2010 01:18:48 GMT-0500 (EST)