Packages in XSLT 3.0

Packages in XSLT 3.0 are a way of creating predefined, re-usable and overridable libraries of functions and templates that can be packaged in an implementation-defined way, or used as-is (the source and manifest of a package is part of the XSLT 3.0 standard)

Using packages with Exselt

To use the packages feature with the Exselt commandline processor, you need to inform the processor where to find the named packages. This page explains three ways this can be achieved.

  1. Leave a default package catalog in place and have it search by default all *.pxsl documents in the current directory
  2. Use the default package catalog location which is searched in the current execution directory by default.
  3. Use a custom package catalog location, which can be handy if you have a global package catalog defined

Using the default package catalog

Place the following file (copy the code and place it in a file named package-catalog.xml) n the same directory as the stylesheet or package that wants to use your packages, and copy any package you want to use to the current directory. Make sure that the extension of packages is .pxsl.

<?xml version="1.0" encoding="UTF-8"?>
<package-catalog xmlns="http://exselt.net/package-catalog"
    default-file-extension="pxsl">
</package-catalog>

Alternatively, you can place this file in the root directory of the processor, however, we do not recommend this practice as it may involve significant overhead if, even if no package is required, the processor has to go over many files in your directory to make any packages available.

Customize the default package catalog

In workflow scenarios where not too many packages are required, it is safe to create a package catalog in that directory, which then subsequently becomes available to any stylesheet or package in that directory. We recommend using exact matching locations. An example of such package catalog can look like the following:

<?xml version="1.0" encoding="UTF-8"?>
<package-catalog xmlns="http://exselt.net/package-catalog"
    default-file-extension="pxsl">
    <packages>
        <package name="urn:prague" 
            version="1.0.0"
            href="file:/D:/projects/Pragu2016/so/package.xsl"/>
    </packages>
</package-catalog>

The details of this format are described below.

The Exselt Package Catalog data model and format

The default package catalog is an XML file with the name package-catalog.xml. The format of this document can be best explained by an example:

<?xml version="1.0" encoding="UTF-8"?>
<package-catalog xmlns="http://exselt.net/package-catalog"
    default-file-extension="pxsl">
    <queries>
        <query extension="pxsl" href="file:///d:/projects/w3.org/xt3/my_tests"/>
    </queries>
    <packages>
        <package name="urn:prague" 
            version="1.0.0"
            href="file:/D:/projects/Pragu2016/so/package.xsl"/>
    </packages>
</package-catalog>

Rules for constructing a package catalog XML document instance are as follows:

  1. All elements must be in the http://exselt.net/package-catalog namespace to be recognized. Unrecognized namespaces are ignored.
  2. Root element package-catalog
    1. Content model can have zero or more queries followed by zero or more packages elements
    2. Attribute default-file-extension defines the extension that needs to be filtered. The processor will look through all files with that extension and will add each XML-valid XSLT file that conforms to the package manifest structure (that is, "is a" package, with xsl:package as its root element and the @name attribute set). It is best to define an extension that is exclusively used for packages, as otherwise, loading and testing too many documents can slow things down. You can also remove the attribute in which case no documents will be queried by extension.
  3. Element queries
    1. Content model can have zero or morequery elements
  4. Element query
    1. Element must be empty
    2. Attribute extension can be used to set the extension that must be queried.
    3. Attribute href should be a qeriable (that is, can be listed, filtered and searched) location. A local folder location will always work, online resource don't work by default and require writing a PackageResolver .NET Assembly.
  5. Element packages
    1. Content model can have zero or more package elements
  6. Element package
    1. Element must be empty
    2. Attribute name must conform to the name of package
    3. Attribute version must conform to the package-version attribute of xsl:use-package and can take the form of (partial) wildcard expressions. Valid version productoins are "1.0.1" for an exact version, "1.0.* for any version starting with "1.0", "4.3.2+" is for any version numerically higher than "4.5.2".
    4. Attribute href defines the location as a valid xs:anyURI value. This location must exist, or a proper PackageResolver must have been registered. It is valid to use online locations, however this is not recommended as downloading and then compiling the online resource can add considerable overhead.