1
0
Fork 0
easejs/lib/class.js

1015 lines
29 KiB
JavaScript
Raw Normal View History

/**
* Contains basic inheritance mechanism
*
* Copyright (C) 2010 Mike Gerwitz
*
* This file is part of ease.js.
*
* ease.js is free software: you can redistribute it and/or modify it under the
* terms of the GNU Lesser General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* @author Mike Gerwitz
* @package core
*/
2011-01-21 00:03:41 -05:00
var util = require( './util' ),
member_builder = require( './member_builder' ),
propobj = require( './propobj' )
;
2010-11-15 23:22:24 -05:00
/*
* IE contains a nasty enumeration "bug" (poor implementation) that makes
* toString unenumerable. This means that, if you do obj.toString = foo,
* toString will NOT show up in `for` or hasOwnProperty(). This is a problem.
*
* This test will determine if this poor implementation exists.
*/
var enum_bug = (
Object.prototype.propertyIsEnumerable.call(
{ toString: function() {} },
'toString'
) === false
)
? true
: false
;
/**
* This module may be invoked in order to provide a more natural looking class
* definition mechanism
*
* This may not be used to extend existing classes. To extend an existing class,
* use the class's extend() method. If unavailable (or extending a non-ease.js
* class/object), use the module's extend() method.
*
2011-03-04 00:17:25 -05:00
* @param {string=} name optional name
* @param {Object} def class definition
*
* @return {Class} new class
*/
module.exports = function()
{
var type = typeof arguments[ 0 ],
result = null
2011-03-04 00:24:42 -05:00
;
2011-03-04 00:24:42 -05:00
switch ( type )
{
2011-03-04 00:24:42 -05:00
// anonymous class
case 'object':
result = createAnonymousClass.apply( null, arguments );
2011-03-04 00:24:42 -05:00
break;
2011-03-04 00:24:42 -05:00
// named class
case 'string':
result = createNamedClass.apply( null, arguments );
2011-03-04 00:24:42 -05:00
break;
default:
// we don't know what to do!
throw TypeError(
"Expecting anonymous class definition or named class definition"
);
}
return result;
};
/**
* Creates a class, inheriting either from the provided base class or the
* default base class
*
* @param {Object} base object to extend (extends Class by default)
*
* @return {Object} extended class
*/
module.exports.extend = function( base )
{
return extend.apply( this, arguments );
};
/**
* Implements an interface or set of interfaces
*
* @param {...Interface} interfaces interfaces to implement
*
* @return {Class} new class containing interface abstractions
*/
module.exports.implement = function()
{
// implement on empty base
return createImplement(
module.exports.extend(),
Array.prototype.slice.call( arguments )
);
};
/**
* Determines whether the provided object is a class created through ease.js
*
* @param {Object} obj object to test
*
* @return {boolean} true if class (created through ease.js), otherwise false
*/
module.exports.isClass = function( obj )
{
obj = obj || {};
return ( obj.prototype instanceof Class )
? true
: false
;
};
/**
* Determines whether the provided object is an instance of a class created
* through ease.js
*
* @param {Object} obj object to test
*
* @return {boolean} true if instance of class (created through ease.js),
* otherwise false
*/
module.exports.isClassInstance = function( obj )
{
obj = obj || {};
return ( obj instanceof Class )
? true
: false;
};
/**
* Determines if the class is an instance of the given type
*
* The given type can be a class, interface, trait or any other type of object.
* It may be used in place of the 'instanceof' operator and contains additional
* enhancements that the operator is unable to provide due to prototypal
* restrictions.
*
* @param {Object} type expected type
* @param {Object} instance instance to check
*
* @return {boolean} true if instance is an instance of type, otherwise false
*/
module.exports.isInstanceOf = function( type, instance )
{
var meta, implemented, i;
try
{
// check prototype chain (with throw an error if type is not a
// constructor (function)
if ( instance instanceof type )
{
return true;
}
}
catch ( e ) {}
// if no metadata is available, then our remaining checks cannot be
// performed
if ( !instance.__cid || !( meta = getMeta( instance ) ) )
{
return false;
}
implemented = meta.implemented;
i = implemented.length;
// check implemented interfaces
while ( i-- )
{
if ( implemented[ i ] === type )
{
return true;
}
}
return false;
};
/**
* Alias for isInstanceOf()
*
* May read better in certain situations (e.g. Cat.isA( Mammal )) and more
* accurately conveys the act of inheritance, implementing interfaces and
* traits, etc.
*/
module.exports.isA = module.exports.isInstanceOf;
/**
* Default class implementation
*
* @return undefined
*/
function Class() {};
/**
* Creates a new anonymous Class from the given class definition
*
* @param {Object} def class definition
*
* @return {Class} new anonymous class
*/
function createAnonymousClass( def )
{
// ensure we have the proper number of arguments (if they passed in
// too many, it may signify that they don't know what they're doing,
// and likely they're not getting the result they're looking for)
if ( arguments.length > 1 )
{
throw Error(
"Expecting one argument for anonymous Class definition; " +
arguments.length + " given."
);
}
return extend( def );
}
/**
* Creates a new named Class from the given class definition
*
* @param {string} name class name
* @param {Object} def class definition
*
* @return {Class} new named class
*/
function createNamedClass( name, def )
{
// if too many arguments were provided, it's likely that they're
// expecting some result that they're not going to get
if ( arguments.length > 2 )
{
throw Error(
"Expecting two arguments for definition of named Class '" + name +
"'; " + arguments.length + " given."
);
}
// if no definition was given, return a staging object, to apply the name to
// the class once it is actually created
if ( def === undefined )
{
return createStaging( name );
}
// the definition must be an object
else if ( typeof def !== 'object' )
{
throw TypeError(
"Unexpected value for definition of named Class '" + name +
"'; object expected"
);
}
// add the name to the definition
def.__name = name;
return extend( def );
}
2010-11-14 22:07:04 -05:00
/**
* Creates a staging object to stage a class name
*
* The class name will be applied to the class generated by operations performed
* on the staging object. This allows applying names to classes that need to be
* extended or need to implement interfaces.
*
* @param {string} cname desired class name
*
* @return {Object} object staging the given class name
*/
function createStaging( cname )
{
return {
extend: function()
{
var args = Array.prototype.slice.apply( arguments );
// extend() takes a maximum of two arguments. If only one
// argument is provided, then it is to be the class definition.
// Otherwise, the first argument is the supertype and the second
// argument is the class definition. Either way you look at it,
// the class definition is always the final argument.
//
// We want to add the name to the definition.
args[ args.length - 1 ].__name = cname;
return extend.apply( null, args );
},
implement: function()
{
// implement on empty base, providing the class name to be used once
// extended
return createImplement(
extend( {} ),
Array.prototype.slice.call( arguments ),
cname
);
},
};
}
/**
* Creates an intermediate object to permit implementing interfaces
*
* This object defers processing until extend() is called. This intermediate
* object ensures that a usable class is not generated until after extend() is
* called, as it does not make sense to create a class without any
* body/definition.
*
* @param {Object} base base class to implement atop of
* @param {Array} ifaces interfaces to implement
* @param {string=} cname optional class name once extended
*
* @return {Object} intermediate implementation object
*/
function createImplement( base, ifaces, cname )
{
ifaces.push( base );
// Defer processing until after extend(). This also ensures that implement()
// returns nothing usable.
return {
extend: function( def )
{
// if a name was provided, use it
if ( cname )
{
def.__name = cname;
}
return extend.apply( null, [
implement.apply( this, ifaces ),
def
] );
},
};
}
2010-11-14 22:07:04 -05:00
/**
* Creates extend function
*
* The 'extending' parameter is used to override the functionality of abstract
* class constructors, allowing them to be instantiated for use in a subclass's
* prototype.
*
* @param {boolean} extending whether a class is currently being extended
*
* @return {Function} extend function
*/
var extend = ( function( extending )
{
var class_id = 0,
instance_id = 0;
/**
* Mimics class inheritance
*
* This method will mimic inheritance by setting up the prototype with the
* provided base class (or, by default, Class) and copying the additional
* properties atop of it.
*
* The class to inherit from (the first argument) is optional. If omitted, the
* first argument will be considered to be the properties list.
*
* @return {Object} extended class
*/
return function extend()
{
// ensure we'll be permitted to instantiate abstract classes for the base
extending = true;
var args = Array.prototype.slice.call( arguments ),
props = args.pop() || {},
base = args.pop() || Class,
prototype = new base(),
cname = '',
hasOwn = Array.prototype.hasOwnProperty;
var properties = {},
prop_init = member_builder.initMembers(),
members = member_builder.initMembers( prototype ),
abstract_methods =
util.clone( getMeta( base ).abstractMethods )
|| { __length: 0 }
;
// grab the name, if one was provided
if ( cname = props.__name )
{
// we no longer need it
delete props.__name;
}
// IE has problems with toString()
if ( enum_bug )
{
if ( props.toString !== Object.prototype.toString )
{
props.__toString = props.toString;
}
}
// increment class identifier
class_id++;
util.propParse( props, {
each: function( name, value, keywords )
{
// disallow use of our internal __initProps() method
if ( name === '__initProps' )
{
throw new Error(
( ( cname ) ? cname + '::' : '' ) +
"__initProps is a reserved method"
);
}
},
property: function( name, value, keywords )
{
properties[ name ] = value;
// build a new property, passing in the other members to compare
// against for preventing nonsensical overrides
member_builder.buildProp(
prop_init, null, name, value, keywords, members
);
},
getter: function( name, value, keywords )
{
member_builder.buildGetter(
members, null, name, value, keywords
);
},
setter: function( name, value, keywords )
{
member_builder.buildSetter(
members, null, name, value, keywords
);
},
method: function( name, func, is_abstract, keywords )
{
member_builder.buildMethod(
members, null, name, func, keywords, getMethodInstance,
class_id
);
if ( is_abstract )
{
abstract_methods[ name ] = true;
abstract_methods.__length++;
}
else if ( ( hasOwn.call( abstract_methods, name ) )
&& ( is_abstract === false )
)
{
// if this was a concrete method, then it should no longer
// be marked as abstract
delete abstract_methods[ name ];
abstract_methods.__length--;
}
},
methodOverride: function( name, pre, func )
{
return util.overrideMethod(
name, pre, func, abstract_methods
);
},
} );
// reference to the parent prototype (for more experienced users)
prototype.___$$parent$$ = base.prototype;
// set up the new class
var new_class = createCtor( cname, abstract_methods, members );
attachPropInit( prototype, prop_init, members, class_id );
new_class.prototype = prototype;
new_class.constructor = new_class;
// important: call after setting prototype
setupProps( new_class, abstract_methods, class_id );
// create internal metadata for the new class
var meta = createMeta( new_class, base );
meta.abstractMethods = abstract_methods;
meta.name = cname;
// lock down the new class (if supported) to ensure that we can't add
// members at runtime
util.freeze( new_class );
// we're done with the extension process
extending = false;
return new_class;
};
/**
* Creates the constructor for a new class
*
* This constructor will call the __constructor method for concrete classes
* and throw an exception for abstract classes (to prevent instantiation).
*
* @param {string} cname class name (may be empty)
* @param {Array.<string>} abstract_methods list of abstract methods
* @param {Object} members class members
*
* @return {Function} constructor
*/
function createCtor( cname, abstract_methods, members )
{
// concrete class
if ( abstract_methods.__length === 0 )
{
var args = null;
// constructor function to be returned
var __self = function()
{
if ( !( this instanceof __self ) )
{
// store arguments to be passed to constructor and
// instantiate new object
args = arguments;
return new __self();
}
// generate and store unique instance id
attachInstanceId( this, ++instance_id, __self );
initInstance( instance_id, this );
this.__initProps();
// call the constructor, if one was provided
if ( this.__construct instanceof Function )
{
// note that since 'this' refers to the new class (even
// subtypes), and since we're using apply with 'this', the
// constructor will be applied to subtypes without a problem
this.__construct.apply( this, ( args || arguments ) );
args = null;
}
// attach any instance properties/methods (done after
// constructor to ensure they are not overridden)
attachInstanceOf( this );
// Provide a more intuitive string representation of the class
// instance. If a toString() method was already supplied for us,
// use that one instead.
if ( !( Object.prototype.hasOwnProperty.call(
members[ 'public' ], 'toString'
) ) )
{
// use __toString if available (see enum_bug), otherwise use
// our own defaults
this.toString = members[ 'public' ].__toString
|| ( ( cname )
? function()
{
return '#<' + cname + '>';
}
: function()
{
return '#<anonymous>';
}
)
;
}
};
// provide a more intuitive string representation
__self.toString = ( cname )
? function() { return cname; }
: function() { return '(Class)'; }
;
return __self;
}
// abstract class
else
{
var __abstract_self = function()
{
if ( !extending )
{
throw Error(
"Abstract class " + ( cname || '(anonymous)' ) +
" cannot be instantiated"
);
}
};
__abstract_self.toString = ( cname )
? function()
{
return cname;
}
: function()
{
return '(AbstractClass)';
}
;
return __abstract_self;
}
}
} )( false );
/**
* Implements interface(s) into an object
*
2011-01-10 19:56:09 -05:00
* This will copy all of the abstract methods from the interface and merge it
* into the given object.
*
2011-01-10 19:56:09 -05:00
* @param {Object} base base object
* @param {...Interface} interfaces interfaces to implement into dest
*
* @return {Object} destination object with interfaces implemented
*/
var implement = function()
{
var args = Array.prototype.slice.call( arguments ),
2011-01-10 19:56:09 -05:00
dest = {},
base = args.pop(),
len = args.length,
arg = null,
abstract_list = [],
implemented = [];
// add each of the interfaces
for ( var i = 0; i < len; i++ )
{
arg = args[ i ];
// copy all interface methods to the class (does not yet deep copy)
2011-01-24 23:38:27 -05:00
util.propParse( arg.prototype, {
method: function( name, func, is_abstract, keywords )
{
dest[ name ] = func;
},
} );
implemented.push( arg );
}
2011-01-10 19:56:09 -05:00
// create a new class with the implemented abstract methods
var class_new = module.exports.extend( base, dest );
getMeta( class_new ).implemented = implemented;
return class_new;
}
/**
* Sets up common properties for the provided function (class)
*
* @param {function()} func function (class) to set up
* @param {Array.<string>} abstract_methods list of abstract method names
* @param {number} class_id unique id to assign to class
*
* @return {undefined}
*/
function setupProps( func, abstract_methods, class_id )
{
2010-12-28 22:08:30 -05:00
attachAbstract( func, abstract_methods );
attachExtend( func );
2011-01-10 19:56:09 -05:00
attachImplement( func );
attachId( func, class_id );
}
/**
* Initializes class instance
*
* This process will create the instance visibility object containing private
* and protected members. The class instance is part of the prototype chain.
* This will be passed to all methods when invoked, permitting them to access
* the private and protected members while keeping them encapsulated.
*
* For each instance, there is always a base. The base will contain a proxy to
* the public members on the instance itself. The base will also contain all
* protected members.
*
* Atop the base object is a private member object, with the base as its
* prototype. There exists a private member object for the instance itself and
* one for each supertype. This is stored by the class id (cid) as the key. This
* permits the private member object associated with the class of the method
* call to be bound to that method. For example, if a parent method is called,
* that call must be invoked in the context of the parent, so the private
* members of the parent must be made available.
*
* The resulting structure looks something like this:
* class_instance = { iid: { cid: {} } }
*
* @param {number} iid instance id
* @param {Object} instance instance to initialize
*
* @return {undefined}
*/
function initInstance( iid, instance )
{
var prot = function() {};
prot.prototype = instance;
// add the visibility objects to the data object for this class instance
instance.___$$vis$$ = new prot();
}
/**
* Attaches __initProps() method to the class prototype
*
* The __initProps() method will initialize class properties for that instance,
* ensuring that their data is not shared with other instances (this is not a
* problem with primitive data types).
*
* The method will also initialize any parent properties (recursive) to ensure
* that subtypes do not have a referencing issue, and subtype properties take
* precedence over those of the parent.
*
* @param {Object} prototype prototype to attach method to
* @param {Object} properties properties to initialize
* @param {number} cid class id
*
* @param {{public: Object, protected: Object, private: Object}} members
*
* @return {undefined}
*/
function attachPropInit( prototype, properties, members, cid )
{
util.defineSecureProp( prototype, '__initProps', function( inherit )
{
// defaults to false, sid = super identifier
inherit = !!inherit;
var iid = this.__iid;
// first initialize the parent's properties, so that ours will overwrite
// them
var parent_init = prototype.___$$parent$$.__initProps;
if ( parent_init instanceof Function )
{
// call the parent prop_init, letting it know that it's been
// inherited so that it does not initialize private members or
// perform other unnecessary tasks
parent_init.call( this, true );
}
// this will return our property proxy, if supported by our environment,
// otherwise just a normal object with everything merged in
var inst_props = propobj.createPropProxy(
this, this.___$$vis$$, properties[ 'public' ]
);
// if we're inheriting, perform a setup that doesn't include everything
// that we don't want (e.g. private properties)
this.___$$vis$$[ cid ] = propobj.setup(
inst_props, properties, members
);
});
}
2010-11-14 01:10:55 -05:00
/**
* Attaches isAbstract() method to the class
*
* @param {Function} func function (class) to attach method to
* @param {Array} methods abstract method names
*
* @return {undefined}
*/
2010-12-28 22:08:30 -05:00
function attachAbstract( func, methods )
2010-11-14 01:10:55 -05:00
{
var is_abstract = ( methods.__length > 0 ) ? true: false;
2010-11-14 01:10:55 -05:00
/**
* Returns whether the class contains abstract methods (and is therefore
* abstract)
*
* @return {Boolean} true if class is abstract, otherwise false
*/
util.defineSecureProp( func, 'isAbstract', function()
2010-11-14 01:10:55 -05:00
{
return is_abstract;
});
2010-11-14 01:10:55 -05:00
}
/**
* Attaches extend method to the given function (class)
*
* @param {Function} func function (class) to attach method to
*
* @return {undefined}
*/
2010-12-28 22:08:30 -05:00
function attachExtend( func )
{
/**
* Shorthand for extending classes
*
2010-12-01 23:19:59 -05:00
* This method can be invoked on the object, rather than having to call
* Class.extend( this ).
*
* @param {Object} props properties to add to extended class
*
* @return {Object} extended class
*/
util.defineSecureProp( func, 'extend', function( props )
2010-11-10 23:28:20 -05:00
{
return extend( this, props );
2010-11-14 22:07:04 -05:00
});
}
2011-01-10 19:56:09 -05:00
/**
* Attaches implement method to the given function (class)
*
* Please see the implement() export of this module for more information.
*
2011-01-10 19:56:09 -05:00
* @param {function()} func function (class) to attach method to
*
* @return {undefined}
*/
function attachImplement( func )
{
util.defineSecureProp( func, 'implement', function()
{
return createImplement(
func,
Array.prototype.slice.call( arguments )
);
2011-01-10 19:56:09 -05:00
});
}
/**
* Attaches the unique id to the class and its prototype
*
* The unique identifier is used internally to match a class and its instances
* with the class metadata. Exposing the id breaks encapsulation to a degree,
* but is a lesser evil when compared to exposing all metadata.
*
* @param {Function} func function (class) to attach method to
* @param {number} id id to assign
*
* @return {undefined}
*/
function attachId( func, id )
{
util.defineSecureProp( func, '__cid', id );
util.defineSecureProp( func.prototype, '__cid', id );
}
/**
* Attaches an instance identifier to a class instance
*
* @param {Object} instance class instance
* @param {number} iid instance id
*
* @return {undefined}
*/
function attachInstanceId( instance, iid )
{
util.defineSecureProp( instance, '__iid', iid );
}
/**
* Attaches partially applied isInstanceOf() method to class instance
*
* @param {Object} instance class instance to attach method to
*
* @return {undefined}
*/
function attachInstanceOf( instance )
{
var method = function( type )
{
return module.exports.isInstanceOf( type, instance );
};
util.defineSecureProp( instance, 'isInstanceOf', method );
util.defineSecureProp( instance, 'isA', method );
}
/**
* Initializes class metadata for the given class
*
* @param {Class} func class to initialize metadata for
* @param {Class} cparent class parent
*
* @return {undefined}
*/
function createMeta( func, cparent )
{
var id = func.__cid,
parent_meta = ( ( cparent.__cid ) ? getMeta( cparent ) : undefined );
// copy the parent prototype's metadata if it exists (inherit metadata)
if ( parent_meta )
{
func.___$$meta$$ = util.clone( parent_meta, true );
}
else
{
// create empty
func.___$$meta$$ = {
implemented: [],
};
}
// store the metadata in the prototype as well (inconsiderable overhead;
// it's just a reference)
func.prototype.___$$meta$$ = func.___$$meta$$;
return func.___$$meta$$;
}
/**
* Returns reference to metadata for the requested class
*
* Since a reference is returned (rather than a copy), the returned object can
* be modified to alter the metadata.
*
2011-03-15 00:17:02 -04:00
* @param {Class} cls class from which to retrieve metadata
*
* @return {Object}
*/
function getMeta( cls )
{
return cls.___$$meta$$ || {};
}
/**
* Returns the instance object associated with the given method
*
* The instance object contains the protected members. This object can be passed
* as the context when calling a method in order to give that method access to
* those members.
*
* One level above the instance object on the prototype chain is the object
* containing the private members. This is swappable, depending on the class id
* associated with the provided method call. This allows methods that were not
* overridden by the subtype to continue to use the private members of the
* supertype.
*
2011-03-15 00:17:02 -04:00
* @param {function()} inst instance that the method is being called from
* @param {number} cid class id
*
* @return {Object,null} instance object if found, otherwise null
*/
function getMethodInstance( inst, cid )
{
var iid = inst.__iid,
data = inst.___$$vis$$;
return ( iid && data )
? data[ cid ]
: null
;
}