├── .gitignore
├── .travis.yml
├── LICENSE
├── README.md
├── composer.json
├── phpunit.xml.dist
├── src
    └── Combinators.php
└── test
    ├── ComposeTest.php
    ├── FlipTest.php
    ├── IdTest.php
    ├── IfElseTest.php
    ├── KTest.php
    └── OnTest.php


/.gitignore:
--------------------------------------------------------------------------------
1 | composer.phar
2 | composer.lock
3 | /vendor/
4 | /build/
5 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | install: composer install
2 | language: php
3 | php:
4 |   - 7.0
5 |   - nightly
6 | script: composer test
7 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2016 php-fp
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Functional combinators for PHP. [![Build Status](https://travis-ci.org/php-fp/php-fp-combinators.svg?branch=master)](https://travis-ci.org/php-fp/php-fp-combinators)
  2 | 
  3 | ## Intro
  4 | 
  5 | Combinators are simple functions that allow you to modify the behaviour of values and functions after they have been created. These allow greater reuse of functions and reduction of boilerplate.
  6 | 
  7 | ## API
  8 | 
  9 | These combinators aren't fully curried by default - mainly for optimisation reasons - but are designed so that most common use cases can be satisfied as is. Consequently, the type signatures use the comma (`,`) to represent multiple arguments.
 10 | 
 11 | ### `compose :: (b -> c), (a -> b) -> a -> c`
 12 | 
 13 | Instead of writing `function ($x) { return f(g(x)); }`, `compose` allows us to express this as `compose('f', 'g')` (where the parameters could be closures, invokables, or anything that can be used as a "function"). Given two functions, `f` and `g`, a function will be returned that takes a value, `x`, and returns `f(g(x))`. This operation is _associative_, so `compose` calls can nest to create longer chains of functions. A simple, two-function example is shown here:
 14 | 
 15 | ```php
 16 | <?php
 17 | 
 18 | use PhpFp\Combinators as F;
 19 | 
 20 | $strictUcFirst = F::compose('ucfirst', 'strtolower');
 21 | $strictUcFirst('HELLO, WORLD'); // Hello, world
 22 | ```
 23 | 
 24 | Note that the functions are called **from left to right**. If the opposite is desired, this can be achieved easily:
 25 | 
 26 | ```php
 27 | <?php
 28 | 
 29 | use PhpFp\Combinators as F;
 30 | 
 31 | // The `flip` function is discussed later in this document.
 32 | $pipe = flip(F::compose());
 33 | $pipe($f, $g)($x) === $g($f($x));
 34 | ```
 35 | 
 36 | ### `flip :: (a, b -> c) -> (b, a) -> c`
 37 | 
 38 | This function takes a two-argument function, and returns the same function with the arguments swapped round:
 39 | 
 40 | ```php
 41 | <?php
 42 | 
 43 | use PhpFp\Combinators as F;
 44 | 
 45 | $divide = function ($x, $y) { return $x / $y; };
 46 | $divideBy = F::flip($divide);
 47 | 
 48 | $divideBy(2, 10); // 5
 49 | ```
 50 | 
 51 | This function becomes much more useful for functions that are curried. It can be useful in composition chains and point-free expressions.
 52 | 
 53 | ### `id :: a -> a`
 54 | 
 55 | Returns whatever it was given! Again, this is useful in composition chains for the times when you don't want to do anything to the value (see `converge`):
 56 | 
 57 | ```php
 58 | <?php
 59 | 
 60 | use PhpFp\Combinators as F;
 61 | 
 62 | F::id(2); // 2
 63 | F::id('hello'); // hello
 64 | ```
 65 | 
 66 | ### `ifElse :: (a -> Bool), (a -> b), (a -> b) -> a -> b`
 67 | 
 68 | This function allows for conditionals in composition chains. Unlike `converge`, which branches and merges, `ifElse` chooses which function to run based on the predicate, and the other function is ignored:
 69 | 
 70 | ```php
 71 | <?php
 72 | 
 73 | use PhpFp\Combinators as F;
 74 | 
 75 | $isOdd = function ($x) { return $x % 2 === 1; };
 76 | $odd = function ($x) { return $x * 3 + 1; };
 77 | $even = function ($x) { return $x / 2; };
 78 | 
 79 | $collatz = F::ifElse($isOdd, $odd, $even);
 80 | $collatz(3); // 10
 81 | $collatz(10); // 5
 82 | ```
 83 | 
 84 | ### `K :: a -> b -> a`
 85 | 
 86 | This function takes a value, and then returns a function that always returns that value, regardless of what it receives. This creates a "constant" function to wrap a value in places where invocation is expected:
 87 | 
 88 | ```php
 89 | <?php
 90 | 
 91 | use function PhpFp\Combinators;
 92 | 
 93 | $isOdd = function ($x) { return $x % 2 === 1; };
 94 | 
 95 | $f = F::ifElse($isOdd, K('Oops!'), function ($x) { return "$x is even!"; });
 96 | $f(1); // 'Oops!'
 97 | $f(2); // '2 is even!'
 98 | ```
 99 | 
100 | ### `on :: (b, b -> c), (a -> b) -> a, a -> c`
101 | 
102 | This function, also called the `Psi` combinator, allows you to call a function on transformations of values. This is really useful for things like sorting on particular properties of objects: we can call a compare function on two objects given a transformation. It's probably best illustrated with an example:
103 | 
104 | ```php
105 | <?php
106 | 
107 | // Get an array value.
108 | $prop = function ($k)
109 | {
110 |     return function ($xs) use ($k)
111 |     {
112 |         return $xs[$k];
113 |     };
114 | };
115 | 
116 | // Sort arrays by their 'test' key.
117 | $sort = function ($xs, $f) use ($prop)
118 | {
119 |     $ys = array_slice($xs, 0);
120 |     usort($ys, on($f, $prop('test')));
121 | 
122 |     return $ys;
123 | };
124 | 
125 | // Standard comparison function.
126 | $f = function ($a, $b) { return $a <=> $b; };
127 | 
128 | $test = [
129 |     ['title' => 'hello',     'test' => 3],
130 |     ['title' => 'goodbye',   'test' => 2],
131 |     ['title' => 'something', 'test' => 4]
132 | ];
133 | 
134 | array_column($sort($test, $f), 'title'); // ['goodbye', 'hello', 'something']
135 | ```
136 | 
137 | ## Contributing
138 | 
139 | If I've missed any of your favourite combinators, feel free to submit a PR. If you have a good idea about how to make any of this README clearer, that would be so great: while these combinators are not new to functional programmers, they _are_ complex and need to be explained well. All help is appreciated :)
140 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "authors": [
 3 |         {
 4 |             "name": "Tom",
 5 |             "email": "tomjharding@live.co.uk"
 6 |         }
 7 |     ],
 8 |     "autoload": {
 9 |         "files": ["src/Combinators.php"]
10 |     },
11 |     "autoload-dev": {
12 |         "psr-4": {
13 |             "PhpFp\\Combinators\\Test\\": "test/"
14 |         }
15 |     },
16 |     "description": "A handful of functional combinators in PHP.",
17 |     "homepage": "http://www.github.com/php-fp/php-fp-combinators",
18 |     "keywords": ["functional", "combinators"],
19 |     "license": "MIT",
20 |     "name": "php-fp/php-fp-combinators",
21 |     "scripts": {
22 |         "test": "phpunit"
23 |     },
24 |     "time": "2016-06-13",
25 |     "versions": "2.0.0",
26 |     "require-dev": {
27 |         "phpunit/phpunit": "^5.7"
28 |     },
29 |     "require": {
30 |         "cypresslab/php-curry": "^0.4.0"
31 |     }
32 | }
33 | 


--------------------------------------------------------------------------------
/phpunit.xml.dist:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit colors="true" bootstrap="vendor/autoload.php">
 3 |     <testsuites>
 4 |         <testsuite name="all">
 5 |             <directory>test/</directory>
 6 |         </testsuite>
 7 |     </testsuites>
 8 | 
 9 |     <filter>
10 |         <whitelist>
11 |             <directory suffix=".php">src/</directory>
12 |         </whitelist>
13 |     </filter>
14 | 
15 |     <logging>
16 |         <log type="coverage-text" target="php://stdout"/>
17 |         <log type="coverage-clover" target="build/logs/clover.xml"/>
18 |         <log type="coverage-html" target="build/coverage" charset="UTF-8" yui="true" highlight="true"/>
19 |     </logging>
20 | </phpunit>
21 | 


--------------------------------------------------------------------------------
/src/Combinators.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp;
 4 | 
 5 | use Cypress\Curry as C;
 6 | 
 7 | class Combinators
 8 | {
 9 |     /**
10 |      * Return a curried version of a combinator.
11 |      * @param string $name
12 |      * @param array $args
13 |      * @return mixed
14 |      */
15 |     public static function __callStatic($name, array $args)
16 |     {
17 |         $f = C\curry([self::class, "{$name}_"]);
18 |         return count($args) ? $f(... $args) : $f;
19 |     }
20 | 
21 |     /**
22 |      * Unary function composition.
23 |      * @param callable $f Outer function.
24 |      * @param callable $g Inner function.
25 |      * @return callable A composed unary function.
26 |      */
27 |     public static function compose_(callable $f, callable $g, $value)
28 |     {
29 |         return $f($g($value));
30 |     }
31 | 
32 |     /**
33 |      * Flip the arguments of a binary function.
34 |      * @param callable $f The function to flip.
35 |      * @return callable The flipped function.
36 |      */
37 |     public static function flip_(callable $f, $y, $x)
38 |     {
39 |         return $f($x, $y);
40 |     }
41 | 
42 |     /**
43 |      * Identity combinator. Return the parameter.
44 |      * @param mixed $x Anything in the world.
45 |      * @return mixed Exactly what $x was.
46 |      */
47 |     public static function id_($x)
48 |     {
49 |         return $x;
50 |     }
51 | 
52 |     /**
53 |      * Conditional branching.
54 |      * @param callable $p A boolean predicate.
55 |      * @param callable $f The "true" function.
56 |      * @param callable $g The "false" function.
57 |      * @return mixed The result of the chosen function.
58 |      */
59 |     public static function ifElse_($p, $f, $g, $x)
60 |     {
61 |         return $p($x) ? $f($x) : $g($x);
62 |     }
63 | 
64 |     /**
65 |      * Constant function.
66 |      * @param mixed $x The constant value.
67 |      * @return callable A unary function that returns $x.
68 |      */
69 |     public static function K_($x, $_)
70 |     {
71 |         return $x;
72 |     }
73 | 
74 |     /**
75 |      * Psi combinator.
76 |      * @param callable $f The outer function.
77 |      * @param callable $nt The parameter transformer.
78 |      * @return callable The transformed function.
79 |      */
80 |     public static function on_(callable $f, callable $nt, $x, $y)
81 |     {
82 |         return $f($nt($x), $nt($y));
83 |     }
84 | }
85 | 


--------------------------------------------------------------------------------
/test/ComposeTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class ComposeTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testCompose()
10 |     {
11 |         $inc = function ($x)
12 |         {
13 |             return $x + 1;
14 |         };
15 | 
16 |         $halve = function ($x)
17 |         {
18 |             return $x / 2;
19 |         };
20 | 
21 |         $f = Combinators::compose($halve, $inc);
22 | 
23 |         $this->assertEquals(
24 |             $f(3),
25 |             2,
26 |             'Composes correctly.'
27 |         );
28 | 
29 |         $this->assertEquals(
30 |             $f(2),
31 |             1.5,
32 |             'Types correctly handled.'
33 |         );
34 |     }
35 | }
36 | 


