- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 24 Jun 2010 20:28:29 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/wicda
In directory hutz:/tmp/cvs-serv21129
Added Files:
Overview.html
Log Message:
WICDA draft
--- NEW FILE: Overview.html ---
<!DOCTYPE html>
<html>
<head>
<title>Web IDL Component Designators and Actions</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "unofficial",
shortName: "wicda",
// publishDate: "2009-10-08",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/wicda/",
// lcEnd: "2009-08-05",
editors: [{name: "Robin Berjon",
url: "http://berjon.com/",
company: "Vodafone",
companyURL: "http://vodafone.com/" },
],
};
</script>
<script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id='abstract'>
This specification provides a way to point into a Web IDL schema and to decorate it by applying
extended attributes to them.
</section>
<section id='sotd'>
<p>
This document describes a completely experimental avenue of thinking and may have no future.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
Web IDL [[!WEBIDL]] is a schema language used for the description of APIs. A feature of the language,
called "Extended Attributes", allows annotations to be applied to schema constructs in order to refine
the way in which they apply within a specific context. Since Web IDL schemata are intended to be reused
by possibly large and varied communities, it can be impractical to place all Extended Attributes onto
the same definition. This specification provides a way to decorate a Web IDL schema by pointing to
its independent components and applying extended attributes to them.
</p>
</section>
<section>
<h2>Definitions</h2>
<dl>
<dt><dfn>extended attribute</dfn></dt>
<dd>
An information item corresponding to the
<a href='http://dev.w3.org/2006/webapi/WebIDL/#prod-ExtendedAttribute'>ExtendedAttribute</a> construct
in Web IDL.
</dd>
</dl>
</section>
<section id='conformance'></section>
<section>
<h2>Information Set of Web IDL Schemata</h2>
<p>
We define an abstract information set for Web IDL Schemata that does not intend to capture the full
breadth of information that may be in a schema but rather the minimal set that is needed to support
the purpose of this specification. It can be extended later.
</p>
<section>
<h2><dfn>root</dfn></h2>
<p>
The <a>root</a> is a specific <a>module</a> that has no name. It is the outermost scope in the tree
and contains all other information items directly or indirectly. Its properties are the same as those of
<a>module</a> information items, except that it has no name.
</p>
</section>
<section>
<h2><dfn>module</dfn></h2>
<p>
A <a>module</a> is a container used to structure namespaces in a Web IDL schema.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the module inside its parent module.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
<dt>modules</dt>
<dd>
An unordered list of zero or more <a>module</a>s directly contained inside this module.
</dd>
<dt>interfaces</dt>
<dd>
An unordered list of zero or more <a>interface</a>s directly contained inside this module.
</dd>
<dt>exceptions</dt>
<dd>
An unordered list of zero or more <a>exception</a>s directly contained inside this module.
</dd>
<dt>typedefs</dt>
<dd>
An unordered list of zero or more <a>typedef</a>s directly contained inside this module.
</dd>
<dt>implements</dt>
<dd>
An unordered list of zero or more <a>implements statement</a>s directly contained inside this module.
</dd>
</dl>
</section>
<section>
<h2><dfn>interface</dfn></h2>
<p>
An <a>interface</a> is a container for a coherent unit of data and behaviour.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the interface inside its parent module.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
<dt>constants</dt>
<dd>
An unordered list of zero or more <a>constant</a>s directly contained inside this interface.
</dd>
<dt>attributes</dt>
<dd>
An unordered list of zero or more <a>attribute</a>s directly contained inside this interface.
</dd>
<dt>operations</dt>
<dd>
An unordered list of zero or more <a>operation</a>s directly contained inside this interface.
</dd>
</dl>
</section>
<section>
<h2><dfn>exception</dfn></h2>
<p>
An <a>exception</a> is a container for data used to describe exceptional situations.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the exception inside its parent module.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
<dt>constants</dt>
<dd>
An unordered list of zero or more <a>constant</a>s directly contained inside this exception.
</dd>
<dt>fields</dt>
<dd>
An unordered list of zero or more <a>field</a>s directly contained inside this exception.
</dd>
</dl>
</section>
<section>
<h2><dfn>typedef</dfn></h2>
<p>
A <a>typedef</a> describes the binding of a name to a type.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the name that is bound inside this scope.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
<section>
<h2><dfn>implements statement</dfn></h2>
<p>
An <a>implements statement</a> is an indication that a given target <a>interface</a> implements
another source interface.
</p>
<dl>
<dt>target</dt>
<dd>
The identifier of the <a>interface</a> that implements the source interface.
</dd>
<dt>source</dt>
<dd>
The identifier of the <a>interface</a> that is implemented by the target interface.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
<section>
<h2><dfn>constant</dfn></h2>
<p>
A <a>constant</a> is an unchanging data item.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the constant inside its parent.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
<section>
<h2><dfn>attribute</dfn></h2>
<p>
An <a>attribute</a> is a data item inside an <a>interface</a>.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the attribute inside its parent interface.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
<section>
<h2><dfn>operation</dfn></h2>
<p>
An <a>operation</a> is a unit of behaviour inside an <a>interface</a>.
</p>
<dl>
<dt>name</dt>
<dd>
A string participating in the identification of the operation inside its parent interface.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
<dt>arguments</dt>
<dd>
An ordered list of zero or more <a>argument</a>s. Collectively the list defines
a sufficient signature to identify an operation when combined with its name.
</dd>
</dl>
</section>
<section>
<h2><dfn>argument</dfn></h2>
<p>
A <a>argument</a> is a unit of data provided to an <a>operation</a>.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the argument.
</dd>
<dt>type name</dt>
<dd>
A string identifying the type of the argument.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
<section>
<h2><dfn>field</dfn></h2>
<p>
A <a>field</a> is a data item inside an <a>exception</a>.
</p>
<dl>
<dt>name</dt>
<dd>
A string identifying the field inside its parent exception.
</dd>
<dt>extended attributes</dt>
<dd>
An ordered list of zero or more <a>extended attribute</a>s.
</dd>
</dl>
</section>
</section>
<section>
<h2>Component Designators</h2>
<p>
A <dfn>component designator</dfn> is a structured string that navigates inside a Web IDL schema.
It is guaranteed to return either exactly one information item, or nothing. Some examples:
</p>
<pre class='example'>
/module:crypto/module:alpine/interface:Dahut/attribute:chirality
/interface:Unicorn/operation:neigh(DOMString,float)
/module:nitro/exception:Boom/constant:sound
/interface:Node
/interface:Examples/operation:build(Unicorn,Dahut)/argument:dahut
</pre>
<section>
<h2>Syntax</h2>
<p>
The formalism used here is created completely out of thin air, hopefully it is intuitively
understandable. There is no white space in a designator. The <code>$variable</code> tokens
map to the information set properties, which are in turn based on the Web IDL syntax.
</p>
<pre>
Designator = ModuleStep* (InterfaceStep | ExceptionStep | TypeDefStep | ImplementsStep)*
ModuleStep = "/module:" $module-name
InterfaceStep = "/interface:" $interface-name (ConstantStep | AttributeStep | OperationStep)?
ExceptionStep = "/exception:" $exception-name (ConstantStep | FieldStep)?
TypeDefStep = "/typedef:" $typedef-name
ImplementsStep = "/implements:" $target "(" $source ")"
ConstantStep = "/constant:" $constant-name
AttributeStep = "/attribute:" $attribute-name
OperationStep = "/operation:" $operation-name "(" Arguments ")" ArgumentStep?
FieldStep = "/field:" $field-name
Arguments = $type-name ("," $type-name)* | ""
ArgumentStep = "/argument:" $argument-name
</pre>
</section>
<section>
<h2>Resolution</h2>
<p>
Given a designator parsed into a set of <var>steps</var> and a Web IDL schema, the designator is
processed as follows in order to return either an information item, or nothing.
</p>
<ol>
<li>Set <var>context</var> to the <a>root</a> information item</li>
<li>
If there are no more <var>steps</var>: if the <var>context</var> is <a>root</a>, return nothing,
otherwise return the <var>context</var>.
</li>
<li>
If the next step is a module step and there is a <a>module</a> contained in the current <var>context</var> with that
exact module name, set <var>context</var> to that module and go to 2; otherwise return nothing.
</li>
<li>
If the next step is an interface step and there is an <a>interface</a> contained in the current <var>context</var>
with that exact interface name, set <var>context</var> to that interface and go to 2; otherwise return nothing.
</li>
<li>
If the next step is an exception step and there is an <a>exception</a> contained in the current <var>context</var>
with that exact exception name, set <var>context</var> to that exception and go to 2; otherwise return nothing.
</li>
<li>
If the next step is a typedef step and there is a <a>typedef</a> contained in the current <var>context</var> with that
exact typedef name, return it; otherwise return nothing.
</li>
<li>
If the next step is an implements step and there is an <a>implements statement</a> contained in the current
<var>context</var> with those exact target and source, return it; otherwise return nothing.
</li>
<li>
If the next step is a constant step and there is a <a>constant</a> contained in the current <var>context</var> with that
exact name, return it; otherwise return nothing.
</li>
<li>
If the next step is an attribute step and there is an <a>attribute</a> contained in the current
<var>context</var> with that exact name, return it; otherwise return nothing.
</li>
<li>
If the next step is a field step and there is a <a>field</a> contained in the current <var>context</var> with that
exact name, return it; otherwise return nothing.
</li>
<li>
If the next step is an operation step and there is an <a>operation</a> contained in the current <var>context</var> with
those exact name and list of <a>argument</a> types in the same order, set <var>context</var> to that operation and go to
2; otherwise return nothing.
</li>
<li>
If the next step is a argument step and there is a <a>argument</a> contained in the current <var>context</var> with that
exact name, return it; otherwise return nothing.
</li>
</ol>
</section>
</section>
<section>
<h2>Actions</h2>
<p>
An <dfn>action</dfn> is a an operation that applies a modification to a Web IDL schema in order to produce a new one.
Actions are grouped inside an <dfn>action sheet</dfn>, which is an ordered list of actions to be performed one after
the other, alongside a touch of metadata.
</p>
<pre class='example'>
{
"name": "Coolness Action Sheet",
"description": "Attributes coolness to various parts of a Web IDL schema",
"actions": [
{ "action": "addExtAttr", "path": "/module:Cryptoids/interface:Unicorn", "value": "[Coolness=prettyGood]" },
{ "action": "addExtAttr", "path": "/module:Mammals/interface:Dahut", "value": "[Coolness=hyper]" },
{ "action": "addExtAttr", "path": "/module:Memetics/exception:Dahunicorn", "value": "[Coolness=storeMeatInIt]" },
]
}
</pre>
<p>
The only action defined in this specification is the <code>addExtAttr</code> action.
</p>
<section>
<h2>Structure</h2>
<p>
An action sheet is a JSON document [[!RFC4627]] with the following properties.
</p>
<dl>
<dt>name</dt>
<dd>
The human-readable name of the action sheet.
</dd>
<dt>description</dt>
<dd>
The human-readable description of the action sheet.
</dd>
<dt>actions</dt>
<dd>
An array of actions. If this property is not present, or if it does not contain an array,
then implementations MUST ignore it.
</dd>
</dl>
<p>
Every action is an object that has an <code>action</code> property which identifies the type of
the action. If the <code>action</code> property is absent, or does not contain a string, then
implementations MUST ignore that action. Other fields of the action depend on the action type.
</p>
<p>
Implementations MUST ignore other properties of action sheets.
</p>
</section>
<section>
<h2>Execution</h2>
<p>
The execution model for action sheets is simple: for each action in the action sheet in order the
implementation MUST execute the action completely and move on to the next action. When all actions
have been executed, the process comes to an end. The execution model for individual actions depends
on the action type.
</p>
</section>
<section>
<h2>The <code>addExtAttr</code> action</h2>
<p>
The <code>addExtAttr</code> action is used to add <a>extended attribute</a>s to information items
that can receive them. It makes use of the following two properties:
</p>
<dl>
<dt>path</dt>
<dd>
A <a>component designator</a> used to address the item in the schema to which the action applies.
If the path is not a valid component designator, then implementations MUST ignore this action.
</dd>
<dt>value</dt>
<dd>
A string in the
<a href='http://dev.w3.org/2006/webapi/WebIDL/#prod-ExtendedAttributeList'>ExtendedAttributeList</a>
syntax containing one or more extended attributes to be added to the designated component. If the
value does not match the syntax, then implementations MUST ignore this action. Implementations MUST
append the extended attributes in the value to those that may already be present on the designated
component.
</dd>
</dl>
<p>
An <code>addExtAttr</code> action is executed in the following manner: the path is resolved against the
Web IDL schema. If it returns nothing, execution stops. If the returned component supports an <a>extended
attribute</a>s property, the one(s) contained in the action value are added at the end of the
extended attributes list.
</p>
</section>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
This specification has no relationship whatsoever to <a href='http://www.w3.org/TR/xmlschema-ref/'>W3C XML
Schema Definition Language (XSD): Component Designators</a>.
</p>
</section>
</body>
</html>
Received on Thursday, 24 June 2010 20:28:32 UTC