"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; } );