rcurses 6.0.2 → 6.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2c123f55e8e4f06030596e1d16aca219f068152bf5d723db7a7aac5d98f1b6d
-  data.tar.gz: 710f29dc036627434e650a7380c8ab8845c4fe075f185a70dfcc4274e84d3f36
+  metadata.gz: ce484ba636e927e6344a8bb0552c49aec18df5cf3d2ebcb1c80c1d3927da3005
+  data.tar.gz: 9565880d7a799a27f364e3ec543f69c5061db9e9951684b3747cad5380b5ce85
 SHA512:
-  metadata.gz: 75f5d56983cab919f679e84123bbe3287a05356fd3c3cfc93def62f0273a386638cf8ca692ffc384e1db00377d6aa75f27bbad355547543649dd82284ef6a661
-  data.tar.gz: e3bc08762e5fbed4f53149eab64b2543b0c6d145388b734037b65fa0eafc20887f4f71945725a5b1e5cf68b3a9b0cda3c5b6a4ea8215dbc853e5a10a5caca782
+  metadata.gz: b6406ba055a63fcd8b187920f4280931b046d651919b08e3792db6a09de8ef5d5383de853847cd44cebf579ccb71c8a7a19b2d147cf825579dca6c96113130b1
+  data.tar.gz: 5522b3932739d6b726bed53a9b349006f0c7ab44bd79038008ed1f4db2cde530d0fe95e6f38d25bbf627b03a2dea4e8dd10f89991761ea048c65eec79f5dd92c

data/README.md

@@ -10,14 +10,23 @@ Here's a somewhat simple example of a TUI program using rcurses: The [T-REX](htt
 
 And here's a much more involved example: The [RTFM](https://github.com/isene/RTFM) terminal file manager.
 
-# NOTE: Version 5.0.0 brings major improvements!
-- **Memory leak fixes** - Better memory management and history limits
-- **Terminal state protection** - Proper terminal restoration on crashes
-- **Enhanced Unicode support** - Better handling of CJK characters and emojis
-- **Error handling improvements** - More robust operation in edge cases
-- **Performance optimizations** - Maintains the speed of version 4.8.3
+# NOTE: Version 6.1.1 adds optional error logging!
+- **Error logging** - Set `RCURSES_ERROR_LOG=1` to log crashes to `/tmp/rcurses_errors_PID.log`
+- **Race-condition free** - Uses process-specific filenames to avoid conflicts
+- **Stack trace preservation** - Full backtraces logged even when screen is cleared
+- **Completely opt-in** - Zero impact unless explicitly enabled
 - **Full backward compatibility** - All existing applications work unchanged
 
+Previous improvements in 6.1.0:
+- **Safe regex substitution** - New `safe_gsub` methods prevent ANSI code corruption
+- **ANSI detection** - Check if strings contain ANSI codes with `has_ansi?`
+- **Visible length calculation** - Get true text length with `visible_length`
+- **Conditional coloring** - Apply colors only when needed with `safe_fg`/`safe_bg`
+
+Previous major improvements in 5.0.0:
+- Memory leak fixes, terminal state protection, enhanced Unicode support
+- Error handling improvements and performance optimizations
+
 Version 4.5 gave full RGB support in addition to 256-colors. Just write a color as a string - e.g. `"d533e0"` for a hexadecimal RGB color (or use the terminal 256 colors by supplying an integer in the range 0-255)
 
 # Why?
