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