1
0
Fork 0
easejs/lib/MemberBuilder.js

582 lines
18 KiB
JavaScript
Raw Permalink Normal View History

/**
* Handles building members (properties, methods)
*
* Copyright (C) 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
*
* This file is part of GNU ease.js.
*
* ease.js is free software: you can redistribute it and/or modify
* it under the terms of the GNU 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* This prototype could have easily been refactored into a number of others
* (e.g. one for each type of member), but that refactoring has been
* deferred until necessary to ensure ease.js maintains a relatively small
* footprint. Ultimately, however, such a decision is a micro-optimization
* and shouldn't harm the design and maintainability of the software.
*
* TODO: Implementation is inconsistent between various members. For
* example, methods use ___$$keywords$$, whereas properties use [ val,
* keywords ]. Decide on a common format.
*/
var util = require( './util' ),
visibility = [ 'public', 'protected', 'private' ]
;
/**
* Responsible for building class members
*
* @param {Function} wrap_method method wrapper
* @param {Function} wrap_override method override wrapper
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
* @param {Function} wrap_proxy method proxy wrapper
* @param {MemberBuilderValidator} validate member validator
*
* @constructor
*/
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
module.exports = function MemberBuilder(
wrap_method, wrap_override, wrap_proxy, validate
)
{
// permit omitting 'new' keyword
if ( !( this instanceof module.exports ) )
{
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
return new module.exports(
wrap_method, wrap_override, wrap_proxy, validate
);
}
this._wrapMethod = wrap_method;
this._wrapOverride = wrap_override;
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
this._wrapProxy = wrap_proxy;
this._validate = validate;
};
// we're throwing everything into the prototype
exports = module.exports.prototype;
/**
* Initializes member object
*
* The member object contains members for each level of visibility (public,
* protected and private).
*
* @param {Object} mpublic default public members
* @param {Object} mprotected default protected members
* @param {Object} mprivate default private members
*
* @return {__visobj}
*/
exports.initMembers = function( mpublic, mprotected, mprivate )
{
return {
'public': mpublic || {},
'protected': mprotected || {},
'private': mprivate || {},
};
};
/**
* Copies a method to the appropriate member prototype, depending on
* visibility, and assigns necessary metadata from keywords
*
* The provided ``member run'' state object is required and will be
* initialized automatically if it has not been already. For the first
* member of a run, the object should be empty.
*
* @param {__visobj} members
* @param {!Object} meta metadata container
* @param {string} name property name
* @param {*} value property value
*
* @param {!Object.<boolean>} keywords parsed keywords
*
* @param {Function} instCallback function to call in order to retrieve
* object to bind 'this' keyword to
*
* @param {number} cid class id
* @param {Object=} base optional base object to scan
*
* @param {Object} state member run state object
*
* @return {undefined}
*/
exports.buildMethod = function(
members, meta, name, value, keywords, instCallback, cid, base, state
)
{
// these defaults will be used whenever a keyword set is unavailable,
// which should only ever be the case if we're inheriting from a
// prototype rather than an ease.js class/etc
var kdefaults = this._methodKeywordDefaults;
// TODO: We can improve performance by not scanning each one individually
// every time this method is called
var prev_data = scanMembers( members, name, base ),
prev = ( prev_data ) ? prev_data.member : null,
prev_keywords = ( prev && ( prev.___$$keywords$$ || kdefaults ) ),
dest = getMemberVisibility( members, keywords, name );
;
// ensure that the declaration is valid (keywords make sense, argument
// length, etc)
this._validate.validateMethod(
name, value, keywords, prev_data, prev_keywords, state
);
// we might be overriding an existing method
if ( keywords[ 'proxy' ] && !( prev && keywords.weak ) )
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
{
// TODO: Note that this is not compatible with method hiding, due to its
// positioning (see hideMethod() below); address once method hiding is
// implemented (the validators currently handle everything else)
dest[ name ] = this._createProxy(
value, instCallback, cid, name, keywords
);
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
}
else if ( prev )
{
2014-03-04 00:19:39 -05:00
if ( keywords.weak && !( prev_keywords[ 'abstract' ] ) )
{
// another member of the same name has been found; discard the
// weak declaration
return false;
}
else if ( keywords[ 'override' ] || prev_keywords[ 'abstract' ] )
{
2014-03-04 00:19:39 -05:00
// if we have the `abstract' keyword at this point, then we are
// an abstract override
var override = ( keywords[ 'abstract' ] )
? aoverride( name )
: prev;
// override the method
dest[ name ] = this._overrideMethod(
2014-03-04 00:19:39 -05:00
override, value, instCallback, cid
);
}
else
{
// by default, perform method hiding, even if the keyword was not
// provided (the keyword simply suppresses the warning)
dest[ name ] = hideMethod( prev, value, instCallback, cid );
}
}
Private methods are no longer wrapped This is an exciting performance optimization that seems to have eluded me for a surprisingly long time, given that the realization was quite random. ease.js accomplishes much of its work through a method wrapper---each and every method definition (well, until now) was wrapped in a closure that performed a number of steps, depending on the type of wrapper involved: 1. All wrappers perform a context lookup, binding to the instance's private member object of the class that defined that particular method. (See "Implementation Details" in the manual for more information.) 2. This context is restored upon returning from the call: if a method returns `this', it is instead converted back to the context in which the method was invoked, which prevents the private member object from leaking out of a public interface. 3. In the event of an override, this.__super is set up (and torn down). There are other details (e.g. the method wrapper used for method proxies), but for the sake of this particular commit, those are the only ones that really matter. There are a couple of important details to notice: - Private members are only ever accessible from within the context of the private member object, which is always the context when executing a method. - Private methods cannot be overridden, as they cannot be inherited. Consequently: 1. We do not need to perform a context lookup: we are already in the proper context. 2. We do not need to restore the context, as we never needed to change it to begin with. 3. this.__super is never applicable. Method wrappers are therefore never necessary for private methods; they have therefore been removed. This has some interesting performance implications. While in most cases the overhead of method wrapping is not a bottleneck, it can have a strong impact in the event of frequent method calls or heavily recursive algorithms. There was one particular problem that ease.js suffered from, which is mentioned in the manual: recursive calls to methods in ease.js were not recommended because it (a) made two function calls for each method call, effectively halving the remaining call stack size, and (b) tail call optimization could not be performed, because recursion invoked the wrapper, *not* the function that was wrapped. By removing the method wrapper on private methods, we solve both of these problems; now, heavily recursive algorithms need only use private methods (which could always be exposed through a protected or public API) when recursing to entirely avoid any performance penalty by using ease.js. Running the test cases on my system (your results may vary) before and after the patch, we have: BEFORE: 0.170s (x1000 = 0.0001700000s each): Declare 1000 anonymous classes with private members 0.021s (x500000 = 0.0000000420s each): Invoke private methods internally AFTER: 0.151s (x1000 = 0.0001510000s each): Declare 1000 anonymous classes with private members 0.004s (x500000 = 0.0000000080s each): Invoke private methods internally This is all the more motivation to use private members, which enforces encapsulation; keep in mind that, because use of private members is the ideal in well-encapsulated and well-factored code, ease.js has been designed to perform best under those circumstances.
2014-03-20 22:36:43 -04:00
else if ( keywords[ 'abstract' ] || keywords[ 'private' ] )
{
Private methods are no longer wrapped This is an exciting performance optimization that seems to have eluded me for a surprisingly long time, given that the realization was quite random. ease.js accomplishes much of its work through a method wrapper---each and every method definition (well, until now) was wrapped in a closure that performed a number of steps, depending on the type of wrapper involved: 1. All wrappers perform a context lookup, binding to the instance's private member object of the class that defined that particular method. (See "Implementation Details" in the manual for more information.) 2. This context is restored upon returning from the call: if a method returns `this', it is instead converted back to the context in which the method was invoked, which prevents the private member object from leaking out of a public interface. 3. In the event of an override, this.__super is set up (and torn down). There are other details (e.g. the method wrapper used for method proxies), but for the sake of this particular commit, those are the only ones that really matter. There are a couple of important details to notice: - Private members are only ever accessible from within the context of the private member object, which is always the context when executing a method. - Private methods cannot be overridden, as they cannot be inherited. Consequently: 1. We do not need to perform a context lookup: we are already in the proper context. 2. We do not need to restore the context, as we never needed to change it to begin with. 3. this.__super is never applicable. Method wrappers are therefore never necessary for private methods; they have therefore been removed. This has some interesting performance implications. While in most cases the overhead of method wrapping is not a bottleneck, it can have a strong impact in the event of frequent method calls or heavily recursive algorithms. There was one particular problem that ease.js suffered from, which is mentioned in the manual: recursive calls to methods in ease.js were not recommended because it (a) made two function calls for each method call, effectively halving the remaining call stack size, and (b) tail call optimization could not be performed, because recursion invoked the wrapper, *not* the function that was wrapped. By removing the method wrapper on private methods, we solve both of these problems; now, heavily recursive algorithms need only use private methods (which could always be exposed through a protected or public API) when recursing to entirely avoid any performance penalty by using ease.js. Running the test cases on my system (your results may vary) before and after the patch, we have: BEFORE: 0.170s (x1000 = 0.0001700000s each): Declare 1000 anonymous classes with private members 0.021s (x500000 = 0.0000000420s each): Invoke private methods internally AFTER: 0.151s (x1000 = 0.0001510000s each): Declare 1000 anonymous classes with private members 0.004s (x500000 = 0.0000000080s each): Invoke private methods internally This is all the more motivation to use private members, which enforces encapsulation; keep in mind that, because use of private members is the ideal in well-encapsulated and well-factored code, ease.js has been designed to perform best under those circumstances.
2014-03-20 22:36:43 -04:00
// we do not want to wrap abstract methods, since they are not
// callable; further, we do not need to wrap private methods, since
// they are only ever accessible when we are already within a
// private context (see test case for more information)
dest[ name ] = value;
}
else
{
// we are not overriding the method, so simply copy it over, wrapping it
// to ensure privileged calls will work properly
dest[ name ] = this._overrideMethod( null, value, instCallback, cid );
}
// store keywords for later reference (needed for pre-ES5 fallback)
dest[ name ].___$$keywords$$ = keywords;
return true;
};
/**
* Default keywords to apply to methods inherited from a prototype.
* @type {Object}
*/
exports._methodKeywordDefaults = { 'virtual': true };
2014-03-04 00:19:39 -05:00
/**
* Creates an abstract override super method proxy to NAME
*
* This is a fairly abstract concept that is disastrously confusing without
* having been put into the proper context: This function is intended to be
* used as a super method for a method override in the case of abstract
* overrides. It only makes sense to be used, at least at this time, with
* mixins.
*
* When called, the bound context (`this') will be the private member object
* of the caller, which should contain a reference to the protected member
* object of the supertype to proxy to. It is further assumed that the
* protected member object (pmo) defines NAME such that it proxies to a
* mixin; this means that invoking it could result in an infinite loop. We
* therefore skip directly to the super-super method, which will be the
* method we are interested in proxying to.
*
* There is one additional consideration: If this super method is proxying
* from a mixin instance into a class, then it is important that we bind the
* calling context to the pmo instaed of our own context; otherwise, we'll
* be executing within the context of the trait, without access to the
* members of the supertype that we are proxying to! The pmo will be used by
* the ease.js method wrapper to look up the proper private member object,
* so it is not a problem that the pmo is being passed in.
*
* That's a lot of text for such a small amount of code.
*
* @param {string} name name of method to proxy to
*
* @return {Function} abstract override super method proxy
*/
function aoverride( name )
{
return function()
{
return this.___$$super$$.prototype[ name ]
2014-03-04 00:19:39 -05:00
.apply( this.___$$pmo$$, arguments );
};
}
/**
* Copies a property to the appropriate member prototype, depending on
* visibility, and assigns necessary metadata from keywords
*
* @param {__visobj} members
* @param {!Object} meta metadata container
* @param {string} name property name
* @param {*} value property value
*
* @param {!Object.<boolean>} keywords parsed keywords
*
* @param {Object=} base optional base object to scan
*
* @return {undefined}
*/
exports.buildProp = function( members, meta, name, value, keywords, base )
{
// TODO: We can improve performance by not scanning each one individually
// every time this method is called
var prev_data = scanMembers( members, name, base ),
prev = ( prev_data ) ? prev_data.member : null,
prev_keywords = ( prev ) ? prev[ 1 ] : null;
this._validate.validateProperty(
name, value, keywords, prev_data, prev_keywords
);
getMemberVisibility( members, keywords, name )[ name ] =
[ value, keywords ];
};
/**
* Copies a getter/setter to the appropriate member prototype, depending on
* visibility, and assigns necessary metadata from keywords
*
'this' now properly binds to the private member object of the instance for getters/setters Getters/setters did not get much attention during the initial development of ease.js, simply because there was such a strong focus on pre-ES5 compatibility---ease.js was created for a project that strongly required it. Given that, getters/setters were not used, since those are ES5 features. As such, I find that two things have happened: 1. There was little incentive to provide a proper implementation; even though I noticed the issues during the initial development, they were left unresolved and were then forgotten about as the project lay dormant for a while. 2. The project was dormant because it was working as intended (sure, there are still things on the TODO-list feature-wise). Since getters/setters were unused in the project for which ease.js was created, the bug was never found and so never addressed. That said, I now am using getters/setters in a project with ease.js and noticed a very odd bug that could not be explained by that project's implementation. Sure enough, it was an ease.js issue and this commit resolves it. Now, there is more to be said about this commit. Mainly, it should be noted that MemberBuilder.buildGetterSetter, when compared with its method counterpart (buildMethod) is incomplete---it does not properly address overrides, the abstract keyword, proxies or the possibility of method hiding. This is certainly something that I will get to, but I want to get this fix out as soon as I can. Since overriding ES5 getters/setters (rather than explicit methods) is more likely to be a rarity, and since a partial fix is better than no fix, this will likely be tagged immediately and a further fix will follow in the (hopefully near) future. (This is an interesting example of how glaring bugs manage to slip through the cracks, even when the developer is initially aware of them.)
2013-01-19 20:54:30 -05:00
* TODO: This should essentially mirror buildMethod with regards to overrides,
* proxies, etc.
*
* @param {!__visobj} members
* @param {!Object} meta metadata container
* @param {string} name getter name
* @param {*} get getter value
* @param {*} set setter value
*
* @param {!Object.<boolean>} keywords parsed keywords
*
'this' now properly binds to the private member object of the instance for getters/setters Getters/setters did not get much attention during the initial development of ease.js, simply because there was such a strong focus on pre-ES5 compatibility---ease.js was created for a project that strongly required it. Given that, getters/setters were not used, since those are ES5 features. As such, I find that two things have happened: 1. There was little incentive to provide a proper implementation; even though I noticed the issues during the initial development, they were left unresolved and were then forgotten about as the project lay dormant for a while. 2. The project was dormant because it was working as intended (sure, there are still things on the TODO-list feature-wise). Since getters/setters were unused in the project for which ease.js was created, the bug was never found and so never addressed. That said, I now am using getters/setters in a project with ease.js and noticed a very odd bug that could not be explained by that project's implementation. Sure enough, it was an ease.js issue and this commit resolves it. Now, there is more to be said about this commit. Mainly, it should be noted that MemberBuilder.buildGetterSetter, when compared with its method counterpart (buildMethod) is incomplete---it does not properly address overrides, the abstract keyword, proxies or the possibility of method hiding. This is certainly something that I will get to, but I want to get this fix out as soon as I can. Since overriding ES5 getters/setters (rather than explicit methods) is more likely to be a rarity, and since a partial fix is better than no fix, this will likely be tagged immediately and a further fix will follow in the (hopefully near) future. (This is an interesting example of how glaring bugs manage to slip through the cracks, even when the developer is initially aware of them.)
2013-01-19 20:54:30 -05:00
* @param {Function} instCallback function to call in order to retrieve
* object to bind 'this' keyword to
*
* @param {number} cid class id
* @param {Object=} base optional base object to scan
*
* @return {undefined}
*
* Closure Compiler is improperly throwing warnings on Object.defineProperty():
* @suppress {checkTypes}
*/
exports.buildGetterSetter = function(
'this' now properly binds to the private member object of the instance for getters/setters Getters/setters did not get much attention during the initial development of ease.js, simply because there was such a strong focus on pre-ES5 compatibility---ease.js was created for a project that strongly required it. Given that, getters/setters were not used, since those are ES5 features. As such, I find that two things have happened: 1. There was little incentive to provide a proper implementation; even though I noticed the issues during the initial development, they were left unresolved and were then forgotten about as the project lay dormant for a while. 2. The project was dormant because it was working as intended (sure, there are still things on the TODO-list feature-wise). Since getters/setters were unused in the project for which ease.js was created, the bug was never found and so never addressed. That said, I now am using getters/setters in a project with ease.js and noticed a very odd bug that could not be explained by that project's implementation. Sure enough, it was an ease.js issue and this commit resolves it. Now, there is more to be said about this commit. Mainly, it should be noted that MemberBuilder.buildGetterSetter, when compared with its method counterpart (buildMethod) is incomplete---it does not properly address overrides, the abstract keyword, proxies or the possibility of method hiding. This is certainly something that I will get to, but I want to get this fix out as soon as I can. Since overriding ES5 getters/setters (rather than explicit methods) is more likely to be a rarity, and since a partial fix is better than no fix, this will likely be tagged immediately and a further fix will follow in the (hopefully near) future. (This is an interesting example of how glaring bugs manage to slip through the cracks, even when the developer is initially aware of them.)
2013-01-19 20:54:30 -05:00
members, meta, name, get, set, keywords, instCallback, cid, base
)
{
var prev_data = scanMembers( members, name, base ),
prev_keywords = ( ( prev_data && prev_data.get )
? prev_data.get.___$$keywords$$
: null
)
;
this._validate.validateGetterSetter(
name, {}, keywords, prev_data, prev_keywords
);
'this' now properly binds to the private member object of the instance for getters/setters Getters/setters did not get much attention during the initial development of ease.js, simply because there was such a strong focus on pre-ES5 compatibility---ease.js was created for a project that strongly required it. Given that, getters/setters were not used, since those are ES5 features. As such, I find that two things have happened: 1. There was little incentive to provide a proper implementation; even though I noticed the issues during the initial development, they were left unresolved and were then forgotten about as the project lay dormant for a while. 2. The project was dormant because it was working as intended (sure, there are still things on the TODO-list feature-wise). Since getters/setters were unused in the project for which ease.js was created, the bug was never found and so never addressed. That said, I now am using getters/setters in a project with ease.js and noticed a very odd bug that could not be explained by that project's implementation. Sure enough, it was an ease.js issue and this commit resolves it. Now, there is more to be said about this commit. Mainly, it should be noted that MemberBuilder.buildGetterSetter, when compared with its method counterpart (buildMethod) is incomplete---it does not properly address overrides, the abstract keyword, proxies or the possibility of method hiding. This is certainly something that I will get to, but I want to get this fix out as soon as I can. Since overriding ES5 getters/setters (rather than explicit methods) is more likely to be a rarity, and since a partial fix is better than no fix, this will likely be tagged immediately and a further fix will follow in the (hopefully near) future. (This is an interesting example of how glaring bugs manage to slip through the cracks, even when the developer is initially aware of them.)
2013-01-19 20:54:30 -05:00
if ( get )
{
get = this._overrideMethod( null, get, instCallback, cid );
// ensure we store the keywords *after* the override, otherwise they
// will be assigned to the wrapped function (the getter)
get.___$$keywords$$ = keywords;
}
Object.defineProperty(
getMemberVisibility( members, keywords, name ),
name,
{
get: get,
'this' now properly binds to the private member object of the instance for getters/setters Getters/setters did not get much attention during the initial development of ease.js, simply because there was such a strong focus on pre-ES5 compatibility---ease.js was created for a project that strongly required it. Given that, getters/setters were not used, since those are ES5 features. As such, I find that two things have happened: 1. There was little incentive to provide a proper implementation; even though I noticed the issues during the initial development, they were left unresolved and were then forgotten about as the project lay dormant for a while. 2. The project was dormant because it was working as intended (sure, there are still things on the TODO-list feature-wise). Since getters/setters were unused in the project for which ease.js was created, the bug was never found and so never addressed. That said, I now am using getters/setters in a project with ease.js and noticed a very odd bug that could not be explained by that project's implementation. Sure enough, it was an ease.js issue and this commit resolves it. Now, there is more to be said about this commit. Mainly, it should be noted that MemberBuilder.buildGetterSetter, when compared with its method counterpart (buildMethod) is incomplete---it does not properly address overrides, the abstract keyword, proxies or the possibility of method hiding. This is certainly something that I will get to, but I want to get this fix out as soon as I can. Since overriding ES5 getters/setters (rather than explicit methods) is more likely to be a rarity, and since a partial fix is better than no fix, this will likely be tagged immediately and a further fix will follow in the (hopefully near) future. (This is an interesting example of how glaring bugs manage to slip through the cracks, even when the developer is initially aware of them.)
2013-01-19 20:54:30 -05:00
set: ( set )
? this._overrideMethod( null, set, instCallback, cid )
: set,
enumerable: true,
configurable: false,
}
);
};
/**
* Returns member prototype to use for the requested visibility
*
* Will throw an exception if multiple access modifiers were used.
*
* @param {__visobj} members
*
* @param {!Object.<boolean>} keywords parsed keywords
* @param {string} name member name
*
* @return {Object} reference to visibility of members argument to use
*/
function getMemberVisibility( members, keywords, name )
{
// there's cleaner ways of doing this, but consider it loop unrolling for
// performance
if ( keywords[ 'private' ] )
{
( keywords[ 'public' ] || keywords[ 'protected' ] )
&& viserr( name );
return members[ 'private' ];
}
else if ( keywords[ 'protected' ] )
{
( keywords[ 'public' ] || keywords[ 'private' ] )
&& viserr( name );
return members[ 'protected' ];
}
else
{
// public keyword is the default, so explicitly specifying it is only
// for clarity
( keywords[ 'private' ] || keywords[ 'protected' ] )
&& viserr( name );
return members[ 'public' ];
}
}
function viserr( name )
{
throw TypeError(
"Only one access modifier may be used for definition of '" +
name + "'"
);
}
/**
* Scan each level of visibility for the requested member
*
* @param {__visobj} members
*
* @param {string} name member to locate
* @param {Object=} base optional base object to scan
*
* @return {{get,set,member}|null}
*/
function scanMembers( members, name, base )
{
var i = visibility.length,
member = null;
// locate requested member by scanning each level of visibility
while ( i-- )
{
var visobj = members[ visibility[ i ] ];
// In order to support getters/setters, we must go off of the
// descriptor. We must also ignore base properties (last argument), such
// as Object.prototype.toString(). However, we must still traverse the
// prototype chain.
if ( member = util.getPropertyDescriptor( visobj, name, true ) )
{
return {
get: member.get,
set: member.set,
member: member.value,
};
}
}
// if a second comparison object was given, try again using it instead of
// the original members object
if ( base !== undefined )
{
var base_methods = base.___$$methods$$,
base_props = base.___$$props$$;
// we must recurse on *all* the visibility objects of the base's
// supertype; attempt to find the class associated with its
// supertype, if any
var base2 = ( ( base.prototype || {} ).___$$parent$$ || {} )
.constructor;
// scan the base's methods and properties, if they are available
return ( base_methods && scanMembers( base_methods, name, base2 ) )
|| ( base_props && scanMembers( base_props, name, base2 ) )
|| null
;
}
// nothing was found
return null;
}
/**
* Hide a method with a "new" method
*/
function hideMethod( super_method, new_method, instCallback, cid )
{
// TODO: This function is currently unimplemented. It exists at present to
// provide a placeholder and ensure that the override keyword is required to
// override a parent method.
//
// We should never get to this point if the default validation rule set is
// used to prevent omission of the 'override' keyword.
throw Error(
'Method hiding not yet implemented (we should never get here; bug).'
);
}
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
/**
* Create a method that proxies to the method of another object
*
* @param {string} proxy_to name of property (of instance) to proxy to
*
* @param {Function} instCallback function to call in order to retrieve
* object to bind 'this' keyword to
*
* @param {number} cid class id
* @param {string} mname name of method to invoke on destination object
* @param {Object} keywords method keywords
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
*
* @return {Function} proxy method
*/
exports._createProxy = function( proxy_to, instCallback, cid, mname, keywords )
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
{
return this._wrapProxy.wrapMethod(
proxy_to, null, cid, instCallback, mname, keywords
Added `proxy' keyword support The concept of proxy methods will become an important, core concept in ease.js that will provide strong benefits for creating decorators and proxies, removing boilerplate code and providing useful metadata to the system. Consider the following example: Class( 'Foo', { // ... 'public performOperation': function( bar ) { this._doSomethingWith( bar ); return this; }, } ); Class( 'FooDecorator', { 'private _foo': null, // ... 'public performOperation': function( bar ) { return this._foo.performOperation( bar ); }, } ); In the above example, `FooDecorator` is a decorator for `Foo`. Assume that the `getValueOf()` method is undecorated and simply needs to be proxied to its component --- an instance of `Foo`. (It is not uncommon that a decorator, proxy, or related class will alter certain functionality while leaving much of it unchanged.) In order to do so, we can use this generic, boilerplate code return this.obj.func.apply( this.obj, arguments ); which would need to be repeated again and again for *each method that needs to be proxied*. We also have another problem --- `Foo.getValueOf()` returns *itself*, which `FooDecorator` *also* returns. This breaks encapsulation, so we instead need to return ourself: 'public performOperation': function( bar ) { this._foo.performOperation( bar ); return this; }, Our boilerplate code then becomes: var ret = this.obj.func.apply( this.obj, arguments ); return ( ret === this.obj ) ? this : ret; Alternatively, we could use the `proxy' keyword: Class( 'FooDecorator2', { 'private _foo': null, // ... 'public proxy performOperation': '_foo', } ); `FooDecorator2.getValueOf()` and `FooDecorator.getValueOf()` both perform the exact same task --- proxy the entire call to another object and return its result, unless the result is the component, in which case the decorator itself is returned. Proxies, as of this commit, accomplish the following: - All arguments are forwarded to the destination - The return value is forwarded to the caller - If the destination returns a reference to itself, it will be replaced with a reference to the caller's context (`this`). - If the call is expected to fail, either because the destination is not an object or because the requested method is not a function, a useful error will be immediately thrown (rather than the potentially cryptic one that would otherwise result, requiring analysis of the stack trace). N.B. As of this commit, static proxies do not yet function properly.
2012-05-02 13:26:47 -04:00
);
};
/**
* Generates a method override function
*
* The override function simply wraps the method so that its invocation will
* pass a __super property. This property may be used to invoke the overridden
* method.
*
* @param {function()} super_method method to override
* @param {function()} new_method method to override with
*
* @param {Function} instCallback function to call in order to retrieve
* object to bind 'this' keyword to
*
* @param {number} cid class id
*
* @return {function()} override method
*/
exports._overrideMethod = function(
super_method, new_method, instCallback, cid
)
{
instCallback = instCallback || function() {};
// return a function that permits referencing the super method via the
// __super property
var override = null;
// are we overriding?
override = (
( super_method )
? this._wrapOverride
: this._wrapMethod
).wrapMethod( new_method, super_method, cid, instCallback );
// This is a trick to work around the fact that we cannot set the length
// property of a function. Instead, we define our own property - __length.
// This will store the expected number of arguments from the super method.
// This way, when a method is being overridden, we can check to ensure its
// compatibility with its super method.
util.defineSecureProp( override,
'__length',
( new_method.__length || new_method.length )
);
return override;
}
/**
* Return the visibility level as a numeric value, where 0 is public and 2 is
* private
*
* @param {Object} keywords keywords to scan for visibility level
*
* @return {number} visibility level as a numeric value
*/
exports._getVisibilityValue = function( keywords )
{
if ( keywords[ 'protected' ] )
{
return 1;
}
else if ( keywords[ 'private' ] )
{
return 2;
}
else
{
// default is public
return 0;
}
}
/**
* End member run and perform post-processing on state data
*
* A ``member run'' should consist of the members required for a particular
* object (class/interface/etc). This action will perform validation
* post-processing if a validator is available.
*
* @param {Object} state member run state
*
* @return {undefined}
*/
exports.end = function( state )
{
this._validate && this._validate.end( state );
};