About xuriella:

Xuriella is an implementation of XSLT 1.0.

Contents

Using XSLT

XSLT stylesheets are invoked using the apply-stylesheet function, which can parse, compile, and apply XSLT stylesheets.

Top-level parameters to the stylesheet can be specified using parameter instances created by make-parameter.

Function apply-stylesheet (stylesheet source-designator &key output parameters uri-resolver navigator)
Arguments:
  • stylesheet -- a stylesheet designator (see below for details)
  • source-designator -- a source document designator (see below for details)
  • output -- optional output sink designator (see below for details)
  • parameters -- a list of parameter instances
  • uri-resolver -- optional function of one argument
  • navigator -- optional XPath navigator
Returns:
The value returned by sax:end-document when called on the designated output sink.
Details:


Apply a stylesheet to a document.

This function takes stylesheet (either a parsed stylesheet or a designator for XML file to be parsed) and a source document, specified using the XML designator source-designator, and applies the stylesheet to the document.

An XML designator is any value accepted by cxml:parse, in particular:
  • Pathnames -- The file referred to by the pathname will parsed using cxml.
  • Stream -- The stream will be parsed using cxml.
  • Xstream -- Similar to the stream case, but using cxml's internal representation of rune streams.
  • String -- The string itself will be parsed as an XML document, and is assumed to have been decoded into characters already.
  • Array of (unsigned-byte 8) -- The array itself will be parsed as an XML document (which has not been decoded yet).


    • Note: Since strings are interpreted as documents, namestrings are not acceptable. Use pathnames instead of namestrings.

    An output sink designator is has the following form:
  • Null -- Designates a string sink. I.e., the result document of the stylesheet will be returned as a string. This as the default.
  • Pathnames -- The file referred to by the pathname will created and written to.
  • Stream -- The stream will be written to.
  • SAX or HAX handler -- Events will be sent directly to this sink.


    • Note: Specificaton of a sink overrides the specification of XML or HTML output method in the styl.sheet.

    Parameters are identified by names, and have values that are strings. Top-level parameters of these names are bound accordingly. If a paramater is not specified, its default value is computed as implemented in the stylesheet. If parameters are specified that the stylesheet does not recognize, they will be ignored.

    A uri-resolver is a function taking a PURI object as an argument and returning a PURI object as a value. The URI resolver will be invoked for all references to external files, e.g. at compilation time using xsl:import and xsl:include, and at run-time using the document() function.

    The URI resolver can be used to rewrite URLs so that file http:// links are replaced by file:// links, for example. Another application are URI resolvers that signal an error instead of returning, for example so that file:// links forbidden.

    The specified navigator will be passed to XPath protocol functions.

    See also:

    Class parameter
    Superclasses:
    common-lisp:structure-object, sb-pcl::slot-object, common-lisp:t
    Documented Subclasses:
    None
    Returned by:
    Slot Access Functions:
    Details:
    The class of top-level parameters to XSLT stylesheets.

    Parameters are identified by expanded names, i.e. a namespace URI and local-name.

    Their value is string.


    Function make-parameter (value local-name &optional (uri ))
    Arguments:
    • value -- The parameter's value, a string.
    • local-name -- The parameter's local name, a string.
    • local-name -- The parameter's namespace URI, a string.
    Returns:
    An instance of parameter.
    Details:


    Creates a paramater.

    See also:

    Compiling stylesheets explicitly

    parse-stylesheet allows the compilation of XSLT stylesheets into objects ahead of time, so that apply-stylesheet only needs to invoke the pre-compiled sheet rather than having to parse and compile it first.

    Function parse-stylesheet (designator &key uri-resolver)
    Arguments:
    • designator -- an XML designator
    • uri-resolver -- optional function of one argument
    Returns:
    An instance of stylesheet.
    Details:


    Parse a stylesheet.

    This function parses and compiles an XSLT stylesheet. The precompiled stylesheet object can then be passed to apply-stylesheet.

    Also refer to apply-stylesheet for details on XML designators.
    See also:

    Class stylesheet
    Superclasses:
    common-lisp:structure-object, sb-pcl::slot-object, common-lisp:t
    Documented Subclasses:
    None
    Returned by:
    Details:
    The class of stylesheets that have been parsed and compiled.

    Pass instances of this class to apply-stylesheet to invoke them.

    See also:

    Profiling support

    The profiling facility records the run time of XSLT templates.

    Function enable-profiling ()
    Returns:
    nil
    Details:
    Enables profiling.

    Resets any existing profile samples and enables profiling for future XSLT processing.

    Also enables XPath profiling, see xpath-sys:enable-profiling.

    Profiling is not thread safe.

    See also:

    Function disable-profiling ()
    Returns:
    nil
    Details:
    Disables profiling.

    Disables profiling for future XSLT processing, but keeps recorded profiling samples for report.

    Also disables XPath profiling, see xpath-sys:disable-profiling.

    See also:

    Function report ()
    Details:
    Shows profiling output.

    Shows cumulative run time and real time, number of calls, and average run time for each template that was invoked.

    See also:

    Defining extension elements

    Xuriella can be extended in two ways:

    Custom XPath functions can be implemented using the extension mechanism in Plexippus.

    Custom XSLT elements can be implemented using the following macros.

    define-extension-group is used to establish a namespace for the extensions, which can then be activated using a namespace declaration and the extension-element-prefixes attribute in the stylesheet.

    Every individual extension element needs at least a definition using define-extension-parser. The parser will run at compilation time and return an XSLT instruction in a sexp syntax. If the extension can be implemented as a transformation into ordinary XSLT elements, the parser only needs to return that XSLT sexp.

    In addition, the sexp representation itself can be extended using define-extension-compiler. The extension compiler will be invoked while the stylesheet is compiled to return a function, usually a closure, that will be called by the stylesheet at run-time.

    Macro define-extension-group (name uri &optional documentation)
    Arguments:
    • name -- The name of the XSLT extension group (a symbol)
    • uri -- Namespace URI for the extension elements (a string)
    • documentation -- Documentation string for the XPath extension
    Details:
    Defines an XSLT extension group with specified short name and namespace uri.

    An XSLT extension group is a collection of XSLT element that are defined using define-extension-parser.
    See also:

    Macro define-extension-parser (ext name (node-var) &body body)
    Arguments:
    • ext -- The name of an XSLT extension group (a symbol)
    • name -- Local name of the extension element (a string)
    • node-var -- Variable name for the node to be parsed, a symbol.
    • body -- Lisp forms, an implicit progn
    Details:
    Defines a parser an extension element.

    The parser function defined by this macro will be invoked when an XSLT extension element is encountered that has the namespace URI of the specified extension group and the local-name of this parser.

    body should return an XSLT instruction in sexp syntax.

    As a (very hypothetical) example, if the return value is computed using

       `(xsl:text ,(princ-to-string node-var))


    the stylesheet will emit a text node at run time, with the string representation of the instruction node as a value.

    Alternatively, a form can be returned that refers to user-specific compiler extensions:

       `(your-package::frob
     ,(stp:attribute-value node-var "frob-arg"))


    Use define-extension-compiler to implement an extension like frob.
    See also:

    Macro define-extension-compiler (symbol (&rest lambda-list) &body body)
    Arguments:
    • symbol -- The name of the extension, a symbol
    • lambda-list -- A destructuring lambda list, optionaly augmented using &environment
    • body -- Lisp forms, an implicit progn
    Details:


    Defines symbol as a name to be used in Xuriella's sexp representation for XSLT.

    It used when XSLT in sexp syntax includes a list of the form:

    (symbol ...arguments...)


    The list arguments is then destructured using the specified lambda list, and body is invoked during compilation time as an implicit progn.

    body should return a function of one argument, which will be called at run time with a context object as an argument.

    See also:

    Functions useful in extensions

    The following functions can be used by extension parsers and compilers, to parse child nodes as instructions, or to compile such instructions, respectively.

    Function parse-body (node &optional (start 0) (param-names 'nil))
    Arguments:
    • node -- A node representing part of a stylesheet.
    • start -- An optional integer, defaulting to 0.
    • param-names -- Undocumented.
    Returns:
    An list of XSLT instructions in sexp syntax
    Details:


    Parses the children of an XSLT instruction.

    This function is for use in XSLT extensions. When defining an extension using define-extension-parser, it can be used to parse the children of the extension node using regular XSLT syntax recursively.

    Specify start to skip the first start child nodes.
    See also:

    Function compile-instruction (form env)
    Arguments:
    • form -- An XSLT instruction in sexp representation
    • env -- An XSLT environment
    Returns:
    A compiled function
    Details:


    Compiles an XSLT instruction.

    This function is for use in XSLT extensions. When defining an extension using define-extension-compiler, pass body forms of the extension that should be interpreted as XSLT instructions to this function.

    The environment is an opaque object, which can be obtained using the &environment lambda list keyword in the extension compiler.

    Other functions in xuriella

    Function parameter-local-name (instance)
    Arguments:
    Returns:
    A stringReturns the parameter's local name.
    Details:


    See also:

    Function parameter-uri (instance)
    Arguments:
    Returns:
    A stringReturns the parameter's namespace URI.
    Details:


    See also:

    Function parameter-value (instance)
    Arguments:
    Returns:
    A stringReturns the parameter's value.
    Details:


    See also:

    Other classes in xuriella

    Class xslt-error
    Superclasses:
    common-lisp:simple-error, common-lisp:simple-condition, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
    Documented Subclasses:
    None
    Details:
    The class of all XSLT errors.

    Index of exported symbols

    xuriella:apply-stylesheet, function
    xuriella:compile-instruction, function
    xuriella:define-extension-compiler, macro
    xuriella:define-extension-group, macro
    xuriella:define-extension-parser, macro
    xuriella:disable-profiling, function
    xuriella:enable-profiling, function
    xuriella:make-parameter, function
    xuriella:parameter, class
    xuriella:parameter-local-name, function
    xuriella:parameter-uri, function
    xuriella:parameter-value, function
    xuriella:parse-body, function
    xuriella:parse-stylesheet, function
    xuriella:report, function
    xuriella:stylesheet, class
    xuriella:xslt-error, class