Initial commit

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].
+

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/
+
+

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.
+

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

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.
+

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.

docs/lualibxslt.md

@@ -0,0 +1,37 @@
+# XML and XSL-T access from Lua
+
+When using Lua from the `<script>` element, XML and XSLT types are
+automatically available when accessed via arguments passed to Lua functions.
+
+Additional functions described here are accessed using `require "libxslt"`.
+
+```lua
+xslt = require "libxslt"
+
+nodeset = xslt.current()
+pos = xslt.position()
+pos = xslt.last()
+nodeset = xslt.nodeset()
+```
+
+## Functions
+
+### current()
+
+Return a node-set containing the current XPath context node. Equivalent to the
+XPath `current()` function.
+
+### position()
+
+Return a number equal to the context position from the current XPath expression
+evaluation context.  Equivalent to the XPath `position()` function.
+
+### last()
+
+Return a number equal to the context size from the current XPath expression
+evaluation context.  Equivalent to the XPath `last()` function.
+
+### nodeset()
+
+Return a new empty nodeset.
+

docs/luaxmldoc.md

@@ -0,0 +1,54 @@
+# XML Document
+
+XML documents are available via the following properties and methods:
+
+## Properties
+
+Document properties are read only variables.
+
+### doc:name
+```lua
+string = doc:name
+```
+
+The document name.
+
+### doc:url
+```lua
+string = doc:url
+```
+
+The document's URL.
+
+### doc:root
+```lua
+node = doc:root
+```
+
+The document's root node.
+
+## Methods
+
+### doc:node()
+```lua
+local node = doc:node()
+```
+
+Create a new node belonging to the document.
+
+### doc:setroot()
+```lua
+old_root = doc:setroot(node)
+```
+
+Set the document's root node to `node`. Returns the old root node.
+
+### doc:serialize()
+```lua
+doc:serialize(func)
+doc:serialize(function (text) io.write (text) end)
+```
+
+Serialise the XML document. The argument is a function repeatedly called to
+write the resulting text.
+