vtparser 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d622edd5fbb0b4f47cb9831699c466aeabc3da9c6bed99370cc7d99d169c8c02
-  data.tar.gz: 33eccc5b843d8c5d734a06d5b2b3d389462c23ea568bf9456ed55a38d6f1a50a
+  metadata.gz: b142e3d52113ff288e56ef70f3a948e71233e3dbf6dd52078c168b205c0f5c69
+  data.tar.gz: 5a76607662cc257ad2b963d2ea8d52d86c3f7e1e5176e9b289966c611d649cb0
 SHA512:
-  metadata.gz: 0e5c6dd30582e24e0ad63b142446280b1be31d51cbae543b78c0019bf626ce2d477ea7bf002ab3707c7dd8056df886d33304eaa2a9509c30a9cac7ac6148e4b9
-  data.tar.gz: ab1f60a0cdd8e079274bb8a7d6a285287b81a3fe1304462086ccdb71910fe09451faadaa4f3ce8935b6a63fdc579a856e069558e7183c8a7c659924e7ad32417
+  metadata.gz: e2861798a37ed651916d3bdd2c5a8c5e990ffc66a92c1e2b006bcfd75fe80e38288af7ca1118681a805573d2b9fb87f01bd1842f6e5232d7e599abc61d0c7255
+  data.tar.gz: 2f1b3fa73f48e839c818c0d433d2d42edc9caa1a9afff6eb4ea6e8e13fd0453405cf364a404b9605346e47a8a625f3c7bd38babe4c9434b629714aca8d331e9b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2024-10-03
+
+- Add keyevent handling
+
 ## [0.1.0] - 2024-10-01
 
 - Initial release

data/README.md

@@ -1,6 +1,10 @@
 # VT 100 Parser Gem
 
-This gem is a parser for VT100 terminal escape sequences. It is based on the C code from https://github.com/haberman/vtparse/.
+This gem is a parser for VT100 terminal escape sequences. It is based on the C code from https://github.com/haberman/vtparse/ and implements the statemachine from https://www.vt100.net/emu/dec_ansi_parser.
+
+The purpose of this Gem is to have a relatively easy way to filter/modify the output of child/sub-processes (for instance launched via `PTY::spawn`) which use animation or colors. 
+
+Uses keyboard mapping logic from https://github.com/vidarh/keyboard_map/
 
 ## Background on VT100 Escape Sequences
 
@@ -22,26 +26,39 @@ gem install vtparser
 
 ## Basic Usage
 