--------------------------------------------------------------------------------
/test/FlipTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class FlipTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testFlip()
10 |     {
11 |         $subtract = function ($x, $y)
12 |         {
13 |             return $x - $y;
14 |         };
15 | 
16 |         $subtractFrom = Combinators::flip($subtract);
17 | 
18 |         $this->assertEquals(
19 |             $subtractFrom(2, 9),
20 |             7,
21 |             'Flips.'
22 |         );
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/test/IdTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class IdTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testId()
10 |     {
11 |         $this->assertEquals(
12 |             2,
13 |             Combinators::id(2),
14 |             'Identity.'
15 |         );
16 |     }
17 | }
18 | 


--------------------------------------------------------------------------------
/test/IfElseTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class IfElseTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testIfElse()
10 |     {
11 |         $isOdd = function ($x) { return $x % 2 === 1; };
12 | 
13 |         $f = Combinators::ifElse(
14 |             $isOdd,
15 |             Combinators::K('Oops!'),
16 |             function ($x) {
17 |                 return "$x is even!";
18 |             }
19 |         );
20 | 
21 |         $this->assertEquals($f(1), 'Oops!', 'Success');
22 |         $this->assertEquals($f(2), '2 is even!', 'Failure');
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/test/KTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class KTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testK()
10 |     {
11 |         $f = Combinators::K(3);
12 | 
13 |         $this->assertEquals(
14 |             $f(2),
15 |             3,
16 |             'Creates a constant.'
17 |         );
18 |     }
19 | }
20 | 


