sup

A curses threads-with-tags style email client

ncursesw-ruby.git

git clone https://supmua.dev/git/ncursesw-ruby/

README.md (13466B) - raw

      1 $Id: README,v 1.16 2009-05-03 14:13:27 t-peters Exp $y
      2 
      3 This directory contains a ruby module for accessing the FSF's ncurses
      4 library.
      5 
      6 * (C) 2002, 2003, 2004 Tobias Peters <t-peters@users.berlios.de>
      7 * (C) 2004 Simon Kaczor <skaczor@cox.net>
      8 * (C) 2005 2006 Tobias Herzke <t-peters@users.berlios.de>
      9 * (C) 2013 2014 Gaute Hope <eg@gaute.vetsj.com>
     10 * (C) 2013 2014 Sup developers
     11 
     12 This module is free software; you can redistribute it and/or
     13 modify it under the terms of the GNU Lesser General Public
     14 License as published by the Free Software Foundation; either
     15 version 2 of the License, or (at your option) any later version.
     16 
     17 This module is distributed in the hope that it will be useful,
     18 but WITHOUT ANY WARRANTY; without even the implied warranty of
     19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     20 Lesser General Public License for more details.
     21 
     22 You should have received a copy of the GNU Lesser General Public
     23 License along with this module; if not, write to the Free Software
     24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
     25 
     26 
     27 # Overview
     28 
     29 This README file explains how to use the `ncurses` ruby interface. It is
     30 assumed that the reader has a rough understanding of what the `ncurses`
     31 library is and how to use it from the C language. It then goes into
     32 detail, explaining what is covered by the ruby interface, and the
     33 rules that were followed in translating the C interface into a ruby
     34 interface.
     35 
     36 This `ncurses` interface provides access to the functions, macros,
     37 global variables and constants of the `ncurses` library.  These are
     38 mapped to a Ruby Module named `ncurses`: Functions and external
     39 variables are implemented as singleton functions of the Module
     40 `Ncurses`.
     41 
     42 This README is organized into the following parts:
     43 - [Overview](#overview)
     44 - [Installation and Usage](#installation-and-usage)
     45 - [External Variables](#external-variables)
     46 - [Constants](#constants)
     47 - [Functions (and their Interfaces)](#functions-and-their-interfaces)
     48 - [Module / Class Hierarchy](#module--class-hierarchy)
     49 - [The Window class](#the-window-class)
     50 - [The Panel Library](#the-panel-library)
     51 - [The Form Library](#the-form-library)
     52 - [The Menu Library](#the-menu-library)
     53 - [Locale handling](#locale-handling)
     54 - [Ncurses and Ruby Threads](#ncurses-and-ruby-threads)
     55 - [Example programs](#example-programs)
     56 
     57 ## General Ncurses Literature
     58 
     59 If you don't know how to use `ncurses` from C, then please read an
     60 introduction to `ncurses` before continuing with this README. Eric
     61 Raymond has written an introduction that should be part of the `ncurses`
     62 development package installed on your computer.
     63 
     64 If you'd like a gentler introduction, then you have two options:
     65 
     66 1. there is a part of a chapter in "The Linux Programmer's Guide" dealing
     67     with `ncurses`, available from www.tldp.org.  It is quite old by now,
     68     but the `ncurses` interface has not changed since then, regarding the
     69     scope of covered functions, so it is still a very good read.
     70 
     71 2. There is also an up-to-date "NCURSES-Programming-HOWTO" in the HOWTO
     72     collection of the Linux Documentation Project, also available at
     73     www.tldp.org, which is worth a read.
     74 
     75 You will also appreciate the extensive man-pages of `ncurses`, a useful
     76 reference while coding.
     77 
     78 ## Installation and Usage
     79 
     80     gem install ncursesw
     81 
     82 Or add to your Gemfile
     83 
     84     gem 'ncursesw'
     85 
     86 If your programs use the `scanw` functions (most unlikely) you will have to
     87 install the `scanf` library for ruby (http://www.rubyhacker.com/code/scanf).
     88 
     89 Most `ncurses` functions are only available after either `Ncurses.initscr` or
     90 `Ncurses.newterm` has returned successfully.
     91 
     92 ## External Variables
     93 
     94 External variables are accessed read-only, by module functions taking no
     95 arguments.  They are spelled exactly like their C counterparts. Sometimes, this
     96 leads to module functions beginning with an uppercase letter (e.g.
     97 `Ncurses.LINES`).
     98 
     99 One of these external variables, `ESCDELAY`, can also be set with a ruby method
    100 (`Ncurses.ESCDELAY=`).
    101 
    102 Another external variable, `Ncurses.RESIZEDELAY` is introduced by this wrapper.
    103 It contains the maximum milliseconds delay with which terminal resizings are
    104 recognized.
    105 
    106 ## Constants
    107 
    108 (static C Preprocessor macros)
    109 
    110 Constants are implemented as module constants in the `Ncurses` module, if
    111 possible. Ruby constants can not start with an underscore, so these constants
    112 have been renamed (they lost the leading underscore). There are, however,
    113 module functions with the same name as these constants, that also return
    114 the constant's value, when invoked (e.g. `Ncurses._ENDLINE` returns the value
    115 of the constant `Ncurses::ENDLINE`, which has the same value as the C constant
    116 `_ENDLINE`).
    117 
    118 Note: The `ncurses` macros starting with `ACS_` are not constants, their value
    119 depends on the terminal in use.  Nevertheless, they are implemented as
    120 constants of the `Ncurses` module, but since they depend on the terminal, they
    121 are not initialized before `initscr()` has been called. If you need more than
    122 one terminal in a single program, you can access the `ACS_` values through member
    123 functions of class `SCREEN`.
    124 
    125 
    126 ## Functions (and their Interfaces)
    127 
    128 Functions (also those only implemented by macros in C) can be accessed
    129 as module functions of the Module Ncurses. They take exactly the same
    130 arguments as their C counterparts. Some of the C functions return additional
    131 arguments through pointer arguments. These are implemented as follows:
    132 
    133 
    134 ## Functions expecting pointers to integer types
    135 
    136 When the C-function expects a pointer to `int`, `short`, `chtype`, or `attr_type`,
    137 You should use a variable containing an empty array as the argument to the ruby
    138 function. This is because ruby passes these types (`int`) "by value" instead of
    139 "by reference"; but arrays are passed by reference, so that you can see the
    140 changes to them.
    141 
    142 **Attention:** some macro-only functions like `getsyx` accept variables of type `int`,
    143 but, being macros, they write values to their arguments. Thus, they also need
    144 empty array arguments when called from ruby.
    145 
    146 Example:
    147 
    148     color_pair_number = 4
    149     foreground_color  = []
    150     background_color  = []
    151     if (Ncurses.pair_content(color_pair_number, foreground_color,
    152                      background_color) != Ncurses::ERR)
    153       "color pair number #{color_pair_number} contains color number " +
    154       "#{foreground_color[0]} as the foreground color, and color "    +
    155       "number #{background_color[0]} as the background color")
    156     end
    157 
    158 There are 2 functions that read a value from the location pointed to by a
    159 pointer to int, and store another value at those locations. These functions are
    160 `mouse_trafo` and `wmouse_trafo`. When calling these functions, you have to provide
    161 2 arrays, each filled with exacly one Integer. The values contained in these
    162 arrays will then be changed by the ruby module function.
    163 
    164 
    165 ## Functions expecting (non-const) pointers to char
    166 
    167 When the C-function expects a pointer to char, you should use a variable
    168 containing an empty string as the argument to the ruby function.
    169 
    170 **Example:**
    171 
    172     line2 = ""
    173     if (Ncurses.mvwinnstr(Ncurses.stdscr, y=2, x=0, line2,
    174                   Ncurses.getmaxx(Ncurses.stdscr)) == Ncurses::ERR)
    175         raise "could not scan 3rd line"
    176     else
    177         Ncurses.beep if line2.index("|")
    178     end
    179 
    180 The string that the C function would store at the pointer-to-char location
    181 will be appended to the given string.
    182 
    183 Functions expecting const pointers to char do not modify the string they
    184 receive, you can pass any string to them.
    185 
    186 
    187 ## Functions expecting pointers to structs
    188 
    189 When the C-function expects a pointer to `WINDOW`, `SCREEN`, `MEVENT`,
    190 `PANEL`, `FORM`, `FIELD` or `FIELDTYPE` then simply pass it the corresponding,
    191 already existing ruby object.
    192 
    193 
    194 ## scanf style functions expecting various pointers
    195 
    196 namely `scanw`, `mvscanw`, `wscanw`, `mvwscanw`.  Use an array after the format string.
    197 The scanned values will be placed there.  Remember, you need `scanf` for ruby
    198 installed for these functions to work.
    199 
    200 ## Module / Class Hierarchy
    201 
    202     module Ncurses
    203         class WINDOW; end
    204         class SCREEN; end
    205         class MEVENT; end
    206         module Panel
    207             class PANEL; end
    208         end
    209         module Form
    210             class FORM; end
    211             class FIELD; end
    212             class FIELDTYPE; end
    213         end
    214         module Menu
    215             class MENU; end
    216             class ITEM; end
    217         end
    218     end
    219 
    220 
    221 ## The Window class
    222 
    223 The class `WINDOW` implements `method_missing` and tries to map invoked
    224 methods to `ncurses` module functions using a simple heuristic:
    225 
    226 If the method name starts with `mv`, it looks for a `ncurses` module
    227 function that starts with `mvw`, and if it exists, adds itself to the
    228 argument list and calls this function.
    229 
    230 If no such module function exists, or the name of the invoked method
    231 does not start with `mv`, it looks if there is a module function with
    232 the name `w` + `methodname`, and if it exists, adds itself again to the
    233 argument list and calls this function.
    234 
    235 If this module function did not exist either, then, as a last step, it
    236 invokes a module function with the same name as the method, adding
    237 itself to the argument list.
    238 
    239 **Example:** If you invoke `win.mvaddch(y,x,ch)` on an `Ncurses::WINDOW`
    240 object, it will delegate the method call to
    241 `Ncurses.mvwaddch(win,y,x,ch)`.
    242 
    243 **Other Examples:**
    244 
    245     win.printw("hello") =>  Ncurses.wprintw(win, "hello")
    246 
    247     win.getmaxyx(y=[],
    248                  x=[])  =>  Ncurses.getmaxyx(win,y,x)
    249 
    250     win.delwin()        =>  Ncurses.delwin(win)          # win cannot be used
    251                                                          # after this call
    252 
    253 
    254 ## The Panel Library
    255 
    256 The panel library has also been wrapped. All panel functions are
    257 implemented as module functions of the module `Ncurses::Panel`.
    258 
    259 Most of these functions are also implemented as methods of class
    260 `Ncurses::Panel::PANEL`, once with their original name and once with the
    261 subword `panel` and an adjacent underscore removed.
    262 
    263 ## The Form Library
    264 
    265 The form library was wrapped inside the `Ncurses:Form` module. All
    266 form functions are implemented as module functions on the module
    267 `Ncurses::Form`. In addition, all function for which the first
    268 parameter is one of the objects are also implemented as an instance
    269 method of the respective class. For example, instead of calling
    270 `post_form(form)`, you can use `form.post_form()`.
    271 
    272 Three objects are defined in the `Ncurses:Form` module:
    273 
    274 1. `FORM`
    275 2. `FIELD`
    276 3. `FIELDTYPE`
    277 
    278 They are wrapping actual ncurses pointers and should be use whenever a
    279 pointer to one of these types is expected in function calls.
    280 
    281 All form constants are defined in the module as Ruby constants with
    282 the same name as the `curses` constants.
    283 
    284 Constructors for `FORM`, `FIELD` and `FIELDTYPE` objects are also provided,
    285 and they expect the same parameters as `new_form`, `new_field` and
    286 `new_fieldtype` `curses` functions.
    287 
    288 Field validation is implemented using Ruby `Proc` objects. You must
    289 provide a Ruby block whenever a function pointer is expected in `curses`
    290 function arguments. See the example `form2.rb` for more details.
    291 
    292 The functions `form_userptr` and `field_userptr` are not supported. Use
    293 `form.user_object` and `field.user_object` to store Ruby objects instead.
    294 
    295 ## The Menu Library
    296 
    297 The menu library was wrapped inside the `Ncurses:Menu` module. All
    298 menu functions are implemented as module functions in the module
    299 `Ncurses::Menu`. In addition, all functions for which the first
    300 parameter is one of the objects, are also implemented as an instance
    301 method of the respective class.
    302 
    303 For example, instead of calling `post_menu(menu)`, you can use
    304 `menu.post_menu()`.
    305 
    306 Two objects are defined in the `Ncurses:Menu` module:
    307 
    308 1. `MENU`
    309 2. `ITEM`
    310 
    311 They are wrapping actual `ncurses` pointers and should be use whenever a
    312 pointer to one of these types is expected in function calls.
    313 
    314 All menu constants are defined in the module as Ruby constants with
    315 the same name as the `curses` constants.
    316 
    317 Constructors for `MENU` and `ITEM` objects are also provided, and they
    318 expect the same parameters as `new_menu` and `new_item` curses functions.
    319 
    320 You must provide a Ruby block whenever a function pointer is expected
    321 in `curses` function arguments.
    322 
    323 The functions `menu_userptr` and `item_userptr` are not supported. Use
    324 `menu.user_object` and `item.user_object` to store Ruby objects instead.
    325 
    326 ## Locale handling
    327 
    328 The C library function `setlocale` is not technically an `ncurses` function.
    329 However, it is used by many `ncurses` programs, and for this purpose,
    330 a wrapper for this function is also included in `ncurses-ruby`.
    331 
    332 The function is implemented as a module function `Ncurses.ruby`, and
    333 expects two arguments, an `Integer` and a `String`.  It returns a string.
    334 The constants that can be used as the Integer argument are also wrapped
    335 as constants in the `ncurses` module.  See the manual page for `setlocale`
    336 for documentation of this function.
    337 
    338 ## Ncurses and Ruby Threads
    339 
    340 The `ncurses` library is not thread-safe. Your application must properly
    341 serialize calls into `ncurses`.
    342 
    343 Prior to release 0.9.2, the `getch` and `wgetch` calls used to block the
    344 complete ruby interpreter, all threads. This is no longer so. Other
    345 threads should now continue to run during blocking calls to `getch` and
    346 `wgetch`.
    347 
    348 ## Example programs
    349 
    350 Directory `examples` contains a few example programs demonstrating how
    351 to use the ncurses library with ruby.  Be sure to read the file
    352 `examples/LICENSES_for_examples`.