Labs/Jetpack/Binary Components: Difference between revisions

Jump to navigation Jump to search

Labs/Jetpack/Binary Components (view source)

Revision as of 22:01, 28 July 2009

701 bytes added ,  28 July 2009
added more, minor reformatting
(added docs for call and construct)
(added more, minor reformatting)
Line 33: Line 33:
This function wraps ''wrappee'' with ''membrane'' (meaning that ''membrane'' mediates all access to and from ''wrappee'').  The wrapped object is returned.
This function wraps ''wrappee'' with ''membrane'' (meaning that ''membrane'' mediates all access to and from ''wrappee'').  The wrapped object is returned.


''membrane'' should be a JavaScript object with any of the following methods defined:
<code>nsJetpack.</code>'''unwrap'''(''wrappedObject'')


::<code>membrane.</code>'''call'''(''wrappee'', ''membrane'', ''thisObj'', ''args'')
Removes the membrane from ''wrappedObject'' and returns the wrappee. If ''wrappedObject'' wasn't ever wrapped by ''nsJetpack.''<code>wrap()</code>, this function returns <code>null</code>.


::This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.call JSClass.call]; alternatively, it could be described as the analog of Python's <code>__call__</code> magic method.  ''thisObj'' is the object that the callee's <code>this</code> variable should be set to, and ''args'' is the array of arguments to be passed to the callee.  This method should return whatever the return value of the callee is, or raise an exception.
<code>nsJetpack.</code>'''getWrapper'''(''wrappedObject'')


::<code>membrane.</code>'''construct'''(''wrappee'', ''membrane'', ''thisObj'', ''args'')
Returns the membrane for the given ''wrappedObject''. If ''wrappedObject'' wasn't ever wrapped by ''nsJetpack.''<code>wrap()</code>, this function returns <code>null</code>.


::This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.construct JSClass.construct].  It's just like ''membrane.''<code>call()</code>, only it's called when the call is preceded by the <code>new</code> operator.
=== Membrane Objects ===


::<code>membrane.</code>'''convert'''(''wrappee'', ''membrane'', ''type'')
A ''membrane object'' is a user-defined JavaScript object with any of the following optional methods defined:


::This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.convert JSClass.convert], and is called when SpiderMonkey needs to coerce ''wrappee'' to a different type.  ''type'' is a string identifying the name of the desired type to coerce to, and can be anything ordinarily returned by JavaScript's ''typeof'' operator.  The default implementation of this is to call ''wrappee.''<code>valueOf()</code>.
<code>membrane.</code>'''call'''(''wrappee'', ''membrane'', ''thisObj'', ''args'')


::'''NOTE:''' Be very careful about implementing this function, as it can easily cause infinite recursion.
This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.call JSClass.call]; alternatively, it could be described as the analog of Python's <code>__call__</code> magic method.  ''thisObj'' is the object that the callee's <code>this</code> variable should be set to, and ''args'' is the array of arguments to be passed to the callee.  This method should return whatever the return value of the callee is, or raise an exception.


::<code>membrane.</code>'''resolve'''(''wrappee'', ''membrane'', ''name'')
<code>membrane.</code>'''construct'''(''wrappee'', ''membrane'', ''thisObj'', ''args'')


::This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.resolve JSClass.resolve].  It's called when the property identified by ''name'' doesn't exist on ''wrappee''. The membrane should either define ''name'' on ''wrappee'' and return ''wrappee'', or&mdash;if ''name'' doesn't exist&mdash;it should return <code>undefined</code>.
This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.construct JSClass.construct].  It's just like ''membrane.''<code>call()</code>, only it's called when the call is preceded by the <code>new</code> operator.


::<code>membrane.</code>'''enumerate'''(''wrappee'', ''membrane'')
<code>membrane.</code>'''convert'''(''wrappee'', ''membrane'', ''type'')


::This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.enumerate JSClass.enumerate].  It should return an iterator that iterates through all the property names in ''wrappee''.
This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.convert JSClass.convert], and is called when SpiderMonkey needs to coerce ''wrappee'' to a different type.  ''type'' is a string identifying the name of the desired type to coerce to, and can be anything ordinarily returned by JavaScript's ''typeof'' operator.  The default implementation of this is to call ''wrappee.''<code>valueOf()</code>.


