--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/dummy_foundation/lib/XML/XQL/Tutorial.pod Thu May 28 10:10:03 2009 +0100
@@ -0,0 +1,1357 @@
+=head1 NAME
+
+XML::XQL::Tutorial - Describes the XQL query syntax
+
+=head1 DESCRIPTION
+
+This document describes basic the features of the XML Query Language (XQL.)
+A proposal for the XML Query Language (XQL) specification was submitted
+to the XSL Working Group in September 1998.
+The spec can be found at L<http://www.w3.org/TandS/QL/QL98/pp/xql.html>.
+Since it is only a proposal at this point, things may change, but it is very
+likely that the final version will be close to the proposal.
+Most of this document was copied straight from the spec.
+
+See also the L<XML::XQL> man page.
+
+=head1 INTRODUCTION
+
+XQL (XML Query Language) provides a natural extension to the XSL pattern
+language. It builds upon the capabilities XSL provides for identifying classes
+of nodes, by adding Boolean logic, filters, indexing into collections of nodes,
+and more.
+
+XQL is designed specifically for XML documents.
+It is a general purpose query language, providing a single syntax
+that can be used for queries, addressing, and patterns.
+XQL is concise, simple, and powerful.
+
+XQL is designed to be used in many contexts. Although it is a superset of XSL
+patterns, it is also applicable to providing links to nodes, for searching
+repositories, and for many other applications.
+
+Note that the term XQL is a working term for the language described in this
+proposal. It is not their intent that this term be used permanently.
+Also, beware that another query language exists called XML-QL,
+which uses a syntax very similar to SQL.
+
+The L<XML::XQL> module has added functionality to the XQL spec, called I<XQL+>.
+To allow only XQL functionality as described in the spec, use the
+XML::XQL::Strict module. Note that the XQL spec makes the distinction between
+core XQL and XQL extensions. This implementation makes no distinction and
+the Strict module, therefore, implements everything described in the XQL spec.
+See the L<XML::XQL> man page for more information about the Strict module.
+This tutorial will clearly indicate when referring to XQL+.
+
+=head1 XQL Patterns
+
+This section describes the core XQL notation. These features should be part
+of every XQL implementation, and serve as the base level of functionality
+for its use in different technologies.
+
+The basic syntax for XQL mimics the URI directory navigation syntax, but
+instead of specifying navigation through a
+physical file structure, the navigation is through elements in the XML tree.
+
+For example, the following URI means find the foo.jpg file within the bar
+directory:
+
+ bar/foo.jpg
+
+Similarly, in XQL, the following means find the collection of fuz elements
+within baz elements:
+
+ baz/fuz
+
+Throughout this document you will find numerous samples. They refer to the data
+shown in the sample file at the end of this man page.
+
+=head1 Context
+
+A I<context> is the set of nodes against which a query operates.
+For the entire query, which is passed to the L<XML::XQL::Query>
+constructor through the I<Expr> option, the context is the list of input nodes
+that is passed to the query() method.
+
+XQL allows a query to select between using the current context as the input
+context and using the 'root context' as the input context.
+The 'root context' is a context containing only the root-most
+element of the document. When using XML::DOM, this is the Document object.
+
+By default, a query uses the current context. A query prefixed with '/'
+(forward slash) uses the root context. A query may
+optionally explicitly state that it is using the current context by using
+the './' (dot, forward slash) prefix. Both of these
+notations are analogous to the notations used to navigate directories in a file
+system.
+
+The './' prefix is only required in one situation. A query may use the '//'
+operator to indicate recursive descent. When
+this operator appears at the beginning of the query, the initial '/' causes the
+recursive decent to perform relative to the
+root of the document or repository. The prefix './/' allows a query to perform
+a recursive descent relative to the current context.
+
+=over 4
+
+=item Examples:
+
+Find all author elements within the current context. Since the period is really
+not used alone, this example forward-references other features:
+
+ ./author
+
+Note that this is equivalent to:
+
+ author
+
+Find the root element (bookstore) of this document:
+
+ /bookstore
+
+Find all author elements anywhere within the current document:
+
+ //author
+
+Find all books where the value of the style attribute on the book is equal to
+the value of the specialty attribute of the bookstore element at the root of
+the document:
+
+ book[/bookstore/@specialty = @style]
+
+=back
+
+=head1 Query Results
+
+The collection returned by an XQL expression preserves document order,
+hierarchy, and identity, to the extent that these are defined.
+That is, a collection of elements will always be returned in document order
+without repeats. Note that the spec states that the order of attributes within
+an element is undefined, but that this implementation does keep attributes
+in document order. See the L<XML::XQL> man page for more details regarding
+I<Document Order>.
+
+=head1 Collections - 'element' and '.'
+
+The collection of all elements with a certain tag name is expressed using the
+tag name itself. This can be qualified by showing that the elements are
+selected from the current context './', but the current context is assumed and
+often need not be noted explicitly.
+
+=over 4
+
+=item Examples:
+
+Find all first-name elements. These examples are equivalent:
+
+ ./first-name
+
+ first-name
+
+Find all unqualified book elements:
+
+ book
+
+Find all first.name elements:
+
+ first.name
+
+=back
+
+=head1 Selecting children and descendants - '/' and '//'
+
+The collection of elements of a certain type can be determined using the path
+operators ('/' or '//'). These operators take as their arguments a collection
+(left side) from which to query elements, and a collection indicating which
+elements to select (right side). The child operator ('/')selects from immediate
+children of the left-side collection, while the descendant operator ('//')
+selects from arbitrary descendants of the left-side collection.
+In effect, the '//' can be thought of as a substitute for one or more levels of
+hierarchy. Note that the path operators change the context as the
+query is performed. By stringing them together users can 'drill down' into the
+document.
+
+=over 4
+
+=item Examples:
+
+Find all first-name elements within an author element. Note that the author
+children of the current context are found, and then first-name children are
+found relative to the context of the author elements:
+
+ author/first-name
+
+Find all title elements, one or more levels deep in the bookstore
+(arbitrary descendants):
+
+ bookstore//title
+
+Note that this is different from the following query, which finds all title
+elements that are grandchildren of bookstore elements:
+
+ bookstore/*/title
+
+Find emph elements anywhere inside book excerpts, anywhere inside the bookstore:
+
+ bookstore//book/excerpt//emph
+
+Find all titles, one or more levels deep in the current context. Note that this
+situation is essentially the only one where
+the period notation is required:
+
+ .//title
+
+=back
+
+=head1 Collecting element children - '*'
+
+An element can be referenced without using its name by substituting the '*'
+collection. The '*' collection returns all
+elements that are children of the current context, regardless of their tag name.
+
+=over 4
+
+=item Examples:
+
+Find all element children of author elements:
+
+ author/*
+
+Find all last-names that are grand-children of books:
+
+ book/*/last-name
+
+Find the grandchildren elements of the current context:
+
+ */*
+
+Find all elements with specialty attributes. Note that this example uses
+subqueries, which are covered in Filters, and
+attributes, which are discussed in Finding an attribute:
+
+ *[@specialty]
+
+=back
+
+=head1 Finding an attribute - '@'
+
+Attribute names are preceded by the '@' symbol. XQL is designed to treat
+attributes and sub-elements impartially,
+and capabilities are equivalent between the two types wherever possible.
+
+Note: attributes cannot contain subelements. Thus, attributes cannot have path
+operators applied to them in a query.
+Such expressions will result in a syntax error.
+The XQL spec states that attributes are inherently unordered and indices
+cannot be applied to them, but this implementation allows it.
+
+=over 4
+
+=item Examples:
+
+Find the style attribute of the current element context:
+
+ @style
+
+Find the exchange attribute on price elements within the current context:
+
+ price/@exchange
+
+The following example is not valid:
+
+ price/@exchange/total
+
+Find all books with style attributes. Note that this example uses subqueries,
+which are covered in Filters:
+
+ book[@style]
+
+Find the style attribute for all book elements:
+
+ book/@style
+
+=back
+
+=head1 XQL Literals
+
+XQL query expressions may contain literal values (i.e. constants.)
+Numbers (integers and floats) are wrapped in XML::XQL::Number objects and
+strings in XML::XQL::Text objects. Booleans (as returned by true() and false())
+are wrapped in XML::XQL::Boolean objects.
+
+Strings must be enclosed in single or double quotes. Since XQL does not allow
+escaping of special characters, it's impossible to create a string with both
+a single and a double quote in it. To remedy this, XQL+ has added the q// and
+qq// string delimiters which behave just like they do in Perl.
+
+For Numbers, exponential notation is not allowed. Use the XQL+ function eval()
+to circumvent this problem. See L<XML::XQL> man page for details.
+
+The empty list or undef is represented by [] (i.e. reference to empty array)
+in this implementation.
+
+=over 4
+
+=item Example
+
+Integer Numbers:
+
+ 234
+ -456
+
+Floating point Numbers:
+
+ 1.23
+ -0.99
+
+Strings:
+
+ "some text with 'single' quotes"
+ 'text with "double" quotes'
+
+Not allowed:
+
+ 1.23E-4 (use eval("1.23E-4", "Number") in XQL+)
+
+ "can't use \"double \"quotes" (use q/can't use "double" quotes/ in XQL+)
+
+=back
+
+=head1 Grouping - '()'
+
+Parentheses can be used to group collection operators for clarity or where the
+normal precedence is inadequate to express an operation.
+
+=head1 Filters - '[]'
+
+Constraints and branching can be applied to any collection by adding a filter
+clause '[ ]' to the collection. The filter is analogous to the SQL WHERE clause
+with ANY semantics. The filter contains a query within it, called the
+subquery. The subquery evaluates to a Boolean, and is tested for each element
+in the collection. Any elements in the collection failing the subquery test are
+omitted from the result collection.
+
+For convenience, if a collection is placed within the filter, a Boolean TRUE
+is generated if the collection contains any members, and a FALSE is generated
+if the collection is empty. In essence, an expression such as author/degree
+implies a collection-to-Boolean conversion function like the following
+mythical 'there-exists-a' method.
+
+ author[.there-exists-a(degree)]
+
+Note that any number of filters can appear at a given level of an expression.
+Empty filters are not allowed.
+
+=over 4
+
+=item Examples:
+
+Find all books that contain at least one excerpt element:
+
+ book[excerpt]
+
+Find all titles of books that contain at least one excerpt element:
+
+ book[excerpt]/title
+
+Find all authors of books where the book contains at least one excerpt, and
+the author has at least one degree:
+
+ book[excerpt]/author[degree]
+
+Find all books that have authors with at least one degree:
+
+ book[author/degree]
+
+Find all books that have an excerpt and a title:
+
+ book[excerpt][title]
+
+=back
+
+=head2 Any and all semantics - '$any$' and '$all$'
+
+Users can explicitly indicate whether to use any or all semantics through
+the $any$ and $all$ keywords.
+
+$any$ flags that a condition will hold true if any item in a set meets that
+condition. $all$ means that all elements in a
+set must meet the condition for the condition to hold true.
+
+$any$ and $all$ are keywords that appear before a subquery expression within
+a filter.
+
+=over 4
+
+=item Examples:
+
+Find all author elements where one of the last names is Bob:
+
+ author[last-name = 'Bob']
+
+ author[$any$ last-name = 'Bob']
+
+Find all author elements where none of the last-name elements are Bob:
+
+ author[$all$ last-name != 'Bob']
+
+Find all author elements where the first last name is Bob:
+
+ author[last-name[0] = 'Bob']
+
+=back
+
+=head1 Indexing into a collection - '[]' and '$to$'
+
+XQL makes it easy to find a specific node within a set of nodes.
+Simply enclose the index ordinal within square brackets. The ordinal is 0 based.
+
+A range of elements can be returned. To do so, specify an expression rather
+than a single value inside of the subscript operator (square brackets).
+Such expressions can be a comma separated list of any of the following:
+
+ n Returns the nth element
+ -n Returns the element that is n-1 units from the last element.
+ E.g., -1 means the last element. -2 is the next to last element.
+ m $to$ n Returns elements m through n, inclusive
+
+=over 4
+
+=item Examples:
+
+Find the first author element:
+
+ author[0]
+
+Find the third author element that has a first-name:
+
+ author[first-name][2]
+
+Note that indices are relative to the parent. In other words, consider the
+following data:
+
+ <x>
+ <y/>
+ <y/>
+ </x>
+ <x>
+ <y/>
+ <y/>
+ </x>
+
+The following expression will return the first y from each of the x's:
+
+ x/y[0]
+
+The following will return the first y from the entire set of y's within x's:
+
+ (x/y)[0]
+
+The following will return the first y from the first x:
+
+ x[0]/y[0]
+
+Find the first and fourth author elements:
+
+ author[0,3]
+
+Find the first through fourth author elements:
+
+ author[0 $to$ 3]
+
+Find the first, the third through fifth, and the last author elements:
+
+ author[0, 2 $to$ 4, -1]
+
+Find the last author element:
+
+ author[-1]
+
+=back
+
+=head1 Boolean Expressions
+
+Boolean expressions can be used within subqueries. For example, one could use
+Boolean expressions to find all nodes of a particular value, or all nodes with
+nodes in particular ranges. Boolean expressions are of the form
+${op}$, where {op} may be any expression of the form {b|a} - that is, the
+operator takes lvalue and rvalue arguments and returns a Boolean result.
+
+Note that the XQL Extensions section defines additional Boolean operations.
+
+=head2 Boolean AND and OR - '$and$' and '$or$'
+
+$and$ and $or$ are used to perform Boolean ands and ors.
+
+The Boolean operators, in conjunction with grouping parentheses, can be used to
+build very sophisticated logical expressions.
+
+Note that spaces are not significant and can be omitted, or included for
+clarity as shown here.
+
+=over 4
+
+=item Examples:
+
+Find all author elements that contain at least one degree and one award.
+
+ author[degree $and$ award]
+
+Find all author elements that contain at least one degree or award and at
+least one publication.
+
+ author[(degree $or$ award) $and$ publication]
+
+=back
+
+=head2 Boolean NOT - '$not$'
+
+$not$ is a Boolean operator that negates the value of an expression within a
+subquery.
+
+=over 4
+
+=item Examples:
+
+Find all author elements that contain at least one degree element and that
+contain no publication elements.
+
+ author[degree $and$ $not$ publication]
+
+Find all author elements that contain publications elements but do not contain
+either degree elements or award elements.
+
+ author[$not$ (degree $or$ award) $and$ publication]
+
+=back
+
+=head1 Union and intersection - '$union$', '|' and '$intersect$'
+
+The $union$ operator (shortcut is '|') returns the combined set of values from
+the query on the left and the query on the right. Duplicates are filtered out.
+The resulting list is sorted in document order.
+
+Note: because this is a union, the set returned may include 0 or more elements
+of each element type in the list. To restrict the returned set to nodes that
+contain at least one of each of the elements in the list, use a filter, as
+discussed in Filters.
+
+The $intersect$ operator returns the set of elements in common between two sets.
+
+=over 4
+
+=item Examples:
+
+Find all first-names and last-names:
+
+ first-name $union$ last-name
+
+Find all books and magazines from a bookstore:
+
+ bookstore/(book | magazine)
+
+Find all books and all authors:
+
+ book $union$ book/author
+
+Find the first-names, last-names, or degrees from authors within either books
+or magazines:
+
+ (book $union$ magazine)/author/(first-name $union$ last-name $union$ degree)
+
+Find all books with author/first-name equal to 'Bob' and all magazines with
+price less than 10:
+
+ book[author/first-name = 'Bob'] $union$ magazine[price $lt$ 10]
+
+=back
+
+=head1 Equivalence - '$eq$', '=', '$ne$' and '!='
+
+The '=' sign is used for equality; '!=' for inequality. Alternatively, $eq$ and
+ $ne$ can be used for equality and inequality.
+
+Single or double quotes can be used for string delimiters in expressions.
+This makes it easier to construct and pass XQL from within scripting languages.
+
+For comparing values of elements, the value() method is implied. That is,
+last-name < 'foo' really means last-name!value() < 'foo'.
+
+Note that filters are always with respect to a context. That is, the expression
+book[author] means for every book element that is found, see if it has an
+author subelement. Likewise, book[author = 'Bob'] means for
+every book element that is found, see if it has a subelement named author
+whose value is 'Bob'. One can examine the value of the context as well, by
+using the . (period). For example, book[. = 'Trenton'] means for every
+book that is found, see if its value is 'Trenton'.
+
+=over 4
+
+=item Examples:
+
+Find all author elements whose last name is Bob:
+
+ author[last-name = 'Bob']
+
+ author[last-name $eq$ 'Bob']
+
+Find all authors where the from attribute is not equal to 'Harvard':
+
+ degree[@from != 'Harvard']
+
+ degree[@from $ne$ 'Harvard']
+
+Find all authors where the last-name is the same as the /guest/last-name element:
+
+ author[last-name = /guest/last-name]
+
+Find all authors whose text is 'Matthew Bob':
+
+ author[. = 'Matthew Bob']
+
+ author = 'Matthew Bob'
+
+=back
+
+=head2 Comparison - '<', '<=', '>', '>=', '$lt', '$ilt$' etc.
+
+A set of binary comparison operators is available for comparing numbers and
+strings and returning Boolean results.
+$lt$, $le$, $gt$, $ge$ are used for less than, less than or equal, greater
+than, or greater than or equal. These same
+operators are also available in a case insensitive form: $ieq$, $ine$, $ilt$,
+$ile$, $igt$, $ige$.
+
+<, <=, > and >= are allowed short cuts for $lt$, $le$, $gt$ and $ge$.
+
+=over 4
+
+=item Examples:
+
+Find all author elements whose last name is bob and whose price is > 50
+
+ author[last-name = 'Bob' $and$ price $gt$ 50]
+
+Find all authors where the from attribute is not equal to 'Harvard':
+
+ degree[@from != 'Harvard']
+
+Find all authors whose last name begins with 'M' or greater:
+
+ author[last-name $ge$ 'M']
+
+Find all authors whose last name begins with 'M', 'm' or greater:
+
+ author[last-name $ige$ 'M']
+
+Find the first three books:
+
+ book[index() $le$ 2]
+
+Find all authors who have more than 10 publications:
+
+ author[publications!count() $gt$ 10]
+
+=back
+
+=head2 XQL+ Match operators - '$match$', '$no_match$', '=~' and '!~'
+
+XQL+ defines additional operators for pattern matching. The $match$ operator
+(shortcut is '=~') returns TRUE if the lvalue matches the pattern described by
+the rvalue. The $no_match$ operator (shortcut is '!~') returns FALSE if they
+match. Both lvalue and rvalue are first cast to strings.
+
+The rvalue string should have the syntax of a Perl rvalue, that is the delimiters
+should be included and modifiers are allowed. When using delimiters other than
+slashes '/', the 'm' should be included. The rvalue should be a string, so don't
+forget the quotes! (Or use the q// or qq// delimiters in XQL+, see L<XML::XQL>
+man page.)
+
+Note that you can't use the Perl substitution operator s/// here. Try using the
+XQL+ subst() function instead.
+
+=over 4
+
+=item Examples:
+
+Find all authors whose name contains bob or Bob:
+
+ author[first-name =~ '/[Bb]ob/']
+
+Find all book titles that don't contain 'Trenton' (case-insensitive):
+
+ book[title !~ 'm!trenton!i']
+
+=back
+
+=head2 Oher XQL+ comparison operators - '$isa', '$can$'
+
+See the L<XML::XQL> man page for other operators available in XQL+.
+
+=head2 Comparisons and vectors
+
+The lvalue of a comparison can be a vector or a scalar. The rvalue of a
+comparison must be a scalar or a value that can be cast at runtime to a scalar.
+
+If the lvalue of a comparison is a set, then any (exists) semantics are used
+for the comparison operators. That is, the result of a comparison is true if
+any item in the set meets the condition.
+
+=head2 Comparisons and literals
+
+The spec states that the lvalue of an expression cannot be a literal.
+That is, I<'1' = a> is not allowed. This implementation allows it, but it's not
+clear how useful that is.
+
+=head2 Casting of literals during comparison
+
+Elements, attributes and other XML node types are casted to strings (Text)
+by applying the value() method. The value() method calls the text() method by
+default, but this behavior can be altered by the user, so the value() method
+may return other XQL data types.
+
+When two values are compared, they are first casted to the same type.
+See the L<XML::XQL> man page for details on casting.
+
+Note that the XQL spec is not very clear on how values should be casted for
+comparison. Discussions with the authors of the XQL spec revealed that there
+was some disagreement and their implementations differed on this point.
+This implementation is closest to that of Joe Lapp from webMethods, Inc.
+
+=head1 Methods - 'method()' or 'query!method()'
+
+XQL makes a distinction between functions and methods.
+See the L<XML::XQL> man page for details.
+
+XQL provides methods for advanced manipulation of collections. These methods
+provide specialized collections of nodes (see Collection methods), as well as
+information about sets and nodes.
+
+Methods are of the form I<method(arglist)>
+
+Consider the query book[author]. It will find all books that have authors.
+Formally, we call the book corresponding to a particular author the reference
+node for that author. That is, every author element that is examined is an author
+for one of the book elements. (See the Annotated XQL BNF Appendix for a much
+more thorough definition of reference node and other terms. See also the
+XML::XQL man page.) Methods always apply to the reference node.
+
+For example, the text() method returns the text contained within a node,
+minus any structure. (That is, it is the concatenation of all text nodes
+contained with an element and its descendants.) The following expression will
+return all authors named 'Bob':
+
+ author[text() = 'Bob']
+
+The following will return all authors containing a first-name child whose
+text is 'Bob':
+
+ author[first-name!text() = 'Bob']
+
+The following will return all authors containing a child named Bob:
+
+ author[*!text() = 'Bob']
+
+Method names are case sensitive.
+See the L<XML::XQL> man page on how to define your own methods and functions.
+
+=head2 Information methods
+
+The following methods provide information about nodes in a collection.
+These methods return strings or numbers,
+and may be used in conjunction with comparison operators within subqueries.
+
+=over 4
+
+=item Method: text()
+
+The text() method concatenates text of the descendents of a node,
+normalizing white space along the way. White space will be preserved for a node
+if the node has the xml:space attribute set to 'preserve', or if the
+nearest ancestor with the xml:space attribute has the attribute set to
+'preserve'. When white space is normalized, it is normalized across the
+entire string. Spaces are used to separate the text between nodes.
+When entity references are used in a document, spacing is not inserted
+around the entity refs when they are expanded.
+
+In this implementation, the method may receive an optional parameter
+to indicate whether the text() of Element nodes should include the text() of
+its Element descendants. See L<XML::XQL> man page for details.
+
+Examples:
+
+Find the authors whose last name is 'Bob':
+
+ author[last-name!text() = 'Bob']
+
+Note this is equivalent to:
+
+ author[last-name = 'Bob']
+
+Find the authors with value 'Matthew Bob':
+
+ author[text() = 'Matthew Bob']
+
+ author[. = 'Matthew Bob']
+
+ author = 'Matthew Bob'
+
+=item Method: rawText()
+
+The rawText() method is similar to the text() method, but it does not
+normalize whitespace.
+
+In this implementation, the method may receive an optional parameter
+to indicate whether the rawText() of Element nodes should include the
+rawText() of its Element descendants. See L<XML::XQL> man page for details.
+
+=item Method: value()
+
+Returns a type cast version of the value of a node. If no data type is
+provided, returns the same as text().
+
+=over 4
+
+=item Shortcuts
+
+For the purposes of comparison, value( )is implied if omitted.
+In other words, when two items are compared, the comparison is between
+the value of the two items. Remember that in absence of type information,
+value() returns text().
+
+The following examples are equivalent:
+
+ author[last-name!value() = 'Bob' $and$ first-name!value() = 'Joe']
+
+ author[last-name = 'Bob' $and$ first-name = 'Joe']
+
+ price[@intl!value() = 'canada']
+
+ price[@intl = 'canada']
+
+=back
+
+=item Method: nodeType()
+
+Returns a number to indicate the type of the node. The values were based
+on the node type values in the DOM:
+
+ element 1
+ attribute 2
+ text 3
+ entity 6 (not in XQL spec)
+ PI 7
+ comment 8
+ document 9
+ doc. fragment 10 (not in XQL spec)
+ notation 11 (not in XQL spec)
+
+Note that in XQL, CDATASection nodes and EntityReference nodes also return 3,
+whereas in the DOM CDATASection returns 4 and EntityReference returns 5.
+Use the XQL+ method DOM_nodeType() to get DOM node type values.
+See the L<XML::DOM> man page for node type values of nodes not mentioned here.
+
+=item Method: nodeTypeString
+
+Returns the name of the node type in lowercase or an empty string. The
+following node types are currently supported 1 (element), 2 (attribute),
+3 (text), 7 (processing_instruction), 8 (comment), 9 (document)
+
+=item Method: nodeName()
+
+Returns the tag name for Element nodes and the attribute name of attributes.
+
+=back
+
+=head2 Collection index methods
+
+=over 4
+
+=item Method: index()
+
+Returns the index of the value within the search context (i.e. with the input
+list of the subquery.) This is not necessarily the same as the index of a
+node within its parent node. Note that the XQL spec doesn't explain it well.
+
+=over 4
+
+=item Examples:
+
+Find the first 3 degrees:
+
+ degree[index() $lt$ 3]
+
+Note that it skips over other nodes that may exist between the degree elements.
+
+Consider the following data:
+
+ <x>
+ <y/>
+ <y/>
+ </x>
+ <x>
+ <y/>
+ <y/>
+ </x>
+
+The following expression will return the first y from each x:
+
+ x/y[index() = 0]
+
+This could also be accomplished by (see Indexing into a Collection):
+
+ x/y[0]
+
+=back
+
+=item Method: end()
+
+The end() method returns true for the last element in the search context.
+Again, the XQL spec does not explain it well.
+
+=over 4
+
+=item Examples:
+
+Find the last book:
+
+ book[end()]
+
+Find the last author for each book:
+
+ book/author[end()]
+
+Find the last author from the entire set of authors of books:
+
+ (book/author)[end()]
+
+=back
+
+=back
+
+=head2 Aggregate methods
+
+=over 4
+
+=item Method: count( [QUERY] )
+
+Returns the number of values inside the search context.
+In XQL+, when the optional QUERY parameter is supplied, it returns the number of
+values returned by the QUERY.
+
+=back
+
+=head2 Namespace methods
+
+The following methods can be applied to a node to return namespace information.
+
+=over 4
+
+=item Method: baseName()
+
+Returns the local name portion of the node, excluding the prefix.
+Local names are defined only for element nodes and attribute nodes.
+The local name of an element node is the local
+portion of the node's element type name. The local name of an attribute node is
+the local portion of the node's attribute name. If a local name is not defined
+for the reference node, the method evaluates to the empty set.
+
+=item Method: namespace()
+
+Returns the URI for the namespace of the node.
+Namespace URIs are defined only for element nodes and attribute nodes.
+The namespace URI of an element node is the namespace URI associated with the
+node's element type name. The namespace URI of an attribute node is
+the namespace URI associated with the node's attribute name. If a namespace
+URI is not defined for the reference node, the method evaluates to the
+empty set.
+
+=item Method: prefix()
+
+Returns the prefix for the node. Namespace prefixes are defined only for
+element nodes and attribute nodes. The namespace prefix of an element
+node is the shortname for the namespace of the node's element type name.
+The namespace prefix of an attribute
+node is the shortname for the namespace of the node's attribute name.
+If a namespace prefix is not defined
+for the reference node, the method evaluates to the empty set.
+
+The spec states: A node's namespace prefix may be defined
+within the query expression, within the document under query, or within both
+the query expression and the document under query. If it is defined in both
+places the prefixes may not agree. In this case, the prefix assigned by
+the query expression takes precedence.
+In this implementation you cannot define the namespace for a query, so this
+can never happen.
+
+=over 4
+
+=item Examples:
+
+Find all unqualified book elements. Note that this does not return my:book
+elements:
+
+ book
+
+Find all book elements with the prefix 'my'. Note that this query does not
+return unqualified book elements:
+
+ my:book
+
+Find all book elements with a 'my' prefix that have an author subelement:
+
+ my:book[author]
+
+Find all book elements with a 'my' prefix that have an author subelement with a
+my prefix:
+
+ my:book[my:author]
+
+Find all elements with a prefix of 'my':
+
+ my:*
+
+Find all book elements from any namespace:
+
+ *:book
+
+Find any element from any namespace:
+
+ *
+
+Find the style attribute with a 'my' prefix within a book element:
+
+ book/@my:style
+
+=back
+
+All attributes of an element can be returned using @*.
+This is potentially useful for applications that treat attributes
+as fields in a record.
+
+=over 4
+
+=item Examples:
+
+Find all attributes of the current element context:
+
+ @*
+
+Find style attributes from any namespace:
+
+ @*:style
+
+Find all attributes from the 'my' namespace, including unqualified attributes on
+elements from the 'my' namespace:
+
+ @my:*
+
+=back
+
+=back
+
+=head1 Functions
+
+This section defines the functions of XQL. The spec states that:
+XQL defines two kinds of functions:
+collection functions and pure functions. Collection functions use the search
+context of the Invocation instance, while pure functions ignore the
+search context, except to evaluate the function's parameters. A collection
+function evaluates to a subset of the search context, and a pure function
+evaluates to either a constant value or to a value that depends only on the
+function's parameters.
+
+Don't worry if you don't get it. Just use them!
+
+=head2 Collection functions
+
+The collection functions provide access to the various types of nodes in a
+document. Any of these collections can be constrained and indexed.
+The collections return the set of children of the reference node meeting the
+particular restriction.
+
+=over 4
+
+=item Function: textNode()
+
+The collection of text nodes.
+
+=item Function: comment()
+
+The collection of comment nodes.
+
+=item Function: pi()
+
+The collection of processing instruction nodes.
+
+=item Function: element( [NAME] )
+
+The collection of all element nodes. If the optional text
+parameter is provided, it only returns element children
+matching that particular name.
+
+=item Function: attribute( [NAME] )
+
+The collection of all attribute nodes. If the optional text
+parameter is provided, it only returns attributes matching that
+particular name.
+
+=item Function: node()
+
+The collection of all non-attribute nodes.
+
+=over 4
+
+=item Examples:
+
+Find the second text node in each p element in the current context:
+
+ p/textNode()[1]
+
+Find the second comment anywhere in the document. See Context for details on
+setting the context to the document root:
+
+ //comment()[1]
+
+=back
+
+=back
+
+=head2 Other XQL Functions
+
+=over 4
+
+=item Function: ancestor(QUERY)
+
+Finds the nearest ancestor matching the provided query. It returns either a
+single element result or an empty set [].
+Note that this node is never the reference node itself.
+
+=over 4
+
+=item Examples:
+
+Find the nearest book ancestor of the current element:
+
+ ancestor(book)
+
+Find the nearest ancestor author element that is contained in a book element:
+
+ ancestor(book/author)
+
+=back
+
+=item Function: id(NAME)
+
+Pure function that evaluates to a set. The set contains an element node that
+has an 'id' attribute whose value is identical to the string that the Text
+parameter quotes. The element node may appear anywhere within the
+document under query. If more than one element node meets these criteria,
+the function evaluates to a set that contains the first node appearing in a
+document ordering of the nodes.
+
+=item Function: true() and false()
+
+Pure functions that each evaluate to a Boolean. "true()" evaluates to 'true',
+and "false()" evaluates to 'false'. These functions are useful in expressions
+that are constructed using entity references or variable substitution, since
+they may replace an expression found in an instance of Subquery without
+violating the syntax required by the instance of Subquery.
+They return an object of type XML::XQL::Boolean.
+
+=item Function: date(QUERY)
+
+"date" is a pure function that typecasts the value of its parameter to a set of
+dates. If the parameter matches a single string, the value of the function is a
+set containing a single date. If the parameter matches a QUERY, the value of
+the function is a set of dates, where the set contains one date for each member
+of the set to which the parameter evaluates.
+
+XQL does not define the representation of the date value, nor does it
+define how the function translates parameter values into dates.
+This implementation uses the Date::Manip module to parse dates, which accepts
+almost any imaginable format. See L<XML::XQL> to plug in your own
+Date implementation.
+
+Include the L<XML::XQL::Date> package to add the XQL date type and the date()
+function, like this:
+
+ use XML::XQL::Date;
+
+=item Perl builtin functions and other XQL+ functions
+
+XQL+ provides XQL function wrappers for most Perl builtin functions.
+It also provides other cool functions like subst(), map(), and eval() that
+allow you to modify documents and embed perl code.
+If this is still not enough, you can add your own function and methods.
+See L<XML::XQL> man page for details.
+
+=back
+
+=head1 Sequence Operators - ';' and ';;'
+
+The whitepaper 'The Design of XQL' by Jonathan Robie, which can be found
+at L<http://www.texcel.no/whitepapers/xql-design.html> describes the sequence
+operators ';;' (precedes) and ';' (immediately precedes.) Although these
+operators are not included in the XQL spec, I thought I'd add them anyway.
+
+=head2 Immediately Precedes - ';'
+
+=over 4
+
+=item Example:
+
+With the following input:
+
+ <TABLE>
+ <ROWS>
+ <TR>
+ <TD>Shady Grove</TD>
+ <TD>Aeolian</TD>
+ </TR>
+ <TR>
+ <TD>Over the River, Charlie</TD>
+ <TD>Dorian</TD>
+ </TR>
+ </ROWS>
+ </TABLE>
+
+Find the TD node that contains "Shady Grove" and the TD node that immediately
+follows it:
+
+ //(TD="Shady Grove" ; TD)
+
+=back
+
+Note that in XML::DOM there is actually a text node with whitespace between
+the two TD nodes, but those are ignored by this operator, unless the text node
+has 'xml:space' set to 'preserve'. See ??? for details.
+
+=head2 Precedes - ';;'
+
+=over 4
+
+=item Example:
+
+With the following input (from Hamlet):
+
+ <SPEECH>
+ <SPEAKER>MARCELLUS</SPEAKER>
+ <LINE>Tis gone!</LINE>
+ <STAGEDIR>Exit Ghost</STAGEDIR>
+ <LINE>We do it wrong, being so majestical,</LINE>
+ <LINE>To offer it the show of violence;</LINE>
+ <LINE>For it is, as the air, invulnerable,</LINE>
+ <LINE>And our vain blows malicious mockery.</LINE>
+ </SPEECH>
+
+Return the STAGEDIR and all the LINEs that follow it:
+
+ SPEECH//( STAGEDIR ;; LINE )
+
+Suppose an actor playing the ghost wants to know when to exit; that is, he
+wants to know who says what line just before
+he is supposed to exit. The line immediately precedes the stagedir, but the
+speaker may occur at any time before the line.
+In this query, we will use the "precedes" operator (";;") to identify a speaker
+that precedes the line somewhere within a
+speech. Our ghost can find the required information with the following query,
+which selects the speaker, the line, and the stagedir:
+
+ SPEECH//( SPEAKER ;; LINE ; STAGEDIR="Exit Ghost")
+
+=back
+
+=head1 Operator Precedence
+
+The following table lists operators in precedence order, highest precedence
+first, where operators of a given row have the same precedence.
+The table also lists the associated productions:
+
+ Production Operator(s)
+ ---------- -----------
+ Grouping ( )
+ Filter [ ]
+ Subscript [ ]
+ Bang !
+ Path / //
+ Match $match$ $no_match$ =~ !~ (XQL+ only)
+ Comparison = != < <= > >= $eq$ $ne$ $lt$ $le$ $gt$
+ $ge$ $ieq$ $ine$ $ilt$ $ile$ $igt$ $ige$
+ Intersection $intersect$
+ Union $union$ |
+ Negation $not$
+ Conjunction $and$
+ Disjunction $or$
+ Sequence ; ;;
+
+=head1 Sample XML Document - bookstore.xml
+
+This file is also stored in samples/bookstore.xml that comes with the
+XML::XQL distribution.
+
+ <?xml version='1.0'?>
+ <!-- This file represents a fragment of a book store inventory database -->
+ <bookstore specialty='novel'>
+ <book style='autobiography'>
+ <title>Seven Years in Trenton</title>
+ <author>
+ <first-name>Joe</first-name>
+ <last-name>Bob</last-name>
+ <award>Trenton Literary Review Honorable Mention</award>
+ </author>
+ <price>12</price>
+ </book>
+ <book style='textbook'>
+ <title>History of Trenton</title>
+ <author>
+ <first-name>Mary</first-name>
+ <last-name>Bob</last-name>
+ <publication>
+ Selected Short Stories of
+ <first-name>Mary</first-name> <last-name>Bob</last-name>
+ </publication>
+ </author>
+ <price>55</price>
+ </book>
+ <magazine style='glossy' frequency='monthly'>
+ <title>Tracking Trenton</title>
+ <price>2.50</price>
+ <subscription price='24' per='year'/>
+ </magazine>
+ <book style='novel' id='myfave'>
+ <title>Trenton Today, Trenton Tomorrow</title>
+ <author>
+ <first-name>Toni</first-name>
+ <last-name>Bob</last-name>
+ <degree from='Trenton U'>B.A.</degree>
+ <degree from='Harvard'>Ph.D.</degree>
+ <award>Pulizer</award>
+ <publication>Still in Trenton</publication>
+ <publication>Trenton Forever</publication>
+ </author>
+ <price intl='canada' exchange='0.7'>6.50</price>
+ <excerpt>
+ <p>It was a dark and stormy night.</p>
+ <p>But then all nights in Trenton seem dark and
+ stormy to someone who has gone through what
+ <emph>I</emph> have.</p>
+ <definition-list>
+ <term>Trenton</term>
+ <definition>misery</definition>
+ </definition-list>
+ </excerpt>
+ </book>
+ <my:book style='leather' price='29.50' xmlns:my='http://www.placeholder-name-here.com/schema/'>
+ <my:title>Who's Who in Trenton</my:title>
+ <my:author>Robert Bob</my:author>
+ </my:book>
+ </bookstore>
+
+=head1 SEE ALSO
+
+The Japanese version of this document can be found on-line at
+L<http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>
+
+L<XML::XQL>, L<XML::XQL::Date>, L<XML::XQL::Query> and L<XML::XQL::DOM>
+