From 0ad2b9ea996fa3f4465c6327de1bc7bf7f0dec7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 26 Aug 2021 08:48:19 +0200 Subject: [PATCH 1/2] Improve documentation, use fully qualified class names in all examples --- README.md | 7 +++++-- examples/01-periodic.php | 3 +-- examples/02-interactive.php | 5 +---- examples/03-commander.php | 15 +++++---------- examples/04-bindings.php | 4 +--- examples/05-cursor.php | 4 +--- examples/11-login.php | 4 +--- 7 files changed, 15 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index d0719c6..9ddbc5b 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,11 @@ Let's take these projects to the next level together! 🚀 Once [installed](#install), you can use the following code to present a prompt in a CLI program: ```php -$stdio = new Stdio(); +setPrompt('Input > '); $stdio->on('data', function ($line) use ($stdio) { @@ -76,7 +79,7 @@ It is responsible for orchestrating the input and output streams by registering and forwarding the corresponding events. ```php -$stdio = new Stdio(); +$stdio = new Clue\React\Stdio\Stdio(); ``` This class takes an optional `LoopInterface|null $loop` parameter that can be used to diff --git a/examples/01-periodic.php b/examples/01-periodic.php index cbf8a58..467a60f 100644 --- a/examples/01-periodic.php +++ b/examples/01-periodic.php @@ -1,11 +1,10 @@ write('Will print periodic messages until you submit anything' . PHP_EOL); diff --git a/examples/02-interactive.php b/examples/02-interactive.php index 2e55093..1b2420a 100644 --- a/examples/02-interactive.php +++ b/examples/02-interactive.php @@ -1,11 +1,8 @@ setPrompt('> '); // limit history to HISTSIZE env diff --git a/examples/03-commander.php b/examples/03-commander.php index 427f512..0f5bf77 100644 --- a/examples/03-commander.php +++ b/examples/03-commander.php @@ -1,13 +1,8 @@ setPrompt('> '); // limit history to HISTSIZE env @@ -21,7 +16,7 @@ } // register all available commands and their arguments -$router = new Router(); +$router = new Clue\Commander\Router(); $router->add('exit | quit', function() use ($stdio) { $stdio->end(); }); @@ -54,8 +49,8 @@ } try { - $args = Arguments\split($line); - } catch (Arguments\UnclosedQuotesException $e) { + $args = Clue\Arguments\split($line); + } catch (Clue\Arguments\UnclosedQuotesException $e) { $stdio->write('Error: Invalid command syntax (unclosed quotes)' . PHP_EOL); return; } @@ -67,7 +62,7 @@ try { $router->handleArgs($args); - } catch (NoRouteFoundException $e) { + } catch (Clue\Commander\NoRouteFoundException $e) { $stdio->write('Error: Invalid command usage' . PHP_EOL); } }); diff --git a/examples/04-bindings.php b/examples/04-bindings.php index 0dbd0ce..8e110fd 100644 --- a/examples/04-bindings.php +++ b/examples/04-bindings.php @@ -1,10 +1,8 @@ setPrompt('> '); // add some special key bindings diff --git a/examples/05-cursor.php b/examples/05-cursor.php index 22fd9b8..98a23f1 100644 --- a/examples/05-cursor.php +++ b/examples/05-cursor.php @@ -1,10 +1,8 @@ on("\033[A", function () use (&$value, $stdio) { diff --git a/examples/11-login.php b/examples/11-login.php index b1a14f1..ad21c29 100644 --- a/examples/11-login.php +++ b/examples/11-login.php @@ -1,10 +1,8 @@ setPrompt('Username: '); $first = true; From 0233e6f27ea7f40fcfea4d585c4155f84c339129 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sat, 28 Aug 2021 00:41:57 +0200 Subject: [PATCH 2/2] Minor documentation improvements --- README.md | 51 ++++++++++++++++++++++++------------------------ src/Readline.php | 2 +- 2 files changed, 26 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 9ddbc5b..5c2c02c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # clue/reactphp-stdio [![CI status](https://github.com/clue/reactphp-stdio/workflows/CI/badge.svg)](https://github.com/clue/reactphp-stdio/actions) -[![Packagist downloads](https://img.shields.io/packagist/dt/clue/stdio-react?color=blue&label=installs)](https://packagist.org/packages/clue/stdio-react) +[![installs on Packagist](https://img.shields.io/packagist/dt/clue/stdio-react?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/stdio-react) Async, event-driven and UTF-8 aware console input & output (STDIN, STDOUT) for -truly interactive CLI applications, built on top of [ReactPHP](https://reactphp.org). +truly interactive CLI applications, built on top of [ReactPHP](https://reactphp.org/). You can use this library to build truly interactive and responsive command line (CLI) applications, that immediately react when the user types in @@ -18,18 +18,18 @@ without requiring any extensions or special installation. * [Support us](#support-us) * [Quickstart example](#quickstart-example) * [Usage](#usage) - * [Stdio](#stdio) - * [Output](#output) - * [Input](#input) - * [Prompt](#prompt) - * [Echo](#echo) - * [Input buffer](#input-buffer) - * [Cursor](#cursor) - * [History](#history) - * [Autocomplete](#autocomplete) - * [Keys](#keys) - * [Bell](#bell) - * [Readline](#readline) + * [Stdio](#stdio) + * [Output](#output) + * [Input](#input) + * [Prompt](#prompt) + * [Echo](#echo) + * [Input buffer](#input-buffer) + * [Cursor](#cursor) + * [History](#history) + * [Autocomplete](#autocomplete) + * [Keys](#keys) + * [Bell](#bell) + * [~~Readline~~](#readline) * [Pitfalls](#pitfalls) * [Install](#install) * [Tests](#tests) @@ -570,7 +570,9 @@ enable or disable emitting the BELL signal when using a disabled function: $stdio->setBell(false); ``` -### Readline +### ~~Readline~~ + +> Deprecated since v2.3.0, see [`Stdio`](#stdio) instead. The deprecated `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 @@ -633,7 +635,7 @@ ob_start(function ($chunk) use ($stdio) { ## Install -The recommended way to install this library is [through Composer](https://getcomposer.org). +The recommended way to install this library is [through Composer](https://getcomposer.org/). [New to Composer?](https://getcomposer.org/doc/00-intro.md) This project follows [SemVer](https://semver.org/). @@ -648,7 +650,7 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. -It's *highly recommended to use PHP 7+* for this project. +It's *highly recommended to use the latest supported PHP version* for this project. Internally, it will use the `ext-mbstring` to count and measure string sizes. If this extension is missing, then this library will use a slighty slower Regex @@ -663,22 +665,19 @@ Input line editing is handled entirely within this library and does not rely on Installing `ext-readline` is entirely optional. Note that *Microsoft Windows is not supported*. -Due to platform inconsistencies, PHP does not provide support for reading from -standard console input without blocking. +Due to platform constraints, PHP does not provide support for reading from +standard console input without blocking on Windows. Unfortunately, until the underlying PHP feature request is implemented (which is unlikely to happen any time soon), there's little we can do in this library. -A work-around for this remains unknown. -Your only option would be to entirely -[disable interactive input for Microsoft Windows](https://github.com/clue/psocksd/commit/c2f2f90ffc8ebf8233839ba2f3553f2698930125). -However this package does work on [`Windows Subsystem for Linux`](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) -(or WSL) without issues. We suggest [installing WSL](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) +However, this package does work on Windows Subsystem for Linux (or WSL) without +issues. We suggest [installing WSL](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) when you want to run this package on Windows. See also [#18](https://github.com/clue/reactphp-stdio/issues/18) for more details. ## Tests To run the test suite, you first need to clone this repo and then install all -dependencies [through Composer](https://getcomposer.org): +dependencies [through Composer](https://getcomposer.org/): ```bash $ composer install @@ -687,7 +686,7 @@ $ composer install To run the test suite, go to the project root and run: ```bash -$ php vendor/bin/phpunit +$ vendor/bin/phpunit ``` ## License diff --git a/src/Readline.php b/src/Readline.php index 3f294e5..1a82cae 100644 --- a/src/Readline.php +++ b/src/Readline.php @@ -11,7 +11,7 @@ use React\Stream\WritableStreamInterface; /** - * @deprecated use Stdio instead + * @deprecated 2.3.0 Use `Stdio` instead * @see Stdio */ class Readline extends EventEmitter implements ReadableStreamInterface