"use strict";
// Copyright 2012 United States Government, as represented by the Secretary of Defense, Under
// Secretary of Defense (Personnel & Readiness).
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
// in compliance with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the License
// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
// or implied. See the License for the specific language governing permissions and limitations under
// the License.
/// Kernel API.
///
/// @module vwf/api/kernel
define( function() {
var exports = {
// TODO: setState
// TODO: getState
// TODO: hashState
/// Create a node from a component specification. Construction may require loading data from
/// multiple remote documents. This function returns before construction is complete. A callback
/// is invoked once the node has fully loaded.
///
/// A simple node consists of a set of properties, methods and events, but a node may specialize
/// a prototype component and may also contain multiple child nodes, any of which may specialize
/// a prototype component and contain child nodes, etc. So components cover a vast range of
/// complexity. The application definition for the overall simulation is a single component
/// instance.
///
/// A node is a component instance--a single, anonymous specialization of its component. Nodes
/// specialize components in the same way that any component may specialize a prototype
/// component. The prototype component is made available as a base, then new or modified
/// properties, methods, events, child nodes and scripts are attached to modify the base
/// implemenation.
///
/// To create a node, we first make the prototoype available by loading it (if it has not
/// already been loaded). This is a recursive call to createNode() with the prototype
/// specification. Then we add new, and modify existing, properties, methods, and events
/// according to the component specification. Then we load an add any children, again
/// recursively calling createNode() for each. Finally, we attach any new scripts and invoke an
/// initialization function.
///
/// @function
///
/// @param {String|Object} nodeComponent
/// @param {String} [nodeAnnotation]
/// @param {String} [baseURI]
/// @param {module:vwf/api/kernel~nodeCallback} [callback]
///
/// @returns {}
createNode: [ /* nodeComponent, nodeAnnotation, baseURI, callback( nodeID ) */ ],
/// Delete a node.
///
/// The node and all of its descendants will be removed from the application.
///
/// @function
///
/// @param {ID} nodeID
///
/// @returns {}
deleteNode: [ /* nodeID */ ],
/// Set node will set the properties of the node specified by the given id and component.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String|Object} nodeComponent
/// @param {module:vwf/api/kernel~nodeCallback} [callback]
///
/// @returns {}
setNode: [ /* nodeID, nodeComponent, callback( nodeID ) */ ],
/// Get node will retrieve the component of the node specified by the given id.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} full
/// @param {Boolean} normalize
///
/// @returns {Object}
getNode: [ /* nodeID, full, normalize */ ],
// TODO: hashNode
/// @function
///
/// @param {ID} nodeID
/// @param {String} childName
/// @param {String|Object} childComponent
/// @param {String} [childURI]
/// @param {module:vwf/api/kernel~nodeCallback} [callback]
///
/// @returns {}
createChild: [ /* nodeID, childName, childComponent, childURI, callback( childID ) */ ],
/// @function
///
/// @param {ID} nodeID
/// @param {String} childName
///
/// @returns {}
deleteChild: [ /* nodeID, childName */ ],
/// addChild calls addingChild() on each model. The child is considered added after each model has
/// run. Additionally, it calls addedChild() on each view. The view is being notified that a
/// child has been added.
///
/// @function
///
/// @param {ID} nodeID
/// @param {ID} childID
/// @param {String} childName
///
/// @returns {}
addChild: [ /* nodeID, childID, childName */ ],
/// removeChild calls removingChild() on each model. The child is considered removed after each model
/// has run. Additionally, it calls removedChild() on each view. The view is being notified that a
/// child has been removed.
///
/// @function
///
/// @param {ID} nodeID
/// @param {ID} childID
///
/// @returns {}
removeChild: [ /* nodeID, childID */ ],
/// setProperties sets all of the properties for a node. It will call settingProperties()
/// on each model and satProperties() on each view.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Object} properties
///
/// @returns {Object}
setProperties: [ /* nodeID, properties */ ],
/// getProperties will get all of the properties for a node. It will call
/// gettingProperties() on each model and gotProperties() on each view.
///
/// @function
///
/// @param {ID} nodeID
///
/// @returns {Object}
getProperties: [ /* nodeID */ ],
/// createProperty will create a property on a node and assign an initial value.
/// It will call creatingProperty() on each model. The property is considered created after each
/// model has run. Additionally, it wil call createdProperty() on each view. The view is being
/// notified that a property has been created.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String} propertyName
/// @param propertyValue
/// @param {String} propertyGet
/// @param {String} propertySet
///
/// @returns {} propertyValue
createProperty: [ /* nodeID, propertyName, propertyValue, propertyGet, propertySet */ ],
// TODO: deleteProperty
/// setProperty sets a specific property value on a node. It will call settingProperty()
/// on each model. The first model to return a non-undefined value has performed the
/// set and dictates the return value. The property is considered set after each model has run.
/// It will also call satProperty() on each view. The view is being notified that a property has
/// been set.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String} propertyName
/// @param {Value} propertyValue
///
/// @returns {Value} propertyValue
setProperty: [ /* nodeID, propertyName, propertyValue */ ],
/// getProperty will retrive a property value for a node. It will call gettingProperty()
/// on each model. The first model to return a non-undefined value dictates the return value.
/// It will also call gotProperty() on each view.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String} propertyName
///
/// @returns {Value} propertyValue
getProperty: [ /* nodeID, propertyName */ ],
/// Create a method on a node. Methods are incoming function calls made to a node.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing a method `methodName`.
/// @param {String} methodName
/// The name of a method on the `nodeID` node.
/// @param {String[]} methodParameters
/// An array of names of the method's positional parameters. The method body uses these
/// names to refer to the caller's arguments.
/// @param {String} methodBody
/// The body of a script to be used as the handler for the method. Strings will be
/// interpreted as JavaScript; other script types may be supported in future releases.
///
/// @returns {Handler} methodHandler
createMethod: [ /* nodeID, methodName, methodParameters, methodBody */ ],
// TODO: deleteMethod
/// Set the handler for a method on a node.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing a method `methodName`.
/// @param {String} methodName
/// The name of a method on the `nodeID` node.
/// @param {Handler} methodHandler
/// A script to set as the handler for the method.
///
/// @returns {Handler} methodHandler
setMethod: [ /* nodeID, methodName, methodHandler */ ],
/// Get the handler for a method on a node.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing a method `methodName`.
/// @param {String} methodName
/// The name of a method on the `nodeID` node.
///
/// @returns {Handler} methodHandler
getMethod: [ /* nodeID, methodName */ ],
/// Invoke a method on a node.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing a method `methodName`.
/// @param {String} methodName
/// The name of a method on the `nodeID` node.
/// @param {Value[]} methodParameters
/// An array of values to pass as arguments to the method call.
///
/// @returns {Value} returnValue
callMethod: [ /* nodeID, methodName, methodParameters */ ],
/// Create an event on a node.
///
/// Events are outgoing function calls that a node makes to announce changes to the node, or
/// to announce changes within a set of nodes that the node manages. Other nodes may attach
/// listener functions to the event which will be called when the event fires.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {String[]} eventParameters
/// An array of names of the event's positional parameters. The names are primarily used
/// to describe arguments that the event will pass to listeners when the event is fired.
/// The event's parameter list will be used as the default list for listeners that don't
/// declare their own parameters.
///
/// @returns {}
createEvent: [ /* nodeID, eventName, eventParameters */ ],
// TODO: deleteEvent
/// Set a node's event and its listeners.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {Event} eventDescriptor
/// The new event, including its listeners.
///
/// @returns {Event}
setEvent: [ /* nodeID, eventName, eventDescriptor */ ],
/// Get a node's event and its listeners.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
///
/// @returns {Event}
getEvent: [ /* nodeID, eventName */ ],
/// Add a function to a node's event to be called when the event fires.
///
/// By default, the handler will be invoked in the context of the sender. For JavaScript
/// handlers, this means that `this` will refer to the node with ID `nodeID`. To invoke the
/// handler on a different node, provide an `eventContextID` when adding the listener.
///
/// For dispatched events (invoked with `kernel.dispatchEvent`), events are fired from a
/// series of nodes until the event is handled. Starting at the application root, the event
/// is fired on the target's ancestors, downward, in a "capture" phase, then fired on the
/// target node, then again fired on the target's ancestors, upward, in a "bubbling" phase.
///
/// For dispatched events, after firing the event at a particular node, if any of the
/// handlers returned a truthy value, the event is considered _handled_ and the dispatch
/// process stops at that node. An event that is handled during the capture phase prevents
/// lower nodes or the target node from receiving the event. Events handled during the
/// bubbling phase catch events not handled by the target node or by lower nodes.
///
/// By default, a listener will only be invoked if it is attached to the event target, or
/// during the bubbling phase, if it attached to a node above the target. To also invoke a
/// listener during the capture phase, pass `eventPhases` as the array `[ "capture" ]`.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node. When the event is fired, all of its
/// listeners will be called.
/// @param {Handler} eventHandler
/// A script to be added as a handler for the event. The `eventParameters` that were
/// provided to the `createEvent` call will be available to the handler body as function
/// parameters if the handler doesn't declare its own parameters.
/// @param {ID} [eventContextID]
/// The ID of the node that the handler is _invoked on_. For JavaScript handlers, `this`
/// will refer to the `eventContextID` node. If `eventContextID` is not provided, the
/// handler will be invoked in the context of the global root pseudo-node.
/// @param {String[]} [eventPhases]
/// An array of strings indicating the event dispatch phases that this handler should
/// respond to. Handlers will be invoked at the target and during the bubbling phase
/// regardless of its `eventPhases`. To also invoke a handler during the capture phase,
/// include `"capture"` in the `eventPhases` array.` `eventPhases` only applies to the
/// propagation performed by `kernel.dispatchEvent`. Once `kernel.fireEvent` is called, it
/// always invokes all of the event's handlers.
///
/// @returns {ListenerID}
addEventListener: [ /* nodeID, eventName, eventHandler, eventContextID, eventPhases */ ],
/// Remove a listener function from a node's event. The handler will no longer be called
/// when the event fires.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {ListenerID} eventListenerID
/// A listener ID previously returned by `kernel.addEventListener` that identifies a
/// listener attached to this `nodeID` and `eventName`.
///
/// @returns {ListenerID}
/// `eventListenerID` if the listener was removed successfully. Otherwise, a falsy value.
removeEventListener: [ /* nodeID, eventName, eventListenerID */ ],
/// Set the handler for a listener on a node's event.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {ListenerID} eventListenerID
/// A listener ID previously returned by `kernel.addEventListener` that identifies a
/// listener attached to this `nodeID` and `eventName`.
/// @param {Listener} eventListener
/// A script to set as the handler for the listener. The `eventParameters` that were
/// provided to the `createEvent` call will be available to the handler body as function
/// parameters if the handler doesn't declare its own parameters.
///
/// @returns {Listener}
setEventListener: [ /* nodeID, eventName, eventListenerID, eventListener */ ],
/// Get the handler for a listener on a node's event.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {ListenerID} eventListenerID
/// A listener ID previously returned by `kernel.addEventListener` that identifies a
/// listener attached to this `nodeID` and `eventName`.
///
/// @returns {Listener}
getEventListener: [ /* nodeID, eventName, eventListenerID */ ],
/// Remove all listener functions from a node's event that are associated with a particular
/// context.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {ID} eventContextID
/// The ID of a context node that handlers may be associated with. Handler context
/// associations are made when `kernel.addEventListener` adds a handler to an event.
///
/// @returns {}
flushEventListeners: [ /* nodeID, eventName, eventContextID */ ],
/// It will call firingEvent() on each model and firedEvent() on each view.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {Value[]} eventParameters
/// An array of values to pass as arguments to calls into the event's listeners.
///
/// @returns {}
fireEvent: [ /* nodeID, eventName, eventParameters */ ],
/// Dispatch an event toward a node. Using fireEvent(), capture (down) and bubble (up) along
/// the path from the global root to the node. Cancel when one of the handlers returns a
/// truthy value to indicate that it has handled the event.
///
/// @function
///
/// @param {ID} nodeID
/// The ID of a node containing an event `eventName`.
/// @param {String} eventName
/// The name of an event on the `nodeID` node.
/// @param {Value[]} eventParameters
/// An array of values to pass as arguments to calls into the event's listeners. Values
/// from `eventParameters` are sent with the `kernel.fireEvent` call to each node.
/// @param {Object} eventNodeParameters
/// A collection of `ID`-indexed arrays of values to pass as additional arguments for
/// `kernel.fireEvent` calls to specific nodes.
///
/// @returns {}
dispatchEvent: [ /* nodeID, eventName, eventParameters, eventNodeParameters */ ],
/// It will call executing() on each model. The script is considered executed after each model
/// has run and all asynchronous calls made inside them have returned.
/// It will then call executed() on each view to notify it that a script has been executed.
/// It will then call the caller-provided callback to notify the caller that the
/// script has been fully executed and all asynchronous actions have completed.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String} scriptText
/// @param {String} scriptType
/// @param {module:vwf/api/kernel~valueCallback} [callback]
///
/// @returns {Value} returnValue
execute: [ /* nodeID, scriptText, scriptType, callback( returnValue ) */ ],
/// @function
///
/// @param {ID} nodeID
///
/// @returns {Number}
random: [ /* nodeID */ ],
/// @function
///
/// @param {ID} nodeID
/// @param {String} seed
seed: [ /* nodeID, seed */ ],
/// It will return the current simulation time.
///
/// @function
///
/// @returns {Number}
time: [],
/// It will return the moniker of the client responsible for the current action. Will be
/// falsy for actions originating in the server, such as time ticks.
///
/// @function
///
/// @returns {String}
client: [],
/// It will return the identifer the server assigned to this client.
///
/// @function
///
/// @returns {String}
moniker: [],
/// Return the application root node. `kernel.application( initializedOnly )` is equivalent
/// to `kernel.global( "application", initializedOnly )`.
///
/// @function
///
/// @param {Boolean} [initializedOnly]
/// If set, only return the application node if the application has completed
/// initialization. Drivers that manage application code should set `initializedOnly`
/// since applications should never have access to uninitialized parts of the application
/// graph.
///
/// @returns {ID}
/// The ID of the application root. `application` may return `undefined` if the entire
/// application has been deleted.
application: [ /* initializedOnly */ ],
/// Return the node's intrinsic state. This consists of:
///
/// source -- the URI of the node's data blob
/// type -- the MIME type of the node's data blob
///
/// The values are returned in an Object with the named properties. If the optional result
/// parameter is provided, the fields are added there (without disturbing any other fields) and
/// result is returned. Otherwise, a new object is created, filled, and returned.
///
/// @function
///
/// @param {ID} nodeID
/// ID of the node to query.
/// @param {Object} [result]
/// An optional Object to receive the result.
///
/// @returns {Object}
intrinsics: [ /* nodeID, result */ ],
/// Return the node's URI. This value will be the component URI for the root node of a component
/// loaded from a URI, and undefined in all other cases.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [searchAncestors]
/// If set and the node doesn't have a URI, search the node's ancestors. Return the URI of
/// the closest ancestor with a URI.
/// @param {Boolean} [initializedOnly]
/// If set, only search ancestors through those that have completed initialization.
///
/// @returns {String}
uri: [ /* nodeID, searchAncestors, initializedOnly */ ],
/// Name calls naming() on each model. The first model to return a non-undefined value dictates
/// the return value.
///
/// @function
///
/// @param {ID} nodeID
///
/// @returns {String}
name: [ /* nodeID */ ],
/// Return a node's prototype.
///
/// @function
///
/// @param {ID} nodeID
///
/// @returns {ID}
/// The ID of the node's prototype, or `undefined` if called on the proto-prototype,
/// `node.vwf`.
prototype: [ /* nodeID */ ],
/// Return a node's prototype, its prototype, etc. up to and including `node.vwf`.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [includeBehaviors]
/// If set, also include the node's and prototypes' behaviors.
///
/// @returns {ID[]}
/// An array of IDs of the node's prototypes.
prototypes: [ /* nodeID, includeBehaviors */ ],
/// Return a node's behaviors.
///
/// @function
///
/// @param {ID} nodeID
///
/// @returns {ID[]}
/// An array of IDs of the node's behaviors. An empty array is returned if the node
/// doesn't have any behaviors.
behaviors: [ /* nodeID */ ],
/// Return the set of global root nodes. Each global node is the root of a tree.
///
/// @function
///
/// @param {Boolean} [initializedOnly]
/// If set, only return root nodes that have completed initialization. Drivers that manage
/// application code should set `initializedOnly` and should also only provide the
/// `kernel.globals` result (even with `initializedOnly` set) to the application if the
/// application itself has completed initialization. Applications should never have access
/// to uninitialized parts of the simulation.
///
/// @returns {Object}
/// An object whose keys are the IDs of the global root nodes. `Object.keys` may be used
/// on the result to get an array of IDs. The global trees are not ordered, and the order
/// of the IDs is not significant.
globals: [ /* initializedOnly */ ],
/// Return a global root node selected by its URI or annotation.
///
/// @function
///
/// @param {String} globalReference
/// A selector that identifies the root to return. `globalReference` may specify either a
/// URI or annotation. The root nodes are searched first by URI, then by annotation if no
/// match is found.
/// @param {Boolean} [initializedOnly]
/// If set, only return a root node if it has completed initialization. Drivers that
/// manage application code should set `initializedOnly` and should also only provide the
/// result of `kernel.global` (even with `initializedOnly` set) to the application if the
/// application itself has completed initialization. Applications should never have access
/// to uninitialized parts of the simulation.
///
/// @returns {ID}
/// The ID of the root node of the selected tree, or `undefined` if `globalReference`
/// doesn't match any root or if `initializedOnly` is set and the selected tree has not
/// completed initialization.
global: [ /* globalReference, initializedOnly */ ],
/// Return the node at the root of the tree containing a node.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [initializedOnly]
/// If set, only return the root node if the node and its ancestors have completed
/// initialization. Drivers that manage application code should set `initializedOnly`
/// since applications should never have access to uninitialized parts of the application
/// graph.
///
/// @returns {ID}
/// The ID of the node at the root of the tree containing the node, or `undefined` if
/// `initializedOnly` is set and the node or one of its ancestors has not completed
/// initialization.
root: [ /* nodeID, initializedOnly */ ],
/// Return a node's parent, grandparent, its parent, etc.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [initializedOnly]
/// If set, only include parents of nodes that have completed initialization. If a portion
/// of the tree containing the node is still initializing, the node's parent, grandparent,
/// etc. will be included if the preceding node is initialized, but the remaining
/// ancestors will be omitted. Drivers that manage application code should set
/// `initializedOnly` since applications should never have access to uninitialized parts
/// of the application graph.
///
/// @returns {ID[]}
/// An array of IDs of the node's ancestors. An empty array is returned for global,
/// top-level nodes that don't have a parent.
ancestors: [ /* nodeID, initializedOnly */ ],
/// Return a node's parent.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [initializedOnly]
/// If set, only return the parent if the node has completed initialization. Drivers that
/// manage application code should set `initializedOnly` since applications should never
/// have access to uninitialized parts of the application graph.
///
/// @returns {ID}
/// The ID of the node's parent, or `undefined` for the application root node or other
/// global, top-level nodes.
parent: [ /* nodeID, initializedOnly */ ],
/// Return a node's children.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [initializedOnly]
/// If set, only return children that have completed initialization. Uninitialized
/// children will appear in the result as `undefined`. Drivers that manage application
/// code should set `initializedOnly` since applications should never have access to
/// uninitialized parts of the application graph.
///
/// @returns {ID[]}
/// An array of IDs of the node's children. An empty array is returned if the node
/// doesn't have any children. The result always contains one element for each child,
/// regardless of their initialization state and whether `initializedOnly` is set.
/// However, `initializedOnly` will cause uninitialized children to appear as `undefined`.
children: [ /* nodeID, initializedOnly */ ],
/// Return a node's child selected by index or name.
///
/// @function
///
/// @param {ID} nodeID
/// @param {String} childReference
/// A selector indicating the child to return. If `childReference` is a number, the child
/// at that index location is returned. Otherwise, a child with the name matching
/// `childReference` (if any) is returned.
/// @param {Boolean} [initializedOnly]
/// If set, only return a child if it has completed initialization. Drivers that manage
/// application code should set `initializedOnly` since applications should never have
/// access to uninitialized parts of the application graph.
///
/// @returns {ID}
/// The ID of the selected child, or `undefined` if `childReference` doesn't match a child
/// or if `initializedOnly` is set and the selected child has not completed
/// initialization.
child: [ /* nodeID, childReference, initializedOnly */ ],
/// Return a node's children, grandchildren, their children, etc.
///
/// @function
///
/// @param {ID} nodeID
/// @param {Boolean} [initializedOnly]
/// If set, only return descendants that have completed initialization. Uninitialized
/// descendants will appear in the result as `undefined`. Descendants of uninitialized
/// descendants will not appear. Drivers that manage application code should set
/// `initializedOnly` since applications should never have access to uninitialized parts
/// of the application graph.
///
/// @returns {ID[]}
/// An array of IDs of the node's descendants. An empty array is returned if the node
/// doesn't have any descendants. The result may contain `undefined` elements when
/// `initializedOnly` is set and some descendants have not completed initialization.
descendants: [ /* nodeID, initializedOnly */ ],
/// Locate nodes matching a search pattern. matchPattern supports an XPath subset consisting of
/// the following:
///
/// "/" -- the application root node
/// "/*" -- children of the application
/// "/name" -- a child of the application having the specified name
/// "/name1/name2/name3/..." -- a descendant of the application along the specified path
/// "//name" -- descendants of the application having the specified name
/// "//*" -- all descendants of the application
/// "//element(*,uri)" -- descendants of the application having uri in their prototype chain
///
/// ".." -- the reference node's parent
/// "." -- the reference node
/// "*", "./*" -- children of the reference node
/// "name", "./name" -- a child of the reference node having the specified name
/// "name1/name2/name3/..." -- a descendant of the reference node along the specified path
/// ".//name" -- descendants of the reference node having the specified name
/// ".//*" -- all descendants of the reference node
/// ".//element(name)" -- same as ".//name"
/// ".//element(*)" -- same as ".//*"
/// ".//element(name,uri)" -- descendants having the specified name and extending uri
/// ".//element(*,uri)" -- descendants extending uri
///
/// "name[name2]" -- a child "name" which also has a child having the second name
/// "name[name2/name3/...]" -- a child "name" which also has a descendant along the path
/// "*[*]" -- children which also have at least one child
/// "name[@property]" -- a child "name" which also has a truthy property with the provided name
/// "*[@*]" -- children which also have at least one truthy property
///
/// XPath elements are interpreted as VWF nodes and XPath attributes are interpreted as VWF
/// properties. The expression must evaluate to an element (node) set since only nodes are
/// distinctly addressable entities in VWF. Properties may be used in predicates.
///
/// The following XPath axes are supported:
/// ancestor-or-self, ancestor, parent, self, child, descendant, descendant-or-self, and
/// attribute (predicates only)
/// along with the following node tests:
/// element(name,type), attribute(name) (in predicates only), and node()
/// the shortcut notation:
/// "//": descendant-or-self:node(), ".": self::node(), "..": "parent::node()",
/// "name": "child::name", "@name": "attribute::name"
/// and the wildcard name:
/// "*"
///
/// This is a naive implementation with several limitations. There is no particular
/// optimization, and some queries can yield large intermediate or final results. Use caution
/// when applying the descendant operators. The results will not necessarily maintain document
/// order. Overlapping queries will cause nodes to be repeated in the results. For example, the
/// query `*``/..` will return the reference node several times, once for each of its children.
///
/// Names in XPath expressions may only contain the characters A-Z, a-z, 0-9, -, and .
/// (period). As an extension, this implementation allows names to contain any character so
/// long as it is quoted using either double or single quotes. Within a quoted name, use the
/// charater "\" to escape the quoting character or the escape character. When assembling an
/// expression, use vwf.utility.xpath.quoteName() to quote names that may have invalid
/// characters.
///
/// @function
///
/// @param {ID} nodeID
/// The reference node. Relative patterns are resolved with respect to this node. `nodeID`
/// is ignored for absolute patterns.
/// @param {String} matchPattern
/// The search pattern.
/// @param {Boolean} [initializedOnly]
/// Interpret nodes that haven't completed initialization as though they don't have
/// ancestors. Drivers that manage application code should set `initializedOnly` since
/// applications should never have access to uninitialized parts of the application graph.
/// @param {module:vwf/api/kernel~nodeCallback} [callback]
/// A callback to receive the search results. If callback is provided, find invokes
/// callback( matchID ) for each match. Otherwise the result is returned as an array.
///
/// @returns {ID[]|undefined}
/// If callback is provided, undefined; otherwise an array of the node ids of the result.
find: [ /* nodeID, matchPattern, initializedOnly, callback( matchID ) */ ],
/// Test a node against a search pattern. See vwf.api.kernel#find for details of the query
/// syntax.
///
/// @function
///
/// @param {ID} nodeID
/// The reference node. Relative patterns are resolved with respect to this node. `nodeID`
/// is ignored for absolute patterns.
/// @param {String} matchPattern
/// The search pattern.
/// @param {ID} testID
/// A node to test against the pattern.
/// @param {Boolean} [initializedOnly]
/// Interpret nodes that haven't completed initialization as though they don't have
/// ancestors. Drivers that manage application code should set `initializedOnly` since
/// applications should never have access to uninitialized parts of the application graph.
///
/// @returns {Boolean}
/// true when testID matches the pattern.
test: [ /* nodeID, matchPattern, testID, initializedOnly */ ],
/// Return client object matching the given search pattern.
///
/// @function
///
/// @param {ID} nodeID
/// The reference node. Relative patterns are resolved with respect to this node. `nodeID`
/// is ignored for absolute patterns.
/// @param {String} matchPattern
/// The search pattern.
/// @param {module:vwf/api/kernel~nodeCallback} [callback]
/// A callback to receive the search results. If callback is provided, find invokes
/// callback( matchID ) for each match. Otherwise the result is returned as an array.
///
/// @returns {ID[]|undefined}
/// If callback is provided, undefined; otherwise an array of the node ids of the result.
///
/// @deprecated in version 0.6.21. Instead of `kernel.findClients( reference, "/pattern" )`,
/// use `kernel.find( reference, "doc('http://vwf.example.com/clients.vwf')/pattern" )`.
findClients: [ /* nodeID, matchPattern, callback( matchID ) */ ],
/// Description.
///
/// @callback module:vwf/api/kernel~nodeCallback
///
/// @param {ID} nodeID
/// Description.
///
/// @callback module:vwf/api/kernel~valueCallback
///
/// @param {Value} returnValue
/// A `Handler` describes a function that may be attached to a property as a setter or
/// getter, to a method, or to an event as a listener.
///
/// A `Handler` is an object containing the following properties. Alternately, a `Handler`
/// may be provided as a `string` or `function` representing just the `body` field.
///
/// @typedef {Object|string|function} Handler
///
/// @property {string[]} [name]
/// The function's name. VWF doesn't make use of the name, but the field is included so
/// that named JavaScript functions can make a round-trip translation through a `Handler`
/// intact.
/// @property {string[]} [parameters]
/// An array of names of the function's positional parameters. The function body uses
/// these names to refer to the caller's arguments. `parameters` may be omitted if the
/// function doesn't declare any parameters, or if `body` is a JavaScript `function`, in
/// which case the parameters are taken from the JavaScript function itself.
/// @property {string|function} body
/// A representation of the statements making up the function body. For handlers of `type`
/// `application/javascript`, `body` should be a string containing JavaScript text that is
/// correct for the span between the opening and closing braces of a JavaScript function
/// definition: `function(...) {` |<= this is the body text =>| `}`. `body` may also be
/// provided as a JavaScript `function` value, in which case the handler's `body` and
/// `arguments` will be taken from the function.
/// @property {string} [type]
/// The {@link https://www.iana.org/assignments/media-types Media Type} of the `body`
/// text. When `body` is a `string`, the default type is `"application/javascript"`, and
/// `type` may be omitted. `type` should be omitted if `body` is a JavaScript `function`
/// value since the type is implicit in that case.
/// A `ListenerID` is a JavaScript primitive value that identifies an event listener. Each
/// listener is assigned a `ListenerID` when it is created that is unique within the node
/// and event.
///
/// @typedef {string|number|boolean|null} ListenerID
/// A `Listener` is an extended `Handler` with additional fields for event listeners.
///
/// Like a `Handler`, a `Listener` may be provided as a `string` or `function` representing
/// just the `body` field.
///
/// @typedef {Object|string|function} Listener
///
/// @property {ListenerID} [id]
/// A unique ID as returned by `kernel.addEventListener` that identifies the listener for
/// a particular `nodeID` and `eventName`.
/// @property {string[]} [name]
/// @see {@link module:vwf/api/kernel.Handler}
/// @property {string[]} [parameters]
/// @see {@link module:vwf/api/kernel.Handler}
/// @property {string|function} body
/// @see {@link module:vwf/api/kernel.Handler}
/// @property {string} [type]
/// @see {@link module:vwf/api/kernel.Handler}
/// @property {ID} [context]
/// The ID of a node that the handler will be _invoked on_. For JavaScript handlers,
/// `this` will refer to the `context` node. If `context` is not provided, the context
/// will be the global root pseudo-node.
/// @property {String[]} [phases]
/// An array of strings indicating the event dispatch phases that this handler should
/// respond to. Listeners will be invoked at the target and during the bubbling phase
/// regardless of its `phases`. To also invoke a handler during the capture phase, include
/// `"capture"` in the `phases` array.` `phases` only applies to the propagation performed
/// by `kernel.dispatchEvent`. Once `kernel.fireEvent` is called, it always invokes all of
/// the event's handlers.
/// An `Event` describes an event and its listeners.
///
/// @typedef {Object} Event
///
/// @property {string[]} [parameters]
/// An array of names of the event's positional parameters. The names are primarily used
/// to describe arguments that the event will pass to listeners when the event is fired.
/// The event's parameter list will be used as the default list for listeners that don't
/// declare their own parameters. `parameters` may be omitted if the event doesn't declare
/// any parameters.
/// @property {Listener[]} [listeners]
/// An array of listeners to be invoked when the event is fired. Listeners will be invoked
/// in the order provided.
};
return exports;
} );