Merge pull request #59 from clue-labs/deprecate-output

Deprecate output helpers, use `write()` instead

README.md

@@ -74,13 +74,6 @@ advanced usage.
 The `Stdio` is a well-behaving writable stream
 implementing ReactPHP's `WritableStreamInterface`.
 
-The `writeln($line)` method can be used to print a line to console output.
-A trailing newline will be added automatically.
-
-```php
-$stdio->writeln('hello world');
-```
-
 The `write($text)` method can be used to print the given text characters to console output.
 This is useful if you need more control or want to output individual bytes or binary output:
 
@@ -89,11 +82,20 @@ $stdio->write('hello');
 $stdio->write(" world\n");
 ```
 
-The `overwrite($text)` method can be used to overwrite/replace the last
+[Deprecated] The `writeln($line)` method can be used to print a line to console output.
+A trailing newline will be added automatically.
+
+```php
+// deprecated
+$stdio->writeln('hello world');
+```
+
+[Deprecated] The `overwrite($text)` method can be used to overwrite/replace the last
 incomplete line with the given text:
 
 ```php
 $stdio->write('Loading…');
+// deprecated
 $stdio->overwrite('Done!');
 ```
 
@@ -477,7 +479,7 @@ $readline->setAutocomplete(null);
 
 #### Stdout
 
-The `Stdout` represents a `WritableStream` and is responsible for handling console output.
+[Deprecated] The `Stdout` represents a `WritableStream` and is responsible for handling console output.
 
 Interfacing with it directly is *not recommended* and considered *advanced usage*.
 
@@ -490,6 +492,7 @@ $stdio->write('hello');
 Should you need to interface with the `Stdout`, you can access the current instance through the [`Stdio`](#stdio):
 
 ```php
+// deprecated
 $stdout = $stdio->getOutput();
 ```
 
@@ -503,7 +506,7 @@ If you want to read a line from console input, use the [`Stdio::on()`](#input) i
 
 ```php
 $stdio->on('line', function ($line) use ($stdio) {
-    $stdio->writeln('You said "' . $line . '"');
+    $stdio->write('You said "' . $line . '"' . PHP_EOL);
 });
 ```
 

examples/01-periodic.php

@@ -8,16 +8,16 @@
 
 $stdio = new Stdio($loop);
 
-$stdio->writeln('Will print periodic messages until you submit anything');
+$stdio->write('Will print periodic messages until you submit anything' . PHP_EOL);
 
 // add some periodic noise
 $timer = $loop->addPeriodicTimer(0.5, function () use ($stdio) {
-    $stdio->writeln(date('Y-m-d H:i:s') . ' hello');
+    $stdio->write(date('Y-m-d H:i:s') . ' hello' . PHP_EOL);
 });
 
 // react to commands the user entered
 $stdio->on('data', function ($line) use ($stdio, $loop, $timer) {
-    $stdio->writeln('you just said: ' . addcslashes($line, "\0..\37") . ' (' . strlen($line) . ')');
+    $stdio->write('you just said: ' . addcslashes($line, "\0..\37") . ' (' . strlen($line) . ')' . PHP_EOL);
 
     $loop->cancelTimer($timer);
     $stdio->end();

examples/02-interactive.php

@@ -36,11 +36,11 @@
     return $offset > 1 ? array() : array('exit', 'quit', 'help', 'echo', 'print', 'printf');
 });
 
-$stdio->writeln('Welcome to this interactive demo');
+$stdio->write('Welcome to this interactive demo' . PHP_EOL);
 
 // react to commands the user entered
 $stdio->on('line', function ($line) use ($stdio) {
-    $stdio->writeln('you just said: ' . $line . ' (' . strlen($line) . ')');
+    $stdio->write('you just said: ' . $line . ' (' . strlen($line) . ')' . PHP_EOL);
 
     if (in_array(trim($line), array('quit', 'exit'))) {
         $stdio->end();

examples/03-commander.php

@@ -29,21 +29,21 @@
     $stdio->end();
 });
 $router->add('help', function () use ($stdio) {
-    $stdio->writeln('Use TAB-completion or use "exit"');
+    $stdio->write('Use TAB-completion or use "exit"' . PHP_EOL);
 });
 $router->add('(echo | print) <words>...', function (array $args) use ($stdio) {
-    $stdio->writeln(implode(' ', $args['words']));
+    $stdio->write(implode(' ', $args['words']) . PHP_EOL);
 });
 $router->add('printf <format> <args>...', function (array $args) use ($stdio) {
-    $stdio->writeln(vsprintf($args['format'],$args['args']));
+    $stdio->write(vsprintf($args['format'],$args['args']) . PHP_EOL);
 });
 
 // autocomplete the following commands (at offset=0/1 only)
 $readline->setAutocomplete(function ($_, $offset) {
     return $offset > 1 ? array() : array('exit', 'quit', 'help', 'echo', 'print', 'printf');
 });
 
-$stdio->writeln('Welcome to this interactive demo');
+$stdio->write('Welcome to this interactive demo' . PHP_EOL);
 
 // react to commands the user entered
 $stdio->on('line', function ($line) use ($router, $stdio, $readline) {
@@ -57,7 +57,7 @@
     try {
         $args = Arguments\split($line);
     } catch (Arguments\UnclosedQuotesException $e) {
-        $stdio->writeln('Error: Invalid command syntax (unclosed quotes)');
+        $stdio->write('Error: Invalid command syntax (unclosed quotes)' . PHP_EOL);
         return;
     }
 
@@ -69,7 +69,7 @@
     try {
         $router->handleArgs($args);
     } catch (NoRouteFoundException $e) {
-        $stdio->writeln('Error: Invalid command usage');
+        $stdio->write('Error: Invalid command usage' . PHP_EOL);
     }
 });
 

src/Stdio.php

@@ -162,11 +162,17 @@ public function write($data)
         }
     }
 
+    /**
+     * @deprecated
+     */
     public function writeln($line)
     {
         $this->write($line . PHP_EOL);
     }
 
+    /**
+     * @deprecated
+     */
     public function overwrite($data = '')
     {
         if ($this->incompleteLine !== '') {
@@ -216,6 +222,9 @@ public function getInput()
         return $this->input;
     }
 
+    /**
+     * @deprecated
+     */
     public function getOutput()
     {
         return $this->output;

src/Stdout.php

@@ -4,6 +4,9 @@
 
 use React\Stream\WritableStream;
 
+/**
+ * @deprecated
+ */
 class Stdout extends WritableStream
 {
     public function __construct()