tans-parser 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f88d3f3ba4bc87f81c46fb3168b660728f980e5fa97daf608ba9f68e35f2bdf
-  data.tar.gz: 5b535136d317e598098cca288e7f8f157f0d0d45b6974f437572860d5554cb14
+  metadata.gz: 4c7b3233b668eeef9d7240a8cddd5f8389cc62fdf3c641103472696daab956f4
+  data.tar.gz: 39391122997e84cde9b4313542a1f2071cc752f66d9577e1c008133359064223
 SHA512:
-  metadata.gz: 32f9a060a089b2d8771b249e5a548b1725498d6b1b1a101cc8cbd547a41939fc8683d93853c734a8eb3f7edcbce6e5cb0fc3af162207727b02ac5f8850e5a5b5
-  data.tar.gz: 34481b9990055c0ba0fdd4d972703cbcab3208360ad6e4877cc0953e3f9de91838095aa5e9f7c54b4e3e563820d5e1b752a3925883021fdda9b45dd0f882862d
+  metadata.gz: 6489e45f59dbb4f7e7375108bc4f6f881fab6989415b5d44d09337bbaa166edb43974c1f6ebf8f1af068637dc7ee8bd604e0e6f55c8ffc0268f5fe610a23ec3e
+  data.tar.gz: e485259b38989cc3f1953691113bc6f92ee6da125c9a0502f38f5550ca75703e0ec3919043f9297b9ee0611044701086b937cb88d2e32a8c5d7047ae6267c461

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 0.1.1
+
+- `TansParser::Element` — value object for recognized UI elements (role, text, position, size, colors)
+- `TansParser::Selector` — scans terminal state for recognized UI elements:
+  - Buttons (`[ OK ]`, `(Cancel)`, `<Submit>`)
+  - Checkboxes (`[x]`, `[*]`, `[ ]` at line starts)
+  - Dialogs (box-drawing character regions)
+  - Statusbars (bottom row with non-default background)
+  - Progress bars (`[####   ]`, `[====>  ]` patterns)
+- Query API: `get_by_text`, `get_by_role`, convenience accessors (`buttons`, `checkboxes`, `dialogs`, `statusbars`, `progress_bars`)
+- `Element#to_h` with nil-value exclusion via `.compact`
+- 36 new tests for selector and element, 100% line and branch coverage maintained
+
 ## 0.1.0
 
 - Initial release: ANSI escape sequence parser extracted from tui-td

data/README.md

@@ -1,9 +1,7 @@
-# tans-parser — Terminal ANSI State Utils
+# tans-parser
 
 Parse raw terminal output with ANSI escape sequences into structured, queryable data.
 
-Zero runtime dependencies. Ruby stdlib only.
-
 ## Installation
 
 Ruby 3.0+ required.
@@ -47,7 +45,7 @@ state.foreground_at(0, 0)  # => "red"
 state.background_at(0, 0)  # => "default"
 state.style_at(0, 0)       # => {bold: false, italic: false, underline: false}
 
-# AI-friendly JSON with highlights
+# JSON with highlights
 state.to_ai_json
 # => {size:, cursor:, text:, highlights:, summary:}
 ```
@@ -70,6 +68,40 @@ resolve_color("color82", nil)   # => [95, 255, 0]
 xterm_256(16)                   # => [0x00, 0x00, 0x00]
 ```
 
+### Element recognition
+
+```ruby
+state = TansParser::State.new(state_data)
+selector = TansParser::Selector.new(state)
+
+# Find UI elements by role
+selector.buttons      # => [Element, ...] — [ OK ], (Cancel), <Submit>
+selector.checkboxes   # => [Element, ...] — [x], [*], [ ] at line starts
+selector.dialogs      # => [Element, ...] — box-drawing character regions (┌─┐│└┘)
+selector.statusbars   # => [Element, ...] — bottom row with non-default background
+selector.progress_bars # => [Element, ...] — [####   ], [====>  ] patterns
+
+# Find by text or role
+selector.get_by_text("OK")       # partial match
+selector.get_by_role(:button)    # also accepts "button" (String)
+```
+
+Each `TansParser::Element` is a Struct:
+
+```ruby
+el = selector.buttons.first
+el.role    # => :button
+el.text    # => "OK"
+el.row     # => 1
+el.col     # => 2
+el.width   # => 4
+el.height  # => 1
+el.checked # => nil (für Checkboxen: true/false)
+el.fg      # => "default"
+el.bg      # => "default"
+el.to_h    # => {role: :button, text: "OK", row: 1, col: 2, ...}
+```
+
 ## Cell format
 
 Each cell is a Hash with these keys:

data/lib/tans-parser.rb

@@ -7,4 +7,6 @@ end
 require_relative "tans_parser/version"
 require_relative "tans_parser/ansi_parser"
 require_relative "tans_parser/ansi_utils"
+require_relative "tans_parser/element"
+require_relative "tans_parser/selector"
 require_relative "tans_parser/state"

data/lib/tans_parser/element.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TansParser
+  # Describes a recognized UI element on the terminal screen.
+  Element = Struct.new(
+    :role,
+    :text,
+    :row, :col,
+    :width, :height,
+    :checked,
+    :focused,
+    :fg, :bg,
+    keyword_init: true,
+  ) do
+    def to_h
+      {
+        role: role,
+        text: text,
+        row: row, col: col,
+        width: width, height: height,
+        checked: checked,
+        focused: focused,
+        fg: fg, bg: bg,
+      }.compact
+    end
+  end
+end

data/lib/tans_parser/selector.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module TansParser
+  # Scans terminal state for recognized UI elements.
+  #
+  #   selector = Selector.new(state)
+  #   selector.get_by_text("OK")       # => [Element, ...]
+  #   selector.get_by_role(:button)    # => [Element, ...]
+  #   selector.buttons                 # => [Element, ...]
+  #   selector.dialogs                 # => [Element, ...]
+  #
+  class Selector
+    TOP_LEFT_CORNERS = /[┌┏┎┍]/
+    BOTTOM_LEFT_CORNERS = %w[└ ┗ ┖ ┕ ╰ ╚].freeze
+    BOTTOM_RIGHT_CORNERS = %w[┘ ┛ ┚ ┙ ╯ ╝].freeze
+
+    attr_reader :state, :elements
+
+    def initialize(state)
+      @state = state.is_a?(State) ? state : State.new(state)
+      @elements = scan
+    end
+
+    # Find elements by visible text (partial match).
+    def get_by_text(text)
+      @elements.select { |e| e.text&.include?(text) }
+    end
+
+    # Find elements by role.
+    def get_by_role(role)
+      @elements.select { |e| e.role == role.to_sym }
+    end
+
+    # Convenience accessors
+    def buttons
+      get_by_role(:button)
+    end
+
+    def checkboxes
+      get_by_role(:checkbox)
+    end
+
+    def dialogs
+      get_by_role(:dialog)
+    end
+
+    def statusbars
+      get_by_role(:statusbar)
+    end
+
+    def progress_bars
+      get_by_role(:progress)
+    end
+
+    private
+
+    def grid
+      @state.grid
+    end
+
+    def scan
+      results = []
+      results.concat(detect_buttons)
+      results.concat(detect_checkboxes)
+      results.concat(detect_dialogs)
+      results.concat(detect_statusbars)
+      results.concat(detect_progress_bars)
+      results
+    end
+
+    # Detects buttons: [ OK ], (Cancel), <Submit>
+    # rubocop:disable Metrics/AbcSize
+    def detect_buttons
+      buttons = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        scan_match = line.enum_for(:scan, /\[([^\]]+)\]|\(([^)]+)\)|<([^>]+)>/)
+        scan_match.each do
+          text = (::Regexp.last_match(1) || ::Regexp.last_match(2) || ::Regexp.last_match(3)).to_s.strip
+          next if text.empty?
+
+          col = ::Regexp.last_match.begin(0)
+          buttons << Element.new(
+            role: :button,
+            text: text,
+            row: r, col: col,
+            width: ::Regexp.last_match[0].length, height: 1,
+            fg: row[col][:fg],
+            bg: row[col][:bg],
+          )
+        end
+      end
+      buttons
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Detects checkboxes: [x], [*], [ ] at start of lines
+    def detect_checkboxes
+      checkboxes = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        match = line.match(/^(\s*)\[([ xX*])\]\s+(.+)/)
+        next unless match
+
+        checked = match[2] != " "
+        label = match[3].strip
+        col = match.begin(3)
+        checkboxes << Element.new(
+          role: :checkbox,
+          text: label,
+          row: r, col: col,
+          width: label.length, height: 1,
+          checked: checked,
+        )
+      end
+      checkboxes
+    end
+
+    # Detects dialogs: regions enclosed by box-drawing characters
+    def detect_dialogs
+      dialogs = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        tl_idx = 0
+        while (tl_idx = line.index(TOP_LEFT_CORNERS, tl_idx))
+          width = dialog_top_width(line, tl_idx)
+          unless width
+            tl_idx += 1
+            next
+          end
+
+          bottom_r = dialog_bottom_row(tl_idx, width, r + 1)
+          if bottom_r
+            height = bottom_r - r + 1
+            text = extract_dialog_text(r + 1, tl_idx + 1, width - 2, height - 2)
+            dialogs << Element.new(
+              role: :dialog,
+              text: text,
+              row: r, col: tl_idx,
+              width: width, height: height,
+            )
+          end
+          tl_idx += 1
+        end
+      end
+      dialogs
+    end
+
+    # Returns the width of a dialog top border if valid, nil otherwise
+    def dialog_top_width(line, tl_idx)
+      top_row = line[tl_idx..]
+      tr_match = top_row.match(/^[┌┏┎┍]([─━]*)([┐┓┒┑])/)
+      return nil unless tr_match
+
+      tr_match[0].length
+    end
+
+    # Returns the row index of a matching bottom border, nil if not found
+    def dialog_bottom_row(tl_idx, width, start_row)
+      r = start_row
+      while r < grid.length
+        bottom_line = grid[r].map { |c| c[:char] }.join
+        bot_left = bottom_line[tl_idx]
+        if BOTTOM_LEFT_CORNERS.include?(bot_left) && bottom_line[tl_idx + width - 1]
+          bot_right = bottom_line[tl_idx + width - 1]
+          return r if BOTTOM_RIGHT_CORNERS.include?(bot_right)
+        end
+        r += 1
+      end
+      nil
+    end
+
+    # Extracts visible text from inside a dialog
+    def extract_dialog_text(start_row, start_col, inner_width, inner_height)
+      lines = []
+      (start_row...[start_row + inner_height, grid.length].min).each do |r|
+        row = grid[r]
+        slice = row[start_col, [inner_width, row.length - start_col].min]
+        line = slice.map { |c| c[:char] }.join.rstrip
+        lines << line unless line.empty?
+      end
+      lines.join(" ").strip
+    end
+
+    # Detects statusbar: bottom row with reversed/inverse colors
+    def detect_statusbars
+      bars = []
+      return bars if grid.empty?
+
+      last_row_idx = grid.length - 1
+      last_row = grid[last_row_idx]
+
+      non_default = last_row.reject { |c| c[:bg] == "default" }
+      return bars if non_default.length < 3
+
+      text = last_row.map { |c| c[:char] }.join.strip
+      return bars if text.empty?
+
+      bars << Element.new(
+        role: :statusbar,
+        text: text,
+        row: last_row_idx, col: 0,
+        width: last_row.length, height: 1,
+        bg: non_default.first[:bg],
+      )
+      bars
+    end
+
+    # Detects progress bars: [####   ] or [=====>  ] patterns
+    def detect_progress_bars
+      bars = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        match = line.match(/\[([#>=-]+)\s*\]/)
+        next unless match
+
+        filled = match[1]
+        total = match[0].length - 2
+        percent = (filled.length.to_f / total * 100).round
+        bars << Element.new(
+          role: :progress,
+          text: "#{percent}%",
+          row: r, col: ::Regexp.last_match.begin(0),
+          width: match[0].length, height: 1,
+          checked: percent == 100,
+        )
+      end
+      bars
+    end
+  end
+end

data/lib/tans_parser/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tans-parser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Haluk Durmus
@@ -124,7 +124,8 @@ dependencies:
 description: tans-parser parses raw terminal output with ANSI escape sequences into
   a structured grid representation with per-cell attributes (char, fg, bg, bold, italic,
   underline, blink). Includes a query API (State) for text search, color inspection,
-  and AI-friendly JSON output.
+  and JSON output, plus heuristic UI element recognition (Selector) for buttons, checkboxes,
+  dialogs, statusbars, and progress bars.
 email:
 - haluk_durmus@yahoo.de
 executables: []
@@ -137,6 +138,8 @@ files:
 - lib/tans-parser.rb
 - lib/tans_parser/ansi_parser.rb
 - lib/tans_parser/ansi_utils.rb
+- lib/tans_parser/element.rb
+- lib/tans_parser/selector.rb
 - lib/tans_parser/state.rb
 - lib/tans_parser/version.rb
 homepage: https://github.com/vurte/tans-parser
@@ -162,5 +165,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Terminal ANSI State Utils — parse ANSI terminal output into structured data
+summary: Parse ANSI terminal output into structured data with UI element recognition
 test_files: []