Support parsing APC, DPS, PM and other generic C1 sequences

Author: clue

README.md

@@ -33,14 +33,28 @@ These chunks do not necessarily represent complete control code byte sequences,
 as a sequence may be broken up into multiple chunks.
 This class reassembles these sequences by buffering incomplete ones.
 
-One of the most common forms of control code sequences is
-[CSI (Control Sequence Introducer)](https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes).
-For example, CSI is used to print colored console output, also known as
-"ANSI color codes" or the more technical term
-[SGR (Select Graphic Rendition)](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics).
-CSI codes also appear on `STDIN`, for example when the user hits special keys,
-such as the cursor, `HOME`, `END` etc. keys.
-Each CSI code gets emitted as a `csi` event with its raw byte sequence:
+The following [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set)
+are supported as defined in [ISO/IEC 2022](https://en.wikipedia.org/wiki/ISO/IEC_2022):
+
+* [CSI (Control Sequence Introducer)](https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes)
+  is one of the most common forms of control code sequences.
+  For example, CSI is used to print colored console output, also known as
+  "ANSI color codes" or the more technical term
+  [SGR (Select Graphic Rendition)](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics).
+  CSI codes also appear on `STDIN`, for example when the user hits special keys,
+  such as the cursor, `HOME`, `END` etc. keys.
+
+* OSC (Operating System Command)
+  is another common form of control code sequences.
+  For example, OSC is used to change the window title or window icon.
+
+* APC (Application Program-Control)
+
+* DPS (Device-Control string)
+
+* PM (Privacy Message)
+
+Each code sequence gets emitted with a dedicated event with its raw byte sequence:
 
 ```php
 $stream->on('csi', function ($sequence) {
@@ -50,16 +64,19 @@ $stream->on('csi', function ($sequence) {
         echo 'cursor DOWN pressed';
     }
 });
+
+$stream->on('osc', function ($sequence) { … });
+$stream->on('apc', function ($sequence) { … });
+$stream->on('dps', function ($sequence) { … });
+$stream->on('pm', 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:
+Other lesser known [C1 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C1_set)
+not listed above are supported by just emitting their 2-byte sequence.
+Each generic C1 code gets emitted as an `c1` event with its raw 2-byte sequence:
 
 ```php
-$stream->on('osc', function ($sequence) {
-    // handle byte sequence
-});
+$stream->on('c1', function ($sequence) { … });
 ```
 
 ## Install

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", "osc", "streaming", "ReactPHP"],
+    "keywords": ["terminal", "control codes", "xterm", "csi", "osc", "apc", "dps", "pm", "c1", "streaming", "ReactPHP"],
     "homepage": "https://github.com/clue/php-term-react",
     "license": "MIT",
     "authors": [

src/ControlCodeParser.php

@@ -13,6 +13,34 @@ class ControlCodeParser extends EventEmitter implements ReadableStreamInterface
     private $closed = false;
     private $buffer = '';
 
+    /**
+     * we know about the following C1 types (7 bit only)
+     *
+     * followed by "[" means it's CSI (Control Sequence Introducer)
+     * followed by "]" means it's OSC (Operating System Controls)
+     * followed by "_" means it's APC (Application Program-Control)
+     * followed by "P" means it's DPS (Device-Control string)
+     * followed by "^" means it's PM (Privacy Message)
+     *
+     * Each of these will be parsed until the sequence ends and then emitted
+     * under their respective name.
+     *
+     * All other C1 types will be emitted under the "c1" name without any
+     * further processing.
+     *
+     * C1 types in 8 bit are currently not supported, as they require special
+     * care with regards to whether UTF-8 mode is enabled. So far this has
+     * turned out to be a non-issue because most terminal emulators *accept*
+     * boths formats, but usually *send* in 7 bit mode exclusively.
+     */
+    private $types = array(
+        '[' => 'csi',
+        ']' => 'osc',
+        '_' => 'apc',
+        'P' => 'dps',
+        '^' => 'pm',
+    );
+
     public function __construct(ReadableStreamInterface $input)
     {
         $this->input = $input;
@@ -95,11 +123,20 @@ public function handleData($data)
                 break;
             }
 
-            $found = false;
+            // if this is an unknown type, just emit as "c1" without further parsing
+            if (!isset($this->types[$this->buffer[1]])) {
+                $data = substr($this->buffer, 0, 2);
+                $this->buffer = (string)substr($this->buffer, 2);
 
-            if ($this->buffer[1] === '[') {
-                // followed by "[" means it's CSI
+                $this->emit('c1', array($data));
+                continue;
+            }
+
+            // this is known type, check for the sequence end
+            $type = $this->types[$this->buffer[1]];
+            $found = false;
 
+            if ($type === 'csi') {
                 // 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]);
@@ -109,39 +146,32 @@ public function handleData($data)
                         $data = substr($this->buffer, 0, $i + 1);
                         $this->buffer = (string)substr($this->buffer, $i + 1);
 
-                        $this->emit('csi', array($data));
+                        $this->emit($type, 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)
+            } else {
+                // all other types are terminated by ST
+                // only OSC can also be terminted by BEL (whichever comes first)
                 $st = strpos($this->buffer, "\x1B\\");
-                $bel = strpos($this->buffer, "\x07");
+                $bel = ($type === 'osc') ? strpos($this->buffer, "\x07") : false;
 
                 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('osc', array($data));
+                    $this->emit($type, 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));
+                    $this->emit($type, array($data));
                     $found = true;
                 }
-            } 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

@@ -100,20 +100,6 @@ public function testEmitsDataAndCsiAndData()
         $this->assertEquals('helloworld', $buffer);
     }
 
-    public function testEmitsNonCsiAsData()
-    {
-        $buffer = '';
-        $this->parser->on('data', function ($chunk) use (&$buffer) {
-            $buffer .= $chunk;
-        });
-        $this->parser->on('csi', $this->expectCallableNever());
-
-        $this->input->emit('data', array("hello\x1B?world"));
-
-        $this->assertEquals("hello\x1B?world", $buffer);
-    }
-
-
     public function testEmitsOscBelAsOneChunk()
     {
         $this->parser->on('data', $this->expectCallableNever());
@@ -148,6 +134,30 @@ public function testEmitsChunkedMiddleOscAsOneChunk()
         $this->input->emit('data', array("d\x07"));
     }
 
+    public function testEmitsDpsStAsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('dps', $this->expectCallableOnceWith("\x1BPasd\x1B\\"));
+
+        $this->input->emit('data', array("\x1BPasd\x1B\\"));
+    }
+
+    public function testDoesNotEmitDpsIfItDoesNotEndWithSt()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('dps', $this->expectCallableNever());
+
+        $this->input->emit('data', array("\x1BPasd\x07"));
+    }
+
+    public function testEmitsUnknownC1AsOneChunk()
+    {
+        $this->parser->on('data', $this->expectCallableNever());
+        $this->parser->on('c1', $this->expectCallableOnceWith("\x1B="));
+
+        $this->input->emit('data', array("\x1B="));
+    }
+
     public function testClosingInputWillCloseParser()
     {
         $this->parser->on('close', $this->expectCallableOnce());