From 5857eed3d6409eefebd026dc6734d8a71ec7b1e5 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Sat, 29 Nov 2014 02:01:40 -0500
Subject: [PATCH] `arity.xsl' stylesheet combined with ref functions into
 `ref.xsl'

These are strongly related---they operate on the same abstraction.
---
 src/apply.xsl                               |  74 ------
 src/apply/arity.xsl                         |  55 -----
 src/apply/partial.xsl                       |   2 +-
 src/apply/ref.xsl                           | 150 ++++++++++++
 test/apply.xspec                            | 158 -------------
 test/apply/arity.xspec                      |  83 -------
 test/apply/{arity-test.xsl => ref-test.xsl} |   5 +-
 test/apply/ref.xspec                        | 244 ++++++++++++++++++++
 8 files changed, 399 insertions(+), 372 deletions(-)
 delete mode 100644 src/apply/arity.xsl
 create mode 100644 src/apply/ref.xsl
 delete mode 100644 test/apply/arity.xspec
 rename test/apply/{arity-test.xsl => ref-test.xsl} (90%)
 create mode 100644 test/apply/ref.xspec

diff --git a/src/apply.xsl b/src/apply.xsl
index fc184c6..b7c4940 100644
--- a/src/apply.xsl
+++ b/src/apply.xsl
@@ -162,78 +162,4 @@
   </message>
 </template>
 
