.mixin bookish

.copy basic.css

.h1 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.)

.def example
   arg, ppl = _args
   ppl ||= 20
   file = arg + ".rb.html"
   sshot = arg + ".png"
   code = File.read(file)  # HTML from vim
   lines = code.split("\n")
   n0 = lines.find_index {|x| x =~ /^<pre/ }
   n1 = lines.find_index {|x| x =~ /^<.pre>/ }
   nlines = n1 - n0 - 1
# hw.png PNG 283x190 283x190+0+0 8-bit sRGB 5443B 0.000u 0:00.000
   img_data = `identify #{sshot}`  # depends on imagemagick
   wimg, himg = img_data.split[2].split("x")
   wide = "100%"  # (wimg.to_i * 2.4).to_i
   high = himg.to_i + 25
   hcode = nlines*ppl.to_i + 25
   hmax = [high, hcode].max  # Code may be longer than screenshot height
   _puts "<!-- high = #{high}   hcode = #{hcode} -->"
   File.open("wrap-#{arg}.html", "w") do |f|
     f.puts "<table width=100% cellpadding=2><tr><td width=65% valign=top>"
     f.puts code
     f.puts "</td><td width=35% valign=top><img src=#{sshot} valign=top></td></tr></table>"
   end
   _puts <<-HTML
     <iframe frameborder=0 
             width=#{wide} height=#{hmax} 
             src='wrap-#{arg}.html'>
     </iframe>
   HTML
.end

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

.example hw

Here are some things to notice:
.list
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.
.end

Here's another example.

.example stdscr

.h3 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.

.dlist |
$$bt[:cbreak] | Like `cbreak in curses. Inverse is `:\_cbreak (preferred) or `:nocbreak
$$bt[:raw] | Like `raw in curses. Inverse is `:\_raw (preferred) or `:noraw
$$bt[:echo] | Like `echo in curses. Inverse is `:\_echo (preferred) or `:noecho
$$bt[:keypad] | Like `keypad in curses. Inverse is `:\_keypad (preferred) or `:nokeypad
$$bt[log: _logfile] | Log debugging information to specified file.
$$bt[fg: _foreground] | Set foreground color for STDSCR.
$$bt[bg: _background] | Set background color for STDSCR.
$$bt[scroll: _Boolean] | Permit (or disallow) window scrolling for STDSCR.
$$bt[cursor: _Boolean] | Turn the cursor on or off.
.end


The defaults for `STDSCR are as follows: 

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

  # can be abbreviated simply:

  RubyText.start
.end

.comment
Skip?
nodelay causes getch to be a non-blocking call. 
If no input is ready, getch returns ERR.

Skip?
notimeout(win, TRUE) -- wgetch does not set a timer. 
Differentiate between sequences received from a function key and those typed by a user.
.end

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.

.list
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.
.end

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.)

.example colortest 15

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

.example brackets 22

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

.example sym_nav 18

<h3>More later...</h3>


.cleanup toc.tmp