Update README.md

Author: clue

README.md

@@ -27,6 +27,226 @@ $loop->run();
 
 See also the [examples](examples).
 
+## Usage
+
+### Stdio
+
+The `Stdio` is the main interface to this library.
+It is responsible for orchestrating the input and output streams
+by registering and forwarding the corresponding events.
+It also registers everything with the main [EventLoop](https://github.com/reactphp/event-loop#usage).
+
+```php
+$loop = React\EventLoop\Factory::create();
+$stdio = new Stdio($loop);
+```
+
+#### Output
+
+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:
+
+```php
+$stdio->write('hello');
+$stdio->write(" world\n");
+```
+
+#### Input
+
+The `Stdio` 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:
+
+```php
+$stdio->on('line', function ($line) {
+    if ($line === 'start') {
+        doSomething();
+    }
+});
+```
+
+You can control various aspects of the console input through the [`Readline`](#readline),
+so read on..
+
+### Readline
+
+The [`Readline`](#readline) class is responsible for reacting to user input and presenting a prompt to the user.
+It does so by reading individual bytes from the input stream and writing the current *user input line* to the output stream.
+
+The *user input line* consists of a *prompt*, following by the current *user input buffer*.
+The `Readline` allows you to control various aspects of this *user input line*.
+
+You can access the current instance through the [`Stdio`](#stdio):
+
+```php
+$readline = $stdio->getReadline();
+```
+
+#### Prompt
+
+The *prompt* will be written at the beginning of the *user input line*, right before the *user input buffer*.
+
+The `setPrompt($prompt)` method can be used to change the input prompt.
+The prompt will be printed to the *user input line* as-is, so you will likely want to end this with a space:
+
+```php
+$readline->setPrompt('Input: ');
+```
+
+The default input prompt is empty, i.e. the *user input line* contains only the actual *user input buffer*.
+You can restore this behavior by passing an empty prompt:
+
+```php
+$readline->setPrompt('');
+```
+
+#### Echo
+
+The *echo mode* controls how the actual *user input buffer* will be presented in the *user input line*.
+
+The `setEcho($echo)` method can be used to control the echo mode.
+The default is to print the *user input buffer* as-is.
+
+You can disable printing the *user input buffer*, e.g. for password prompts.
+The user will still be able to type, but will not receive any indication of the current *user input buffer*.
+Please note that this often leads to a bad user experience as users will not even see their cursor position.
+Simply pass a boolean `false` like this:
+
+```php
+$readline->setEcho(false);
+```
+
+Alternatively, you can also *hide* the *user input buffer* by using a replacement character.
+One replacement character will be printed for each character in the *user input buffer*.
+This is useful for password prompts to give users an indicatation that their key presses are registered.
+This often provides a better user experience and allows users to still control their cursor position. 
+Simply pass a string replacement character likes this:
+
+```php
+$readline->setEcho('*');
+```
+
+To restore the original behavior where every character appears as-is, simply pass a boolean `true`:
+
+```php
+$readline->setEcho(true);
+```
+
+#### Input buffer
+
+Everything the user types will be buffered in the current *user input buffer*.
+Once the user hits enter, the *user input buffer* will be processed and cleared.
+
+The `setInput($buffer)` method can be used to control the *user input buffer*.
+The user will be able to delete and/or rewrite the buffer at any time.
+Changing the *user input buffer* can be useful for presenting a preset input to the user
+(like the last password attempt).
+Simple pass an input string like this:
+
+```php
+$readline->setInput('lastpass');
+```
+
+The `getInput()` method can be used to access the current *user input buffer*.
+This can be useful if you want to append some input behind the current *user input buffer*.
+You can simply access the buffer like this:
+
+```php
+$buffer = $readline->getInput();
+```
+
+#### Cursor
+
+By default, users can control their (horizontal) cursor position by using their arrow keys on the keyboard.
+Also, every character pressed on the keyboard advances the cursor position.
+
+The `setMove($toggle)` method can be used to control whether users are allowed to use their arrow keys.
+To disable the left and right arrow keys, simply pass a boolean `false` like this:
+
+```php
+$readline->setMove(false);
+```
+
+To restore the default behavior where the user can use the left and right arrow keys,
+simply pass a boolean `true` like this:
+
+```php
+$readline->setMove(true);
+```
+
+The `getCursorPosition()` method can be used to access the current cursor position.
+This can be useful if you want to get a substring of the current *user input buffer*.
+Simply invoke it like this:
+
+```php
+$position = $readline->getCursorPosition();
+```
+
+The `moveCursorTo($position)` method can be used to set the current cursor position to the given absolute character position.
+For example, to move the cursor to the beginning of the *user input buffer*, simply call:
+
+```php
+$readline->moveCursorTo(0);
+```
+
+The `moveCursorBy($offset)` method can be used to change the cursor position
+by the given number of characters relative to the current position.
+A positive number will move the cursor to the right - a negative number will move the cursor to the left.
+For example, to move the cursor one character to the left, simply call:
+
+```php
+$readline->moveCursorBy(-1);
+```
+
+### Advanced
+
+#### Stdout
+
+The `Stdout` represents a `WritableStream` and is responsible for handling console output.
+
+Interfacing with it directly is *not recommended* and considered *advanced usage*.
+
+If you want to print some text to console output, use the [`Stdio::write()`](#output) instead:
+
+```php
+$stdio->write('hello');
+```
+
+Should you need to interface with the `Stdout`, you can access the current instance through the [`Stdio`](#stdio):
+
+```php
+$stdout = $stdio->getOutput();
+```
+
+#### Stdin
+
+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->writeln('You said "' . $line . '"');
+});
+```
+
+Should you need to interface with the `Stdin`, you can access the current instance through the [`Stdio`](#stdio):
+
+You can access the current instance through the [`Stdio`](#stdio):
+
+```php
+$stdin = $stdio->getInput();
+```
+
 ## Install
 
 The recommended way to install this library is [through composer](https://getcomposer.org).