nsIXULTemplateQueryProcessor Interface

 Add a variable binding for a particular rule. A binding allows an
 additional variable to be set for a result, outside of those defined
 within the query. These bindings are always optional, in that they will
 never affect the results generated.

 This function will never be called after generateResults. Any bindings
 that were added should be applied to each result when the result's
 ruleMatched method is called, since the bindings are different for each
 rule.

 The reference aRef may be used to determine the reference when
 calculating the value for the binding, for example when a value should
 depend on the value of another variable.

 The syntax of the expression aExpr is defined by the query processor. If
 the syntax is invalid, the binding should be ignored. Only fatal errors
 should be thrown, or NS_ERROR_UNEXPECTED if generateResults has already
 been called.

 As an example, if the reference aRef is the variable '?count' which
 holds the value 5, and the expression aExpr is the string '+2', the value
 of the variable aVar would be 7, assuming the query processor considers
 the syntax '+2' to mean add two to the reference.

 @param aRuleNode rule to add the binding to
 @param aVar variable that will be bound
 @param aRef variable that holds reference value
 @param aExpr expression used to compute the value to assign

void addBinding(in nsIDOMNode aRuleNode, in nsIAtom aVar, in nsIAtom aRef, in AString aExpr)

 Compare two results to determine their order, used when sorting results.
 This method should return -1 when the left result is less than the right,
 0 if both are equivalent, and 1 if the left is greater than the right.
 The comparison should only consider the values for the specified
 variable.

 If the comparison variable is null, the results may be
 sorted in a natural order, for instance, based on the order the data in
 stored in the datasource.

 This method must only be called with results that were created by this
 query processor.

 @param aLeft the left result to compare
 @param aRight the right result to compare
 @param aVar variable to compare

 @param returns -1 if less, 0 if equal, or 1 if greater

PRInt32 compareResults(in nsIXULTemplateResult aLeft, in nsIXULTemplateResult aRight, in nsIAtom aVar)

 Compile a query from a node. The result of this function will later be
 passed to generateResults for result generation. If null is returned,
 the query will be ignored.

 The template builder will call this method once for each query within
 the template, before any results can be generated using generateResults,
 but after initializeForBuilding has been called. This method should not
 be called again for the same query unless the template is rebuilt.

 The reference variable may be used by the query processor as a
 placeholder for the reference point, or starting point in the query.

 The member variable is determined from the member attribute on the
 template, or from the uri in the first action's rule if that attribute is
 not present. A rule processor may use the member variable as a hint to
 indicate what variable is expected to contain the results.

 @param aBuilder the template builder
 @param aQuery <query> node to compile
 @param aRefVariable the reference variable
 @param aMemberVariable the member variable

 @returns a compiled query object

nsISupports compileQuery(in nsIXULTemplateBuilder aBuilder, in nsIDOMNode aQuery, in nsIAtom aRefVariable, in nsIAtom aMemberVariable)

 Called when the template builder is being destroyed so that the query
 processor can clean up any state. The query processor should remove as
 much state as possible, such as results or references to the builder.
 This method will also be called when the template is going to be rebuilt.

void done()

 Generate the results of a query and return them in an enumerator. The
 enumerator must contain nsIXULTemplateResult objects. If there are no
 results, an empty enumerator must be returned.

 The datasource will be the same as the one passed to the earlier
 initializeForBuilding method. The context reference (aRef) is a reference
 point used when calculating results.

 The value of aQuery must be the result of a previous call to compileQuery
 from this query processor. This method may be called multiple times,
 typically with different values for aRef.

 @param aDatasource datasource for the data
 @param aRef context reference value used as a starting point
 @param aQuery the compiled query returned from query compilation

 @returns an enumerator of nsIXULTemplateResult objects as the results

 @throws NS_ERROR_INVALID_ARG if aQuery is invalid

nsISimpleEnumerator generateResults(in nsISupports aDatasource, in nsIXULTemplateResult aRef, in nsISupports aQuery)

 Retrieve the datasource to use for the query processor. The list of
 datasources in a template is specified using the datasources attribute as
 a space separated list of URIs. This list is processed by the builder and
 supplied to the query processor in the aDataSources array as a list of
 nsIURI objects or nsIDOMNode objects. This method may return an object
 corresponding to these URIs and the builder will supply this object to
 other query processor methods. For example, for an XML source, the
 datasource might be an nsIDOMNode.

 All of these URIs are checked by the builder so it is safe to use them,
 however note that a URI that redirects may still needs to be checked to
 ensure that the document containing aRootNode may access it. This is the
 responsibility of the query processor if it needs to load the content of
 the URI.

 If the query processor needs to load the datasource asynchronously, it
 may set the aShouldDelayBuilding returned parameter to true to delay
 building the template content, and call the builder's Rebuild method when
 the data is available.

 @param aDataSources  the list of nsIURI objects and/or nsIDOMNode objects
 @param aRootNode     the root node the builder is attached to
 @param aIsTrusted    true if the template is in a trusted document
 @param aBuilder      the template builder
 @param aShouldDelayBuilding [out] whether the builder should wait to
                                   build the content or not
 @returns a datasource object

nsISupports getDatasource(in nsIArray aDataSources, in nsIDOMNode aRootNode, in boolean aIsTrusted, in nsIXULTemplateBuilder aBuilder, out boolean aShouldDelayBuilding)

 Initialize for query generation. This will be called before the rules are
 processed and whenever the template is rebuilt. This method must be
 called once before any of the other query processor methods except for
 translateRef.

 @param aDatasource datasource for the data
 @param aBuilder the template builder
 @param aRootNode the root node the builder is attached to

 @throws NS_ERROR_INVALID_ARG if the datasource is not supported or
         NS_ERROR_UNEXPECTED if generateResults has already been called.

void initializeForBuilding(in nsISupports aDatasource, in nsIXULTemplateBuilder aBuilder, in nsIDOMNode aRootNode)

 Translate a ref attribute string into a result. This is used as the
 reference point by the template builder when generating the first level
 of content. For recursive generation, the result from the parent
 generation phase will be used directly as the reference so a translation
 is not needed. This allows all levels to be generated using objects that
 all implement the nsIXULTemplateResult interface.

 This method may be called before initializeForBuilding, so the
 implementation may use the supplied datasource if it is needed to
 translate the reference.

 @param aDatasource datasource for the data
 @param aRefString the ref attribute string

 @return the translated ref

nsIXULTemplateResult translateRef(in nsISupports aDatasource, in AString aRefString)