tutorial(3)

NAME

XML::XQL::Tutorial - Describes the XQL query syntax

DESCRIPTION

This document describes basic the features of the XML
Query Language (XQL.) A proposal for the XML Query Lan
guage (XQL) specification was submitted to the XSL Working
Group in September 1998. The spec can be found at
<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.

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 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 dis
tinction 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

This section describes the core XQL notation. These fea
tures 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 naviga
tion syntax, but instead of specifying navigation through
a physical file structure, the navigation is through ele
ments 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

A context is the set of nodes against which a query oper ates. For the entire query, which is passed to the
XML::XQL::Query constructor through the 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 pre
fixed 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 nota
tions 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 exam
ple 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

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 implementa
tion does keep attributes in document order. See the
XML::XQL man page for more details regarding Document
Order.

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.

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

The collection of elements of a certain type can be deter
mined using the path operators ('/' or '//'). These opera
tors 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 col
lection, 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.

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 rel
ative 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, any
where inside the bookstore:

bookstore//book/excerpt//emph; Find all titles, one or more levels deep in the cur
rent context. Note that this situation is essentially
the only one where the period notation is required:

.//title

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 con
text, regardless of their tag name.

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 con
text:

*/*; Find all elements with specialty attributes. Note that
this example uses subqueries, which are covered in
Filters, and attributes, which are discussed in Find
ing an attribute:

*[@specialty]

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.

Examples:: Find the style attribute of the current element con
text:

@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

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

The empty list or undef is represented by [] (i.e. refer
ence 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

Grouping - '()'

Parentheses can be used to group collection operators for
clarity or where the normal precedence is inadequate to
express an operation.

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 fil ter, a Boolean TRUE is generated if the collection con tains any members, and a FALSE is generated if the collec tion 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 ele
ment:

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

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 sub script 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

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.

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 paren
theses, 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.

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]
Boolean NOT - '$not$'
$not$ is a Boolean operator that negates the value of an expression within a subquery.
Examples:: Find all author elements that contain at least one
degree element and that contain no publication ele
ments.

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$ publica

tion]

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

The $union$ operator (shortcut is '|') returns the com
bined 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.

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$ maga

zine[price $lt$ 10]

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 ele ment 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'
Comparison - '<', '<=', '>', '>=', '$lt', '$ilt$' etc.
A set of binary comparison operators is available for com paring 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$.
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]
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// delim iters in XQL+, see XML::XQL man page.)
Note that you can't use the Perl substitution operator s/// here. Try using the XQL+ subst() function instead.
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']
Oher XQL+ comparison operators - '$isa', '$can$'
See the XML::XQL man page for other operators available in XQL+.
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.
Comparisons and literals
The spec states that the lvalue of an expression cannot be a literal. That is, '1' = a is not allowed. This imple mentation allows it, but it's not clear how useful that is.
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 XML::XQL man page for details on cast ing.
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 dis agreement and their implementations differed on this point. This implementation is closest to that of Joe Lapp from webMethods, Inc.

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

XQL makes a distinction between functions and methods.
See the XML::XQL man page for details.

XQL provides methods for advanced manipulation of collec
tions. 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 correspond
ing 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 firstname 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.
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.
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 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'
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 XML::XQL man page for
details.
Method: value(): Returns a type cast version of the value of a node. If
no data type is provided, returns the same as text().; 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']
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 EntityRefer
ence nodes also return 3, whereas in the DOM CDATASec
tion returns 4 and EntityReference returns 5. Use the
XQL+ method DOM_nodeType() to get DOM node type val ues. See the XML::DOM man page for node type values
of nodes not mentioned here.
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)
Method: nodeName(): Returns the tag name for Element nodes and the
attribute name of attributes.
Collection index methods
Method: index(): Returns the index of the value within the search con
text (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.; 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]
Method: end(): The end() method returns true for the last element in
the search context. Again, the XQL spec does not
explain it well.; 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()]
Aggregate methods
Method: count( [QUERY] ): Returns the number of values inside the search con
text. In XQL+, when the optional QUERY parameter is
supplied, it returns the number of values returned by
the QUERY.
Namespace methods
The following methods can be applied to a node to return namespace information.
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 ele
ment 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.
Method: namespace(): Returns the URI for the namespace of the node. Names
pace 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 ele
ment 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.
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 docu
ment 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 prece
dence. In this implementation you cannot define the
namespace for a query, so this can never happen.; 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
All attributes of an element can be returned using @*. This is potentially useful for applications that treat attributes as fields in a record.
Examples:: Find all attributes of the current element con
text:

@*; Find style attributes from any namespace:

@*:style; Find all attributes from the 'my' namespace,
including unqualified attributes on elements from
the 'my' namespace:

@my:*

Functions

This section defines the functions of XQL. The spec states
that: XQL defines two kinds of functions: collection func
tions 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!

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 particu
lar restriction.

Function: textNode(): The collection of text nodes.
Function: comment(): The collection of comment nodes.
Function: pi(): The collection of processing instruction nodes.
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.
Function: attribute( [NAME] ): The collection of all attribute nodes. If the optional
text parameter is provided, it only returns attributes
matching that particular name.
Function: node(): The collection of all non-attribute nodes.; 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]
Other XQL Functions
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 refer
ence node itself.; Examples:
Find the nearest book ancestor of the current ele
ment:

ancestor(book)

Find the nearest ancestor author element that is
contained in a book element:

ancestor(book/author)
Function: id(NAME): Pure function that evaluates to a set. The set con
tains an element node that has an 'id' attribute whose
value is identical to the string that the Text parame
ter quotes. The element node may appear anywhere
within the document under query. If more than one ele
ment node meets these criteria, the function evaluates
to a set that contains the first node appearing in a
document ordering of the nodes.
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 vari
able substitution, since they may replace an expres
sion found in an instance of Subquery without violat
ing the syntax required by the instance of Subquery.
They return an object of type XML::XQL::Boolean.
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 XML::XQL to plug in
your own Date implementation.; Include the XML::XQL::Date package to add the XQL date
type and the date() function, like this:

use XML::XQL::Date;; Perl builtin functions and other XQL+ functions
XQL+ provides XQL function wrappers for most Perl
builtin functions. It also provides other cool func
tions 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 XML::XQL man page for details.

Sequence Operators - ';' and ';;'

The whitepaper 'The Design of XQL' by Jonathan Robie,
which can be found at <http://www.texcel.no/whitepa
pers/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.

Immediately Precedes - ';'

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)
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.
Precedes - ';;'
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 immedi ately 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")

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 asso ciated productions:: Production Operator(s)
---------- ----------Grouping ( )
Filter [ ]
Subscript [ ]
Bang !
Path / //
Match $match$ $no_match$ =~ !~ (XQL+ on; ly)
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

This file is also stored in samples/bookstore.xml that comes with the XML::XQL distribution.: <?xml version='1.0'?>

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

tion</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>

docs.sk

comprehensive documentation repository

Most Viewed