rfc:readline_interactive_shell_result_function

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
rfc:readline_interactive_shell_result_function [2021/01/16 20:50] – tandrerfc:readline_interactive_shell_result_function [2021/01/20 00:45] – tandre
Line 1: Line 1:
-====== PHP RFC: Configurable callback to dump results of expressions in `php -a` ====== +====== PHP RFC: Dump results of expressions in `php -a` ====== 
-  * Version: 0.1+  * Version: 0.2
   * Date: 2020-12-19   * Date: 2020-12-19
   * Author: Tyson Andre, tandre@php.net   * Author: Tyson Andre, tandre@php.net
-  * Status: Under Discussion+  * Status: Voting
   * Implementation: https://github.com/php/php-src/pull/5962/files   * Implementation: https://github.com/php/php-src/pull/5962/files
   * First Published at: https://wiki.php.net/rfc/readline_interactive_shell_result_function   * First Published at: https://wiki.php.net/rfc/readline_interactive_shell_result_function
Line 14: Line 14:
 (I've seen https://github.com/bobthecow/psysh mentioned as an alternative for ''php -a'' while investigating this, but that's a shell written from scratch, and doesn't have some functionality from ''php -a'' such as tolerance of fatal errors) (I've seen https://github.com/bobthecow/psysh mentioned as an alternative for ''php -a'' while investigating this, but that's a shell written from scratch, and doesn't have some functionality from ''php -a'' such as tolerance of fatal errors)
  
-Because PHP's interactive shell is written in C, adding new features or bug fixes would require a lot of time getting familiar with 
-C programming, PHP's internals and memory management, and with PHP's internal C ast representation. It would be easier and more accessible to extend PHP's interactive shell through code written in PHP rather than code written in C. 
  
 ===== Proposal ===== ===== Proposal =====
Line 22: Line 20:
 Additionally, add a new function ''readline_interactive_shell_result_function'' to the ''readline'' PHP module. This function only affects interactive shells - it can be used to set or clear a closure when ''extension_loaded('readline') === true'', but that closure would only be called in interactive shells (i.e. ''php -a''). Additionally, add a new function ''readline_interactive_shell_result_function'' to the ''readline'' PHP module. This function only affects interactive shells - it can be used to set or clear a closure when ''extension_loaded('readline') === true'', but that closure would only be called in interactive shells (i.e. ''php -a'').
  
-This will dump the results of expressions every time a statement containing a single expression such as ''2+2;'' or ''$x = call_function();'' is evaluated (but not non-expressions such as ''class X{}'' or combinations of expressions such as ''$x = 1; $y = $x*2;''.+This will dump the results of expressions every time a statement containing a single expression such as ''2+2;'' or ''$x = call_function();'' is evaluated (but not non-expressions such as ''class X{}'', statement blocks such as ''{ $x = 1; }'', or combinations of expressions such as ''$x = 1; $y = $x*2;''.
  
 An example of the behavior of the default expression dumper is below: An example of the behavior of the default expression dumper is below:
Line 78: Line 76:
 newline not automatically appended by shell newline not automatically appended by shell
 => 44 => 44
-php > { print("test\n"); }; // statement blocks can be used to avoid dumping expression results+php > { print("test\n"); } // statement blocks can be used to avoid dumping expression results
 test test
 php > php >
Line 86: Line 84:
  
 <code php> <code php>
-php -a+$ php -a
 Interactive shell Interactive shell
  
Line 120: Line 118:
  */  */
 function readline_interactive_shell_result_function(?callable $callback): bool; function readline_interactive_shell_result_function(?callable $callback): bool;
 +</code>
 +
 +The default implementation added as part of this RFC is effectively identical to the below implementation, but written in C. It can be replaced with a userland implementation or disabled at any time, even in [[https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file|auto_prepend_file]]. (Because the default implementation is written in C, it will work even if the ini setting ''disable_functions'' includes var_dump and var_export.)
 +
 +<code php>
 +readline_interactive_shell_result_function(
 +    function(string $code, $result) {
 +        if (!isset($result)) {
 +            return;
 +        }
 +        if (is_scalar($result)) {
 +            echo "=> " . var_export($result, true) . "\n";
 +        } else {
 +            echo "=> "; var_dump($result);
 +        }});
 </code> </code>
  
Line 125: Line 138:
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-None, only interactive sessions are affected, and only when this functionality is enabled and a callback is installed.+ 
 +Only interactive sessions (''php -a'') are affected, by a difference in the output sent to stdout. The dumping of expression results can be disabled entirely with the ini setting ''cli.enable_interactive_shell_result_function = Off'', or temporarily by calling ''readline_interactive_shell_result_function(null)'' 
 + 
 +In interactive sessions, this will start calling [[https://www.php.net/manual/en/language.oop5.magic.php#object.debuginfo|__debugInfo()]] if it exists due to calling ''var_dump()'' on objects. Implementations of ''__debugInfo()'' may throw or have other side effects after the expression is evaluated. 
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 162: Line 179:
   * i.e. change ''foo(); bar();'' to ''foo(); return (bar());''   * i.e. change ''foo(); bar();'' to ''foo(); return (bar());''
  
-===== Proposed Voting Choices ===== +===== Vote =====
- +
-Voting starts on 2021-01-03 and ends 2021-01-17.+
  
 Yes/No, requiring 2/3 majority Yes/No, requiring 2/3 majority
 +
 +<doodle title="Dump results of expressions in `php -a` as described in this RFC" auth="tandre" voteType="single" closed="false">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== References ===== ===== References =====
  
   * https://externals.io/message/111073 "Improving the usability of PHP's interactive shell? (completions, displaying expression results, custom syntax)"   * https://externals.io/message/111073 "Improving the usability of PHP's interactive shell? (completions, displaying expression results, custom syntax)"
-  * https://wiki.php.net/rfc/readline_interactive_shell_result_function_straw_poll+  * https://wiki.php.net/rfc/readline_interactive_shell_result_function_straw_poll "Straw poll: Interest in configurable callback to dump results of expressions in ''php -a''" 
 + 
 +===== Changelog ===== 
 + 
 +0.2: Dump non-null expression results by default with var_dump()/var_export() 
 +0.3: Document the default implementation used in the implementation
rfc/readline_interactive_shell_result_function.txt · Last modified: 2021/02/03 00:39 by tandre

Page Tools