Merge pull request #62 from clue-labs/deprecate-input

Deprecate input helpers, use Stdio as ReadableStreamInterface instead

Author: clue

README.md

@@ -36,9 +36,10 @@ $stdio = new Stdio($loop);
 
 $stdio->getReadline()->setPrompt('Input > ');
 
-$stdio->on('line', function ($line) use ($stdio) {
+$stdio->on('data', function ($line) use ($stdio) {
+    $line = rtrim($line, "\r\n");
     var_dump($line);
-    
+
     if ($line === 'quit') {
         $stdio->end();
     }
@@ -64,10 +65,9 @@ $stdio = new Stdio($loop);
 ```
 
 See below for waiting for user input and writing output.
-Alternatively, the `Stdio` is also a well-behaving duplex stream
+The `Stdio` class is a well-behaving duplex stream
 (implementing ReactPHP's `DuplexStreamInterface`) that emits each complete
-line as a `data` event (including the trailing newline). This is considered
-advanced usage.
+line as a `data` event (including the trailing newline).
 
 #### Output
 
@@ -107,28 +107,37 @@ You can `pipe()` any readable stream into this stream.
 The `Stdio` is a well-behaving readable stream
 implementing ReactPHP's `ReadableStreamInterface`.
 
-It will emit a `line` event for every line read from console input.
-The event will contain the input buffer as-is, without the trailing newline.
+It will emit a `data` event for every line read from console input.
+The event will contain the input buffer as-is, including the trailing newline.
 You can register any number of event handlers like this:
 
 ```php
-$stdio->on('line', function ($line) {
-    if ($line === 'start') {
+$stdio->on('data', function ($line) {
+    if ($line === "start\n") {
         doSomething();
     }
 });
 ```
 
+Because the `Stdio` is a well-behaving redable stream that will emit incoming
+data as-is, you can also use this to `pipe()` this stream into other writable
+streams.
+
 You can control various aspects of the console input through the [`Readline`](#readline),
 so read on..
 
-Using the `line` event is the recommended way to wait for user input.
-Alternatively, using the `Readline` as a readable stream is considered advanced
-usage.
+[Deprecated] It will emit a `line` event for every line read from console input.
+The event will contain the input buffer as-is, without the trailing newline.
+You can register any number of event handlers like this:
 
-Alternatively, you can also use the `Stdio` as a readable stream, which emits
-each complete line as a `data` event (including the trailing newline).
-This can be used to `pipe()` this stream into other writable streams.
+```php
+// deprecated
+$stdio->on('line', function ($line) {
+    if ($line === 'start') {
+        doSomething();
+    }
+});
+```
 
 ### Readline
 
@@ -145,10 +154,11 @@ $readline = $stdio->getReadline();
 ```
 
 See above for waiting for user input.
+
 Alternatively, the `Readline` is also a well-behaving readable stream
 (implementing ReactPHP's `ReadableStreamInterface`) that emits each complete
-line as a `data` event (without the trailing newline). This is considered
-advanced usage.
+line as a `data` event (without the trailing newline).
+This is considered advanced usage.
 
 #### Prompt
 
@@ -303,11 +313,12 @@ If you want to automatically add everything from the user input to the history,
 you may want to use something like this:
 
 ```php
-$readline->on('data', function ($line) use ($readline) {
+$stdio->on('data', function ($line) use ($readline) {
+    $line = rtrim($line);
     $all = $readline->listHistory();
 
     // skip empty line and duplicate of previous line
-    if (trim($line) !== '' && $line !== end($all)) {
+    if ($line !== '' && $line !== end($all)) {
         $readline->addHistory($line);
     }
 });
@@ -498,14 +509,15 @@ $stdout = $stdio->getOutput();
 
 #### Stdin
 
-The `Stdin` represents a `ReadableStream` and is responsible for handling console input.
+[Deprecated] The `Stdin` represents a `ReadableStream` and is responsible for handling console input.
 
 Interfacing with it directly is *not recommended* and considered *advanced usage*.
 
 If you want to read a line from console input, use the [`Stdio::on()`](#input) instead:
 
 ```php
-$stdio->on('line', function ($line) use ($stdio) {
+$stdio->on('data', function ($line) use ($stdio) {
+    $line = rtrim($line, "\r\n");
     $stdio->write('You said "' . $line . '"' . PHP_EOL);
 });
 ```
@@ -515,6 +527,7 @@ Should you need to interface with the `Stdin`, you can access the current instan
 You can access the current instance through the [`Stdio`](#stdio):
 
 ```php
+// deprecated
 $stdin = $stdio->getInput();
 ```
 

examples/02-interactive.php

@@ -21,16 +21,6 @@
     $readline->limitHistory($limit);
 }
 
-// add all lines from input to history
-$readline->on('data', function ($line) use ($readline) {
-    $all = $readline->listHistory();
-
-    // skip empty line and duplicate of previous line
-    if (trim($line) !== '' && $line !== end($all)) {
-        $readline->addHistory($line);
-    }
-});
-
 // autocomplete the following commands (at offset=0/1 only)
 $readline->setAutocomplete(function ($_, $offset) {
     return $offset > 1 ? array() : array('exit', 'quit', 'help', 'echo', 'print', 'printf');
@@ -39,7 +29,16 @@
 $stdio->write('Welcome to this interactive demo' . PHP_EOL);
 
 // react to commands the user entered
-$stdio->on('line', function ($line) use ($stdio) {
+$stdio->on('data', function ($line) use ($stdio, $readline) {
+    $line = rtrim($line, "\r\n");
+
+    // add all lines from input to history
+    // skip empty line and duplicate of previous line
+    $all = $readline->listHistory();
+    if ($line !== '' && $line !== end($all)) {
+        $readline->addHistory($line);
+    }
+
     $stdio->write('you just said: ' . $line . ' (' . strlen($line) . ')' . PHP_EOL);
 
     if (in_array(trim($line), array('quit', 'exit'))) {

examples/03-commander.php

@@ -46,11 +46,13 @@
 $stdio->write('Welcome to this interactive demo' . PHP_EOL);
 
 // react to commands the user entered
-$stdio->on('line', function ($line) use ($router, $stdio, $readline) {
+$stdio->on('data', function ($line) use ($router, $stdio, $readline) {
+    $line = rtrim($line, "\r\n");
+
     // add all lines from input to history
     // skip empty line and duplicate of previous line
     $all = $readline->listHistory();
-    if (trim($line) !== '' && $line !== end($all)) {
+    if ($line !== '' && $line !== end($all)) {
         $readline->addHistory($line);
     }
 

examples/11-login.php

@@ -14,7 +14,8 @@
 $username = null;
 $password = null;
 
-$stdio->on('line', function ($line) use ($stdio, &$first, &$username, &$password) {
+$stdio->on('data', function ($line) use ($stdio, &$first, &$username, &$password) {
+    $line = rtrim($line, "\r\n");
     if ($first) {
         $stdio->getReadline()->setPrompt('Password: ');
         $stdio->getReadline()->setEcho('*');

src/Stdin.php

@@ -5,7 +5,9 @@
 use React\Stream\Stream;
 use React\EventLoop\LoopInterface;
 
-// TODO: only implement ReadableStream
+/**
+ * @deprecated
+ */
 class Stdin extends Stream
 {
     private $oldMode = null;

src/Stdio.php

@@ -217,6 +217,9 @@ public function close()
         $this->output->close();
     }
 
+    /**
+     * @deprecated
+     */
     public function getInput()
     {
         return $this->input;