/ 
XML-QL-0.07
River stage zero No dependents
/ XML::QL

NAME

XML::QL - An XML query language

VERSION

0.07

SYNOPSIS

$ql = 'WHERE <head>$head</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:

<BOOK>
	<AUTHOR></AUTHOR>
</BOOK>

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:

<BOOK>
	<AUTHOR>$author</AUTHOR>
</BOOK>

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:

<BOOK TYPE='non-fiction'>
	<AUTHOR>$author</AUTHOR>
</BOOK>

We can also express this as a regular expression:

<BOOK TYPE='non-.*'>
	<AUTHOR>$author</AUTHOR>
</BOOK>

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:

<BOOK TYPE='non-.* AS_ELEMENT $type'>
	<AUTHOR>$author</AUTHOR>
</BOOK>

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 - Only minor fixes so far msergeant@ndirect.co.uk, sergeant@geocities.com

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.