PHP: rfc:partial_function_application

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Partial Function Application ======
  * Version: 1.1
  * Date: 2020-04-22
  * Author: Paul Crovella, Levi Morrison
  * Status: Draft
  * First Published at: https://wiki.php.net/rfc/partial_function_application

===== Introduction =====
Partial function application is the process of binding only some of the arguments to a function call and leaving the remainder to be bound a later point. In PHP this would be done by a closure.

===== Proposal =====
Support partial function application via the argument placeholder ''?''. Any function or method call in which one or more of the arguments is an argument placeholder instead results in a closure being returned which wraps the called function, fixing the given (non-placeholder) arguments.

Type declarations, parameter names, reference parameters, optional defaults, variadics are all taken on by the closure from the function definition. All arguments given to a closure, including those beyond what are specified in the signature, get passed along to the underlying function.

The basic idea is to use a partial function call to stamp out a copy of the function, sans parameters where fixed arguments have already been given.

==== Types ====

Type declarations are retained, as are parameter names (e.g. for reflection.)

<PHP>
function f(int $x, int $y): int {}

$partialFoo = f(?, 42);
</PHP>

is equivalent to

<PHP>
$partial = function(int $x): int {
    return f($x, 42);
};
</PHP>


==== Variables/References ====

Variable arguments are ''use''d, and done so by reference if specified in the called function definition.

<PHP>
function f($value, &$ref) {}
 
$array = ['arg' => 0];

$f = f(?, $array['arg']);
</PHP>

is equivalent to

<PHP> 
$ref = &$array['arg'];
$f = function($value) use (&$ref) {
    return f($value, $ref);
};
</PHP>


==== Optional Parameters ====

Optional parameters remain optional, inheriting defaults.

<PHP>
function f($a = 0, $b = 1) {}

$f = f(?, 2);
</PHP>

is equivalent to

<PHP>
$partial = function($a = 0) {
    return f($a, 2);
};
</PHP>


==== func_num_args et al. ====

In order to keep ''func_num_args'' and friends happy, the arguments passed through will only be those up to and including the right-most actually given - whether at call time or during partial application. In other words, trailing optional parameters in the closure will not have their resolved defaults sent to the underlying function.

<PHP>
function f($a = 0, $b = 0, $c = 0, $d = 0) {
    echo func_num_args();
}

$f = f(?, 1, ?, ?);
$f(0, 2); // prints 3
$f(); // prints 2
</PHP>


==== Extra Arguments ====

You can pass as many additional arguments as you like when calling a function in PHP, beyond what's specified in the signature. When you pass extra arguments to the closure, or during partial application, they are passed along to the wrapped function.

<PHP>
function f($a, $b) {
    print_r(func_get_args());
}

$f = f(?, 2);
</PHP>

is actually akin to:

<PHP>
$f = function($a, ...$extraArgs) {
    return f($a, 2, ...$extraArgs);
};
</PHP>

(Though without unnecessary packing/unpacking, or ''$extraArgs'' appearing in reflection.)

So calling: ''$f(1, 3, 4)'' results in:

<PHP>
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)
</PHP>


==== Trailing Placeholders ====

Continuing on that, it is not required to include placeholders for trailing arguments, though at least one placeholder somewhere is necessary to indicate partial application. This is primarily to ease partial application of functions with long lists of optional parameters.

<PHP>
function f($m, $n, $o, $x = 0, $y = 0, $z = 0) {}

$f = f(1, ?);
</PHP>

is roughly (minding the ''func_num_args'' section above) equivalent to

<PHP>
$f = function($n, $o, $x = 0, $y = 0, $z = 0) {
    return f(1, $n, $o, $x, $y, $z);
};
</PHP>


==== Extra Trailing Placeholders ====

Additional placeholders beyond a function's signature do not cause an error and have no additional impact, though effectively allow you to apply all arguments to a function to be called later.

<PHP>
$n = 1000000;

$log10ofn = log10($n, ?);
</PHP>

is equivalent to

<PHP>
$log10ofn = function() use ($n) {
    return log10($n);
}
</PHP>


==== Variadic Functions ====

Variadic functions retain their signatures. Placeholders in a variadic position remain optional in the closure (there are no defaults, places not filled are simply not included in what's sent to the underlying function.) Fixed and placeholder arguments can be interleaved together.

<PHP>
function f(...$args) {
    print_r($args);
}

$f = f(?, 2, ?, 4, ?, 6);
$f(1, 3);
</PHP>

Would output:

<PHP>
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 6
)
</PHP>

==== Use as an identifier ===

Although not the primary goal, this feature would also provide a way to reference a function as a callable if needed in a given context.  Specifically, a function that partials all of its parameters would result in a closure that is functionally identical to the original function.  For example:

<PHP>
function by5(int $x) { return $x * 5; }

$arr = [1, 2, 3, 4, 5];

$result = array_map(by5(?), $arr);
</PHP>

That would make such functions still accessible to refactoring and static analysis tools, while avoiding any new syntax.

===== Backward Incompatible Changes =====

None.

===== Proposed PHP Version(s) =====

Next major/minor
Page Tools
