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