RubyText

RubyText is a curses wrapper. The modern variant is ncurses, and there are also others. This tutorial doesn't cover much of "real" curses, as the aim is to wrap it and make it simpler.

This project is somewhat in its infancy. Once it is a little more mature, I hope to produce an Elixir version. (Elixir is not usually used at the desktop, but it can be.)

Let's start at the beginning with the overused "hello world" example.

Here are some things to notice:

Obviously you have to require the rubytext library.
You have to invoke RubyText.start (possibly with parameters).
When the curses environment is started, things like puts are overridden.
We call getch here (get a character) to make the program "pause" so as not to exit before we see anything.
At program exit, your screen will be restored to normal.

Here's another example.

The start method

The start method can take a number of parameters, some of which are keyword arguments. If you know curses, some of these will be familiar, while others provide functionality unrelated to what curses provides.

:cbreak: Like cbreak in curses. Inverse is :_cbreak (preferred) or :nocbreak
:raw: Like raw in curses. Inverse is :_raw (preferred) or :noraw
:echo: Like echo in curses. Inverse is :_echo (preferred) or :noecho
:keypad: Like keypad in curses. Inverse is :_keypad (preferred) or :nokeypad
log: logfile: Log debugging information to specified file.
fg: foreground: Set foreground color for STDSCR.
bg: background: Set background color for STDSCR.
scroll: Boolean: Permit (or disallow) window scrolling for STDSCR.
cursor: Boolean: Turn the cursor on or off.

The defaults for STDSCR are as follows:

  RubyText.start(:cbreak, :_raw, :_echo, :keypad, log: "/tmp/rubytext.log",
                 fg: White, bg: Blue, scroll: true)

  # can be abbreviated simply:

  RubyText.start

If you're a relative curses newbie (like me), you may have some confusion about the cbreak and raw modes. Let's clear it up a little with these four facts.

First of all, neither of these permits buffered keyboard input or line editing (such as backspace).
As for interrupts such as ^C and ^Z, cbreak permits these (handles them as usual).
The same interrupts are not honored by raw; instead, they are read as characters.
Finally, cbreak mode overrides raw mode if they are specified together.

As for colors: The defaults of White and Blue are purely arbitrary. They may change.

The standard curses implementation recognizes eight colors: Black, Blue, Cyan, Green, Magenta, Red, White, Yellow. Each of these constants refers to a symbol of the same (lowercased) name. What these colors look like in your own local environment may depend on many factors such as your operating system and terminal driver.

My own environment is iterm on Mac OSX with fairly standard settings. Here is some code that will display all 64 possibilities of foreground/background. (Note that curses seems to "cheat" when these two are the same, presumably to preserve legibility.)

You can use to retrieve characters from the screen as though it were a two-dimensional array. Similarly, = will set characters.

Methods that specify coordinates for points can replace one or more of those coordinates with symbols such as :top, :left, and :center.

RubyText

The start method

More later...