ncurses 0.9.1

data/Changes

@@ -0,0 +1,27 @@
+ncurses-ruby-0.9:
+ * Forms wrapper contributed by Simon Kaczor
+ * ncurses-ruby now also works with ncurses-4.2
+   (an old release from 1998, needed for Zaurus-port)
+ * First binary package for Sharp Zaurus (arm-linux)
+
+ncurses-ruby-0.8:
+ * Bugfix: Calls into the ncurses library prior to calling
+   Ncurses::initscr or Ncurses::newterm had previously crashed
+   the Ruby interpreter.
+   Fixed by delaying the binding of most Ncurses functions
+   until after Ncurses::initscr or Ncurses::newterm have been
+   called.
+ * Replaced module functions with singleton functions. This
+   means that
+     include Ncurses
+     initscr
+   is no longer possible. Instead, use
+     Ncurses.initscr
+   Reasons: - Consistency. The shortcut has never been possible
+              with all ncurses functions.
+            - Namespace pollution. Some ncurses functions have
+              too common names.
+
+ncurses-ruby-0.7.2:
+ * reintroduced Ncurses::pechochar and Ncurses::redrawwin in the ncurses build.
+   These had been removed by mistake because they did not work with PDCurses.

data/MANIFEST

@@ -0,0 +1,27 @@
+Changes
+COPYING
+MANIFEST
+README
+README.windows
+THANKS
+TODO
+VERSION
+examples/example.rb
+examples/form.rb
+examples/form2.rb
+examples/hello_ncurses.rb
+examples/LICENSES_for_examples
+examples/rain.rb
+examples/tclock.rb
+examples/read_line.rb
+examples/test_scanw.rb
+extconf.rb
+form_wrap.c
+form_wrap.h
+make_dist.rb
+ncurses_wrap.c
+ncurses_wrap.h
+lib/ncurses.rb
+panel_wrap.c
+panel_wrap.h
+

data/README

