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.

friends-of-reactphp/partial