::<code>membrane.</code>'''getProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')
'''NOTE:''' Be very careful about implementing this function, as it can easily cause infinite recursion.


::This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.getProperty]; alternatively, it could be described as the analog of Python's <code>__getattr__</code> magic method. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily return.  This function should return the value of the property, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.
<code>membrane.</code>'''resolve'''(''wrappee'', ''membrane'', ''name'')


::<code>membrane.</code>'''setProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')
This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.resolve JSClass.resolve].  It's called when the property identified by ''name'' doesn't exist on ''wrappee''.  The membrane should either define ''name'' on ''wrappee'' and return ''wrappee'', or&mdash;if ''name'' doesn't exist&mdash;it should return <code>undefined</code>.


::This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.setProperty]; alternatively, it could be described as the analog of Python's <code>__setattr__</code> magic method. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily set the value of the property to.  This function should return the value to set the property to, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.
<code>membrane.</code>'''enumerate'''(''wrappee'', ''membrane'')


::<code>membrane.</code>'''addProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')
This is essentially a JavaScript version of [https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass.enumerate JSClass.enumerate].  It should return an iterator that iterates through all the property names in ''wrappee''.


::This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.addProperty], and is called immediately after a new property has been added to ''wrappee''. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily set the initial value of the property to.  This function should return the initial value to set the property to, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.
<code>membrane.</code>'''getProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')


::<code>membrane.</code>'''delProperty'''(''wrappee'', ''membrane'', ''name'')
This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.getProperty]; alternatively, it could be described as the analog of Python's <code>__getattr__</code> magic method. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily return.  This function should return the value of the property, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.


::This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.delProperty]; alternatively, it could be described as the analog of Python's <code>__delattr__</code> magic method. ''name'' is the name of the property being deleted.  This function should return <code>true</code> if the property can be deleted, and <code>false</code> if not.
<code>membrane.</code>'''setProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')


=== unwrap() ===
This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.setProperty]; alternatively, it could be described as the analog of Python's <code>__setattr__</code> magic method. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily set the value of the property to.  This function should return the value to set the property to, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.


=== getWrapper() ===
<code>membrane.</code>'''addProperty'''(''wrappee'', ''membrane'', ''name'', ''defaultValue'')
 
This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.addProperty], and is called immediately after a new property has been added to ''wrappee''. ''name'' is the name of the property being accessed, and ''defaultValue'' is the value that JavaScript would ordinarily set the initial value of the property to.  This function should return the initial value to set the property to, which may be ''defaultValue'' or something different. Alternatively, the method may also throw an exception.
 
<code>membrane.</code>'''delProperty'''(''wrappee'', ''membrane'', ''name'')
 
This is essentially a JavaScript version of [https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp JSClass.delProperty]; alternatively, it could be described as the analog of Python's <code>__delattr__</code> magic method. ''name'' is the name of the property being deleted.  This function should return <code>true</code> if the property can be deleted, and <code>false</code> if not.


== Memory Profiling ==
== Memory Profiling ==
Line 83: Line 89:
The source code for this functionality is in [http://hg.mozilla.org/labs/jetpack/file/tip/components/src/memory_profiler.cpp memory_profiler.cpp].
The source code for this functionality is in [http://hg.mozilla.org/labs/jetpack/file/tip/components/src/memory_profiler.cpp memory_profiler.cpp].


=== profileMemory() ===
<code>nsJetpack.</code>'''profileMemory'''(''code'', ''filename'', ''lineNumber'', ''namedObjects'')
 
'''TODO:''' Document this function.


== Miscellaneous Functions ==
== Miscellaneous Functions ==
Line 89: Line 97:
The source code for this functionality is in [http://hg.mozilla.org/labs/jetpack/file/tip/components/src/tcb.cpp tcb.cpp].
The source code for this functionality is in [http://hg.mozilla.org/labs/jetpack/file/tip/components/src/tcb.cpp tcb.cpp].


=== functionInfo() ===
<code>nsJetpack.</code>'''functionInfo'''(''func'')
 
'''TODO:''' Document this function.
 
<code>nsJetpack.</code>'''seal'''(''object'')


=== seal() ===
'''TODO:''' Document this function.
Avarma
93

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/158249"

Navigation menu