--------------------------------------------------------------------------------
/test/OnTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PhpFp\Combinators\Test;
 4 | 
 5 | use PhpFp\Combinators;
 6 | 
 7 | class OnTest extends \PHPUnit_Framework_TestCase
 8 | {
 9 |     public function testOn()
10 |     {
11 |         $prop = function ($k)
12 |         {
13 |             return function ($xs) use ($k)
14 |             {
15 |                 return $xs[$k];
16 |             };
17 |         };
18 | 
19 |         $sort = function ($xs, $f) use ($prop)
20 |         {
21 |             $ys = array_slice($xs, 0);
22 |             usort($ys, Combinators::on($f, $prop('test')));
23 | 
24 |             return $ys;
25 |         };
26 | 
27 |         $f = function ($a, $b)
28 |         {
29 |             return $a <=> $b;
30 |         };
31 | 
32 |         $test = [
33 |             [
34 |                 'title' => 'hello',
35 |                 'test' => 3
36 |             ],
37 | 
38 |             [
39 |                 'title' => 'goodbye',
40 |                 'test' => 2
41 |             ],
42 | 
43 |             [
44 |                 'title' => 'something',
45 |                 'test' => 4
46 |             ]
47 |         ];
48 | 
49 |         $this->assertEquals(
50 |             array_column($sort($test, $f), 'title'),
51 |             ['goodbye', 'hello', 'something'],
52 |             'Transforms parameters.'
53 |         );
54 |     }
55 | }
56 | 


--------------------------------------------------------------------------------