Saxonica.com

fn:collection

fn:collection() → node()*

Function signature

$srcval

xs:string

Result

node() *

XPath 2.0 Specification

Returns the default collection if there is one.

Saxon implements this function by passing a null URI to the registered CollectionURIResolver. The default CollectionURIResolver implementation supplied with the product handles this by returning an empty sequence, but a user-supplied CollectionURIResolver is free to handle this case any way it wishes.

fn:collection(string $srcval) → node()*

Function signature

$srcval

xs:string

Result

node() *

XPath 2.0 Specification

Loads an external collection of nodes identified by the URI of the collection

If a user-defined CollectionURIResolver has been registered, the action of this function is entirely user-defined. A resolver may be registered using the setCollectionResolver() method on the Configuration object, or (in XSLT) using setAttribute() on the TransformerFactory. The CollectionURIResolver may be nominated using the -cr option on the command line. The following paragraphs define how the function behaves if the standard CollectionURIResolver is used.

The standard collection URI resolver first tries to interpret the argument as a reference to a directory. This treats the collection URI as the URI of a directory in filestore, and by default returns the result of parsing every file in the directory. Optional query parameters may be added to the URI: a simple pattern such as select=*.xml restricts the files to those that match the pattern; and the option recurse=yes causes subdirectories to be expanded recursively. So, for example, collection("dir?select=*.xml;recurse=yes") returns the result of parsing all files with extension "xml" in the directory named dir and all its subdirectories, recursively.

The detailed rules for the filter pattern are as follows: the pattern is converted to a regular expression by prepending "^", appending "$", replacing "." by "\.", and replacing "*" by ".*". The filter then matches all files whose names match the resulting regular expression. This means that it is possible to use filters such as *.(xml|xsl). Note however, that special characters used in the URL may need to be escaped using the %HH convention: this can be achieved using the iri-to-uri() function.

The query parameter validation=strict or validation=lax requests schema validation of each input document. The values validation=strip or validation=preserve request no validation. The default is to validate using the default mode set in the configuration.

The query parameter strip-space=yes causes stripping of all whitespace-only text nodes. The default is to strip such nodes only if the relevant option is set in the configuration, or if requested in the XSLT stylesheet.

The query parameter on-error=fail|warning|ignore may be specified to control the action taken if processing of one of the input files fails (for example, because it is not well-formed or valid XML).

The query parameter parser=full.class.name selects a parser (XMLReader) to be used to parse the source file. For example, John Cowan's TagSoup parser may be selected by specifying parser=org.ccil.cowan.tagsoup.Parser (this parses arbitrary ill-formed HTML and presents it to Saxon as well-formed XML).

If the URI does not identify a directory, it is interpreted as the URI of an XML catalogue document containing the URIs of the documents that make up the collection. An example of a catalogue is:

<collection>
  <doc href="doc1.xml"/>
  <doc href="doc2.xml"/>
  <doc href="doc3.xml"/>
</collection>

Next