@@ -0,0 +1,273 @@
+$Id: README,v 1.10 2004/05/13 21:54:41 t-peters Exp $
+------------------------------------------------------------------------
+This directory contains a ruby module for accessing the FSF's ncurses
+library.
+(C) 2002, 2003, 2004 Tobias Peters <t-peters@users.berlios.de>
+(C) 2004 Simon Kaczor <skaczor@cox.net>
+
+This module is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later version.
+
+This module is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this module; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+------------------------------------------------------------------------
+
+This wrapper provides access to the functions, macros, global variables and
+constants of the ncurses library.  These are mapped to a Ruby Module named
+"Ncurses":  Functions and external variables are implemented as singleton
+functions of the Module Ncurses.
+
+This wrapper can also be used to access the PDCurses library
+(http://pdcurses.sourceforge.net/). See README.windows for details.
+
+If you don't know how to use ncurses from C, then stop reading here, and read
+an introduction to ncurses. Eric Raymond has written an introduction that
+should be part of the ncurses development package installed on your computer.
+If you need a gentler introduction, then you have two options:
+(1) there is a part of a chapter in "The Linux Programmer's Guide" dealing with
+    ncurses, available from www.tldp.org.  It is quite old by now,
+    but the ncurses interface has not changed since then, regarding the scope
+    of covered functions, so it is still a very good read.
+(2) There is also an up-to-date "NCURSES-Programming-HOWTO" in the HOWTO
+    collection of the Linux Documentation Project, also available at
+    www.tldp.org, which is worth a read.
+
+You will also appreciate the extensive man-pages of ncurses.
+
+
+Installation and Usage
+======================
+
+ruby extconf.rb
+make
+make install
+
+In your programs:
+require "ncurses.rb"
+
+If your programs use the scanw functions (most unlikely) you will have to
+install the scanf library for ruby (http://www.rubyhacker.com/code/scanf).
+
+Most ncurses functions are only available after either Ncurses.initscr or
+Ncurses.newterm has returned successfully.
+
+External Variables
+==================
+
+External variables are accessed read-only, by module functions taking no
+arguments.  They are spelled exactly like their C counterparts. Sometimes, this
+leads to module functions beginning with an uppercase letter (e.g.
+Ncurses.LINES).
+
+One of these external variables, ESCDELAY, is also settable with a ruby method
+(Ncurses.ESCDELAY=).
+
+
+Constants
+=========
+(static C Preprocessor macros)
+
+Constants are implemented as module constants in the Ncurses module, if
+possible. Ruby constants can not start with an underscore, so these constants
+have been renamed (they lost the leading underscore). There are,however,
+module functions with the same name as these constants, that also return
+the constant's value, when invoked (e.g. "Ncurses._ENDLINE" returns the value
+of the constant "Ncurses::ENDLINE", which has the same value as the C constant
+"_ENDLINE").
+
+Note: The ncurses macros starting with ACS_ are not constants, their value
+depends on the terminal in use.  Nevertheless, they are implemented as
+constants of the Ncurses module, but since they depend on the terminal, they
+are not initialized before initscr() has been called. If you need more than
+one terminal in a single program, you can access the ACS_ values through member
+functions of class SCREEN.
+
+
+Functions
+=========
+
+Functions (also those only implemented by macros in C) can also be accessed
+through module functions of the Module Ncurses. They take exactly the same
+arguments as their C counterparts. Some of the C functions return additional
+arguments through pointer arguments. These are implemented as follows:
+
+
+Functions expecting pointers to integer types
+---------------------------------------------
+
+When the C-function expects a pointer to int, short, chtype, or attr_type,
+You should use a variable containing an empty array as the argument to the ruby
+function. This is because ruby passes these types (ints) "by value" instead of
+"by reference"; but arrays are passed by reference, so that you can see the
+changes to them.
+Attention: some macro-only functions like getsyx accept variables of type int,
+but, being macros, they write values to their arguments. Thus, they also need
+empty array arguments when called from ruby.
+Example: 
+	color_pair_number = 4
+	foreground_color  = []
+	background_color  = []
+	if (Ncurses.pair_content(color_pair_number, foreground_color,
+			         background_color) != Ncurses::ERR)
+	  "color pair number #{color_pair_number} contains color number " +
+	  "#{foreground_color[0]} as the foreground color, and color "    +
+	  "number #{background_color[0]} as the background color")
+	end
+
+There are 2 functions that read a value from the location pointed to by a
+pointer to int, and store another value at those locations. These functions are
+mouse_trafo and wmouse_trafo. When calling these functions, you have to provide
+2 arrays, each filled with exacly one Integer. The values contained in these
+arrays will then be changed by the ruby module function.
+
+
+Functions expecting (non-const) pointers to char
+------------------------------------------------
+
+When the C-function expects a pointer to char, you should use a variable
+containing an empty string as the argument to the ruby function.
+Example:
+	line2 = ""
+	if (Ncurses.mvwinnstr(Ncurses.stdscr, y=2, x=0, line2,
+			      Ncurses.getmaxx(Ncurses.stdscr)) == Ncurses::ERR)
+		raise "could not scan 3rd line"
+	else
+		Ncurses.beep if line2.index("|")
+	end
+The string that the C function would store at the pointer-to-char location
+will be appended to the given string.
+
+Functions expecting const pointers to char do not modify the string they
+receive, you can pass any string to them.
+
+
+
+Functions expecting pointers to structs
+---------------------------------------------------
+
+When the C-function expects a pointer to WINDOW, SCREEN, MEVENT,
+PANEL, FORM, FIELD or FIELDTYPE then simply pass it the corresponding,
+already existing ruby object.
+
+
+scanf style functions expecting various pointers
+---------------------------------------------------
+
+namely scanw, mvscanw, wscanw, mvwscanw.  Use an array after the format string.
+The scanned values will be placed there.  Remember, you need scanf for ruby
+installed for these functions to work.
+
+Module / Class Hierarchie
+=========================
+
+module Ncurses
+	class WINDOW; end
+	class SCREEN; end
+	class MEVENT; end
+	module Panel 
+		class PANEL; end
+	end
+	module Form
+		class FORM; end
+		class FIELD; end
+		class FIELDTYPE; end
+	end
+end
+
+
+Where to find the functions
+===========================
+
+As stated, all ncurses functions are implemented as module functions in the
+module Ncurses. If you know how an ncurses function is named in C (example:
+"mvaddch"), then call the corresponding module functions with the
+same number of arguments (example: "Ncurses.mvaddch(y,x,ch)")
+
+The class window implements method_missing and tries to map invoked methods
+to Ncurses module functions using a simple heuristic:
+If the method name starts with "mv", it looks for a Ncurses module function
+that starts with "mvw", and if it exists, adds itself to the argument list
+and calls this function.
+If no such module function exists, or the name of the invoked method does not
+start with "mv", it looks if there is a module function with the name "w" +
+methodname, and if it exists, adds itself again to the argument list and calls
+this function.
+If this module function did not exist either, then, as a last step, it invokes
+a module function with the same name as the method, adding itself to the
+argument list.
+
+Example: If you invoke win.mvaddch(y,x,ch) on an Ncurses::WINDOW object, it
+will delegate the method call to Ncurses.mvwaddch(win,y,x,ch).
+
+Other examples:
+ win.delwin()        =>  Ncurses.delwin(win)          # win cannot be used
+                                                      # after this call
+ win.printw("hello") =>  Ncurses.wprintw(win, "hello")
+ win.getmaxyx(y=[],
+              x=[])  =>  Ncurses.getmaxyx(win,y,x)
+
+
+Example programs
+================
+
+Directory "examples" contains a few example programs demonstrating how to use
+the library with ruby.  Be sure to read the file
+"examples/LICENSES_for_examples".
+
+
+Applications using ncurses-ruby
+===============================
+
+aeditor - Pair programming editor, http://metaeditor.sourceforge.net/
+raggle - RSS aggregator, http://www.raggle.org/about/
+
+The panel library
+=================
+
+The panel library has also been wrapped. All panel functions are implemented
+as module functions of the module Ncurses::Panel.
+
+Most of these functions are also implemented as methods of class
+Ncurses::Panel::PANEL, once with their original name and once with the subword
+"panel" and an adjacent underscore removed.
+
+The form library
+================
+
+The form library was wrapped inside the Ncurses:Form module. All
+form functions are implemented as module functions on the module
+Ncurses::Form. In addition, all function for which the first
+parameter is one of the objects are also implemented as an instance 
+method of that object. For example, instead of calling
+post_form(form), you can use form.post_form().
+
+Three objects are defined in the Ncurses:Form module:
+	1. FORM
+	2. FIELD
+	3. FIELDTYPE
+
+They are wrapping actual ncurses pointers and should be use whenever a
+pointer to one of these types is expected in function calls.
+
+All form constants are defined in the module as Ruby constants with
+the same name as the curses constants.
+
+Constructors for FORM, FIELD and FIELDTYPE objects are also provided,
+and they expect the same parameters as new_form, new_field and
+new_fieldtype curses functions.
+
+Field validation is implemented using Ruby Proc objects. You must
+provide a Ruby block whenever a function pointer is expected in curses
+function arguments. See the example form2.rb for more details.
+
+The functions form_userptr and field_userptr are not supported. Use
+form.user_object and field.user_object to store Ruby objects instead.
+

