diff -r 7c11c3d8d025 -r 60be34e1b006 deprecated/buildtools/buildsystemtools/lib/XML/XQL/Query.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/deprecated/buildtools/buildsystemtools/lib/XML/XQL/Query.pod	Wed Oct 27 16:03:51 2010 +0800
@@ -0,0 +1,155 @@
+=head1 NAME
+
+XML::XQL::Query - Creates an XQL query evaluater from a XQL expression
+
+=head1 SYNOPSIS
+
+ use XML::XQL;
+
+ $parser = new XML::DOM::Parser;
+ $doc = $parser->parsefile ("file.xml");
+
+ # Return all elements with tagName='title' under the root element 'book'
+ $query = new XML::XQL::Query (Expr => "book/title");
+ @result = $query->solve ($doc);
+
+ # Or (to save some typing)
+ @result = XML::XQL::solve ("book/title", $doc);
+
+=head1 DESCRIPTION
+
+To perform XQL queries on an XML::DOM document (or, in the future, on other XML
+storage structures), you first have to create an XML::XQL::Query object and
+pass it a valid XQL query expression. You can then perform queries on one or
+more documents by calling the solve() method.
+
+=head1 XML::XQL::Query constructor
+
+Usage, e.g:
+
+ $query = new XML::XQL::Query(
+	Expr => "book/author",
+	Func => [ myfunc => \&my_func,		# define 2 functions
+		  myfunc2 => \&my_func2 ],
+	FuncArgCount => [ myfunc2 => [2, -1] ], # myfunc2 has 2 or more args
+	AllowedOutSideSubquery => [ myfunc => 1 ],
+	ConstFunc => [ myfunc2 => 1],
+	CompareOper => [ mycmp => \&mycmp ],	# define comparison operator
+	q => "str");				# use str// as string delim
+
+=over 4
+
+=item Expr => STRING
+
+The query expression to be evaluated.
+
+=item NodeQuery => BOOLEAN
+
+If set to 1, the query is a I<Node Query> as opposed to a 
+I<Full Query> (which is the default.) 
+A node query is a query that is only capable of returning Nodes. 
+A full query is capable of returning Node values and non-Node values. 
+Non-Node values include XML Primitives, element type names, namespace URI's, 
+concatenated text nodes, and node type names. The distinction is significant
+because node queries may appear as XSL match and select patterns, while full 
+queries have use in other applications.
+The difference between the two forms of queries is trivial and exists only as 
+constraints on the syntax of node queries. 
+Node queries may contain nested full queries.
+
+=item Func => [ FUNCNAME => FUNCREF, ...]
+
+Defines one or more functions. FUNCNAME is the name as used in the query 
+expression. FUNCREF can be either a function reference like \&my_func or
+an anonymous sub.
+See also: defineFunction
+
+=item Method => [ FUNCNAME => FUNCREF, ...]
+
+Defines one or more methods. FUNCNAME is the name as used in the query 
+expression. FUNCREF can be either a function reference like \&my_func or
+an anonymous sub.
+See also: defineMethod
+
+=item FuncArgCount => [ FUNCNAME => ARGCOUNT, ...]
+
+Defines the number of arguments for one or more functions or methods. 
+FUNCNAME is the name as used in the query expression. 
+See also: defineFunction and defineMethod
+
+=item AllowedOutsideSubquery => [ FUNCNAME => BOOLEAN, ...]
+
+Defines whether the specified function or method is allowed outside
+subqueries. FUNCNAME is the name as used in the query expression. 
+See also: defineFunction and defineMethod
+
+=item ConstFunc => [ FUNCNAME => BOOLEAN, ...]
+
+Defines whether the function (not method!) is a "constant" function.
+FUNCNAME is the name as used in the query expression. 
+See L<Constant Function Invocations> for a definition of "constant"
+See also: defineFunction and defineMethod
+
+=item CompareOper => [ OPERNAME => FUNCREF, ...]
+
+Defines the comparison operator with the specified OPERNAME, e.g. if
+OPERNAME is "contains", you can use "$contains$" in the query.
+See also: defineComparisonOperators
+
+=item q => TOKEN
+
+Defines the q// token. See also: defineTokenQ
+
+=item qq => TOKEN
+
+Defines the qq// token. See also: defineTokenQQ
+
+=item Error => FUNCREF
+
+Defines the function that is called when errors occur during parsing the
+query expression. The default function prints an error message to STDERR.
+
+=item Debug => FLAGS
+
+Sets the debug level for the Yapp parser that parses the query expression.
+Default value is 0 (don't print anything). The maximum value is 0x17, which
+prints a lot of stuff. See the Parse::Yapp manpage for the meaning of the
+individual bits.
+
+=item Reserved hash keys
+
+Users may add their own (key, value) pairs to the Query constructor.
+Beware that the key 'Tree' is used internally.
+
+=back
+
+=head1 XML::XQL::Query methods
+
+=over 4
+
+=item solve (INPUT_LIST...)
+
+Note that solve takes a list of nodes which are assumed to be in document order
+and must belong to the same document. E.g:
+
+ $query = new XML::XQL::Query (Expr => "doc//book");
+ @result = $query->solve ($doc);
+ @result2 = $query->solve ($node1, $node2, $node3);
+
+=back
+
+The following functions are also available at the query level, i.e. when called
+on a Query object they only affect this Query and no others:
+
+ defineFunction, defineMethod, defineComparisonOperators, 
+ defineTokenQ, defineTokenQQ
+
+See L<Global functions|XML::XQL/XML::XQL global functions> for details.
+Another way to define these features for a particular Query is by passing the
+appropriate values to the XML::XQL::Query constructor.
+
+=head1 SEE ALSO
+
+L<XML::XQL> for general information about the XML::XQL module
+
+L<XML::XQL::Tutorial> which describes the XQL syntax