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