-
-<!--
-  Create a reference to dynamic function @var{name} with arity
-  @var{arity}
-
-  This function @emph{does not} verify that the function @var{name}
-  exists, nor does it verify that the provided @var{arity} is valid
-  for it.  Further, the returned function reference will work
-  @emph{only with dynamic functions}—that is, an application template
-  is needed.  See @file{transform/apply-gen.xsl} for more information
-  and examples.
--->
-<function name="f:make-ref" as="element( f:ref )">
-  <param name="name"  as="xs:QName" />
-  <param name="arity" as="xs:integer" />
-
-  <variable name="ns"
-            select="namespace-uri-from-QName( $name )" />
-
-  <f:ref arity="{$arity}">
-    <element name="{$name}"
-             namespace="{$ns}" />
-  </f:ref>
-</function>
-
-
-<!--
-  Determines whether @var{fnref} represents a valid dynamic function
-  reference
-
-  This can be used to determine if @var{fnref} is valid as input to
-  other functions, some of which may produce an error if called with
-  an invalid dynamic function reference.
-
-  @i{Implementation details:} To be valid, @var{fnref} must:
-
-  @enumerate
-  @item Be an element of type @code{f:ref};
-  @item Have a numeric @code{@arity}; and
-  @item Have a child target function node.
-  @enumerate
--->
-<function name="f:is-ref" as="xs:boolean">
-  <param name="fnref" as="item()*" />
-
-  <variable name="ref" select="$fnref[ 1 ]" />
-
-  <!-- for @arity check: note that NaN != NaN -->
-  <sequence select="$ref instance of element( f:ref )
-                    and number( $ref/@arity ) = number( $ref/@arity )
-                    and exists( $ref/*[ 1 ] )" />
-</function>
-
-
-<!--
-  Retrieve the QName of the target dynamic function
-
-  Usually, this would match precisely the QName of the target
-  function.
-
-  @i{Implementation details:} This actually represents the QName of
-  the @emph{application template}, which could differ from the target
-  function name.  One reason this may be the case is to provide a
-  function alias.
--->
-<function name="f:QName" as="xs:QName?">
-  <param name="fnref" as="element( f:ref )" />
-
-  <variable name="target" as="element()?"
-            select="$fnref/element()[ 1 ]" />
-
-  <sequence select="node-name( $target )" />
-</function>
-
 </stylesheet>
diff --git a/src/apply/arity.xsl b/src/apply/arity.xsl
deleted file mode 100644
index ad24032..0000000
--- a/src/apply/arity.xsl
+++ /dev/null
@@ -1,55 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
-  Arity calculations on dynamic and partially applied functions
-
-  Copyright (C) 2014 LoVullo Associates, Inc.
-
-    This file is part of hoxsl.
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
--->
-
-<stylesheet version="2.0"
-  xmlns="http://www.w3.org/1999/XSL/Transform"
-  xmlns:xs="http://www.w3.org/2001/XMLSchema"
-  xmlns:f="http://www.lovullo.com/hoxsl/apply">
-
-
-
-<!--
-  Attempt to retrieve arity of dynamic function @var{fnref}
-
-  @var{fnref} must be a dynamic function reference satisfying
-  @code{f:is-ref}.  Partially applied function references will have an
-  arity equivalent to the free parameters in the target function.
--->
-<function name="f:arity" as="xs:integer">
-  <param name="fnref" as="item()+" />
-
-  <variable name="ref" as="element( f:ref )"
-            select="$fnref[ 1 ]" />
-
-  <variable name="arity" as="xs:integer"
-            select="$ref/@arity" />
-
-  <variable name="partial" as="xs:integer"
-            select="if ( $ref/@partial ) then
-                      $ref/@partial
-                    else
-                      0" />
-
-  <sequence select="$arity - $partial" />
-</function>
-
-</stylesheet>
diff --git a/src/apply/partial.xsl b/src/apply/partial.xsl
index 3953377..8a8fcba 100644
--- a/src/apply/partial.xsl
+++ b/src/apply/partial.xsl
@@ -29,7 +29,7 @@
   xmlns:f="http://www.lovullo.com/hoxsl/apply"
   xmlns:_f="http://www.lovullo.com/hoxsl/apply/_priv">
 
-<import href="arity.xsl" />
+<import href="ref.xsl" />
 
 
 <!--
diff --git a/src/apply/ref.xsl b/src/apply/ref.xsl
new file mode 100644
index 0000000..8c6df09
--- /dev/null
+++ b/src/apply/ref.xsl
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Dynamic function reference
+
+  Copyright (C) 2014 LoVullo Associates, Inc.
+
+    This file is part of hoxsl.
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  A dynamic function reference is a sequence describing a dynamic
+  function to be applied.  It consists of two major parts—the dynamic
+  function reference descriptor and the arguments to bind to its
+  parameters:
+
+  @example
+    (desc[, arg1[, ...argn]])
+  @end example
+
+  The descriptor @var{desc} has the following format:
+
+  @example
+    <f:ref arity="N" [...]>
+      <target />
+    </f:ref>
+  @end example
+
+  where the @var{target} node shares the same QName as the function to
+  be applied, and @var{@arity} is its arity.  The @var{f:ref} node may
+  be decorated with additional attributes depending on its context or
+  constructor.
+-->
+
+<stylesheet version="2.0"
+  xmlns="http://www.w3.org/1999/XSL/Transform"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:f="http://www.lovullo.com/hoxsl/apply">
+
+
+<!--
+  Create a reference to dynamic function @var{name} with arity
+  @var{arity}
+
+  This function @emph{does not} verify that the function @var{name}
+  exists, nor does it verify that the provided @var{arity} is valid
+  for it.  Further, the returned function reference will work
+  @emph{only with dynamic functions}—that is, an application template
+  is needed.  See @file{transform/apply-gen.xsl} for more information
+  and examples.
+-->
+<function name="f:make-ref" as="element( f:ref )">
+  <param name="name"  as="xs:QName" />
+  <param name="arity" as="xs:integer" />
+
+  <variable name="ns"
+            select="namespace-uri-from-QName( $name )" />
+
+  <f:ref arity="{$arity}">
+    <element name="{$name}"
+             namespace="{$ns}" />
+  </f:ref>
+</function>
+
+
+<!--
+  Determines whether @var{fnref} represents a valid dynamic function
+  reference
+
+  This can be used to determine if @var{fnref} is valid as input to
+  other functions, some of which may produce an error if called with
+  an invalid dynamic function reference.
+
+  @i{Implementation details:} To be valid, @var{fnref} must:
+
+  @enumerate
+  @item Be an element of type @code{f:ref};
+  @item Have a numeric @code{@arity}; and
+  @item Have a child target function node.
+  @enumerate
+-->
+<function name="f:is-ref" as="xs:boolean">
+  <param name="fnref" as="item()*" />
+
+  <variable name="ref" select="$fnref[ 1 ]" />
+
+  <!-- for @arity check: note that NaN != NaN -->
+  <sequence select="$ref instance of element( f:ref )
+                    and number( $ref/@arity ) = number( $ref/@arity )
+                    and exists( $ref/*[ 1 ] )" />
+</function>
+
+
+<!--
+  Retrieve the QName of the target dynamic function
+
+  Usually, this would match precisely the QName of the target
+  function.
+
+  @i{Implementation details:} This actually represents the QName of
+  the @emph{application template}, which could differ from the target
+  function name.  One reason this may be the case is to provide a
+  function alias.
+-->
+<function name="f:QName" as="xs:QName?">
+  <param name="fnref" as="element( f:ref )" />
+
+  <variable name="target" as="element()?"
+            select="$fnref/element()[ 1 ]" />
+
+  <sequence select="node-name( $target )" />
+</function>
+
+
+<!--
+  Attempt to retrieve arity of dynamic function @var{fnref}
+
+  @var{fnref} must be a dynamic function reference satisfying
+  @code{f:is-ref}.  Partially applied function references will have an
+  arity equivalent to the free parameters in the target function.
+-->
+<function name="f:arity" as="xs:integer">
+  <param name="fnref" as="item()+" />
+
+  <variable name="ref" as="element( f:ref )"
+            select="$fnref[ 1 ]" />
+
+  <variable name="arity" as="xs:integer"
+            select="$ref/@arity" />
+
+  <variable name="partial" as="xs:integer"
+            select="if ( $ref/@partial ) then
+                      $ref/@partial
+                    else
+                      0" />
+
+  <sequence select="$arity - $partial" />
+</function>
+
+</stylesheet>
diff --git a/test/apply.xspec b/test/apply.xspec
index 7f6ad61..cbaff69 100644
--- a/test/apply.xspec
+++ b/test/apply.xspec
@@ -418,162 +418,4 @@
       </scenario>
     </scenario>
   </scenario>
-
-
-  <scenario label="f:make-ref constructor">
-    <scenario label="when called with a function QName and arity">
-      <variable name="qname"
-                select="QName( $foo-uri, 'reftest' )" />
-      <variable name="arity"
-                select="2" />
-
-      <call function="f:make-ref">
-        <param name="name"  select="$qname" />
-        <param name="arity" select="$arity" />
-      </call>
-
-      <expect label="produces a dynamic function reference"
-              test="f:is-ref( $x:result )" />
-
-      <expect label="produces provided reference arity"
-              test="f:arity( $x:result ) = $arity" />
-
-      <expect label="produces reference to expected QName"
-              test="f:QName( $x:result ) = $qname" />
-    </scenario>
-
-
-    <scenario label="produces a valid dynamic function reference">
-      <call function="f:apply">
-        <param name="fnref"
-               select="f:make-ref( QName( $foo-uri, 'fn1' ),
-                                   1 )" />
-        <param name="arg1"
-               select="$args/foo:arg1" />
-      </call>
-
-      <expect label="that can be applied using f:apply"
-              test="$x:result[ 1 ] = foo:applied[ @n = 1 ]
-                    and $x:result[ 2 ] is $args/foo:arg1" />
-    </scenario>
-  </scenario>
-
-
-  <scenario label="f:is-ref predicate">
-    <scenario label="given a valid dynamic function reference">
-      <call function="f:is-ref">
-        <param name="fnref"
-               select="f:make-ref( QName( $foo-uri, 'foo' ), 0 )" />
-      </call>
-
-      <expect label="returns true()"
-              select="true()" />
-    </scenario>
-
-
-    <scenario label="given an invalid dynamic function reference">
-      <call function="f:is-ref">
-        <param name="fnref">
-          <foo:bar />
-        </param>
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-
-
-    <scenario label="given a dynamic function reference without arity">
-      <call function="f:is-ref">
-        <param name="fnref">
-          <f:ref>
-            <foo:bar />
-          </f:ref>
-        </param>
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-
-
-    <scenario label="given a dynamic function reference without
-                     integral arity">
-      <call function="f:is-ref">
-        <param name="fnref">
-          <f:ref arity="moo">
-            <foo:bar />
-          </f:ref>
-        </param>
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-
-
-    <scenario label="given a dynamic function reference without target
-                     node">
-      <call function="f:is-ref">
-        <param name="fnref">
-          <f:ref arity="0" />
-        </param>
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-
-
-    <scenario label="given an empty sequence">
-      <call function="f:is-ref">
-        <param name="fnref" select="()" />
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-
-
-    <scenario label="given a non-element">
-      <call function="f:is-ref">
-        <param name="fnref" select="5" />
-      </call>
-
-      <expect label="returns false()"
-              select="false()" />
-    </scenario>
-  </scenario>
-
-
-  <scenario label="f:QName accessor">
-    <scenario label="given a valid dynamic function reference">
-      <variable name="foo-qname"
-                select="QName( $foo-uri, 'foo' )" />
-
-      <call function="f:QName">
-        <param name="fnref"
-               select="f:make-ref( $foo-qname, 0 )" />
-      </call>
-
-      <expect label="returns QName"
-              test="$x:result instance of xs:QName" />
-
-      <expect label="returns QName of target dynamic function"
-              select="$foo-qname" />
-    </scenario>
-
-
-    <scenario label="given a dynamic function reference with no target
-                     node">
-      <call function="f:QName">
-        <param name="fnref">
-          <f:ref arity="5" />
-        </param>
-      </call>
-
-      <expect label="returns empty sequence"
-              select="()" />
-    </scenario>
-  </scenario>
 </description>
diff --git a/test/apply/arity.xspec b/test/apply/arity.xspec
deleted file mode 100644
index a09198f..0000000
--- a/test/apply/arity.xspec
+++ /dev/null
@@ -1,83 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
-  Tests arity calculations
-
-  Copyright (C) 2014 LoVullo Associates, Inc.
-
-    This file is part of hoxsl.
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
--->
-
-<description xmlns="http://www.jenitennison.com/xslt/xspec"
-             xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-             xmlns:x="http://www.jenitennison.com/xslt/xspec"
-             xmlns:f="http://www.lovullo.com/hoxsl/apply"
-             xmlns:foo="http://www.lovullo.com/_junk"
-             stylesheet="arity-test.xsl">
-
-  <variable name="foo-uri"
-            select="namespace-uri-for-prefix(
-                      'foo', root(.)/element() )" />
-
-  <variable name="test-arity"
-            select="5" />
-
-  <variable name="test-fn"
-            select="f:make-ref( QName( $foo-uri, 'foo:bar' ),
-                                $test-arity )" />
-
-
-  <scenario label="f:arity">
-    <scenario label="given a proper function reference">
-      <variable name="test-arity"
-                select="5" />
-
-      <!-- test our format directly; do not rely on the
-           apply-gen code -->
-      <call function="f:arity">
-        <param name="fnref" select="$test-fn" />
-      </call>
-
-      <expect label="provides function arity"
-              select="$test-arity" />
-    </scenario>
-
-
-    <scenario label="given a partially applied function reference">
-      <call function="f:arity">
-        <param name="fnref"
-               select="f:apply( $test-fn, 1, 2 )" />
-      </call>
-
-      <expect label="provides arity of the target function minus the
-                     number of bound parameters"
-              select="$test-arity - 2" />
-    </scenario>
-
-
-    <scenario label="given a multiply-partially-applied function reference">
-      <call function="f:arity">
-        <param name="fnref"
-               select="f:apply(
-                         f:apply( $test-fn, 1, 2 ),
-                         3 )" />
-      </call>
-
-      <expect label="provides arity of the target function minus the
-                     number of bound parameters"
-              select="$test-arity - 3" />
-    </scenario>
-  </scenario>
-</description>
diff --git a/test/apply/arity-test.xsl b/test/apply/ref-test.xsl
similarity index 90%
rename from test/apply/arity-test.xsl
rename to test/apply/ref-test.xsl
index 0993c3f..268b805 100644
--- a/test/apply/arity-test.xsl
+++ b/test/apply/ref-test.xsl
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
-  Tests arity calculations
+  Tests dynamic function reference
 
   Copyright (C) 2014 LoVullo Associates, Inc.
 
@@ -29,4 +29,7 @@
   <!-- this imports the SUT, as well as additional functions we need
        for testing -->
   <import href="../../src/apply.xsl" />
+
+  <!-- numerous templates for arity tests -->
+  <import href="../apply-test.xsl" />
 </stylesheet>
diff --git a/test/apply/ref.xspec b/test/apply/ref.xspec
new file mode 100644
index 0000000..da2a9df
--- /dev/null
+++ b/test/apply/ref.xspec
@@ -0,0 +1,244 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Tests dynamic function reference
+
+  Copyright (C) 2014 LoVullo Associates, Inc.
+
+    This file is part of hoxsl.
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<description xmlns="http://www.jenitennison.com/xslt/xspec"
+             xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+             xmlns:x="http://www.jenitennison.com/xslt/xspec"
+             xmlns:f="http://www.lovullo.com/hoxsl/apply"
+             xmlns:foo="http://www.lovullo.com/_junk"
+             stylesheet="ref-test.xsl">
+
+  <variable name="foo-uri"
+            select="namespace-uri-for-prefix(
+                      'foo', root(.)/element() )" />
+
+  <variable name="test-arity"
+            select="5" />
+
+  <variable name="test-fn"
+            select="f:make-ref( QName( $foo-uri, 'foo:bar' ),
+                                $test-arity )" />
+
+
+  <scenario label="f:make-ref constructor">
+    <scenario label="when called with a function QName and arity">
+      <variable name="qname"
+                select="QName( $foo-uri, 'reftest' )" />
+      <variable name="arity"
+                select="2" />
+
+      <call function="f:make-ref">
+        <param name="name"  select="$qname" />
+        <param name="arity" select="$arity" />
+      </call>
+
+      <expect label="produces a dynamic function reference"
+              test="f:is-ref( $x:result )" />
+
+      <expect label="produces provided reference arity"
+              test="f:arity( $x:result ) = $arity" />
+
+      <expect label="produces reference to expected QName"
+              test="f:QName( $x:result ) = $qname" />
+    </scenario>
+
+
+    <scenario label="produces a valid dynamic function reference">
+      <variable name="arg">
+        <foo:bar />
+      </variable>
+
+      <call function="f:apply">
+        <param name="fnref"
+               select="f:make-ref( QName( $foo-uri, 'fn1' ),
+                                   1 )" />
+        <param name="arg1" select="$arg" />
+      </call>
+
+      <expect label="that can be applied using f:apply"
+              test="$x:result[ 1 ] = foo:applied[ @n = 1 ]
+                    and $x:result[ 2 ] is $arg" />
+    </scenario>
+  </scenario>
+
+
+  <scenario label="f:is-ref predicate">
+    <scenario label="given a valid dynamic function reference">
+      <call function="f:is-ref">
+        <param name="fnref"
+               select="f:make-ref( QName( $foo-uri, 'foo' ), 0 )" />
+      </call>
+
+      <expect label="returns true()"
+              select="true()" />
+    </scenario>
+
+
+    <scenario label="given an invalid dynamic function reference">
+      <call function="f:is-ref">
+        <param name="fnref">
+          <foo:bar />
+        </param>
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+
+
+    <scenario label="given a dynamic function reference without arity">
+      <call function="f:is-ref">
+        <param name="fnref">
+          <f:ref>
+            <foo:bar />
+          </f:ref>
+        </param>
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+
+
+    <scenario label="given a dynamic function reference without
+                     integral arity">
+      <call function="f:is-ref">
+        <param name="fnref">
+          <f:ref arity="moo">
+            <foo:bar />
+          </f:ref>
+        </param>
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+
+
+    <scenario label="given a dynamic function reference without target
+                     node">
+      <call function="f:is-ref">
+        <param name="fnref">
+          <f:ref arity="0" />
+        </param>
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+
+
+    <scenario label="given an empty sequence">
+      <call function="f:is-ref">
+        <param name="fnref" select="()" />
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+
+
+    <scenario label="given a non-element">
+      <call function="f:is-ref">
+        <param name="fnref" select="5" />
+      </call>
+
+      <expect label="returns false()"
+              select="false()" />
+    </scenario>
+  </scenario>
+
+
+  <scenario label="f:QName accessor">
+    <scenario label="given a valid dynamic function reference">
+      <variable name="foo-qname"
+                select="QName( $foo-uri, 'foo' )" />
+
+      <call function="f:QName">
+        <param name="fnref"
+               select="f:make-ref( $foo-qname, 0 )" />
+      </call>
+
+      <expect label="returns QName"
+              test="$x:result instance of xs:QName" />
+
+      <expect label="returns QName of target dynamic function"
+              select="$foo-qname" />
+    </scenario>
+
+
+    <scenario label="given a dynamic function reference with no target
+                     node">
+      <call function="f:QName">
+        <param name="fnref">
+          <f:ref arity="5" />
+        </param>
+      </call>
+
+      <expect label="returns empty sequence"
+              select="()" />
+    </scenario>
+  </scenario>
+
+
+  <scenario label="f:arity">
+    <scenario label="given a proper function reference">
+      <variable name="test-arity"
+                select="5" />
+
+      <!-- test our format directly; do not rely on the
+           apply-gen code -->
+      <call function="f:arity">
+        <param name="fnref" select="$test-fn" />
+      </call>
+
+      <expect label="provides function arity"
+              select="$test-arity" />
+    </scenario>
+
+
+    <scenario label="given a partially applied function reference">
+      <call function="f:arity">
+        <param name="fnref"
+               select="f:apply( $test-fn, 1, 2 )" />
+      </call>
+
+      <expect label="provides arity of the target function minus the
+                     number of bound parameters"
+              select="$test-arity - 2" />
+    </scenario>
+
+
+    <scenario label="given a multiply-partially-applied function reference">
+      <call function="f:arity">
+        <param name="fnref"
+               select="f:apply(
+                         f:apply( $test-fn, 1, 2 ),
+                         3 )" />
+      </call>
+
+      <expect label="provides arity of the target function minus the
+                     number of bound parameters"
+              select="$test-arity - 3" />
+    </scenario>
+  </scenario>
+</description>