Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5001.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/XML::QL.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "QL 3"
.TH QL 3 "1999-05-26" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
XML::QL \- An XML query language
.SH "VERSION"
.IX Header "VERSION"
0.07
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
$ql = '\s-1WHERE\s0
         <head>$head</head>
       ORDER-BY
         \f(CW$head\fR
       \s-1IN\s0
         \*(L"file:REC\-xml\-19980210.xml\*(R"
       \s-1CONSTRUCT\s0
         \f(CW$head\fR';
.PP
print \s-1XML::QL\-\s0>query($sql);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is an early implementation of a note published by the W3C called
\&\*(L"\s-1XML\-QL:\s0 A Query Language for \s-1XML\s0\*(R". XML-QL allows the user to query an \s-1XML\s0
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.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "query( ""query"" )" 4
.el .IP "query( ``query'' )" 4
.IX Item "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.
.SH "XML\-QL: The Query Language"
.IX Header "XML-QL: The Query Language"
The basic syntax consists of two parts, a \s-1WHERE\s0 clause to describe the data
to search for, and a \s-1CONSTRUCT\s0 clause to describe how to return the data that
is found.
.IP "\s-1WHERE\s0" 4
.IX Item "WHERE"
\&\s-1WHERE\s0 XML-searchstring [\s-1ORDER\-BY\s0 variable [\s-1DESCENDING\s0] [, variable [\s-1DESCENDING\s0]] ] \s-1IN\s0 'filename'
.Sp
The \s-1WHERE\s0 clause can be separated into several parts. The first is the search string,
the second is an optional ORDER-BY clause much like \s-1ORDER\s0 \s-1BY\s0 in \s-1SQL\s0, and last is
the required \s-1XML\s0 document file name. Each of these parts is described below.
.RS 4
.IP "XML-searchstring" 4
.IX Item "XML-searchstring"
The search string \s-1MUST\s0 be a valid \s-1XML\s0 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.
.Sp
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:
.Sp
.Vb 3
\&        <BOOK>
\&                <AUTHOR></AUTHOR>
\&        </BOOK>
.Ve
.Sp
This search string will search for the \s-1AUTHOR\s0 tag nested within a \s-1BOOK\s0 tag. Note
however that no information has been selected for retrieval. In the following
example, we actually grab some information:
.Sp
.Vb 3
\&        <BOOK>
\&                <AUTHOR>$author</AUTHOR>
\&        </BOOK>
.Ve
.Sp
The variable name \f(CW$author\fR will grab the information that it finds withing this tag,
and makes this information avalable to us for use in the \s-1CONSTRUCT\s0 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.
.Sp
In the following example we take it a step further by searching for books of that are
non\-fiction:
.Sp
.Vb 3
\&        <BOOK TYPE='non-fiction'>
\&                <AUTHOR>$author</AUTHOR>
\&        </BOOK>
.Ve
.Sp
We can also express this as a regular expression:
.Sp
.Vb 3
\&        <BOOK TYPE='non-.*'>
\&                <AUTHOR>$author</AUTHOR>
\&        </BOOK>
.Ve
.Sp
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.
.Sp
Now lets say that besides matching the \s-1TYPE\s0, we also wanted to grab the value.
Consider this example:
.Sp
.Vb 3
\&        <BOOK TYPE='non-.* AS_ELEMENT $type'>
\&                <AUTHOR>$author</AUTHOR>
\&        </BOOK>
.Ve
.Sp
The \s-1AS_ELEMENT\s0 keyword allows you to save the matched value for later use in the
\&\s-1CONSTRUCT\s0 portion of the query.
.IP "ORDER-BY" 4
.IX Item "ORDER-BY"
The ORDER-BY clause allows to sort the data retrieved in the variables. You may
specify multiple variables, and specify \s-1DESCENDING\s0 for a reverse sort. This clause
is not required. For example:
.Sp
ORDER-BY \f(CW$type\fR, \f(CW$author\fR \s-1DESCENDING\s0
.IP "\s-1IN\s0" 4
.IX Item "IN"
The \s-1IN\s0 clause is a required clause that specifies the file name of the \s-1XML\s0 file.
This can be any \s-1URI\s0 that is supported by \s-1LWP\s0, 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:
.Sp
\&\s-1IN\s0 'REC\-xml\-19980210.xml'
.Sp
\&\s-1IN\s0 'file://othermachine/share/filename.xml'
.Sp
\&\s-1IN\s0 'http://www.example.com/file.xml'
.RE
.RS 4
.RE
.IP "\s-1CONSTRUCT\s0" 4
.IX Item "CONSTRUCT"
The \s-1CONSTRUCT\s0 construct allows you to specify a template for output. The template
will match character for character from the first space after the word \s-1CONSTRUCT\s0
to the end of the XML-QL query. For example:
.Sp
$ql = '(where clause...)
       \s-1CONSTRUCT\s0
	Type: \f(CW$type\fR
	Author: \f(CW$author\fR';
.Sp
The ouput of this will then be a carriage return, a tab, \*(L"Type: \*(R", the contents
of \f(CW$type\fR, a carriage return, a tab, \*(L"Author: \*(R", and the contents of \f(CW$author\fR. This
construct will be repeated for every match found and returned as a single string.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robert Hanson \- Initial Version
rhanson@blast.net
.PP
Matt Sergeant \- Only minor fixes so far
msergeant@ndirect.co.uk, sergeant@geocities.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Robert's Original licence \fBwas\fR:
I hereby reserve \s-1NO\s0 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.
.PP
However that only stands for version 0.01 of the module. All versions above that
are released under the same terms as perl itself.
Creat By MiNi SheLL
Email: devilkiller@gmail.com