rcurses 6.0.2 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2c123f55e8e4f06030596e1d16aca219f068152bf5d723db7a7aac5d98f1b6d
-  data.tar.gz: 710f29dc036627434e650a7380c8ab8845c4fe075f185a70dfcc4274e84d3f36
+  metadata.gz: 5132248f03d0f62fed76d2f525b0a84bf512ba0454054623e4d8528b435d9f64
+  data.tar.gz: 11ab84d968557065955885eb27d188677889d78e5ee46acc1a62064bc9b27116
 SHA512:
-  metadata.gz: 75f5d56983cab919f679e84123bbe3287a05356fd3c3cfc93def62f0273a386638cf8ca692ffc384e1db00377d6aa75f27bbad355547543649dd82284ef6a661
-  data.tar.gz: e3bc08762e5fbed4f53149eab64b2543b0c6d145388b734037b65fa0eafc20887f4f71945725a5b1e5cf68b3a9b0cda3c5b6a4ea8215dbc853e5a10a5caca782
+  metadata.gz: 12c461a57d353bc5a7273de1a664676a95c2d9ef445096e08222b447b45a1b0b847e9cc1570e475046e24f49264cabb1ae9b9c1e2944e09639bd9b2c881e20b6
+  data.tar.gz: 8602247bbf7c6e6377349f68dc7c2f8ff422f28890886ad5772a5aa1f5b6aed7acd1dcee8d1a66afeb7cf563dc4da832dc3caf4225922e1ffa7d6591f9204d28

data/README.md

@@ -94,7 +94,7 @@ Method         | Description
 new/init       | Initializes a Pane with optional arguments `x, y, w, h, fg and bg`
 move(x,y)      | Move the pane by `x`and `y` (`mypane.move(-4,5)` will move the pane left four characters and five characters down)
 refresh        | Refreshes/redraws the Pane with content
