friends-of-reactphp / partial

Partial function application.

React/Partial

Partial function application.

Install

The recommended way to install react/partial is through composer.

{
    "require": {
        "react/partial": "~2.0"
    }
}

Concept

Partial application (or partial function application) refers to the process of fixing a number of arguments to a function, producing another function of smaller arity. Given a function f:(X x Y x Z) -> N, we might fix (or 'bind') the first argument, producing a function of type f:(Y x Z) -> N. Evaluation of this function might be represented as f partial(2, 3). Note that the result of partial function application in this case is a function that takes two arguments.

Basically, what this allows you to do is pre-fill arguments of a function, which is particularly useful if you don't have control over the function caller.

Let's say you have an async operation which takes a callback. How about a file download. The callback is called with a single argument: The contents of the file. Let's also say that you have a function that you want to be called once that file download completes. This function however needs to know an additional piece of information: the filename.

public function handleDownload($filename)
{
    $this->downloadFile($filename, ...);
}

public function downloadFile($filename, $callback)
{
    $contents = get the darn file asynchronously...
    $callback($contents);
}

public function processDownloadResult($filename, $contents)
{
    echo "The file $filename contained a shitload of stuff:\n";
    echo $contents;
}

The conventional approach to this problem is to wrap everything in a closure like so:

public function handleDownload($filename)
{
    $this->downloadFile($filename, function ($contents) use ($filename) {
        $this->processDownloadResult($filename, $contents);
    });
}

This is not too bad, especially with PHP 5.4, but with 5.3 you need to do the annoying $that = $this dance, and in general it's a lot of verbose boilerplate that you don't really want to litter your code with.

This is where partial application can help. Since we want to pre-fill an argument to the function that will be called, we just call bind, which will insert it to the left of the arguments list. The return value of bind is a new function which takes one $content argument.

use function React\Partial\bind;

public function handleDownload($filename)
{
    $this->downloadFile($filename, bind([$this, 'processDownloadResult'], $filename));
}

Partialing is dependency injection for functions! How awesome is that?

Examples

bind

use function React\Partial\bind;

$add = function ($a, $b) {
    return $a + $b;
};

$addOne = bind($add, 1);

echo sprintf("%d\n", $addOne(5));
// outputs 6

bind_right

use function React\Partial\bind_right;

$div = function ($a, $b, $c) {
    return $a / $b / $c;
};

$divMore = bind_right($div, 20, 10);

echo sprintf("%F\n", $divMore(100)); // 100 / 20 / 10
// outputs 0.5

placeholder

It is possible to use the … function (there is an alias called placeholder) to skip some arguments when partially applying.

This allows you to pre-define arguments on the right, and have the left ones bound at call time.

This example skips the first argument and sets the second and third arguments to 0 and 1 respectively. The result is a function that returns the first character of a string.

Note: Usually your IDE should help but accessing the "…"-character (HORIZONTAL ELLIPSIS, U+2026) differs on various platforms.

• Windows: ALT + 0133
• Mac: ALT + ; or ALT + .
• Linux: AltGr + .

use function React\Partial\bind;
use function React\Partial\…;

$firstChar = bind('substr', …(), 0, 1);
$mapped = array_map($firstChar, array('foo', 'bar', 'baz'));

var_dump($mapped);
// outputs ['f', 'b', 'b']

Tests

To run the test suite, you need PHPUnit.

$ phpunit

License

MIT, see LICENSE.

partial's Issues

Use argument unpacking and direct function invocation

What about a PHP 5.6 version that uses argument unpacking and direct function invocation. Did that for functional-php and it makes the code significantly nicer (and also slightly faster): lstrojny/functional-php@bfd7cae

[RFC] Use Classes and __invoke to allow 'lifting'

Is anyone interested in changes that would package current functionality into a class that is constructed with a callable and an integer for arity? This would let us implement the __invoke magic method to allow lifting the partial by binding passed in arguments and returning $this unless the arity has been reduced to 0, in which case we would actually execute. For example:

$map = new Partial('array_map', 2);
$inc = $map(function($x) { return $x++; });
$inc([1, 2, 3]); // returns [2, 3, 4]

We would reduce the arity by the count of non-placeholder arguments passed in each time:

$sub = new Partial('substr', 3);
$chunk2 = $sub(…, …, 2);
$last2 = $chunk(…, -2);
$last2('lol'); // 'ol'

I suppose you could make the method to execute the internal callable public and default the arity to unbounded, so that it's possible to pass along a filter with array_diff. Someone would just have to call a method at the end like evaluate(), or the previous actor would call something like finalize() which would fix the arity to 0 and fail if there were still any Placeholders.

Comments? I am issuing a request for them.