diff --git a/README.md b/README.md index c4a757b..294edd5 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,20 @@ # xslt-extra -Libxslt Extension Modules + +## Libxslt Extension Modules + +This collection implements various extension elements and functions for libxslt +that have proved useful in a few projects. The functions or elements actually +implemented follow no particular plan, rather they are somewhat randomly chosen +based on immediate need over time. + +They attempt to follow the specifications from [exslt.org](http://exslt.org/) +or XPath 2.0 functions where feasible, although some functions appear in +neither specification. Since XPath 2.0 has a number of features not present in +the libxml2 implementation, corresponding implementations are at most similar +rather than identical. + +## Copyright & Licence + +The Libxslt Extension Modules are copyright © 2020 Brian Stafford. +They are released under the [MIT Licence][1]. + diff --git a/docs/download.md b/docs/download.md new file mode 100644 index 0000000..f7c7247 --- /dev/null +++ b/docs/download.md @@ -0,0 +1,54 @@ +# Download + +The Libxslt Extension Modules are available from [GitHub][5]. Clone the +repository as follows: + +```sh +$ git clone https://github.com/iarthair/xslt-extra.git +``` + +## Dependencies + +### libxml2 + +The libxml2 development package is required to build the extension modules. +If your distribution does not provide libxml2, you can [download it here][1]. + +### libxslt + +The libxslt development package is required to build the extension modules. +If your distribution does not provide libxml2, you can [download it here][2]. + +### regcomp() + +Most modern C libraries provide the POSIX.1-2001, POSIX.1-2008 regcomp() family +of functions, required to build the regular expression functions. + +## Installation + +The libxslt extension functions use the [Meson build system][3]. Refer to the +Meson manual for standard configuration options. + +Meson supports multiple build system backends. To build with [Ninja][4] do the +following: + +``` sh +$ meson [options] --buildtype=release builddir +$ ninja -C builddir install +``` + +Note that the meson/ninja installer does not require an explicit `sudo`, +instead it will prompt for a password during install. This avoids polluting +builddir with files owned by root. + +## Reporting Bugs + +Bug should be reported using the GitHub issue tracker. + +[5]: https://github.com/iarthair/xslt-extra +[1]: http://xmlsoft.org/downloads.html +[2]: http://xmlsoft.org/XSLT/downloads.html +[3]: https://mesonbuild.com/Getting-meson.html +[4]: https://ninja-build.org/ + + diff --git a/docs/functions.md b/docs/functions.md new file mode 100644 index 0000000..224494e --- /dev/null +++ b/docs/functions.md @@ -0,0 +1,66 @@ +# XPath String Functions + +## string-join() +```xquery +xmlns:fn="https://iarthair.github.io/xpfunctions" + +string fn:string-join(node-set,string?) +``` + +Concatenate a list of strings with an intervening separator. The list of +strings is specified by a node-set passed in the first argument. Each +element in the node-set is converted to a string as if by using the XPath +`string()` function. If the separator is not specified an empty string is used. + +### Arguments + +* `node-set`: A node-set converted to a list of strings. +* `string`?: An optional separator string. If omitted an empty string is used. + +### Returns + +* `string`: the concatenated string + +--- + +## ends-with() +```xquery +xmlns:fn="https://iarthair.github.io/xpfunctions" + +boolean fn:ends-with(string,string) +``` + +Test whether a string ends with the specified suffix. If either argument is +not a string it is converted as if with the XPath `string()` function. + +### Arguments + +* `string`: String to test. +* `string`: Suffix to search for. + +### Returns + +* `boolean`: true if the test string has the specified suffix. + +--- + +## class-match() +```xquery +xmlns:fn="https://iarthair.github.io/xpfunctions" + +string fn:class-match(string, string?) +``` + +Test whether the token specified in the second argument matches any of the +space-separated tokens in the 1st argument. If either argument is +not a string it is converted as if with the XPath `string()` function. + +### Arguments + +* `string`: list of space separated tokens. +* `string`: token to test. + +### Returns + +* `boolean`: true if the token matches. + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..afb3760 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,29 @@ +# Libxslt Extension Modules + +Although [libxml2 and libxslt](https://www.xmlsoft.org/) are widely available, +unfortunately they implement only XPath 1.0 and XSL-T 1.0. Therefore a lot of +useful features are missing, particularly XPath functions. + +This collection implements various extension elements and functions for libxslt +that have proved useful in a few projects. The functions or elements actually +implemented follow no particular plan, rather they are somewhat randomly chosen +based on immediate need over time. + +In principle the XPath extension functions are independent of libxslt and could +be implemented using only libxml2, however the extension modules rely on the +module loading mechanism in libxslt and so they are only available when used +through an XSL-T stylesheet. + +They attempt to follow the specifications from [exslt.org](http://exslt.org/) +or XPath 2.0 functions where feasible, although some functions appear in +neither specification. Since XPath 2.0 has a number of features not present in +the libxml2 implementation, corresponding implementations are at most similar +rather than identical. + +## Copyright & Licence + +The Libxslt Extension Modules are copyright [© 2020 Brian Stafford](license.md). +They are released under the [MIT Licence][1] since this is the licence used +by libxml2 and libxslt. + +[1]: https://opensource.org/licenses/mit-license.html diff --git a/docs/lang.md b/docs/lang.md new file mode 100644 index 0000000..59bf2fb --- /dev/null +++ b/docs/lang.md @@ -0,0 +1,94 @@ +# RFC 4647 Language Tag Matching + +The following functions implement [RFC 4647][1] language tag matching. + +In each function the range argument is a string of space separated language +tags listed in order of decreasing preference. + +[1]: https://tools.ietf.org/html/rfc4647 + +## lang() +```xquery +xmlns:lang="https://iarthair.github.io/lang" + +boolean lang:lang(string) +``` + +Compare the context node's language against the range specified in the first +argument. The language of a node is the value of `xml:lang` attribute or, if +absent, the one carried by the nearest ancestor. + +This is similar to the XPath `lang()` function except that the comparison is +guaranteed to be the algorithm described in RFC 4647 and consistent with the +other functions in this namespace URI. + +### Arguments + +* `string`: the language range to accept. + +### Returns + +* `boolean`: true if the node is matched by the range. + +--- + +## accept-lang() +```xquery +xmlns:lang="https://iarthair.github.io/lang" + +node-set lang:accept-lang(node-set,string) +``` + +Return a node-set of elements whose language is the most specific match for the +range specified in the second argument. The language of a node is the value of +`xml:lang` attribute or, if absent, the one carried by the nearest ancestor. + +### Arguments + +* `node-set`: the set of nodes to be matched. +* `string`: the language range to accept. + +### Returns + +* `node-set`: set of matching nodes. + +--- + +## canonic-lang() +```xquery +xmlns:lang="https://iarthair.github.io/lang" + +string lang:canonic-lang(string) +``` + +Return the canonic form of the language tag in the argument string or an empty +string if it is not a valid RFC 4646 tag. + +### Arguments + +* `string`: the language tag. + +### Returns + +* `string`: the canonic tag. + +--- + +## extract-lang() +```xquery +xmlns:lang="https://iarthair.github.io/lang" + +string lang:extract-lang(string) +``` + +Return the language tag extracted from the string or an empty string if it is +not a valid RFC 4646 tag. + +### Arguments + +* `string`: the language tag. + +### Returns + +* `string`: the canonic tag. + diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..1ad1772 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,21 @@ +# The MIT License + +Copyright © 2020 Brian Stafford + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/lualibxslt.md b/docs/lualibxslt.md new file mode 100644 index 0000000..e903680 --- /dev/null +++ b/docs/lualibxslt.md @@ -0,0 +1,37 @@ +# XML and XSL-T access from Lua + +When using Lua from the `