-See the minimal example below and the [`examples`](https://github.com/coezbek/vtparser/examples) directory for more examples.
+See the minimal example below:
 
 ```ruby
-require 'vtparser'
+require_relative '../lib/vtparser'
 
 # Instantiate the parser with a block to handle actions
 parser = VTParser.new do |action, ch, intermediate_chars, params|
 
   # For this minimal example, we'll just turn everything back strings to print
-  print VtParser::to_ansi(action, ch, intermediate_chars, params)
+  print VTParser::to_ansi(action, ch, intermediate_chars, params)
 
 end
 
-# Sample input containing ANSI escape sequences
-input = "\e[31mHello, \e[1mWorld!\e[0m"
+# Sample input containing ANSI escape sequences (red text, bold text)
+input = "\e[31mHello, \e[1mWorld!\e[0m\n"
 
 # Parse the input
 parser.parse(input)
 ```
 
+Further samples in the [`examples directory`](https://github.com/coezbek/vtparser/tree/main/examples):
+
+- [`echo_keys.rb`](https://github.com/coezbek/vtparser/tree/main/examples/echo_keys.rb): Echoes the keys pressed by the user
+- [`indent_cli.rb`](https://github.com/coezbek/vtparser/tree/main/examples/indent_cli.rb): Indents the output of simple command line tools
+
+## Limitations
+
+- The parser is based on the implementation https://github.com/haberman/vtparse/ and based on a state machine which precedes Unicode. As such it does not have state transitions for Unicode characters. Rather, it will output them as `:ignore` actions. In case unicode characters are used inside escape sequences, the parser will likely not be able to handle them correctly.
+
+- The state machine does not expose all input characters to the implementation in relationship to the `DSC` (Device Control String) sequences. In particular the "Final Character" is swallowed by the statemachine from https://www.vt100.net/emu/dec_ansi_parser. To circumvent this limitation, I have modified the parser to expose the final character as intermediate_chars to the `:hook` action.
+
+- The parser only outputs full `actions`. So triggering an event for the `ESC` key doesn't work (as expected).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/echo_keys.rb

@@ -0,0 +1,27 @@
+require 'io/console'
+require_relative '../lib/vtparser'
+
+#
+# Example for how to switch to raw mode to output infos about each keypress
+#
+STDIN.raw do |io|
+
+  parser = VTParser.new do |action, ch, intermediate_chars, params|
+
+    puts "  New VTParser action: #{action}, ch: #{ch.inspect}, ch0x: #{ch.ord.to_s(16)}, intermediate_chars: #{intermediate_chars}, params: #{params}\r\n"
+    
+    parser.to_key(action, ch, intermediate_chars, params) do |event|
+
+      puts "    Keyevent: #{event.to_sym.inspect} #{event.inspect}\r\n"
+      exit(1) if event.to_sym == :ctrl_c
+    
+    end
+  end
+
+  loop do
+    ch = $stdin.getch
+    
+    puts "Getch: #{ch.inspect}\r\n"
+    parser.parse ch
+  end
+end

data/examples/indent_cli.rb

@@ -4,6 +4,19 @@ require 'rainbow/refinement' # for colorizing output
 using Rainbow
 require_relative '../lib/vtparser'
 
+#
+# 'indent_cli.rb' - Example for vtparser
+#
+# This example demonstrates how to use the VTParser to indent the output of simple (!) tty programs 
+# with colorized or animated output.
+#
+# Run with `ruby indent_cli.rb <command>`` where <command> is the command you want to run.
+#
+# Two simple examples are included:
+# - A simple spinner animation is included in `examples/spinner.rb`: `ruby indent_cli.rb 'ruby spinner.rb'`
+# - A simple progress bar animation is included in `examples/progress.rb`: `ruby indent_cli.rb 'ruby progress.rb'`
+#
+
 # Get the command from ARGV
 command = ARGV.join(' ')
 if command.empty?
@@ -12,13 +25,22 @@ if command.empty?
 end
 
 line_indent = '   ▐  '.yellow
+line_indent_length = 6
+
+#
+# Use VTParser to process the VT100 escape sequences outputted by nested program and prepend the line_indent text.
+#
 first_line = true
 parser = VTParser.new do |action, ch, intermediate_chars, params|
   print line_indent if first_line
   first_line = false
 
+  if $DEBUG && (action != :print || !(ch =~ /\P{Cc}/))
+    puts "action: #{action}, ch: #{ch.inspect}, ch0x: 0x#{ "%02x" % ch.ord}, intermediate_chars: #{intermediate_chars}, params: #{params}"
+  end
   to_output = VTParser::to_ansi(action, ch, intermediate_chars, params)
 
+  # Handle newlines, carriage returns, and cursor movement 
   case action
   when :print, :execute, :put, :osc_put
     if ch == "\n" || ch == "\r"
@@ -27,16 +49,13 @@ parser = VTParser.new do |action, ch, intermediate_chars, params|
       next
     end
   when :csi_dispatch
-    if to_output == "\e[2K"
+    if to_output == "\e[2K" # Clear line
       print "\e[2K"
       print line_indent
       next
     else
-      if ch == 'G'
-        # puts "to_output: #{to_output.inspect} action: #{action} ch: #{ch.inspect}"
-        # && parser.params.size == 1
-        print "\e[#{parser.params[0] + 6}G"
-
+      if ch == 'G' # Cursor movement to column
+        print "\e[#{parser.params[0] + line_indent_length}G"
         next
       end
     end
@@ -45,9 +64,13 @@ parser = VTParser.new do |action, ch, intermediate_chars, params|
   print to_output
 end
 
+#
+# Spawn the given command using PTY::spawn, and connect pipes.
+#
 begin
   PTY.spawn(command) do |stdout_and_stderr, stdin, pid|
 
+    # Start separate thread to pipe stdin to the child process
     Thread.new do     
       while pid != nil
         stdin.write(STDIN.readpartial(1024)) # Requires user to press enter!
@@ -57,8 +80,12 @@ begin
       exit(0)
     end
 
+    # Pipe stdout and stderr to the parser
     begin
-      stdout_and_stderr.winsize = $stdout.winsize
+      # Ensure the child process has the proper window size, because 
+      #  - tools such as yarn use it to identify tty mode
+      #  - some tools use it to determine the width of the terminal for formatting
+      stdout_and_stderr.winsize = [$stdout.winsize.first, $stdout.winsize.last - line_indent_length]
 
       stdout_and_stderr.each_char do |char|
 
@@ -73,7 +100,7 @@ begin
     Process.wait(pid)
     pid = nil
     exit_status = $?.exitstatus
-    result = exit_status == 0
+    # result = exit_status == 0
 
     # Clear the line, reset the cursor to the start of the line
     print "\e[2K\e[1G"

data/examples/minimal.rb

@@ -0,0 +1,15 @@
+require_relative '../lib/vtparser'
+
+# Instantiate the parser with a block to handle actions
+parser = VTParser.new do |action, ch, intermediate_chars, params|
+
+  # For this minimal example, we'll just turn everything back strings to print
+  print VTParser::to_ansi(action, ch, intermediate_chars, params)
+
+end
+
+# Sample input containing ANSI escape sequences (red text, bold text)
+input = "\e[31mHello, \e[1mWorld!\e[0m\n"
+
+# Parse the input
+parser.parse(input)

data/examples/progress.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+#
+# Helper script to be used to demonstrate `indent_cli.rb`. It displays a full-width animated progress bar.
+# 
+
+require 'ruby-progressbar'
+
+loop do
+  progressbar = ProgressBar.create
+  99.times { 
+    progressbar.increment 
+    sleep 0.02
+  }
+  print "\r"
+end

data/examples/spinner.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+#
+# Helper script to be used to demonstrate `indent_cli.rb`
+# 
+
+# See: https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
+frames = [
+  "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"
+]
+interval = 0.08 # 80 milliseconds
+
+# Infinite loop to display the animation until interrupted
+loop do
+  frames.each do |frame|
+    print "\r  #{frame}  " # "\r" moves the cursor back to the start of the line
+    sleep(interval)
+  end
+end

data/lib/vtparser/keymap.rb

@@ -0,0 +1,177 @@
+require 'set'
+
+#
+# Logic taken from vidarh/keyboard_map gem
+#
+# https://github.com/vidarh/keyboard_map
+#
+# See examples/keymap.rb for usage
+#
+
+class KeyEvent
+  attr_reader :modifiers, :key, :args
+
+  def initialize(key, *modifiers, args: nil)
+    @key = key
+    @args = args
+    @modifiers = modifiers.map(&:to_sym).to_set
+  end
+
+  def to_s
+    (modifiers.to_a.sort << key).join('_')
+  end
+
+  def to_sym
+    to_s.to_sym
+  end
+
+  def ==(other)
+    case other
+    when KeyEvent
+      self.modifiers == other.modifiers && self.key == other.key
+    when Symbol
+      self.to_sym == other
+    else
+      self.to_s == other
+    end
+  end
+end
+
+module Keymap
+
+  SINGLE_KEY_EVENT = {
+    "\t" => :tab,
+    "\r" => :enter,
+    "\n" => :enter,
+    "\u007F" => :backspace
+  }.freeze
+
+  CSI_BASIC_MAP = {
+    "A" => :up,
+    "B" => :down,
+    "C" => :right,
+    "D" => :left,
+    "E" => :keypad_5,
+    "F" => :end,
+    "H" => :home,
+  }.freeze
+
+  CSI_TILDE_MAP = {
+    "1"  => :home,
+    "2"  => :insert,
+    "3"  => :delete,
+    "4"  => :end,
+    "5"  => :page_up,
+    "6"  => :page_down,
+    "15" => :f5,
+    "17" => :f6,
+    "18" => :f7,
+    "19" => :f8,
+    "20" => :f9,
+    "21" => :f10,
+    "23" => :f11,
+    "24" => :f12,
+  }.freeze
+
+  SS3_KEY_MAP = {
+    "P" => :f1,
+    "Q" => :f2,
+    "R" => :f3,
+    "S" => :f4,
+  }.freeze
+  
+  def map_modifiers(mod)
+    return [] if mod.nil? || mod < 2
+    modifiers = []
+    mod = mod - 1  # Subtract 1 to align with modifier bits
+    modifiers << :shift if mod & 1 != 0
+    modifiers << :alt   if mod & 2 != 0
+    modifiers << :ctrl  if mod & 4 != 0
+    modifiers
+  end
+
+  def to_key(action, ch, intermediate_chars, params, &block)
+
+    case action
+    when :execute, :print, :ignore
+      # Control characters (e.g., Ctrl+C)
+      key = map_control_character(ch)
+      yield key if key
+    #when :print, :ignore
+      # Regular printable characters
+      #yield KeyboardEvent.new(ch)
+    when :esc_dispatch
+      # ESC sequences without intermediates
+      if intermediate_chars == ''
+        key = process_esc_sequence(ch)
+        yield key if key
+      else
+        # Handle other ESC sequences if necessary
+      end
+    when :csi_dispatch
+      key = process_csi_sequence(params, intermediate_chars, ch)
+      yield key if key
+    when :collect, :param, :clear
+      # Handled internally; no action needed here
+    else
+      # Handle other actions if necessary
+    end
+  end
+
+  def map_control_character(ch)
+    if SINGLE_KEY_EVENT.key?(ch)
+      return KeyboardEvent.new(SINGLE_KEY_EVENT[ch])
+    elsif ch.ord.between?(0x01, 0x1A)
+      # Ctrl+A to Ctrl+Z
+      key = (ch.ord + 96).chr
+      return KeyboardEvent.new(key, :ctrl)
+    else
+      return KeyboardEvent.new(ch)
+    end
+  end
+
+  def process_esc_sequence(final_char)
+    case final_char
+    when 'Z'
+      # Shift+Tab
+      return KeyboardEvent.new(:tab, :shift)
+    when "\e"
+      # Double ESC
+      return KeyboardEvent.new(:esc)
+    else
+      # Meta key (Alt) combinations
+      if final_char.ord.between?(0x20, 0x7E)
+        return KeyboardEvent.new(final_char, :meta)
+      else
+        # Handle other ESC sequences if necessary
+      end
+    end
+  end
+
+  def process_csi_sequence(params, intermediate_chars, final_char)
+    key = nil
+    modifiers = []
+    params = params.map(&:to_i)
+
+    if intermediate_chars == ''
+      if final_char == '~'
+        # Sequences like ESC [ 1 ~
+        key = CSI_TILDE_MAP[params[0].to_s]
+        modifiers = map_modifiers(params[1]) if params.size > 1
+      else
+        # Sequences like ESC [ A
+        key = CSI_BASIC_MAP[final_char]
+        modifiers = map_modifiers(params[0]) if params.size > 0
+      end
+    else
+      # Handle intermediates if necessary
+    end
+
+    if key
+      return KeyboardEvent.new(key, *modifiers)
+    else
+      # Handle unrecognized sequences
+    end
+  end
+
+end

data/lib/vtparser/parser.rb

@@ -1,6 +1,10 @@
+require_relative "keymap"
+
 class VTParser
   attr_reader :intermediate_chars, :params
 
+  include Keymap
+
   def initialize(&block)
     @callback = block
     @state = :GROUND

data/lib/vtparser/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vtparser
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vtparser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Christopher Oezbek
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-01 00:00:00.000000000 Z
+date: 2024-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-prompt
@@ -58,14 +58,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0.40'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0.40'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A pure Ruby VT100 parser that can be used to parse ANSI escape sequences.
 email:
 - c.oezbek@gmail.com
@@ -73,12 +87,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".bash_history"
 - CHANGELOG.md
 - README.md
 - Rakefile
+- examples/echo_keys.rb
 - examples/indent_cli.rb
+- examples/minimal.rb
+- examples/progress.rb
+- examples/spinner.rb
 - lib/vtparser.rb
+- lib/vtparser/keymap.rb
 - lib/vtparser/parser.rb
 - lib/vtparser/version.rb
 homepage: https://github.com/coezbek/vtparser
@@ -103,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.20
 signing_key: 
 specification_version: 4
 summary: Pure Ruby VT100 parser

data/.bash_history

@@ -1,117 +0,0 @@
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec
-rspec ./spec/vtparser_spec.rb:153
-rspec ./spec/vtparser_spec.rb:153
-rspec ./spec/vtparser_spec.rb:153
-rspec ./spec/vtparser_spec.rb:153
-rspec ./spec/vtparser_spec.rb:153
-rspec ./spec/vtparser_spec.rb:153
-rspec
-rspec
-rspec
-rspec ./spec/vtparser_spec.rb:37
-rspec ./spec/vtparser_spec.rb:37
-rspec
-rspec
-rspec       expect(output).to eq(input)
-rspec ./spec/vtparser_spec.rb:156
-rspec ./spec/vtparser_spec.rb:156
-rspec ./spec/vtparser_spec.rb:156
-rspec ./spec/vtparser_spec.rb:156
-rspec 
-rspec 
-D
-rspec ./spec/vtparser_spec.rb
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb:137 
-rspec ./spec/vtparser_spec.rb
-rspec ./spec/vtparser_spec.rb
-rspec ./spec/vtparser_spec.rb
-bundle
-rspec ./spec/vtparser_spec.rb
-rspec ./spec/vtparser_spec.rb
-ruby lib/vtparser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-bundle
-bundle
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-irb
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'yarn add --dev esbuild from "."'
-ruby lib/vtparser/parser.rb 'joe'
-joe
-ruby lib/vtparser/parser.rb 'vim'
-vim
-ruby example/indent_cli.rb 'vim'
-ruby examples/indent_cli.rb 'vim'
-ruby examples/indent_cli.rb 'vim'
-ruby examples/indent_cli.rb 'vim'
-ruby examples/indent_cli.rb 'joe'
-ruby examples/indent_cli.rb 'joe'
-ruby examples/indent_cli.rb 'joe'
-lsss
-less
-less README.md 
-ls
-exit
-ls
-ruby examples/indent_cli.rb 'less'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-less README.md
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/indent_cli.rb 'less README.md'
-ruby examples/test.rb 
-kkllllijjaaa
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/test.rb 
-ruby examples/indent_cli.rb
-ruby examples/indent_cli.rb 'bundle gem test17'
-ruby examples/indent_cli.rb 'bundle gem test18'