Author: erights
Date: Tue Jul 7 00:34:07 2009
New Revision: 3555
Modified:
wiki/NiceNeighbor.wiki
Log:
Edited wiki page through web user interface.
Modified: wiki/NiceNeighbor.wiki
==============================================================================
--- wiki/NiceNeighbor.wiki (original)
+++ wiki/NiceNeighbor.wiki Tue Jul 7 00:34:07 2009
@@ -4,13 +4,18 @@
= Coexistence Today by Taming =
-(The documentation here corresponds to Caja once
http://codereview.appspot.com/50041/show has been committed.)
+(The documentation here corresponds to Caja once
+http://codereview.appspot.com/50041/show has been committed.)
----
http://google-caja.googlecode.com/svn/trunk/doc/images/nn-today.png
----
-On !JavaScript as implemented on browsers today (ES3R), inter-object
security is not quite defensible against untrusted, untranslated,
unverified !JavaScript code. Thus, Cajita's security today relies on the
assumption that Cajita objects will only be made directly accessible to
+On !JavaScript as implemented on browsers today (ES3R),
+inter-object security is not quite defensible against untrusted,
+untranslated, unverified !JavaScript code. Thus, Cajita's
+security today relies on the assumption that Cajita objects will
+only be made directly accessible to
# _Cajoled code_, i.e., the !JavaScript code generated by a cajoler -- a
trusted Cajita-to-!JavaScript compiler.
# _Trusted !JavaScript_, such as cajita.js -- the Cajita runtime.
# _Tamed innocent !JavaScript_, such as the core ES3 library or the
browser's DOM API.
@@ -143,6 +148,13 @@
The most problematic aspect of the above taxonomy is exophoric
functions. To be explained.
+== Taming API Naming Convention ==
+
+|| `___.mark*(`_obj_`,...)` || Marks _obj_ as being a particular kind of
Cajita object, such as a constructor, and therefore being usable from
Cajita in certain ways. ||
+|| `___.grant*(`_obj_`,`_name_`,...)` || Grants some kind of access to the
_name_ property of _obj_, perhaps also marking the current value of
_obj_`[`_name_`]` at the same time. ||
+
+For those taming methods that don't fit either of these patterns, see the
documentation on that method.
+
== Taming Normal Property Attributes ==
The following operations are only relevant for taming constructed
@@ -151,7 +163,10 @@
array is not frozen, then all its mentionable properties are also
implicitly writable and deletable.
-Even on constructed objects, stringified numbers (all _X_ such that _X_`
=== String(Number(`_X_`)`) and "`length`" are implicitly whitelisted as
well. On an accessible object, access to such properties cannot be denied.
+Even on constructed objects, stringified numbers (all _X_ such that
+_X_` === String(Number(`_X_`)`) and "`length`" are implicitly
+whitelisted as well. On an accessible object, access to such
+properties cannot be denied.
|| *Current API* || *Similar ES5 attribute* || *Common Semantics*||
*Differences* ||
|| `___.grantRead(`_obj_`,`_name_`)` || _none_ || ES5 has no non-readable
properties. || This operation makes actual uncajoled properties directly
visible to cajoled code. ||
@@ -224,18 +239,35 @@
_constructors_ or as frozen _simple-functions_. In all cases, if _optName_
is provided, it will be used for debugging purposes as the name of the
function.
|| *Current API* || *Meaning* ||
-|| `___.ctor(`_fun_`,`_optSuper_`,`_optName_`)` || Marks _fun_ as a
constructor -- it can only be called with `new`. Returns _fun_. ||
+|| `___.markCtor(`_fun_`,`_optSuper_`,`_optName_`)` || Marks _fun_ as a
constructor -- it can only be called with `new`. Returns _fun_. ||
|| `___.extend(`_hiddenFun_`,`_someSuper_`,`_optName_`)` || Use when
_hiddenFun_ is a constructor which should not be exposed that makes tamed
instances that should be exposed. Returns a new inert tamed constructor
which will not make anything, but will be be `instanceof`-equivalent to
_hiddenFun_. ||
-|| `___.frozenFunc(`_fun_`,`_optName_`)` || Marks _fun_ as a
simple-function -- one that does not mention `this`. A simple function can
be called as a function, method, or constructor. It is first class --
reading a readable property whose value is a simple-function obtains the
simple-function itself. ||
-|| `___.func(`_fun_`,`_optName_`)` || Not a taming API. Should only be
called by the cajoler's generated code. ||
-
-If _fun_ is a constructor and _fun_`.prototype` inherits directly from
_aSuper_`.prototype`, then the _optSuper_ argument to `___.ctor` should be
_aSuper_. _optSuper_ must be another function marked as a constructor.
_optSuper_ may only be absent or `undefined` when _fun_`.prototype`
inherits from nothing. Currently, this is only the case for
`Object.prototype` itself.
+|| `___.markFuncFreeze(`_fun_`,`_optName_`)` || Marks _fun_ as a
simple-function -- one that does not mention `this` -- and freeze it. A
simple function can be called as a function, method, or constructor. It is
first class -- reading a readable property whose value is a simple-function
obtains the simple-function itself. ||
+|| `___.markFuncOnly(`_fun_`,`_optName_`)` || Not a taming API. Should
only be called by the cajoler's generated code. ||
-`___.extend` should be called before _hiddenFun_`.prototype` is
initialized, since it will replace _hiddenFun_`.prototype` with a
prototypical object that inherits from _someSuper_`.prototype`. The
_someSuper_ argument of `___.extend` may either be a hidden constructor
used as the first argument of a previous call to `___.extend`, or it may be
the tamed inert constructor returned from a previous such call. If the
returned inert constructor is to be made available to cajoled code under
some name, _optName_ should be that name. For example, Domita's
`TameElement` makes tamed wrappers for real HTMLElements, so Domita exposes
+If _fun_ is a constructor and _fun_`.prototype` inherits directly from
+_aSuper_`.prototype`, then the _optSuper_ argument to `___.markCtor`
+should be _aSuper_. _optSuper_ must be another function marked as a
+constructor. _optSuper_ may only be absent or `undefined` when
+_fun_`.prototype` inherits from nothing. Currently, this is only the
+case for `Object.prototype` itself.
+
+`___.extend` should be called before _hiddenFun_`.prototype` is
+initialized, since it will replace _hiddenFun_`.prototype` with a
+prototypical object that inherits from
+_someSuper_`.prototype`. The _someSuper_ argument of `___.extend`
+may either be a hidden constructor used as the first argument of
+a previous call to `___.extend`, or it may be the tamed inert
+constructor returned from a previous such call. If the returned
+inert constructor is to be made available to cajoled code under
+some name, _optName_ should be that name. For example, Domita's
+`TameElement` makes tamed wrappers for real HTMLElements, so
+Domita exposes
{{{
nodeClasses.HTMLElement = ___.extend(TameElement,
TameBackedNode, 'HTMLElement');
}}}
-which denies cajoled access to the `TameElement` constructor; but allows
the caja expression `node instanceof HTMLElement` to succeed if node was
made by `new TameElement(`_..._`)`.
+which denies cajoled access to the `TameElement` constructor; but
+allows the caja expression `node instanceof HTMLElement` to succeed if
+node was made by `new TameElement(`_..._`)`.
== Taming Methods ==
@@ -247,7 +279,7 @@
`___.grantFunc(`_obj_`,`_name_`)`, both makes _obj_`[`_name_`]` readable
(as if by `___.grantRead(`_obj_`,`_name_`)`), and marks its current
value as a frozen simple-function (as if by
-`___.frozenFunc(`_obj_`[`_name_`],`_name_`)`).
+`___.markFuncFreeze(`_obj_`[`_name_`],`_name_`)`).
The remaining cases in the table determine the taming of exophoric
methods. To decide which one to use, one must understand the