-border_refresh | Refresh the Pane border only
+border_refresh | Refresh the Pane border only - **CRITICAL**: Use this after changing border property
 full_refresh   | Refreshes/redraws the Pane with content completely (without diff rendering)
 edit           | An editor for the Pane. When this is invoked, all existing font dressing is stripped and the user gets to edit the raw text. The user can add font effects similar to Markdown; Use an asterisk before and after text to be drawn in bold, text between forward-slashes become italic, and underline before and after text means the text will be underlined, a hash-sign before and after text makes the text reverse colored. You can also combine a whole set of dressings in this format: `<23,245,biurl\|Hello World!>` - this will make "Hello World!" print in the color 23 with the background color 245 (regardless of the Pane's fg/bg setting) in bold, italic, underlined, reversed colored and blinking. Hitting `ESC` while in edit mode will disregard the edits, while `Ctrl-S` will save the edits
 editline       | Used for one-line Panes. It will print the content of the property `prompt` and then the property `text` that can then be edited by the user. Hitting `ESC` will disregard the edits, while `ENTER` will save the edited text
@@ -242,6 +242,119 @@ end
 You can also pass a timeout to `getchr` with `getchr(time)` to wait for `time` number of seconds and returning `nil` if the user does not press a key.
 
 
+# Proper Initialization and Common Pitfalls
+
+## Critical: Proper Application Initialization
+
+When building TUI applications with rcurses, follow this exact initialization pattern to avoid blank/frozen screens:
+
+```ruby
+#!/usr/bin/env ruby
+require 'rcurses'
+require 'io/wait'  # CRITICAL for stdin flush
+
+class MyApp
+  include Rcurses
+  include Rcurses::Input
+  
+  def run
+    # 1. Initialize rcurses FIRST
+    Rcurses.init!
+    
+    # 2. Get terminal size
+    @h, @w = IO.console.winsize
+    
+    # 3. Create your panes
+    @pane_top = Pane.new(1, 1, @w, 1, 255, 235)
+    @pane_left = Pane.new(1, 3, @w/3, @h-4, 15, 0)
+    @pane_right = Pane.new(@w/3+2, 3, @w-@w/3-2, @h-4, 255, 0)
+    
+    # 4. Load initial data and render
+    load_data
+    render_all
+    
+    # 5. CRITICAL: Flush stdin before main loop
+    # This prevents cursor position requests from blocking initial render
+    $stdin.getc while $stdin.wait_readable(0)
+    
+    # 6. Main loop pattern
+    loop do
+      render_all           # Render first
+      chr = getchr         # Then get input
+      handle_input(chr)    # Then handle it
+      break if chr == 'q'
+    end
+  ensure
+    # Clean up
+    Cursor.show
+  end
+  
+  def render_all
+    # Use text= and refresh, NOT say for initial renders
+    @pane_top.text = "My Application"
+    @pane_top.refresh
+    
+    @pane_left.text = @content
+    @pane_left.refresh
+  end
+end
+```
+
+## Common Pitfalls and Solutions
+
+### 1. Blank Panes on Startup
+**Problem:** All panes appear blank until user input.  
+**Cause:** Terminal sends cursor position request (`\e[6n`) that blocks rendering.  
+**Solution:** Always flush stdin before main loop: `$stdin.getc while $stdin.wait_readable(0)`
+
+### 2. Using `say` vs `text=` and `refresh`
+**When to use `say`:**
+- For status messages and one-time updates
+- When you want to reset scroll position (ix = 0)
+
+**When to use `text=` and `refresh`:**
+- In render loops where you control scrolling
+- When you need to preserve scroll position
+
+```ruby
+# For render loops - preserves scroll
+@pane.text = content
+@pane.ix = saved_scroll_position  # Maintain scroll
+@pane.refresh
+
+# For status messages - resets scroll
+@pane.say("Processing...")
+```
+
+### 3. Double Rendering
+**Problem:** Calling both `say` and `refresh` causes double rendering.  
+**Solution:** `say` already calls refresh internally - don't call refresh after say.
+
+### 4. Missing require 'io/wait'
+**Problem:** `wait_readable` method not found.  
+**Solution:** Always include `require 'io/wait'` for stdin flush.
+
+### 5. Border Changes Not Visible
+**Problem:** Changing pane border property doesn't show visual changes.  
+**Cause:** Border changes require explicit refresh to be displayed.  
+**Solution:** Use `border_refresh` method after changing border property.
+
+```ruby
+# Wrong - border change not visible
+@pane.border = true
+
+# Correct - border change visible immediately  
+@pane.border = true
+@pane.border_refresh
+```
+
+## Reference Applications
+
+Study these applications for best practices:
+- [RTFM](https://github.com/isene/RTFM) - File manager with complex pane management
+- [GiTerm](https://github.com/isene/GiTerm) - Git interface with dynamic content
+- [T-REX](https://github.com/isene/T-REX) - Calculator with simpler UI
+
 # Example
 
 Try this in `irb`:

data/lib/rcurses.rb

@@ -5,7 +5,7 @@
 # Web_site:   http://isene.com/
 # Github:     https://github.com/isene/rcurses
 # License:    Public domain
-# Version:    6.0.0: Breaking change - no auto-init, apps must call Rcurses.init!
+# Version:    6.1.0: Added safe_gsub methods to prevent ANSI code corruption
 
 require 'io/console' # Basic gem for rcurses
 require 'io/wait'    # stdin handling

data/lib/string_extensions.rb

@@ -156,5 +156,55 @@ class String
 
     out
   end
+  
+  # Safely apply regex replacements without corrupting ANSI sequences
+  # This method temporarily removes ANSI codes, applies the regex, then restores them
+  def safe_gsub(pattern, replacement = nil, &block)
+    # Store all ANSI sequences and replace with placeholders
+    ansi_sequences = []
+    placeholder_text = self.gsub(/\e\[[0-9;]*m/) do |match|
+      ansi_sequences << match
+      "⟨ANSI#{ansi_sequences.length - 1}⟩"
+    end
+    
+    # Apply the regex to the placeholder text
+    result = if block_given?
+      placeholder_text.gsub(pattern, &block)
+    else
+      placeholder_text.gsub(pattern, replacement)
+    end
+    
+    # Restore ANSI sequences
+    ansi_sequences.each_with_index do |ansi, index|
+      result.gsub!("⟨ANSI#{index}⟩", ansi)
+    end
+    
+    result
+  end
+  
+  # Safe version of gsub! that modifies in place
+  def safe_gsub!(pattern, replacement = nil, &block)
+    result = safe_gsub(pattern, replacement, &block)
+    self.replace(result)
+  end
+  
+  # Check if string contains ANSI codes
+  def has_ansi?
+    !!(self =~ /\e\[[0-9;]*m/)
+  end
+  
+  # Get the visible length (without ANSI codes)
+  def visible_length
+    pure.length
+  end
+  
+  # Apply color only if not already colored
+  def safe_fg(color)
+    has_ansi? ? self : fg(color)
+  end
+  
+  def safe_bg(color)
+    has_ansi? ? self : bg(color)
+  end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rcurses
 version: !ruby/object:Gem::Version
-  version: 6.0.2
+  version: 6.1.0
 platform: ruby
 authors:
 - Geir Isene
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 2025-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clipboard