0.07 Wed May 26 1999
- Fixed another wierd bug :)
- Let expat handle context.
NAME
XML::QL - An XML query language
VERSION
0.07
SYNOPSIS
$ql = 'WHERE $head ORDER-BY $head IN "file:REC-xml-
19980210.xml" CONSTRUCT $head';
print XML::QL->query($sql);
DESCRIPTION
This module is an early implementation of a note published by
the W3C called "XML-QL: A Query Language for XML". XML-QL allows
the user to query an XML document much like a database, and
describe a construct for output. Currently this module only
offers partial functionality as described in the specification,
and even some of that has been changed for ease of use. This
documentation will describe the fuctionality of this module as
well as differences from the XML-QL specification.
METHODS
query( "query" )
This is the only method required to use this module. This
one method allows the user to pass a valid XML-QL query to
the module, and the return value is the output.
XML-QL: The Query Language
The basic syntax consists of two parts, a WHERE clause to
describe the data to search for, and a CONSTRUCT clause to
describe how to return the data that is found.
WHERE
WHERE XML-searchstring [ORDER-BY variable [DESCENDING] [,
variable [DESCENDING]] ] IN 'filename'
The WHERE clause can be separated into several parts. The
first is the search string, the second is an optional ORDER-
BY clause much like ORDER BY in SQL, and last is the
required XML document file name. Each of these parts is
described below.
XML-searchstring
The search string MUST be a valid XML snippet. This is
one are where this module differs from the
specification. It has been implemented in this way so
that the search string may be parsed by the XML::Parser
module.
The first step in building a query is to list the tags
to search for in the document. For example, consider the
following search string:
This search string will search for the AUTHOR tag nested
within a BOOK tag. Note however that no information has
been selected for retrieval. In the following example,
we actually grab some information:
$author
The variable name $author will grab the information that
it finds withing this tag, and makes this information
avalable to us for use in the CONSTRUCT section of the
query. You will notice that variable names start with a
dollar sign ($), as this is called for by the
specification. In Perl, this means that if the query is
enclosed in double quotes, this dollar sign must be
escaped.
In the following example we take it a step further by
searching for books of that are non-fiction:
$author
We can also express this as a regular expression:
$author
This is another area where this module differs from the
specification. The regular expesssion ability as defined
in the specification only allows for a subset of the
ability available in a Perl regular expression. With
this module, the full range of regular expression syntax
has been made available. This also means that you must
also escape things such as periods(.), parenthesis (),
and brackets ([]). All non tag matched are case
insensitive.
Now lets say that besides matching the TYPE, we also
wanted to grab the value. Consider this example:
$author
The AS_ELEMENT keyword allows you to save the matched
value for later use in the CONSTRUCT portion of the
query.
ORDER-BY
The ORDER-BY clause allows to sort the data retrieved in
the variables. You may specify multiple variables, and
specify DESCENDING for a reverse sort. This clause is
not required. For example:
ORDER-BY $type, $author DESCENDING
IN The IN clause is a required clause that specifies the file
name of the XML file. This can be any URI that is
supported by LWP, or it can be a single file name
enclosed in quotes. In later versions of this module
there will be support for multiple files, directories.
The following will work:
IN 'REC-xml-19980210.xml'
IN 'file://othermachine/share/filename.xml'
IN 'http://www.example.com/file.xml'
CONSTRUCT
The CONSTRUCT construct allows you to specify a template for
output. The template will match character for character from
the first space after the word CONSTRUCT to the end of the
XML-QL query. For example:
$ql = '(where clause...) CONSTRUCT Type: $type Author:
$author';
The ouput of this will then be a carriage return, a tab,
"Type: ", the contents of $type, a carriage return, a tab,
"Author: ", and the contents of $author. This construct will
be repeated for every match found and returned as a single
string.
AUTHOR
Robert Hanson - Initial Version rhanson@blast.net
Matt Sergeant - Current bug fixes, matt@sergeant.org
COPYRIGHT
Robert's Original licence was: I hereby reserve NO rights to
this module, except for maybe a little recognition if you decide
to rewrite it and redistribute as your own. Beyond that, you can
do whatever you want with this. I would just appreciate a copy
of any improvements to this module.
However that only stands for version 0.01 of the module. All
versions above that are released under the same terms as perl
itself.