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