@@ -94,7 +103,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
@@ -129,12 +138,34 @@ pure           | Strip text of any "dressing" (example: with `text = "TEST".b`,
 clean_ansi     | Strip seemingly uncolored strings of ansi code (those that are enclosed in "\e[0m"
 shorten(n)     | Shorten the pure version of the string to 'n' characters, preserving any ANSI coding
 inject("chars",pos) | Inject "chars" at position 'pos' in the pure version of the string (if 'pos' is '-1', then append at end). Preserves any ANSI code
+safe_gsub(pattern, replacement) | Apply regex substitution without corrupting existing ANSI codes (example: `colored_text.safe_gsub(/\[([^\]]*)\]/) { |m| m.fg(46) }`)
+safe_gsub!(pattern, replacement) | In-place version of safe_gsub
+has_ansi?      | Check if string contains ANSI escape sequences (returns true/false)
+visible_length | Get the visible length of text (excluding ANSI codes)
+safe_fg(fg)    | Apply foreground color only if string doesn't already have ANSI codes
+safe_bg(bg)    | Apply background color only if string doesn't already have ANSI codes
 
 PS: Blink does not work in conjunction with setting a background color in urxvt. It does work in gnome-terminal. But the overall performance in urxvt as orders of magnitude better than gnome-terminal.
 
 # Cleaning up upon exit
 End a program with `Rcurses.clear_screen` to clear the screen for any rcurses residues.
 
+# Error Logging (New in 6.1.1)
+When applications using rcurses crash, stack traces are typically lost because rcurses clears the screen on exit. To debug crashes, you can now enable error logging:
+
+```bash
+RCURSES_ERROR_LOG=1 my_rcurses_app
+```
+
+This will create a detailed error log at `/tmp/rcurses_errors_PID.log` containing:
+- Full stack trace with line numbers
+- Error class and message
+- Process information (PID, program name, working directory)
+- Ruby and rcurses version information
+- Relevant environment variables
+
+Each process gets its own log file (using PID) to prevent race conditions when multiple rcurses applications are running simultaneously. The feature is completely opt-in and has zero performance impact when disabled.
+
 # module Cursor
 To use this module, first do `include Rcurses::Cursor`. Create a new cursor object with `mycursor = Rcurses::Cursor`. Then you can apply the following methods to `mycursor`:
 
@@ -242,6 +273,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.1: Added optional error logging with RCURSES_ERROR_LOG=1
 
 require 'io/console' # Basic gem for rcurses
 require 'io/wait'    # stdin handling
@@ -124,15 +124,18 @@ module Rcurses
     
     # Private: Display error information after terminal cleanup
     def display_error(error)
+      # Log error to file if RCURSES_ERROR_LOG is set
+      log_error_to_file(error) if ENV['RCURSES_ERROR_LOG'] == '1'
+
       # Only display if we're in a TTY and not in a test environment
       return unless $stdout.tty?
-      
+
       # Add some spacing and make the error very visible
       puts "\n\n\e[41;37m                    APPLICATION CRASHED                    \e[0m"
       puts "\e[31m═══════════════════════════════════════════════════════════\e[0m"
       puts "\e[33mError Type:\e[0m #{error.class}"
       puts "\e[33mMessage:\e[0m    #{error.message}"
-      
+
       # Show backtrace if debug mode is enabled
       if ENV['DEBUG'] || ENV['RCURSES_DEBUG']
         puts "\n\e[33mBacktrace:\e[0m"
@@ -142,11 +145,54 @@ module Rcurses
       else
         puts "\n\e[90mTip: Set DEBUG=1 or RCURSES_DEBUG=1 to see the full backtrace\e[0m"
       end
-      
+
       puts "\e[31m═══════════════════════════════════════════════════════════\e[0m"
       puts "\e[33mNote:\e[0m The application state above shows where the error occurred."
+
+      # Show log file location if logging is enabled
+      if ENV['RCURSES_ERROR_LOG'] == '1'
+        puts "\e[33mError logged to:\e[0m /tmp/rcurses_errors_#{Process.pid}.log"
+      end
       puts ""
     end
+
+    # Private: Log error details to a PID-specific file
+    def log_error_to_file(error)
+      return unless ENV['RCURSES_ERROR_LOG'] == '1'
+
+      log_file = "/tmp/rcurses_errors_#{Process.pid}.log"
+      timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S")
+
+      begin
+        File.open(log_file, "a") do |f|
+          f.puts "=" * 60
+          f.puts "RCURSES ERROR LOG - #{timestamp}"
+          f.puts "PID: #{Process.pid}"
+          f.puts "Program: #{$0}"
+          f.puts "Working Directory: #{Dir.pwd}"
+          f.puts "Ruby Version: #{RUBY_VERSION}"
+          f.puts "Rcurses Version: 6.1.1"
+          f.puts "=" * 60
+          f.puts "Error Class: #{error.class}"
+          f.puts "Error Message: #{error.message}"
+          f.puts
+          f.puts "Full Backtrace:"
+          error.backtrace.each_with_index do |line, i|
+            f.puts "  #{i}: #{line}"
+          end
+          f.puts
+          f.puts "Environment Variables:"
+          ENV.select { |k, v| k.start_with?('RCURSES') || k == 'DEBUG' }.each do |k, v|
+            f.puts "  #{k}=#{v}"
+          end
+          f.puts "=" * 60
+          f.puts
+        end
+      rescue => file_error
+        # Silently fail if we can't write to log file - don't interfere with main error display
+        # This prevents cascading errors that could hide the original problem
+      end
+    end
     
     # Public: Run a block with proper error handling and terminal cleanup
     # This ensures errors are displayed after terminal is restored

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.1
 platform: ruby
 authors:
 - Geir Isene
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 2025-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clipboard