view release on metacpan or  search on metacpan

lib/XML/XQL.pm  view on Meta::CPAN

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

=item 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 I<query parameter>.
It uses expandType to expand XQL primitive type names.

=item Function: document (QUERY) or doc (QUERY)

The document() function creates a new L<XML::XML::Document> 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:

 <doc>
  <file name="file1.xml"/>
  <file name="file2.xml"/>
 </doc>

Then the following query will return two L<XML::XML::Document>s, 
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().

=item 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.

=item 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 I<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.

=back

=head2 XPath functions and methods

The following functions were found in the XPath specification:

=over 4

=item Function: concat (STRING, STRING, STRING*) 

The concat function returns the concatenation of its arguments.

=item 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.

=item Function: contains (STRING, STRING) 

The contains function returns true if the first argument string contains the 
second argument string, and otherwise returns false.

=item 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.

=item 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.

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