Read XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition Online
Authors: Michael Kay
XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (556 page)
doc(if (ends-with(@href, ‘/’)
then substring(@href, 1, string-length(@href)-1)
else @href)
Many string manipulations that can be done using
ends-with()
(but not those that rely on collations) can also be achieved using the
matches()
function, which allows regular expressions to be used. The above example could also be coded using
replace()
:
doc(replace(@href, ‘/$’, ‘’))
See Also
contains()
on page 730
matches()
on page 828
starts-with()
on page 875
string-length()
on page 880
substring()
on page 883
error
The
error()
function can be called when the application detects an error condition; it causes evaluation of the XPath expression as a whole to fail. In XSLT, this will cause the entire transformation to fail.
Signature
| Argument | Type | Meaning |
| code (optional) | xs:QName? | An error code |
| description (optional) | xs:string | A description of the error |
| object (optional) | item()? | A value associated with the error |
| Result | None | This function does not return a result; it always raises an error |
The
error()
function in fact has four signatures:
- error()
- error(code)
- error(code, description)
- error(code, description, object)
The
code
argument can be an empty sequence if the
description
is present, but not otherwise.
Effect
The
error()
function always reports an error, it never returns a result.
Calling the
error()
function causes the XPath expression as a whole to fail, since XPath provides no try/catch mechanism for catching errors.
Under XSLT, calling the error function causes the whole transformation to fail: the effect is the same as
The various arguments can be used to provide information about the error. The exact way in which this information is used depends on the implementation.
Error codes are defined as QNames. The error codes defined by the system (such as
XPTY0004
for the type error that occurs when calling a function with incorrect arguments) are technically local names associated with the namespace
http://www.w3.org/2005/xqt-errors
. User-defined error codes should be in a user-owned namespace. There is an assumption that a calling application will have access to these error codes, either as a QName, or as a URI with a fragment identifier (for example
http://www.w3.org/2005/xqt-errors#XPTY0004
). However, the details depend on the API design.
Examples
| Expression | Result |
| error() | Causes termination, with no explanation |
| error(xs:QName(“docbook: invalid-page-ref”)) | Causes termination, with an error code invalid-page-ref in the namespace associated with thedocbookprefix |
| error((), “Invalid parameter value”) | Causes termination, with a specified message, but no specified error code |
Usage
The
error()
function is useful when the application encounters a condition that it is not designed to handle, for example, invalid arguments passed to a function.
Every runtime error defined by the XSLT and XPath suite of specifications itself has a short code, such as FORG0001. These codes (which are listed in Appendix B) are all to be regarded as the local part of a QName, whose namespace URI is
http://www.w3.org/2005/xqt-errors
. The specification suggests that this code might be made available to applications via the API of the XPath processor, though there is nothing prescriptive about this. It makes sense for vendor-defined and user-defined error codes to fit into the same scheme of things by using
xs:QName
values as error values, with an explicit namespace. An implementation that allows error messages to be localized will typically provide some way of using the
xs:QName
as a code to look up a message in a file of message texts appropriate to the user's language.
This error-handling scheme is fine for product-quality applications that need to be delivered to a large number of users, localized to different languages, and so on. If you're just writing a simple stylesheet that's going to be used once and thrown away, it's all rather over the top. In this case, you can just pass a message that says what's gone wrong in the form of a string.
See Also
trace()
on page 896
Error codes: Appendix B
escape-html-uri
The
escape-html-uri()
function applies the URI escaping conventions defined in the HTML 4.0 specification to an input string.
For example,escape-html-uri(‘http://www.wikipedia.org/Gerhard Schröder’)returnshttp://www.wikipedia.org/Gerhard Schr%C3%B6der.
Signature
| Argument | Type | Meaning |
| value | xs:string? | The input string, to which URI escaping is to be applied. An empty sequence is treated as a zero-length string. |
| Result | xs:string | The URI in its escaped form, as a string . |
Effect
The result string is formed from the input string by escaping non-ASCII characters according to the rules defined in the HTML 4.0 specification. Non-ASCII characters are escaped by first encoding them in UTF-8, then representing each byte of the UTF-8 encoding in the form %HH where HH represents the byte as two hexadecimal digits. The digits A–F are always in upper case.