data/README.windows

@@ -0,0 +1,35 @@
+$Id: README.windows,v 1.2 2003/03/22 20:00:59 t-peters Exp $
+------------------------------------------------------------------------
+
+Ncurses has been ported to the cygwin environment.  If you are using the
+cygwin version of ruby on windows, you can simply use this version of
+ncurses.
+
+Instead, if you are using a native windows version of Ruby (compiled with
+mingw, visual c++, borland c++), then you can use this wrapper with the
+PDCurses library (http://pdcurses.sourceforge.net/). In this case,
+ncurses-ruby wraps the subset of curses features that are common to ncurses
+and PDCurses.
+
+Here's how to compile ncurses-ruby on windows using PDCurses and MinGW:
+(For those not familiar enough with the mingw compiler, you can get a
+ precompiled mingw ruby from
+ http://www.ruby-lang.org/~eban/ruby/binaries/mingw/, and a precompiled
+ ncurses-ruby version from this project's download area
+ http://developer.berlios.de/project/filelist.php?group_id=273)
+
+- compile ruby with mingw 2.0 and install it somewhere. remember to set up
+  the PATH environment correctly.
+
+- get the sources for PDCurses and compile them using the provided Makefile
+  "win32/mingwin32.mak"
+
+- next, move the pdcurses header files ("curses.h", "panel.h") into mingw's
+  include directory. Also, move the generated libraries ("pdcurses.a",
+  "panel.a") into mingw's lib directory, while renaming these libraries to
+  "libpdcurses.a" and "libpanel.a"
+
+- compile and install ncurses-ruby using the commands "ruby extconf.rb",
+  "make", "make install"
+
+- try out the examples

data/THANKS

@@ -0,0 +1,11 @@
+$Id: THANKS,v 1.5 2004/07/31 08:34:17 t-peters Exp $
+
+A list of people that helped me with ncurses-ruby
+
+Akinori MUSHA   (knu at idaemons dot org)
+Jan Becvar      (jan dot becvar at solnet dot cz)
+Juergen Daubert
+Doug Kearns
+Simon Kaczor    (skaczor at cox dut net)
+Hiroshi Sainohira
+Andreas Schwarz

data/TODO

@@ -0,0 +1,15 @@
+$Id: TODO,v 1.6 2003/03/22 22:55:27 t-peters Exp $
+
+This is the complete list of functions present in ncurses that have not yet
+been wrapped by ncurses-ruby:
+
+terminfo functions: setupterm, setterm, set_curterm, del_curterm, restartterm,
+                    tparm, tputs, vidputs
+
+termcap fuctions:   tgetent, tgetflag, tgetnum, tgetstr, tgoto
+
+ncurses
+kernel functions:   ripoffline
+
+No sense in
+wrapping these:     vw_printw, vwprintw, vwscanw

data/VERSION

@@ -0,0 +1 @@
+0.9.1

data/examples/LICENSES_for_examples

@@ -0,0 +1,26 @@
+$Id: LICENSES_for_examples,v 1.6 2004/05/13 21:55:17 t-peters Exp $
+
+Ideally, an example program on how to use a library should be in the public
+domain.
+
+Some of the example programs contained in this dircectory have not been put in
+the public domain, however.
+
+The reason is because I did not write all programs completely myself -- I've
+adapted the following example programs from ncurses programs in other
+programming languages, or I have included example programs contributed by
+other authors, and I have to respect their original licenses:
+- rain.rb is adapted from rain.c from the ncurses library distribution.
+- example.rb is adapted from an example program for the python ncurses binding.
+- tclock.rb is adapted from tclock.c from the ncurses library distribution.
+- form.rb anf form2.rb have been written by Simon Kaczor, who has adapted them
+  from sample code from the NCurses Programming HOWTO.
+
+See the comments in the source files for restrictions imposed on copying and
+modifying these.
+
+That said, I suppose you may still look at their source code and learn how
+ncurses programs generally work, as long as you dont start your own programs
+by loading the example program into your editor and modify it to your needs.
+
+Tobias Peters <t-peters@users.berlios.de>

data/examples/example.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+
+# $Id: example.rb,v 1.4 2002/03/04 13:24:29 t-peters Exp $
+
+# This file provides an example for the usage of the ncurses-ruby module.
+# Copyright (C) 2002 Tobias Peters <t-peters@users.berlios.de>
+#
+# The following license applys only to this file. It is less restrictive
+# than the license for the rest of the ncurses-ruby distribution. 
+# I've adapted this file from someone else, see below. 
+#
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this file
+# (the "Software"), to deal in the Software without restriction,
+# including without limitation the rights to use, copy, modify, merge,
+# publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+
+# this file is adapted from an example of the python ncurses binding
+# pyncurses (http://pyncurses.sf.net/), which has the following copyright
+# statement:
+
+# Copyright (c) 2000 by Harry Henry Gebel
+# 
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation files
+# (the "Software"), to deal in the Software without restriction,
+# including without limitation the rights to use, copy, modify, merge,
+# publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+
+require "ncurses"
+
+def moving(scr)
+  scr.clear() # clear screen
+  scr.move(5,5) # move cursor
+  scr.addstr("move(5,5)")
+  scr.refresh() # update screen
+  sleep(2)
+  scr.move(2,2)
+  scr.addstr("move(2,2)")
+  scr.refresh()
+  sleep(2)
+  scr.move(10, 2)
+  scr.addstr("Press a key to continue")
+  scr.getch()
+end
+
+def border(scr)
+  scr.clear()
+  scr.border(*([0]*8)) # calls WINDOW#border(0, 0, 0, 0, 0, 0, 0, 0)
+  scr.move(3,3)
+  scr.addstr("Press a key to continue")
+  scr.getch()
+end
+
+def two_borders()
+  # make a new window as tall as the screen and half as wide, in the left half
+  # of the screen
+  one = Ncurses::WINDOW.new(0, Ncurses.COLS() / 2, 0, 0)
+  # make one for the right half
+  two = Ncurses::WINDOW.new(0, Ncurses.COLS() - (Ncurses.COLS() / 2),
+			    0, Ncurses.COLS() / 2)
+  one.border(*([0]*8))
+  two.border(*([0]*8))
+  one.move(3,3)
+  two.move(2,5)
+  one.addstr("move(3,3)")
+  two.addstr("move(2,5)")
+  two.move(5,3)
+  two.addstr("Press a key to continue")
+  one.noutrefresh() # copy window to virtual screen, don't update real screen
+  two.noutrefresh()
+  Ncurses.doupdate() # update read screen
+  two.getch()
+end
+
+begin
+  # initialize ncurses
+  Ncurses.initscr
+  Ncurses.cbreak           # provide unbuffered input
+  Ncurses.noecho           # turn off input echoing
+  Ncurses.nonl             # turn off newline translation
+  Ncurses.stdscr.intrflush(false) # turn off flush-on-interrupt
+  Ncurses.stdscr.keypad(true)     # turn on keypad mode
+
+  Ncurses.stdscr.addstr("Press a key to continue") # output string
+  Ncurses.stdscr.getch                             # get a charachter
+
+  moving(Ncurses.stdscr) # demo of moving cursor
+  border(Ncurses.stdscr) # demo of borders
+  two_borders()          # demo of two windows with borders
+
+ensure
+  Ncurses.echo
+  Ncurses.nocbreak
+  Ncurses.nl
+  Ncurses.endwin
+end