Support parsing OSC sequences

Author: clue

README.md

@@ -52,6 +52,16 @@ $stream->on('csi', function ($sequence) {
 });
 ```
 
+Another common form of control code sequences is OSC (Operating System Command).
+For example, OSC is used to change the window title or window icon.
+Each OSC code gets emitted as an `osc` event with its raw byte sequence:
+
+```php
+$stream->on('osc', function ($sequence) {
+    // handle byte sequence
+});
+```
+
 ## Install
 
 The recommended way to install this library is [through Composer](https://getcomposer.org).

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "clue/term-react",
     "description": "Streaming terminal emulator, built on top of React PHP",
-    "keywords": ["terminal", "control codes", "xterm", "csi", "streaming", "ReactPHP"],
+    "keywords": ["terminal", "control codes", "xterm", "csi", "osc", "streaming", "ReactPHP"],
     "homepage": "https://github.com/clue/php-term-react",
     "license": "MIT",
     "authors": [

examples/stdin-codes.php

@@ -15,13 +15,16 @@
 $stdin = new Stream(STDIN, $loop);
 $parser = new ControlCodeParser($stdin);
 
-$parser->on('csi', function ($code) {
+$decoder = function ($code) {
     echo 'Code:';
     for ($i = 0; isset($code[$i]); ++$i) {
         echo sprintf(" %02X", ord($code[$i]));
     }
     echo PHP_EOL;
-});
+};
+
+$parser->on('csi', $decoder);
+$parser->on('osc', $decoder);
 
 $parser->on('data', function ($bytes) {
     echo 'Data: ' . $bytes . PHP_EOL;

src/ControlCodeParser.php

@@ -89,38 +89,59 @@ public function handleData($data)
             }
 
             // ESC is now at start of buffer
-
             // check following byte to determine type
             if (!isset($this->buffer[1])) {
                 // type currently unknown, wait for next data chunk
                 break;
             }
 
+            $found = false;
+
             if ($this->buffer[1] === '[') {
                 // followed by "[" means it's CSI
-            } else {
-                $data = substr($this->buffer, 0, 2);
-                $this->buffer = (string)substr($this->buffer, 2);
 
-                $this->emit('data', array($data));
-                continue;
-            }
+                // CSI is now at the start of the buffer, search final character
+                for ($i = 2; isset($this->buffer[$i]); ++$i) {
+                    $code = ord($this->buffer[$i]);
 
+                    // final character between \x40-\x7E
+                    if ($code >= 64 && $code <= 126) {
+                        $data = substr($this->buffer, 0, $i + 1);
+                        $this->buffer = (string)substr($this->buffer, $i + 1);
 
-            // CSI is now at the start of the buffer, search final character
-            $found = false;
-            for ($i = 2; isset($this->buffer[$i]); ++$i) {
-                $code = ord($this->buffer[$i]);
+                        $this->emit('csi', array($data));
+                        $found = true;
+                        break;
+                    }
+                }
+            } elseif ($this->buffer[1] === ']') {
+                // followed by "]" means it's OSC (Operating System Controls)
+
+                // terminated by ST or BEL (whichever comes first)
+                $st = strpos($this->buffer, "\x1B\\");
+                $bel = strpos($this->buffer, "\x07");
 
-                // final character between \x40-x7E
-                if ($code >= 64 && $code <= 126) {
-                    $data = substr($this->buffer, 0, $i + 1);
-                    $this->buffer = (string)substr($this->buffer, $i + 1);
+                if ($st !== false && ($bel === false || $bel > $st)) {
+                    // ST comes before BEL or no BEL found
+                    $data = substr($this->buffer, 0, $st + 2);
+                    $this->buffer = (string)substr($this->buffer, $st + 2);
 
-                    $this->emit('csi', array($data));
+                    $this->emit('osc', array($data));
+                    $found = true;
+                } elseif ($bel !== false) {
+                    // BEL comes before ST or no ST found
+                    $data = substr($this->buffer, 0, $bel + 1);
+                    $this->buffer = (string)substr($this->buffer, $bel + 1);
+
+                    $this->emit('osc', array($data));
                     $found = true;
-                    break;
                 }
+            } else {
+                $data = substr($this->buffer, 0, 2);
+                $this->buffer = (string)substr($this->buffer, 2);
+
+                $this->emit('data', array($data));
+                continue;
             }
 
             // no final character found => wait for next data chunk

tests/ControlCodeParserTest.php

@@ -108,9 +108,44 @@ public function testEmitsNonCsiAsData()
         });
         $this->parser->on('csi', $this->expectCallableNever());
 
-        $this->input->emit('data', array("hello\x1B]world"));
+        $this->input->emit('data', array("hello\x1B?world"));
 
-        $this->assertEquals("hello\x1B]world", $buffer);
+        $this->assertEquals("hello\x1B?world", $buffer);
+    }
+
+
+    public function testEmitsOscBelAsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('osc', $this->expectCallableOnceWith("\x1B]asd\x07"));
+
+        $this->input->emit('data', array("\x1B]asd\x07"));
+    }
+
+    public function testEmitsOscStAsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('osc', $this->expectCallableOnceWith("\x1B]asd\x1B\\"));
+
+        $this->input->emit('data', array("\x1B]asd\x1B\\"));
+    }
+
+    public function testEmitsChunkedStartOscAsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('osc', $this->expectCallableOnceWith("\x1B]asd\x07"));
+
+        $this->input->emit('data', array("\x1B"));
+        $this->input->emit('data', array("]asd\x07"));
+    }
+
+    public function testEmitsChunkedMiddleOscAsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('osc', $this->expectCallableOnceWith("\x1B]asd\x07"));
+
+        $this->input->emit('data', array("\x1B]as"));
+        $this->input->emit('data', array("d\x07"));
     }
 
     public function testClosingInputWillCloseParser()