From ebc6891c3c7939eb3d0ff529afdec0f7404acddd Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Mon, 8 Dec 2014 02:09:10 -0500
Subject: [PATCH] Initial thrushing implementation

f:thrushr
---
 Makefile                   |   1 +
 src/apply/thrush.xsl       | 146 +++++++++++++++++++++++++++++++++++++
 test/apply/thrush-test.xsl |  78 ++++++++++++++++++++
 test/apply/thrush.xspec    | 118 ++++++++++++++++++++++++++++++
 4 files changed, 343 insertions(+)
 create mode 100644 src/apply/thrush.xsl
 create mode 100644 test/apply/thrush-test.xsl
 create mode 100644 test/apply/thrush.xspec

diff --git a/Makefile b/Makefile
index ab7c49e..cd27f00 100644
--- a/Makefile
+++ b/Makefile
@@ -20,6 +20,7 @@ path_src  := src
 path_test := test
 
 test_apply := $(path_test)/apply/partial-test.xsl.apply \
+              $(path_test)/apply/thrush-test.xsl.apply \
               $(path_test)/transform/apply-gen-test-in.xsl.apply
 
 .PHONY: check test
diff --git a/src/apply/thrush.xsl b/src/apply/thrush.xsl
new file mode 100644
index 0000000..68e3233
--- /dev/null
+++ b/src/apply/thrush.xsl
@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Implementation of the Thrush combinator
+
+  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/>.
+
+  The Thrush combinator is defined as @math{Txy = yx}.
+
+  The Clojure macros @code{->} and @code{->>} (thread left/right) are
+  popular Thrush-like implementations which result in a familiar
+  pipeline-like style processing.
+
+  This allows re-ordering applications in a way that humans actually
+  think about them: left-to-right, not inside-out.  Here's an example:
+
+  @example
+    sum( filter( get-values( $foo ), predicate() ) ).
+  @end example
+
+  This would be better represented as a pipeline, as is common in
+  shell:
+
+  @example
+    get-values foo | filter predicate | sum
+  @end example
+
+  which we might express using @code{f:thrush} as
+
+  @example
+    f:thrush( get-values( $foo ),
+              filter( predicate() ),
+              sum() )
+  @end example
+
+  assuming that @code{filter} and @code{sum} above return dynamic
+  function references.
+
+  Above, @code{f:thrush} is equivalent to Clojure's @code{->>}; this
+  is aliased to @code{f:thrushr} for clarity, if you'd prefer to use
+  that.  We also have @code{thrushl}, which is like Clojure's
+  @code{->}, in that it maps the return value of a function to the
+  @emph{first} parameter of the function following
+  it.  @code{f:thrush} is an alias of @code{f:thrushr} (rather than
+  @code{f:thrushl}) because it is a natural fit with partial
+  application (especially currying).
+
+  OOP does similar using objects and method chaining:
+
+  @example
+    get-values( 'foo' )
+      .filter( predicate() )
+      .sum();
+  @end example
+
+  Indeed, the syntax @code{A.B(C)} is just syntactic sugar for
+  applying @code{B} within the context of @code{A}—@code{B(A,C)}—which
+  can be done using @code{f:thrushl}.
+-->
+
+<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"
+  xmlns:_f="http://www.lovullo.com/hoxsl/apply/_priv">
+
+<import href="../apply.xsl" />
+
+
+<!--
+  Alias of @code{f:thrushr}.
+-->
+<function name="f:thrush" as="item()">
+  <param name="list" as="item()+" />
+
+  <sequence select="f:thrushr( $list )" />
+</function>
+
+
+<!--
+  Given a @var{list} of the form @code{(value, f1, f2, ...)}, return
+  the result @code{...(f2(f1(value)))}
+
+  If @var{list} consists only of @code{value}, simply return
+  @code{value}.  Any number of functions may be provided in @var{list}
+  to form a pipeline; the result of the final application will be
+  returned.
+
+  All functions @emph{must} be unary; partial application should be
+  used to provide beginning arguments.  For example, this would yield
+  the value @code{5}:
+
+  @example
+    <sequence select="f:thrush( 5, f:partial( f:add(), 4 ) )" />
+  @end example
+
+  See the @code{apply-gen} stylesheet for auto-generating curried
+  functions to simplify the above partial application.
+-->
+<function name="f:thrushr" as="item()">
+  <param name="list" as="item()+" />
+
+  <sequence select="_f:thrushr-fold( subsequence( $list, 2 ),
+                                     $list[ 1 ] )" />
+</function>
+
+
+<function name="_f:thrushr-fold" as="item()">
+  <param name="fnref"  as="item()*" />
+  <param name="result" />
+
+  <choose>
+    <when test="empty( $fnref )">
+      <sequence select="$result" />
+    </when>
+
+    <otherwise>
+      <!-- FIXME: need abstraction -->
+      <variable name="next" as="item()*"
+                select="subsequence( $fnref,
+                                     f:length( $fnref ) + 1 )" />
+
+      <!-- map the next unary function to the previous result, then
+           pass that result along for further mapping -->
+      <sequence select="_f:thrushr-fold(
+                          $next,
+                          f:partial( $fnref, $result ) )" />
+    </otherwise>
+  </choose>
+</function>
+
+</stylesheet>
diff --git a/test/apply/thrush-test.xsl b/test/apply/thrush-test.xsl
new file mode 100644
index 0000000..5f91e7e
--- /dev/null
+++ b/test/apply/thrush-test.xsl
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Tests dynamic function application
+
+  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"
+            xmlns:foo="http://www.lovullo.com/_junk">
+
+  <import href="../../src/apply/thrush.xsl" />
+
+  <import href="thrush-test.xsl.apply" />
+
+
+  <function name="foo:give-foo" as="node()">
+    <param name="_" />
+
+    <!-- little bunny... -->
+    <foo:foo hop="forest"/>
+  </function>
+
+
+  <function name="foo:echo" as="item()">
+    <param name="item" as="item()" />
+
+    <sequence select="$item" />
+  </function>
+
+
+  <function name="foo:add1" as="xs:decimal">
+    <param name="to" as="xs:decimal" />
+
+    <sequence select="$to + 1" />
+  </function>
+
+
+  <function name="foo:add" as="xs:decimal">
+    <param name="x" as="xs:decimal" />
+    <param name="y" as="xs:decimal" />
+
+    <sequence select="$x + $y" />
+  </function>
+
+
+  <function name="foo:add3" as="xs:decimal">
+    <param name="x" as="xs:decimal" />
+    <param name="y" as="xs:decimal" />
+    <param name="z" as="xs:decimal" />
+
+    <sequence select="$x + $y + $z" />
+  </function>
+
+
+  <function name="foo:double" as="xs:decimal">
+    <param name="value" as="xs:decimal" />
+
+    <sequence select="$value * 2" />
+  </function>
+</stylesheet>
diff --git a/test/apply/thrush.xspec b/test/apply/thrush.xspec
new file mode 100644
index 0000000..73b2fa5
--- /dev/null
+++ b/test/apply/thrush.xspec
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Tests thrushing
+
+  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="thrush-test.xsl">
+
+  <variable name="doc">
+    <foo:parent name="foo">
+      <foo:child />
+    </foo:parent>
+  </variable>
+
+
+  <scenario label="f:thrushr function">
+    <scenario label="with a single item">
+      <call function="f:thrush">
+        <param name="list" select="$doc/foo:child" />
+      </call>
+
+      <!-- we should retain context if the value wasn't copied -->
+      <expect label="returns the value with context in tact"
+              test="$x:result/parent::foo:parent/@name = 'foo'" />
+    </scenario>
+
+
+    <!-- first, we need to test that we actually get the return value
+       of the second function -->
+    <scenario label="with a second, unary function">
+      <call function="f:thrush">
+        <param name="list" select="$doc, foo:give-foo()" />
+      </call>
+
+      <expect label="provides results of second function">
+        <foo:foo hop="forest" />
+      </expect>
+
+
+      <scenario label="value passed to second function">
+        <call function="f:thrush">
+          <param name="list" select="$doc/foo:child, foo:echo()" />
+        </call>
+
+        <expect label="should retain context"
+                test="$x:result/parent::foo:parent/@name = 'foo'" />
+      </scenario>
+    </scenario>
+
+
+    <!-- continue to test a simple case (unary) so that failures help to
+         track down a problem, not confound further -->
+    <scenario label="with multiple unary functions">
+      <call function="f:thrush">
+        <param name="list" select="1,
+                                   foo:add1(),
+                                   foo:add1(),
+                                   foo:echo(),
+                                   foo:double(),
+                                   foo:echo()" />
+      </call>
+
+      <expect label="returns last application having passed previous
+                     results to each"
+              test="$x:result = 6" />
+    </scenario>
+
+
+    <scenario label="with (n>1)-ary functions">
+      <call function="f:thrush">
+        <param name="list" select="1,
+                                   f:apply( foo:add3(), 2, 3 )" />
+      </call>
+
+      <expect label="both previous result and partial arguments are
+                     passed"
+              test="$x:result = 6" />
+    </scenario>
+
+
+    <scenario label="with a pipeline of (n>2) functions of varying
+                     arity">
+      <call function="f:thrush">
+        <param name="list"
+               select="5,
+                       foo:add1(),
+                       foo:add( 3 ),
+                       foo:double(),
+                       f:apply( foo:add3(), 2, 1 )" />
+      </call>
+
+      <expect label="arguments are passed, ordered, through the
+                     pipeline to yield a final result"
+              test="$x:result = 21" />
+    </scenario>
+  </scenario>
+</description>