Debian Codegraph @

vendor/clue/term-react/README.md

raw
1 # clue/reactphp-term
2
3 [![CI status](https://github.com/clue/reactphp-term/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/reactphp-term/actions)
4 [![installs on Packagist](https://img.shields.io/packagist/dt/clue/term-react?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/term-react)
5
6 Streaming terminal emulator, built on top of [ReactPHP](https://reactphp.org/).
7
8 **Table of Contents**
9
10 * [Support us](#support-us)
11 * [Usage](#usage)
12 * [ControlCodeParser](#controlcodeparser)
13 * [Install](#install)
14 * [Tests](#tests)
15 * [License](#license)
16 * [More](#more)
17
18 ## Support us
19
20 We invest a lot of time developing, maintaining and updating our awesome
21 open-source projects. You can help us sustain this high-quality of our work by
22 [becoming a sponsor on GitHub](https://github.com/sponsors/clue). Sponsors get
23 numerous benefits in return, see our [sponsoring page](https://github.com/sponsors/clue)
24 for details.
25
26 Let's take these projects to the next level together! 🚀
27
28 ## Usage
29
30 ### ControlCodeParser
31
32 The `ControlCodeParser(ReadableStreamInterface $input)` class can be used to
33 parse any control code byte sequences (ANSI / VT100) when reading from an input stream and it
34 only returns its plain data stream.
35 It wraps a given `ReadableStreamInterface` and exposes its plain data through
36 the same interface.
37
38 ```php
39 $stdin = new React\Stream\ReadableResourceStream(STDIN);
40
41 $stream = new ControlCodeParser($stdin);
42
43 $stream->on('data', function ($chunk) {
44 var_dump($chunk);
45 });
46 ```
47
48 As such, you can be sure the resulting `data` events never include any control
49 code byte sequences and it can be processed like a normal plain data stream.
50
51 React's streams emit chunks of data strings and make no assumption about any
52 byte sequences.
53 These chunks do not necessarily represent complete control code byte sequences,
54 as a sequence may be broken up into multiple chunks.
55 This class reassembles these sequences by buffering incomplete ones.
56
57 The following [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set)
58 are supported as defined in [ISO/IEC 2022](https://en.wikipedia.org/wiki/ISO/IEC_2022):
59
60 * [CSI (Control Sequence Introducer)](https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes)
61 is one of the most common forms of control code sequences.
62 For example, CSI is used to print colored console output, also known as
63 "ANSI color codes" or the more technical term
64 [SGR (Select Graphic Rendition)](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics).
65 CSI codes also appear on `STDIN`, for example when the user hits special keys,
66 such as the cursor, `HOME`, `END` etc. keys.
67
68 * OSC (Operating System Command)
69 is another common form of control code sequences.
70 For example, OSC is used to change the window title or window icon.
71
72 * APC (Application Program-Control)
73
74 * DPS (Device-Control string)
75
76 * PM (Privacy Message)
77
78 Each code sequence gets emitted with a dedicated event with its raw byte sequence:
79
80 ```php
81 $stream->on('csi', function ($sequence) {
82 if ($sequence === "\x1B[A") {
83 echo 'cursor UP pressed';
84 } else if ($sequence === "\x1B[B") {
85 echo 'cursor DOWN pressed';
86 }
87 });
88
89 $stream->on('osc', function ($sequence) { … });
90 $stream->on('apc', function ($sequence) { … });
91 $stream->on('dps', function ($sequence) { … });
92 $stream->on('pm', function ($sequence) { … });
93 ```
94
95 Other lesser known [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set)
96 not listed above are supported by just emitting their 2-byte sequence.
97 Each generic C1 code gets emitted as an `c1` event with its raw 2-byte sequence:
98
99 ```php
100 $stream->on('c1', function ($sequence) { … });
101 ```
102
103 All other [C0 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C0_.28ASCII_and_derivatives.29),
104 also known as [ASCII control codes](https://en.wikipedia.org/wiki/ASCII#ASCII_control_code_chart),
105 are supported by just emitting their single-byte value.
106 Each generic C0 code gets emitted as an `c0` event with its raw single-byte value:
107
108 ```php
109 $stream->on('c0', function ($code) {
110 if ($code === "\n") {
111 echo 'ENTER pressed';
112 }
113 });
114 ```
115
116 ## Install
117
118 The recommended way to install this library is [through Composer](https://getcomposer.org/).
119 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
120
121 This project follows [SemVer](https://semver.org/).
122 This will install the latest supported version:
123
124 ```bash
125 composer require clue/term-react:^1.4
126 ```
127
128 See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
129
130 This project aims to run on any platform and thus does not require any PHP
131 extensions and supports running on legacy PHP 5.3 through current PHP 8+ and
132 HHVM.
133 It's *highly recommended to use the latest supported PHP version* for this project.
134
135 ## Tests
136
137 To run the test suite, you first need to clone this repo and then install all
138 dependencies [through Composer](https://getcomposer.org/):
139
140 ```bash
141 composer install
142 ```
143
144 To run the test suite, go to the project root and run:
145
146 ```bash
147 vendor/bin/phpunit
148 ```
149
150 ## License
151
152 This project is released under the permissive [MIT license](LICENSE).
153
154 > Did you know that I offer custom development services and issuing invoices for
155 sponsorships of releases and for contributions? Contact me (@clue) for details.
156
157 ## More
158
159 * If you want to learn more about processing streams of data, refer to the documentation of
160 the underlying [react/stream](https://github.com/reactphp/stream) component.
161
162 * If you want to process UTF-8 encoded console input, you may
163 want to use [clue/reactphp-utf8](https://github.com/clue/reactphp-utf8) on the resulting
164 plain data stream.
165
166 * If you want to to display or inspect the control codes, you may
167 want to use either [clue/hexdump](https://github.com/clue/php-hexdump) or
168 [clue/caret-notation](https://github.com/clue/php-caret-notation) on the emitted
169 control byte sequences.
170
171 * If you want to process standard input and output (STDIN and STDOUT) from a TTY, you may
172 want to use [clue/reactphp-stdio](https://github.com/clue/reactphp-stdio) instead of
173 using this low-level library.