rcurses

KO | EN

gitlite — search

#javascript #react #ai #llm #go #machine-learning #rust #linux #docker #nodejs #java #kubernetes #ios #open-source

(★ 29)

An alternative curses library written in pure Ruby

rcurses 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# rcurses - An alternative curses library written in pure Ruby
 
![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/rcurses.svg)](https://badge.fury.io/rb/rcurses) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)
 
<img src="img/rcurses-logo.png" width="150" height="150">

Create curses applications for the terminal easier than ever.

Here's a somewhat simple example of a TUI program using rcurses: The [T-REX](https://github.com/isene/T-REX) calculator.

And here's a much more involved example: The [RTFM](https://github.com/isene/RTFM) terminal file manager.

# What's new in 6.2.0

- **Popup widget** - New `Rcurses::Popup` class for modal dialogs with auto-centering, border, scrolling, and built-in key handling (see Popup section below)
- **Built-in emoji picker** - Panes with `emoji = true` get a `Ctrl-E` shortcut in editline that opens an emoji overlay with category tabs, search, and cursor-positioned grid rendering
- **Pane color cache invalidation** - Changing `fg` or `bg` on a Pane now forces a full repaint automatically (no more stale diff-rendering artifacts)
- **Startup stdin flush** - `Rcurses.init!` now flushes pending stdin data (cursor position responses) to prevent first-keypress blocking
- **Pane update flag** - Set `pane.update = false` to skip rendering during batch operations
- **Wider ESC timeout** - Escape sequence detection timeout increased from 50ms to 150ms for better terminal compatibility
- **Unicode display_width fixes** - Improved handling of FE0F variation selectors, ZWJ sequences, and dingbat characters
- **Editline improvements** - Unicode-aware padding, content truncation, multiline paste joins all lines

Previous notable versions: 6.1.1 (error logging), 6.1.0 (safe ANSI methods), 6.0.0 (explicit init!), 5.0.0 (memory fixes), 4.5 (RGB colors)

# Why?
Having struggled with the venerable curses library and the ruby interface to it for many years, I finally got around to write an alternative - in pure Ruby.

# Design principles
Simple and with minimum of external dependencies.

# Installation
Simply run `gem install rcurses`.

To use this library do:
```
require 'rcurses'
```

# Features
* Create panes (with the colors and(or border), manipulate the panes and add content
* Dress up text (in panes or anywhere in the terminal) in bold, italic, underline, reverse color, blink and in any 256 terminal colors for foreground and background
* Use a simple editor to let users edit text in panes
* Left, right or center align text in panes
* Cursor movement around the terminal

# The elements
`rcurses` gives you the following elements:
* The class `Pane` to create and manilpulate panes/boxes
* Extensions to the class String to print text in various degrees of fancy and also strip any fanciness
* A module `Cursor` to give you cursor movements around the terminal
* A module `Rinput` providing the function `getchr` to capture a single character input from the user (much better than any Ruby built-ins)

# class Pane
To create a pane do something like this:
```
mypane = Rcurses::Pane.new(80, 30, 30, 10, 19, 229)
```
This will create a pane/box starting at terminal column/x 80 and row/y 30 with the width of 30 characters and a hight of 10 characters and with the foreground color 19 and background color 229 (from the 256 choices available)

The format for creating a pane is:
```
Rcurses::Pane.new(x, y, w, h, fg, bg)
```
You can drop the last two 256-color codes to create a pane with the defaults for your terminal.

By adding values for the terminal size in your program:
```
@max_h, @max_w = IO.console.winsize
```
...you can use these values to create proportinally sized panes. So, a hight value of "@max_h/2" is valid to create a pane with the height of half the terminal height (the integer corresponding to half the terminal height will then be accessible as the variable `h`). Use the variables `@max_h` for terminal height and `@max_w` for terminal width.

Avaliable properties/variables:

Property       | Description
---------------|---------------------------------------------------------------
x              | The x (column) position of the Pane
y              | The y (row) position of the Pane
w              | The width of the Pane
h              | The heigth of the Pane
fg             | Foreground color for the Pane
bg             | Background color for the Pane
border         | Draw border around the Pane (=true) or not (=false), default being false
scroll         | Whether to indicate more text to be shown above/below the Pane, default is true
scroll_fg      | Color for scroll indicators (∆/∇), defaults to pane fg color if nil
text           | The text/content of the Pane
ix             | The line number at the top of the Pane, starts at 0, the first line of text in the Pane
index          | An attribute that can be used to track the selected line/element in the pane
align          | Text alignment in the Pane: "l" = lefts aligned, "c" = center, "r" = right, with the default "l"
prompt         | The prompt to print at the beginning of a one-liner Pane used as an input box
moreup         | Set to true when there is more text above what is shown (top scroll bar i showing)
moredown       | Set to true when there is more text below what is shown (bottom scroll bar i showing)
update         | When false, refresh is a no-op (default: true). Useful during batch operations
emoji          | When true, Ctrl-E in editline opens the built-in emoji picker (default: false)
emoji_refresh  | Optional lambda/proc called after emoji picker closes, to redraw the UI

The methods for Pane:

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 - **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
clear          | Clears the pane
cleanup        | Cleans up pane memory (history, caches) - useful for memory management
say(text)      | Short form for setting panel.text, then doing a refresh of that panel
ask(prompt,text) | Short form of setting panel.prompt, then panel.text, doing a panel.editline and then returning panel.text
pagedown       | Scroll down one page height in the text (minus one line), but not longer than the length of the text
pageup         | Scroll up one page height in the text (minus one line)
linedown       | Scroll down one line in the text
lineup         | Scroll up one line in the text
bottom         | Scroll to the bottom of the text in the pane
top            | Scroll to the top of the text in the pane

# class Popup

A reusable popup overlay widget for modal dialogs, selection menus, and informational displays. Extends `Pane` with auto-centering, built-in scrolling, and keyboard handling.

```ruby
# Auto-centered popup with default size
popup = Rcurses::Popup.new(w: 50, h: 20)

# Explicit position
popup = Rcurses::Popup.new(x: 10, y: 5, w: 50, h: 20, fg: 255, bg: 236)
```

**Modal usage** (blocks until ESC or ENTER):
```ruby
result = popup.modal(content_string)
# Returns selected line index on ENTER, or nil on ESC
# Built-in: UP/DOWN/PgUP/PgDN/HOME/END for scrolling
```

**Custom key handling**:
```ruby
result = popup.modal(content) do |chr, index|
  case chr
  when 'd'
    delete_item(index)
    :dismiss        # Close popup
  when 'e'
    "edit:#{index}" # Return custom value
  end
end
```

**Manual control** (non-blocking):
```ruby
popup.show(content_string)
# ... your own input loop ...
popup.dismiss(refresh_panes: [pane1, pane2])  # Clears area, refreshes underlying panes
```

# Emoji Picker

Panes can opt in to a built-in emoji picker that opens with `Ctrl-E` during editline:

```ruby
pane.emoji = true                   # Enable Ctrl-E shortcut
pane.emoji_refresh = -> { render }  # Optional: redraw UI after picker closes
pane.editline                       # Ctrl-E now opens emoji overlay
```

The picker features category tabs (Tab/Shift-Tab), arrow navigation, search-by-keyword, and cursor-positioned grid rendering for pixel-perfect alignment regardless of Unicode width variations.

# class String extensions
Method extensions provided for the class String.

A color can either be an integer in the range 0-255 for the usual 256 colors in a terminal, or it can be a string representing RGB. So both of these are valid: `string.fg(219)` and `string.fg("4d22a0")`.

Method         | Description
---------------|---------------------------------------------------------------
fg(fg)         | Set text to be printed with the foreground color `fg` (example: `"TEST".fg(84)`)
bg(bg)         | Set text to be printed with the background color `bg` (example: `"TEST".bg("dd32a9")`)
fb(fg, bg)     | Set text to be printed with the foreground color `fg` and background color `bg` (example: `"TEST".fb(84,196)`)
bd             | Set text to be printed in bold (example: `"TEST".bd`)
it             | Set text to be printed in italic (example: `"TEST".it`)
ul             | Set text to be printed underlined (example: `"TEST".ul`)
l              | Set text to be printed blinking (example: `"TEST".l`)
rv             | Set text to be printed in reverse colors (example: `"TEST".rv`)
c(code)        | Use coded format like "TEST".c("204,45,bui") to print "TEST" in bold, underline italic, fg=204 and bg=45 (the format is `.c("fg,bg,biulr")`)
pure           | Strip text of any "dressing" (example: with `text = "TEST".bd`, you will have bold text in the variable `text`, then with `text.pure` it will show "uncoded" or pure text)
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`:

Method            | Description
------------------|---------------------------------------------------------------
save              | Save current position
restore           | Restore cursor position
pos               | Query cursor current position (example: `row,col = mycursor.pos`)
colget            | Query cursor current cursor col/x position (example: `row = mycursor.rowget`)
rowget            | Query cursor current cursor row/y position (example: `row = mycursor.rowget`)         
set(c = 1, r = 1) | Set the position of the cursor to row/y,col/x (example: `mycursor.set(row,col)`) (default = top row, first column)
col(c = 1)        | Cursor moves to the nth position horizontally in the current line (default = first column)
row(r = 1)        | Cursor moves to the nth position vertically in the current column (default = first/top row)
up(n = 1)         | Move cursor up by n (default is 1 character up)
down(n = 1)       | Move cursor down by n (default is 1 character down)
left(n = 1)       | Move cursor backward by n (default is one character)
right(n = 1)      | Move cursor forward by n (default is one character)
next_line         | Move cursor down to beginning of next line
prev_line         | Move cursor up to beginning of previous line
clear_char(n = 1) | Erase n characters from the current cursor position (default is one character)
clear_line        | Erase the entire current line and return to beginning of the line
clear_line_before | Erase from the beginning of the line up to and including the current cursor position
clear_line_after  | Erase from the current position (inclusive) to the end of the line
scroll_up         | Scroll display up one line
scroll_down       | Scroll display down one line
clear_screen_down | Clear screen down from current row
hide              | Hide the cursor
show              | Show cursor

# The function getchr
rcurses provides a vital extension to Ruby in reading characters entered by the user. This is especially needed for curses applications where readline inputs are required.
The function getchr is automatically included in your arsenal when you first do `include Rcurses::Input`.

Simply use `chr = getchr` in a program to read any character input by the user. The returning code (the content of `chr` in this example) could be any of the following:

Key pressed     | string returned
----------------|----------------------------------------------------------
`esc`           | "ESC"
`up`            | "UP"
`shift-up`      | "S-UP"
`ctrl-up`       | "C-UP"
`down`          | "DOWN"
`shift-down`    | "S-DOWN"
`ctrl-down`     | "C-DOWN"
`right`         | "RIGHT"
`shift-right`   | "S-RIGHT"
`ctrl-right`    | "C-RIGHT"
`left`          | "LEFT"
`shifth-left`   | "S-LEFT"
`ctrl-left`     | "C-LEFT"
`shift-tab`     | "S-TAB"
`insert`        | "INS"   
`ctrl-insert`   | "C-INS"
`del`           | "DEL"   
`ctrl-del`      | "C-DEL"
`pageup`        | "PgUP"  
`ctrl-pageup`   | "C-PgUP"
`pagedown`      | "PgDOWN"
`ctrl-pagedown` | "C-PgDOWN"
`home`          | "HOME"  
`ctrl-home`     | "C-HOME"
`end`           | "END"   
`ctrl-end`      | "C-END"
`backspace`     | "BACK"
`ctrl- `        | "C-SPACE"
`ctrl-h`        | "BACK"
`ctrl-a`        | "C-A"
`ctrl-b`        | "C-B"
`ctrl-c`        | "C-C"
`ctrl-d`        | "C-D"
`ctrl-e`        | "C-E"
`ctrl-f`        | "C-F"
`ctrl-g`        | "C-G"
`ctrl-i`        | "C-I"
`ctrl-j`        | "C-J"
`ctrl-k`        | "C-K"
`ctrl-l`        | "C-L"
`ctrl-m`        | "C-M"
`ctrl-n`        | "C-N"
`ctrl-o`        | "C-O"
`ctrl-p`        | "C-P"
`ctrl-q`        | "C-Q"
`ctrl-r`        | "C-R"
`ctrl-s`        | "C-S"
`ctrl-t`        | "C-T"
`ctrl-u`        | "C-U"
`ctrl-v`        | "C-V"
`ctrl-a`        | "WBACK"
`ctrl-x`        | "C-X"
`ctrl-y`        | "C-Y"
`ctrl-z`        | "C-Z"
`enter`         | "ENTER"
`tab`           | "TAB"
`F1` - `F12`    | "F1" - "F12"

Any other character enter will be returned (to `chr` in the example above).

In order to handle several character pased into STDIN by the user (and not only returned the first character only, your program should empty the STDIN like this:

```
while $stdin.ready?
  chr += $stdin.getc
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. String formatting methods renamed in 7.0.0
**Change:** In version 7.0.0, the short method names were renamed to avoid conflicts with Ruby built-ins: `.b` became `.bd` (bold), `.i` became `.it` (italic), `.u` became `.ul` (underline), `.r` became `.rv` (reverse). The old `.b` method conflicted with Ruby's built-in `String#b` which returns a binary-encoded copy of the string.
**Migration:** Replace `.b` with `.bd`, `.i` with `.it`, `.u` with `.ul`, `.r` with `.rv` in your code.

### 6. 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`:
```
require 'rcurses'
@max_h, @max_w = IO.console.winsize
mypane = Rcurses::Pane.new(@max_w/2, 30, 30, 10, 19, 229)
mypane.border = true
mypane.text = "Hello".it + " World!".bd.it + "\n \n" + "rcurses".rv + " " + "is cool".c("16,212")
mypane.refresh
mypane.edit
```
... and then try to add some bold text by enclosing it in '*' and italics by enclosing text in '/'. Then press 'ctrl-s' to save your edited text - and then type `mypane.refresh` to see the result.

And - try running the example file `rcurses_example.rb`.

# Version History

## v6.2.0
- New `Popup` class for modal dialogs with auto-centering, border, scrolling, and key handling
- Built-in emoji picker with category tabs, search, and cursor-positioned grid rendering
- Pane `fg`/`bg` setters now invalidate diff-rendering cache (fixes color change artifacts)
- `Rcurses.init!` flushes pending stdin data to prevent startup keypress blocking
- New pane attributes: `update` (skip rendering), `emoji` (enable Ctrl-E picker), `emoji_refresh`
- ESC sequence timeout widened from 50ms to 150ms for better terminal compatibility
- Unicode `display_width` fixes: FE0F/FE0E treated as zero-width, improved ZWJ promotion
- Editline: Unicode-aware padding, content truncation, multiline paste joins all lines

## v6.1.8
- Added `scroll_fg` pane attribute for custom scroll indicator (∆/∇) color
- When set, scroll markers use this color instead of the pane's foreground color
- Defaults to nil (existing behavior unchanged)

## v5.1.2 (2025-08-13)
- Added comprehensive scrolling best practices documentation (SCROLLING_BEST_PRACTICES.md)
- Documentation improvements for developers implementing scrollable panes

## v5.1.1
- Bug fixes and stability improvements

# Not yet implemented
Let me know what other features you like to see.

# License and copyright
Just steal or borrow anything you like. This is now Public Domain.

rcurses

rcurses 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

rcurses

rcurses 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README