=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>