NAME

DESCRIPTION

See also the XML::XQL man page.

INTRODUCTION

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 XML::XQL module has added functionality to the XQL spec, called 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 XML::XQL man page for more information about the Strict module. This tutorial will clearly indicate when referring to XQL+.

XQL Patterns

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.

Context

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.

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]
    

Query Results

Collections - 'element' and '.'

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
    

Selecting children and descendants - '/' and '//'

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
    

Collecting element children - '*'

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]
    

Finding an attribute - '@'

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.

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
    

XQL Literals

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 XML::XQL man page for details.

The empty list or undef is represented by [] (i.e. reference to empty array) in this implementation.

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+)
    

Grouping - '()'

Filters - '[]'

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.

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]
    

Indexing into a collection - '[]' and '$to$'

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

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]
    

Boolean Expressions

Note that the XQL Extensions section defines additional Boolean operations.

Union and intersection - '$union$', '|' and '$intersect$'

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.

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]
    

Equivalence - '$eq$', '=', '$ne$' and '!='

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'.

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'
    

Methods - 'method()' or 'query!method()'

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 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 XML::XQL man page on how to define your own methods and functions.

Functions

Don't worry if you don't get it. Just use them!

Sequence Operators - ';' and ';;'

Operator Precedence

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

Sample XML Document - bookstore.xml

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

SEE ALSO

XML::XQL, XML::XQL::Date, XML::XQL::Query and XML::XQL::DOM