This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: XML/XPath/Node/Comment, Next: XML/XPath/Node/Element, Prev: XML/XPath/Node/Attribute, Up: Module List an XML comment: **************************** NAME ==== Comment - an XML comment: API === new ( data ) ------------ Create a new comment node. getValue / getData ------------------ Returns the value in the comment toString -------- Returns the comment with - encoded as a numeric entity (if it exists in the comment text).  File: pm.info, Node: XML/XPath/Node/Element, Next: XML/XPath/Node/Namespace, Prev: XML/XPath/Node/Comment, Up: Module List an ************ NAME ==== Element - an API === new ( name, prefix ) -------------------- Create a new Element node with name "name" and prefix "prefix". The name be "prefix:local" if prefix is defined. I know that sounds wierd, but it works ;-) getName ------- Returns the name (including "prefix:" if defined) of this element. getLocalName ------------ Returns just the local part of the name (the bit after "prefix:"). getChildNodes ------------- Returns the children of this element. In list context returns a list. In scalar context returns an array ref. getChildNode ( pos ) -------------------- Returns the child at position pos. appendChild ( childnode ) ------------------------- Appends the child node to the list of current child nodes. getAttribute ( name ) --------------------- Returns the attribute node with key name. getAttributes / getAttributeNodes --------------------------------- Returns the attribute nodes. In list context returns a list. In scalar context returns an array ref. appendAttribute ( attrib_node) ------------------------------ Appends the attribute node to the list of attributes (XML::XPath stores attributes in order). getNamespace ( prefix ) ----------------------- Returns the namespace node by the given prefix getNamespaces / getNamespaceNodes --------------------------------- Returns the namespace nodes. In list context returns a list. In scalar context returns an array ref. appendNamespace ( ns_node ) --------------------------- Appends the namespace node to the list of namespaces. getPrefix --------- Returns the prefix of this element getExpandedName --------------- Returns the expanded name of this element (not yet implemented right). string_value ------------ For elements, the string_value is the concatenation of all string_values of all text-descendants of the element node in document order. toString ( [ norecurse ] ) -------------------------- Output (and all children) the node to a string. Doesn't process children if the norecurse option is a true value.  File: pm.info, Node: XML/XPath/Node/Namespace, Next: XML/XPath/Node/PI, Prev: XML/XPath/Node/Element, Up: Module List an XML namespace node ********************* NAME ==== Namespace - an XML namespace node API === new ( prefix, expanded ) ------------------------ Create a new namespace node, expanded is the expanded namespace URI. getPrefix --------- Returns the prefix getExpanded ----------- Returns the expanded URI toString -------- Returns a string that you can add to the list of attributes of an element: xmlns:prefix="expanded"  File: pm.info, Node: XML/XPath/Node/PI, Next: XML/XPath/Node/Text, Prev: XML/XPath/Node/Namespace, Up: Module List an XML processing instruction node ********************************** NAME ==== PI - an XML processing instruction node API === new ( target, data ) -------------------- Create a new PI node. getTarget --------- Returns the target getData ------- Returns the data  File: pm.info, Node: XML/XPath/Node/Text, Next: XML/XPath/NodeSet, Prev: XML/XPath/Node/PI, Up: Module List an XML text node **************** NAME ==== Text - an XML text node API === new ( text ) ------------ Create a new text node. getValue / getData ------------------ Returns the text string_value ------------ Returns the text appendText ( text ) ------------------- Adds the given text string to this node.  File: pm.info, Node: XML/XPath/NodeSet, Next: XML/XPath/Number, Prev: XML/XPath/Node/Text, Up: Module List a list of XML document nodes **************************** NAME ==== XML::XPath::NodeSet - a list of XML document nodes DESCRIPTION =========== An XML::XPath::NodeSet object contains an ordered list of nodes. The nodes each take the same format as described in *Note XML/XPath/XMLParser: XML/XPath/XMLParser,. SYNOPSIS ======== my $results = $xp->find('//someelement'); if (!$results->isa('XML::XPath::NodeSet')) { print "Found $results\n"; exit; } foreach my $context ($results->get_nodelist) { my $newresults = $xp->find('./other/element', $context); ... } API === new() ----- You will almost never have to create a new NodeSet object, as it is all done for you by XPath. get_nodelist() -------------- Returns a list of nodes. See *Note XML/XPath/XMLParser: XML/XPath/XMLParser, for the format of the nodes. string_value() -------------- Returns the string-value of the first node in the list. See the XPath specification for what "string-value" means. to_literal() ------------ Returns the concatenation of all the string-values of all the nodes in the list. get_node($pos) -------------- Returns the node at $pos. The node position in XPath is based at 1, not 0. size() ------ Returns the number of nodes in the NodeSet. pop() ----- Equivalent to perl's pop function. push(@nodes) ------------ Equivalent to perl's push function. append($nodeset) ---------------- Given a nodeset, appends the list of nodes in $nodeset to the end of the current list. shift() ------- Equivalent to perl's shift function. unshift(@nodes) --------------- Equivalent to perl's unshift function. prepend($nodeset) ----------------- Given a nodeset, prepends the list of nodes in $nodeset to the front of the current list.  File: pm.info, Node: XML/XPath/Number, Next: XML/XPath/PerlSAX, Prev: XML/XPath/NodeSet, Up: Module List Simple numeric values. ********************** NAME ==== XML::XPath::Number - Simple numeric values. DESCRIPTION =========== This class holds simple numeric values. It doesn't support -0, +/- Infinity, or NaN, as the XPath spec says it should, but I'm not hurting anyone I don't think. API === new($num) --------- Creates a new XML::XPath::Number object, with the value in $num. Does some rudimentary numeric checking on $num to ensure it actually is a number. value() ------- Also as overloaded stringification. Returns the numeric value held.  File: pm.info, Node: XML/XPath/PerlSAX, Next: XML/XPath/XMLParser, Prev: XML/XPath/Number, Up: Module List A PerlSAX event generator for my wierd node structure ***************************************************** NAME ==== XML::XPath::PerlSAX - A PerlSAX event generator for my wierd node structure SYNOPSIS ======== use XML::XPath; use XML::XPath::PerlSAX; use XML::DOM::PerlSAX; my $xp = XML::XPath->new(filename => 'test.xhtml'); my $paras = $xp->find('/html/body/p'); my $handler = XML::DOM::PerlSAX->new(); my $generator = XML::XPath::PerlSAX->new( Handler => $handler ); foreach my $node ($paras->get_nodelist) { my $domtree = $generator->parse($node); # do something with $domtree } DESCRIPTION =========== This module generates PerlSAX events to pass to a PerlSAX handler such as XML::DOM::PerlSAX. It operates specifically on my wierd tree format. Unfortunately SAX doesn't seem to cope with namespaces, so these are lost completely. I believe SAX2 is doing namespaces. Other ===== The XML::DOM::PerlSAX handler I tried was completely broken (didn't even compile before I patched it a bit), so I don't know how correct this is or how far it will work. This software may only be distributed as part of the XML::XPath package.  File: pm.info, Node: XML/XPath/XMLParser, Next: XML/XPathScript, Prev: XML/XPath/PerlSAX, Up: Module List The default XML parsing class that produces a node tree ******************************************************* NAME ==== XML::XPath::XMLParser - The default XML parsing class that produces a node tree SYNOPSIS ======== my $parser = XML::XPath::XMLParser->new( filename => $self->get_filename, xml => $self->get_xml, ioref => $self->get_ioref, parser => $self->get_parser, ); my $root_node = $parser->parse; DESCRIPTION =========== This module generates a node tree for use as the context node for XPath processing. It aims to be a quick parser, nothing fancy, and yet has to store more information than most parsers. To achieve this I've used array refs everywhere - no hashes. I don't have any performance figures for the speedups achieved, so I make no appologies for anyone not used to using arrays instead of hashes. I think they make good sense here where we know the attributes of each type of node. Node Structure ============== All nodes have the same first 2 entries in the array: node_parent and node_pos. The type of the node is determined using the ref() function. The node_parent always contains an entry for the parent of the current node - except for the root node which has undef in there. And node_pos is the position of this node in the array that it is in (think: $node == $node->[node_parent]->[node_children]->[$node->[node_pos]] ) Nodes are structured as follows: Root Node --------- The root node is just an element node with no parent. [ undef, # node_parent - check for undef to identify root node undef, # node_pos undef, # node_prefix [ ... ], # node_children (see below) ] Element Node ------------ [ $parent, # node_parent , # node_pos 'xxx', # node_prefix - namespace prefix on this element [ ... ], # node_children 'yyy', # node_name - element tag name [ ... ], # node_attribs - attributes on this element [ ... ], # node_namespaces - namespaces currently in scope ] Attribute Node -------------- [ $parent, # node_parent - the element node , # node_pos 'xxx', # node_prefix - namespace prefix on this element 'href', # node_key - attribute name 'ftp://ftp.com/', # node_value - value in the node ] Namespace Nodes --------------- Each element has an associated set of namespace nodes that are currently in scope. Each namespace node stores a prefix and the expanded name (retrieved from the xmlns:prefix="..." attribute). [ $parent, , 'a', # node_prefix - the namespace as it was written as a prefix 'http://my.namespace.com', # node_expanded - the expanded name. ] Text Nodes ---------- [ $parent, , 'This is some text' # node_text - the text in the node ] Comment Nodes ------------- [ $parent, , 'This is a comment' # node_comment ] Processing Instruction Nodes ---------------------------- [ $parent, , 'target', # node_target 'data', # node_data ] Usage ===== If you feel the need to use this module outside of XML::XPath (for example you might use this module directly so that you can cache parsed trees), you can follow the following API: new --- The new method takes either no parameters, or any of the following parameters: filename xml parser ioref This uses the familiar hash syntax, so an example might be: use XML::XPath::XMLParser; my $parser = XML::XPath::XMLParser->new(filename => 'example.xml'); The parameters represent a filename, a string containing XML, an XML::Parser instance and an open filehandle ref respectively. You can also set or get all of these properties using the get_ and set_ functions that have the same name as the property: e.g. get_filename, set_ioref, etc. parse ----- The parse method generally takes no parameters, however you are free to pass either an open filehandle reference or an XML string if you so require. The return value is a tree that XML::XPath can use. The parse method will die if there is an error in your XML, so be sure to use perl's exception handling mechanism (eval{};) if you want to avoid this. parsefile --------- The parsefile method is identical to parse() except it expects a single parameter that is a string naming a file to open and parse. Again it returns a tree and also dies if there are XML errors. NOTICES ======= This file is distributed as part of the XML::XPath module, and is copyright 2000 Fastnet Software Ltd. Please see the documentation for the module as a whole for licencing information.  File: pm.info, Node: XML/XPathScript, Next: XML/XQL, Prev: XML/XPath/XMLParser, Up: Module List Stand alone XPathScript *********************** NAME ==== XML::XPathScript - Stand alone XPathScript SYNOPSIS ======== use XML::XPathScript; my $xps = XML::XPathScript->new(xml => $xml, stylesheet => $stylesheet); $xps->process; DESCRIPTION =========== This is a standalone version of XPathScript, originally part of the AxKit project at http://axkit.org/ XPathScript is a stylesheet language similar in many ways to XSLT (in concept, not in appearance), for transforming XML from one format to another format (possibly HTML). The documentation for the XPathScript language is available on the AxKit web site at the URL above. USAGE ===== TODO BUGS ==== Currently output is to STDOUT. I'd like to fix this, though my time on this module is limited as I do not personally have a use for this module, since I mainly just use AxKit itself. Patches welcome. AUTHOR ====== Matt Sergeant, matt@sergeant.org LICENSE ======= This is free software. You may distribute it under the same terms as Perl itself.  File: pm.info, Node: XML/XQL, Next: XML/XQL/DOM, Prev: XML/XPathScript, Up: Module List A perl module for querying XML tree structures with XQL ******************************************************* NAME ==== XML::XQL - A perl module for querying XML tree structures with XQL SYNOPSIS ======== use XML::XQL; use XML::XQL::DOM; $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); $query->dispose; # Avoid memory leaks - Remove circular references # Or (to save some typing) @result = XML::XQL::solve ("book/title", $doc); # Or (to save even more typing) @result = $doc->xql ("book/title"); DESCRIPTION =========== The XML::XQL module implements the XQL (XML Query Language) proposal submitted to the XSL Working Group in September 1998. The spec can be found at: `http:' in this node Most of the contents related to the XQL syntax can also be found in the *Note XML/XQL/Tutorial: XML/XQL/Tutorial, that comes with this distribution. Note that XQL is not the same as XML-QL! The current implementation only works with the *Note XML/DOM: XML/DOM, module, but once the design is stable and the major bugs are flushed out, other extensions might follow, e.g. for XML::Grove. XQL was designed to be extensible and this implementation tries to stick to that. Users can add their own functions, methods, comparison operators and data types. Plugging in a new XML tree structure (like XML::Grove) should be a piece of cake. To use the XQL module, either use XML::XQL; or use XML::XQL::Strict; The Strict module only provides the core XQL functionality as found in the XQL spec. By default (i.e. by using XML::XQL) you get 'XQL+', which has some additional features. See the section `Additional Features in XQL+' in this node for the differences. This module is still in development. See the To-do list in XQL.pm for what still needs to be done. Any suggestions are welcome, the sooner these implementation issues are resolved, the faster we can all use this module. If you find a bug, you would do me great favor by sending it to me in the form of a test case. See the file t/xql_template.t that comes with this distribution. If you have written a cool comparison operator, function, method or XQL data type that you would like to share, send it to enno@att.com and I will add it to this module. XML::XQL global functions ========================= solve (QUERY_STRING, INPUT_LIST...) @result = XML::XQL::solve ("doc//book", $doc); This is provided as a shortcut for: $query = new XML::XQL::Query (Expr => "doc//book"); @result = $query->solve ($doc); $query->dispose; Note that with *Note XML/XQL/DOM: XML/XQL/DOM,, you can also write (see *Note XML/DOM/Node: XML/DOM/Node, for details): @result = $doc->xql ("doc//book"); setDocParser (PARSER) Sets the XML::DOM::Parser that is used by the new XQL+ document() method. By default it uses an XML::DOM::Parser that was created without any arguments, i.e. $PARSER = new XML::DOM::Parser; defineFunction (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE [, CONST, [QUERY_ARG]]]) Defines the XQL function (at the global level, i.e. for all newly created queries) with the specified NAME. The ARGCOUNT parameter can either be a single number or a reference to a list with numbers. A single number expands to [ARGCOUNT, ARGCOUNT]. The list contains pairs of numbers, indicating the number of arguments that the function allows. The value -1 means infinity. E.g. [2, 5, 7, 9, 12, -1] means that the function can have 2, 3, 4, 5, 7, 8, 9, 12 or more arguments. The number of arguments is checked when parsing the XQL query string. The second parameter must be a reference to a Perl function or an anonymous sub. E.g. '\&my_func' or 'sub { ... code ... }' If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or method may also be used outside subqueries in *node queries*. (See NodeQuery parameter in Query constructor) If CONST (default is 0) is set to 1, the function is considered to be "constant". See `Constant Function Invocations' in this node for details. If QUERY_ARG (default is 0) is not -1, the argument with that index is considered to be a 'query parameter'. If the query parameter is a subquery, that returns multiple values, the result list of the function invocation will contain one result value for each value of the subquery. E.g. 'length(book/author)' will return a list of Numbers, denoting the string lengths of all the author elements returned by 'book/author'. Note that only methods (not functions) may appear after a Bang "!" operator. This is checked when parsing the XQL query string. See also: defineMethod generateFunction (NAME, FUNCNAME, RETURN_TYPE [, ARGCOUNT [, ALLOWED_OUTSIDE [, CONST [, QUERY_ARG]]]]) Generates and defines an XQL function wrapper for the Perl function with the name FUNCNAME. The function name will be NAME in XQL query expressions. The return type should be one of the builtin XQL Data Types or a class derived from XML::XQL::PrimitiveType (see `Adding Data Types' in this node.) See defineFunction for the meaning of ARGCOUNT, ALLOWED_OUTSIDE, CONST and QUERY_ARG. Function values are always converted to Perl strings with xql_toString before they are passed to the Perl function implementation. The function return value is cast to an object of type RETURN_TYPE, or to the empty list [] if the result is undef. It uses expandType to expand XQL primitive type names. If RETURN_TYPE is "*", it returns the function result as is, unless the function result is undef, in which case it returns []. defineMethod (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE]) Defines the XQL method (at the global level, i.e. for all newly created queries) with the specified NAME. The ARGCOUNT parameter can either be a single number or a reference to a list with numbers. A single number expands to [ARGCOUNT, ARGCOUNT]. The list contains pairs of numbers, indicating the number of arguments that the method allows. The value -1 means infinity. E.g. [2, 5, 7, 9, 12, -1] means that the method can have 2, 3, 4, 5, 7, 8, 9, 12 or more arguments. The number of arguments is checked when parsing the XQL query string. The second parameter must be a reference to a Perl function or an anonymous sub. E.g. '\&my_func' or 'sub { ... code ... }' If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or method may also be used outside subqueries in *node queries*. (See NodeQuery parameter in Query constructor) Note that only methods (not functions) may appear after a Bang "!" operator. This is checked when parsing the XQL query string. See also: defineFunction defineComparisonOperators (NAME => FUNCREF [, NAME => FUNCREF]*) Defines XQL comparison operators at the global level. The FUNCREF parameters must be a references to a Perl function or an anonymous sub. E.g. '\&my_func' or 'sub { ... code ... }' E.g. define the operators $my_op$ and $my_op2$: defineComparisonOperators ('my_op' => \&my_op, 'my_op2' => sub { ... insert code here ... }); defineElementValueConvertor (TAG_NAME, FUNCREF) Defines that the result of the value() call for Elements with the specified TAG_NAME uses the specified function. The function will receive two parameters. The second one is the TAG_NAME of the Element node and the first parameter is the Element node itself. FUNCREF should be a reference to a Perl function, e.g. \&my_sub, or an anonymous sub. E.g. to define that all Elements with tag name 'date-of-birth' should return XML::XQL::Date objects: defineElementValueConvertor ('date-of-birth', sub { my $elem = shift; # Always pass in the node as the second parameter. This is # the reference node for the object, which is used when # sorting values in document order. new XML::XQL::Date ($elem->xql_text, $elem); }); These convertors can only be specified at a global level, not on a per query basis. To undefine a convertor, simply pass a FUNCREF of undef. defineAttrValueConvertor (ELEM_TAG_NAME, ATTR_NAME, FUNCREF) Defines that the result of the value() call for Attributes with the specified ATTR_NAME and a parent Element with the specified ELEM_TAG_NAME uses the specified function. An ELEM_TAG_NAME of "*" will match regardless of the tag name of the parent Element. The function will receive 3 parameters. The third one is the tag name of the parent Element (even if ELEM_TAG_NAME was "*"), the second is the ATTR_NAME and the first is the Attribute node itself. FUNCREF should be a reference to a Perl function, e.g. \&my_sub, or an anonymous sub. These convertors can only be specified at a global level, not on a per query basis. To undefine a convertor, simply pass a FUNCREF of undef. defineTokenQ (Q) Defines the token for the q// string delimiters at a global level. The default value for XQL+ is 'q', for XML::XQL::Strict it is undef. A value of undef will deactivate this feature. defineTokenQQ (QQ) Defines the token for the qq// string delimiters at a global level. The default value for XQL+ is 'qq', for XML::XQL::Strict it is undef. A value of undef will deactivate this feature. expandType (TYPE) Used internally to expand type names of XQL primitive types. E.g. it expands "Number" to "XML::XQL::Number" and is not case-sensitive, so "number" and "NuMbEr" will both expand correctly. defineExpandedTypes (ALIAS, FULL_NAME [, ...]) For each pair of arguments it allows the class name FULL_NAME to be abbreviated with ALIAS. The definitions are used by expandType(). (ALIAS is always converted to lowercase internally, because expandType is case-insensitive.) Overriding the ALIAS for "date", also affects the object type returned by the date() function. setErrorContextDelimiters (START, END, BOLD_ON, BOLD_OFF) Sets the delimiters used when printing error messages during query evaluation. The default delimiters on Unix are `tput smul` (underline on) and `tput rmal` (underline off). On other systems (that don't have tput), the delimiters are ">>" and "<<" resp. When printing the error message, the subexpression that caused the error will be enclosed by the delimiters, i.e. underlined on Unix. For certain subexpressions the significant keyword, e.g. "$and$" is enclosed in the bold delimiters BOLD_ON (default: `tput bold` on Unix, "" elsewhere) and BOLD_OFF (default: (`tput rmul` . `tput smul`) on Unix, "" elsewhere, see $BoldOff in XML::XQL::XQL.pm for details.) isEmptyList (VAR) Returns 1 if VAR is [], else 0. Can be used in user defined functions. Additional Features in XQL+ =========================== Parent operator '..' The '..' operator returns the parent of the current node, where '.' would return the current node. This is not part of any XQL standard, because you would normally use return operators, which are not implemented here. Sequence operators ';' and ';;' The sequence operators ';' (precedes) and ';;' (immediately precedes) are not in the XQL spec, but are described in 'The Design of XQL' by Jonathan Robie who is one of the designers of XQL. It can be found at `http:' in this node See also the XQL Tutorial for a description of what they mean. q// and qq// String Tokens String tokens a la q// and qq// are allowed. q// evaluates like Perl's single quotes and qq// like Perl's double quotes. Note that the default XQL strings do not allow escaping etc., so it's not possible to define a string with both single and double quotes. If 'q' and 'qq' are not to your liking, you may redefine them to something else or undefine them altogether, by assigning undef to them. E.g: # at a global level - shared by all queries (that don't (re)define 'q') XML::XQL::defineTokenQ ('k'); XML::XQL::defineTokenQQ (undef); # at a query level - only defined for this query $query = new XML::XQL::Query (Expr => "book/title", q => 'k', qq => undef); From now on k// works like q// did and qq// doesn't work at all anymore. Query strings can have embedded Comments For example: $queryExpr = "book/title # this comment is inside the query string [. = 'Moby Dick']"; # this comment is outside Optional dollar delimiters and case-insensitive XQL keywords The following XQL keywords are case-insensitive and the dollar sign delimiters may be omitted: $and$, $or$, $not$, $union$, $intersect$, $to$, $any$, $all$, $eq$, $ne$, $lt$, $gt$, $ge$, $le$, $ieq$, $ine$, $ilt$, $igt$, $ige$, $ile$. E.g. $AND$, $And$, $aNd$, and, And, aNd are all valid replacements for $and$. Note that XQL+ comparison operators ($match$, $no_match$, $isa$, $can$) still require dollar delimiters and are case-sensitive. Comparison operator: $match$ or '=~' E.g. "book/title =~ '/(Moby|Dick)/']" will return all book titles containing Moby or Dick. Note that the match expression needs to be quoted and should contain the // or m// delimiters for Perl. When casting the values to be matched, both are converted to Text. Comparison operator: $no_match$ or '!~' E.g. "book/title !~ '/(Moby|Dick)/']" will return all book titles that don't contain Moby or Dick. Note that the match expression needs to be quoted and should contain the // or m// delimiters for Perl. When casting the values to be matched, both are converted to Text. Comparison operator: $isa$ E.g. '//. $isa$ "XML::XQL::Date"' returns all elements for which the value() function returns an XML::XQL::Date object. (Note that the value() function can be overridden to return a specific object type for certain elements and attributes.) It uses expandType to expand XQL primitive type names. Comparison operator: $can$ E.g. '//. $can$ "swim"' returns all elements for which the value() function returns an object that implements the (Perl) swim() method. (Note that the value() function can be overridden to return a specific object type for certain elements and attributes.) Function: once (QUERY) E.g. 'once(id("foo"))' will evaluate the QUERY expression only once per query. Certain query results (like the above example) will always return the same value within a query. Using once() will cache the QUERY result for the rest of the query. Note that "constant" function invocations are always cached. See also `Constant Function Invocations' in this node Function: subst (QUERY, EXPR, EXPR [,MODIFIERS, [MODE]]) E.g. 'subst(book/title, "[M|m]oby", "Dick", "g")' will replace Moby or moby with Dick globally ("g") in all book title elements. Underneath it uses Perl's substitute operator s///. Don't worry about which delimiters are used underneath. The function returns all the book/titles for which a substitution occurred. The default MODIFIERS string is "" (empty.) The function name may be abbreviated to "s". For most Node types, it converts the value() to a string (with xql_toString) to match the string and xql_setValue to set the new value in case it matched. For XQL primitives (Boolean, Number, Text) and other data types (e.g. Date) it uses xql_toString to match the String and xql_setValue to set the result. Beware that performing a substitution on a primitive that was found in the original XQL query expression, changes the value of that constant. If MODE is 0 (default), it treats Element nodes differently by matching and replacing *text blocks* occurring in the Element node. A text block is defined as the concatenation of the raw text of subsequent Text, CDATASection and EntityReference nodes. In this mode it skips embedded Element nodes. If a text block matches, it is replaced by a single Text node, regardless of the original node type(s). If MODE is 1, it treats Element nodes like the other nodes, i.e. it converts the value() to a string etc. Note that the default implementation of value() calls text(), which normalizes whitespace and includes embedded Element descendants (recursively.) This is probably not what you want to use in most cases, but since I'm not a professional psychic... :-) Function: map (QUERY, CODE) E.g. 'map(book/title, "s/[M|m]oby/Dick/g; $_")' will replace Moby or moby with Dick globally ("g") in all book title elements. Underneath it uses Perl's map operator. The function returns all the book/titles for which a change occurred. ??? add more specifics Function: eval (EXPR [,TYPE]) Evaluates the Perl expression EXPR and returns an object of the specified TYPE. It uses expandType to expand XQL primitive type names. If the result of the eval was undef, the empty list [] is returned. E.g. 'eval("2 + 5", "Number")' returns a Number object with the value 7, and 'eval("%ENV{USER}")' returns a Text object with the user name. Consider using once() to cache the return value, when the invocation will return the same result for each invocation within a query. ??? add more specifics Function: new (TYPE [, QUERY [, PAR] *]) Creates a new object of the specified object TYPE. The constructor may have any number of arguments. The first argument of the constructor (the 2nd argument of the new() function) is considered to be a 'query parameter'. See defineFunction for a definition of *query parameter*. It uses expandType to expand XQL primitive type names. Function: document (QUERY) or doc (QUERY) The document() function creates a new `XML::XML::Document' in this node for each result of QUERY (QUERY may be a simple string expression, like "/usr/enno/file.xml". See t/xql_document.t or below for an example with a more complex QUERY.) document() may be abbreviated to doc(). document() uses an XML::DOM::Parser underneath, which can be set with XML::XQL::setDocParser(). By default it uses a parser that was created without any arguments, i.e. $PARSER = new XML::DOM::Parser; Let's try a more complex example, assuming $doc contains: Then the following query will return two `XML::XML::Document' in this nodes, one for file1.xml and one for file2.xml: @result = XML::XQL::solve ("document(doc/file/@name)", $doc); The resulting documents can be used as input for following queries, e.g. @result = XML::XQL::solve ("document(doc/file/@name)/root/bla", $doc); will return all /root/bla elements from the documents returned by document(). Method: DOM_nodeType () Returns the DOM node type. Note that these are mostly the same as nodeType(), except for CDATASection and EntityReference nodes. DOM_nodeType() returns 4 and 5 respectively, whereas nodeType() returns 3, because they are considered text nodes. Function wrappers for Perl builtin functions XQL function wrappers have been provided for most Perl builtin functions. When using a Perl builtin function like "substr" in an XQL+ querry, an XQL function wrapper will be generated on the fly. The arguments to these functions may be regular XQL+ subqueries (that return one or more values) for a *query parameter* (see generateFunction for a definition.) Most wrappers of Perl builtin functions have argument 0 for a query parameter, except for: chmod (parameter 1 is the query parameter), chown (2) and utime (2). The following functions have no query parameter, which means that all parameters should be a single value: atan2, rand, srand, sprintf, rename, unlink, system. The function result is casted to the appropriate XQL primitive type (Number, Text or Boolean), or to an empty list if the result was undef. XPath functions and methods --------------------------- The following functions were found in the XPath specification: Function: concat (STRING, STRING, STRING*) The concat function returns the concatenation of its arguments. Function: starts-with (STRING, STRING) The starts-with function returns true if the first argument string starts with the second argument string, and otherwise returns false. Function: contains (STRING, STRING) The contains function returns true if the first argument string contains the second argument string, and otherwise returns false. Function: substring-before (STRING, STRING) The substring-before function returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string, or the empty string if the first argument string does not contain the second argument string. For example, substring-before("1999/04/01","/") returns 1999. Function: substring-after (STRING, STRING) The substring-after function returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string, or the empty string if the first argument string does not contain the second argument string. For example, substring-after("1999/04/01","/") returns 04/01, and substring-after("1999/04/01","19") returns 99/04/01. Function: substring (STRING, NUMBER [, NUMBER] ) The substring function returns the substring of the first argument starting at the position specified in the second argument with length specified in the third argument. For example, substring("12345",2,3) returns "234". If the third argument is not specified, it returns the substring starting at the position specified in the second argument and continuing to the end of the string. For example, substring("12345",2) returns "2345". More precisely, each character in the string is considered to have a numeric position: the position of the first character is 1, the position of the second character is 2 and so on. NOTE: This differs from the substr method , in which the method treats the position of the first character as 0. The XPath spec says this about rounding, but that is not true in this implementation: *The returned substring contains those characters for which the position of the character is greater than or equal to the rounded value of the second argument and, if the third argument is specified, less than the sum of the rounded value of the second argument and the rounded value of the third argument; the comparisons and addition used for the above follow the standard IEEE 754 rules; rounding is done as if by a call to the round function.* Method: string-length ( [ QUERY ] ) The string-length returns the number of characters in the string. If the argument is omitted, it defaults to the context node converted to a string, in other words the string-value of the context node. Note that the generated XQL wrapper for the Perl built-in substr does not allow the argument to be omitted. Method: normalize-space ( [ QUERY ] ) The normalize-space function returns the argument string with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of whitespace characters by a single space. Whitespace characters are the same as those allowed by the S production in XML. If the argument is omitted, it defaults to the context node converted to a string, in other words the string-value of the context node. Function: translate (STRING, STRING, STRING) The translate function returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string. For example, translate("bar","abc","ABC") returns the string BAr. If there is a character in the second argument string with no character at a corresponding position in the third argument string (because the second argument string is longer than the third argument string), then occurrences of that character in the first argument string are removed. For example, translate("--aaa--","abc-","ABC") returns "AAA". If a character occurs more than once in the second argument string, then the first occurrence determines the replacement character. If the third argument string is longer than the second argument string, then excess characters are ignored. NOTE: The translate function is not a sufficient solution for case conversion in all languages. A future version may provide additional functions for case conversion. This function was implemented using tr///d. Function: sum ( QUERY ) The sum function returns the sum of the QUERY results, by converting the string values of each result to a number. Function: floor (NUMBER) The floor function returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer. Function: ceiling (NUMBER) The ceiling function returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer. Function: round (NUMBER) The round function returns the number that is closest to the argument and that is an integer. If there are two such numbers, then the one that is closest to positive infinity is returned. Implementation Details ====================== XQL Builtin Data Types The XQL engine uses the following object classes internally. Only Number, Boolean and Text are considered *primitive XQL types*: * XML::XQL::Number For integers and floating point numbers. * XML::XQL::Boolean For booleans, e.g returned by true() and false(). * XML::XQL::Text For string values. * XML::XQL::Date For date, time and date/time values. E.g. returned by the date() function. * XML::XQL::Node Superclass of all XML node types. E.g. all subclasses of XML::DOM::Node subclass from this. * Perl list reference Lists of values are passed by reference (i.e. using [] delimiters). The empty list [] has a double meaning. It also means 'undef' in certain situations, e.g. when a function invocation or comparison failed. Type casting in comparisons When two values are compared in an XML comparison (e.g. $eq$) the values are first casted to the same data type. Node values are first replaced by their value() (i.e. the XQL value() function is used, which returns a Text value by default, but may return any data type if the user so chooses.) The resulting values are then casted to the type of the object with the highest xql_primType() value. They are as follows: Node (0), Text (1), Number (2), Boolean (3), Date (4), other data types (4 by default, but this may be overriden by the user.) E.g. if one value is a Text value and the other is a Number, the Text value is cast to a Number and the resulting low-level (Perl) comparison is (for $eq$): $number->xql_toString == $text->xql_toString If both were Text values, it would have been $text1->xql_toString eq $text2->xql_toString Note that the XQL spec is vague and even conflicting where it concerns type casting. This implementation resulted after talking to Joe Lapp, one of the spec writers. Adding Data Types If you want to add your own data type, make sure it derives from XML::XQL::PrimitiveType and implements the necessary methods. I will add more stuff here to explain it all, but for now, look at the code for the primitive XQL types or the Date class (*Note XML/XQL/Date: XML/XQL/Date, in Date.pm.) Document Order The XQL spec states that query results always return their values in *document order*, which means the order in which they appeared in the original XML document. Values extracted from Nodes (e.g. with value(), text(), rawText(), nodeName(), etc.) always have a pointer to the reference node (i.e. the Node from which the value was extracted.) These pointers are acknowledged when (intermediate) result lists are sorted. Currently, the only place where a result list is sorted is in a $union$ expression, which is the only place where the result list can be unordered. (If you find that this is not true, let me know.) Non-node values that have no associated reference node, always end up at the end of the result list in the order that they were added. The XQL spec states that the reference node for an XML Attribute is the Element to which it belongs, and that the order of values with the same reference node is undefined. This means that the order of an Element and its attributes would be undefined. But since the XML::DOM module keeps track of the order of the attributes, the XQL engine does the same, and therefore, the attributes of an Element are sorted and appear after their parent Element in a sorted result list. Constant Function Invocations If a function always returns the same value when given "constant" arguments, the function is considered to be "constant". A "constant" argument can be either an XQL primitive (Number, Boolean, Text) or a "constant" function invocation. E.g. date("12-03-1998") true() sin(0.3) length("abc") date(substr("12-03-1998 is the date", 0, 10)) are constant, but not: length(book[2]) Results of constant function invocations are cached and calculated only once for each query. See also the CONST parameter in defineFunction. It is not necessary to wrap constant function invocations in a once() call. Constant XQL functions are: date, true, false and a lot of the XQL+ wrappers for Perl builtin functions. Function wrappers for certain builtins are not made constant on purpose to force the invocation to be evaluated every time, e.g. 'mkdir("/user/enno/my_dir", "0644")' (although constant in appearance) may return different results for multiple invocations. See %PerlFunc in Plus.pm for details. Function: count ([QUERY]) The count() function has no parameters in the XQL spec. In this implementation it will return the number of QUERY results when passed a QUERY parameter. Method: text ([RECURSE]) When expanding an Element node, the text() method adds the expanded text() value of sub-Elements. When RECURSE is set to 0 (default is 1), it will not include sub-elements. This is useful e.g. when using the $match$ operator in a recursive context (using the // operator), so it won't return parent Elements when one of the children matches. Method: rawText ([RECURSE]) See text(). SEE ALSO ======== *Note XML/XQL/Query: XML/XQL/Query,, *Note XML/XQL/DOM: XML/XQL/DOM,, *Note XML/XQL/Date: XML/XQL/Date, The Japanese version of this document can be found on-line at `http:' in this node The *Note XML/XQL/Tutorial: XML/XQL/Tutorial, manual page. The Japanese version can be found at `http:' in this node The XQL spec at `http:' in this node The Design of XQL at `http:' in this node The DOM Level 1 specification at `http:' in this node The XML spec (Extensible Markup Language 1.0) at `http:' in this node The *Note XML/Parser: XML/Parser, and *Note XML/Parser/Expat: XML/Parser/Expat, manual pages. AUTHOR ====== Please send bugs, comments and suggestions to Enno Derksen <`enno@att.com'>  File: pm.info, Node: XML/XQL/DOM, Next: XML/XQL/Date, Prev: XML/XQL, Up: Module List Adds XQL support to XML::DOM nodes ********************************** NAME ==== XML::XQL::DOM - Adds XQL support to XML::DOM nodes SYNOPSIS ======== use XML::XQL; use XML::XQL::DOM; $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); # Or (see XML::DOM::Node) @result = $doc->xql ("book/title"); DESCRIPTION =========== XML::XQL::DOM adds methods to *Note XML/DOM: XML/DOM, nodes to support XQL queries on XML::DOM document structures. See *Note XML/XQL: XML/XQL, and *Note XML/XQL/Query: XML/XQL/Query, for more details. *Note XML/DOM/Node: XML/DOM/Node, describes the *xql()* method.  File: pm.info, Node: XML/XQL/Date, Next: XML/XQL/Query, Prev: XML/XQL/DOM, Up: Module List Adds an XQL::Node type for representing and comparing dates and times ********************************************************************* NAME ==== XML::XQL::Date - Adds an XQL::Node type for representing and comparing dates and times SYNOPSIS ======== use XML::XQL; use XML::XQL::Date; my $query = new XML::XQL::Query (Expr => "doc//timestamp[. < date('12/31/1999')]"); my @results = $query->solve ($doc); DESCRIPTION =========== This package uses the *Note Date/Manip: Date/Manip, package to add an XQL node type (called XML::XQL::Date) that can be used to represent dates and times. The Date::Manip package can parse almost any date or time format imaginable. (I tested it with Date::Manip 5.33 and I know for sure that it doesn't work with 5.20 or lower.) It also adds the XQL date function which creates an XML::XQL::Date object from a string. See *Note XML/XQL/Tutorial: XML/XQL/Tutorial, for a description of the date() function. You can plug in your own Date type, if you don't want to use Date::Manip for some reason. See *Note XML/XQL: XML/XQL, and the XML::XQL::Date source file for more details.  File: pm.info, Node: XML/XQL/Query, Next: XML/XQL/Tutorial, Prev: XML/XQL/Date, Up: Module List Creates an XQL query evaluater from a XQL expression **************************************************** NAME ==== XML::XQL::Query - Creates an XQL query evaluater from a XQL expression 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); 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. 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 Expr => STRING The query expression to be evaluated. NodeQuery => BOOLEAN If set to 1, the query is a *Node Query* as opposed to a *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. 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 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 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 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 ConstFunc => [ FUNCNAME => BOOLEAN, ...] Defines whether the function (not method!) is a "constant" function. FUNCNAME is the name as used in the query expression. See `Constant Function Invocations' in this node for a definition of "constant" See also: defineFunction and defineMethod 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 q => TOKEN Defines the q// token. See also: defineTokenQ qq => TOKEN Defines the qq// token. See also: defineTokenQQ 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. 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. Reserved hash keys Users may add their own (key, value) pairs to the Query constructor. Beware that the key 'Tree' is used internally. XML::XQL::Query methods ======================= 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); 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 `Global functions|XML::XQL' in this node for details. Another way to define these features for a particular Query is by passing the appropriate values to the XML::XQL::Query constructor. SEE ALSO ======== *Note XML/XQL: XML/XQL, for general information about the XML::XQL module *Note XML/XQL/Tutorial: XML/XQL/Tutorial, which describes the XQL syntax