655
|
1 |
=head1 NAME
|
|
2 |
|
|
3 |
XML::XQL::Query - Creates an XQL query evaluater from a XQL expression
|
|
4 |
|
|
5 |
=head1 SYNOPSIS
|
|
6 |
|
|
7 |
use XML::XQL;
|
|
8 |
|
|
9 |
$parser = new XML::DOM::Parser;
|
|
10 |
$doc = $parser->parsefile ("file.xml");
|
|
11 |
|
|
12 |
# Return all elements with tagName='title' under the root element 'book'
|
|
13 |
$query = new XML::XQL::Query (Expr => "book/title");
|
|
14 |
@result = $query->solve ($doc);
|
|
15 |
|
|
16 |
# Or (to save some typing)
|
|
17 |
@result = XML::XQL::solve ("book/title", $doc);
|
|
18 |
|
|
19 |
=head1 DESCRIPTION
|
|
20 |
|
|
21 |
To perform XQL queries on an XML::DOM document (or, in the future, on other XML
|
|
22 |
storage structures), you first have to create an XML::XQL::Query object and
|
|
23 |
pass it a valid XQL query expression. You can then perform queries on one or
|
|
24 |
more documents by calling the solve() method.
|
|
25 |
|
|
26 |
=head1 XML::XQL::Query constructor
|
|
27 |
|
|
28 |
Usage, e.g:
|
|
29 |
|
|
30 |
$query = new XML::XQL::Query(
|
|
31 |
Expr => "book/author",
|
|
32 |
Func => [ myfunc => \&my_func, # define 2 functions
|
|
33 |
myfunc2 => \&my_func2 ],
|
|
34 |
FuncArgCount => [ myfunc2 => [2, -1] ], # myfunc2 has 2 or more args
|
|
35 |
AllowedOutSideSubquery => [ myfunc => 1 ],
|
|
36 |
ConstFunc => [ myfunc2 => 1],
|
|
37 |
CompareOper => [ mycmp => \&mycmp ], # define comparison operator
|
|
38 |
q => "str"); # use str// as string delim
|
|
39 |
|
|
40 |
=over 4
|
|
41 |
|
|
42 |
=item Expr => STRING
|
|
43 |
|
|
44 |
The query expression to be evaluated.
|
|
45 |
|
|
46 |
=item NodeQuery => BOOLEAN
|
|
47 |
|
|
48 |
If set to 1, the query is a I<Node Query> as opposed to a
|
|
49 |
I<Full Query> (which is the default.)
|
|
50 |
A node query is a query that is only capable of returning Nodes.
|
|
51 |
A full query is capable of returning Node values and non-Node values.
|
|
52 |
Non-Node values include XML Primitives, element type names, namespace URI's,
|
|
53 |
concatenated text nodes, and node type names. The distinction is significant
|
|
54 |
because node queries may appear as XSL match and select patterns, while full
|
|
55 |
queries have use in other applications.
|
|
56 |
The difference between the two forms of queries is trivial and exists only as
|
|
57 |
constraints on the syntax of node queries.
|
|
58 |
Node queries may contain nested full queries.
|
|
59 |
|
|
60 |
=item Func => [ FUNCNAME => FUNCREF, ...]
|
|
61 |
|
|
62 |
Defines one or more functions. FUNCNAME is the name as used in the query
|
|
63 |
expression. FUNCREF can be either a function reference like \&my_func or
|
|
64 |
an anonymous sub.
|
|
65 |
See also: defineFunction
|
|
66 |
|
|
67 |
=item Method => [ FUNCNAME => FUNCREF, ...]
|
|
68 |
|
|
69 |
Defines one or more methods. FUNCNAME is the name as used in the query
|
|
70 |
expression. FUNCREF can be either a function reference like \&my_func or
|
|
71 |
an anonymous sub.
|
|
72 |
See also: defineMethod
|
|
73 |
|
|
74 |
=item FuncArgCount => [ FUNCNAME => ARGCOUNT, ...]
|
|
75 |
|
|
76 |
Defines the number of arguments for one or more functions or methods.
|
|
77 |
FUNCNAME is the name as used in the query expression.
|
|
78 |
See also: defineFunction and defineMethod
|
|
79 |
|
|
80 |
=item AllowedOutsideSubquery => [ FUNCNAME => BOOLEAN, ...]
|
|
81 |
|
|
82 |
Defines whether the specified function or method is allowed outside
|
|
83 |
subqueries. FUNCNAME is the name as used in the query expression.
|
|
84 |
See also: defineFunction and defineMethod
|
|
85 |
|
|
86 |
=item ConstFunc => [ FUNCNAME => BOOLEAN, ...]
|
|
87 |
|
|
88 |
Defines whether the function (not method!) is a "constant" function.
|
|
89 |
FUNCNAME is the name as used in the query expression.
|
|
90 |
See L<Constant Function Invocations> for a definition of "constant"
|
|
91 |
See also: defineFunction and defineMethod
|
|
92 |
|
|
93 |
=item CompareOper => [ OPERNAME => FUNCREF, ...]
|
|
94 |
|
|
95 |
Defines the comparison operator with the specified OPERNAME, e.g. if
|
|
96 |
OPERNAME is "contains", you can use "$contains$" in the query.
|
|
97 |
See also: defineComparisonOperators
|
|
98 |
|
|
99 |
=item q => TOKEN
|
|
100 |
|
|
101 |
Defines the q// token. See also: defineTokenQ
|
|
102 |
|
|
103 |
=item qq => TOKEN
|
|
104 |
|
|
105 |
Defines the qq// token. See also: defineTokenQQ
|
|
106 |
|
|
107 |
=item Error => FUNCREF
|
|
108 |
|
|
109 |
Defines the function that is called when errors occur during parsing the
|
|
110 |
query expression. The default function prints an error message to STDERR.
|
|
111 |
|
|
112 |
=item Debug => FLAGS
|
|
113 |
|
|
114 |
Sets the debug level for the Yapp parser that parses the query expression.
|
|
115 |
Default value is 0 (don't print anything). The maximum value is 0x17, which
|
|
116 |
prints a lot of stuff. See the Parse::Yapp manpage for the meaning of the
|
|
117 |
individual bits.
|
|
118 |
|
|
119 |
=item Reserved hash keys
|
|
120 |
|
|
121 |
Users may add their own (key, value) pairs to the Query constructor.
|
|
122 |
Beware that the key 'Tree' is used internally.
|
|
123 |
|
|
124 |
=back
|
|
125 |
|
|
126 |
=head1 XML::XQL::Query methods
|
|
127 |
|
|
128 |
=over 4
|
|
129 |
|
|
130 |
=item solve (INPUT_LIST...)
|
|
131 |
|
|
132 |
Note that solve takes a list of nodes which are assumed to be in document order
|
|
133 |
and must belong to the same document. E.g:
|
|
134 |
|
|
135 |
$query = new XML::XQL::Query (Expr => "doc//book");
|
|
136 |
@result = $query->solve ($doc);
|
|
137 |
@result2 = $query->solve ($node1, $node2, $node3);
|
|
138 |
|
|
139 |
=back
|
|
140 |
|
|
141 |
The following functions are also available at the query level, i.e. when called
|
|
142 |
on a Query object they only affect this Query and no others:
|
|
143 |
|
|
144 |
defineFunction, defineMethod, defineComparisonOperators,
|
|
145 |
defineTokenQ, defineTokenQQ
|
|
146 |
|
|
147 |
See L<Global functions|XML::XQL/XML::XQL global functions> for details.
|
|
148 |
Another way to define these features for a particular Query is by passing the
|
|
149 |
appropriate values to the XML::XQL::Query constructor.
|
|
150 |
|
|
151 |
=head1 SEE ALSO
|
|
152 |
|
|
153 |
L<XML::XQL> for general information about the XML::XQL module
|
|
154 |
|
|
155 |
L<XML::XQL::Tutorial> which describes the XQL syntax
|