ffi-ncurses 0.3.3 → 0.4.0

data/COPYING

@@ -0,0 +1,22 @@
+ffi-ncurses
+
+Copyright (c) 2008-2011 Sean O'Halpin sean.ohalpin at gmail.com
+
+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.

data/Gemfile

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+source :rubygems
+
+gem "ffi"
+gem "ffi-locale"

data/Gemfile.lock

@@ -0,0 +1,13 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ffi (1.0.9)
+    ffi-locale (1.0.0)
+      ffi (>= 1.0.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ffi
+  ffi-locale

data/History.txt

@@ -1,3 +1,31 @@
+= Changelog for ffi-ncurses
+
+== 0.4.0 / 2011-09-25
+
+* Supports all functions in ncursesw except the =vwprintw/vwscanw=
+  family.
+* Added =ACS= constants (box characters). See =examples/acs.rb= and
+  =examples/wacs.rb=.
+* Added support for =libpanelw=. See =examples/panel_simple.rb=.
+* Better examples. See =examples/viewer.rb= for a simple but complete
+  file viewing application.
+* Methods with boolean arguments now =true= or =false= as well as 1 or
+  0.
+* Start of a compatibility layer for the existing C extension-based
+  Ncurses Ruby libraries - require 'ffi-ncurses/ncurses'.  Runs all
+  the examples from ncurses-ruby without changes (except those relying
+  on menus and forms). See =examples/ncurses/*.rb=.
+* Sets the locale (using FFI::Locale.setlocale(LC_ALL, "")) in ruby
+  1.8.x to enable UTF-8 input. See =examples/getkey.rb= to see how to
+  distinguish between function keys and Unicode characters.
+
+== 0.3.4 / 2010-08-28
+
+* Added MIT licence (License.txt, COPYING)
+* Bumped version
+* Added nested PDat struct to WinStruct
+* Reformatted comments for rocco
+
 == 0.3.3 / 2010-08-24
 
 * Depends on ffi again (>= 0.6.3)
@@ -7,16 +35,17 @@
 * Included keydefs.rb by default
 * Examples have been tested with:
   - jruby-1.5.1
-  - rbx-1.0.0-20100514
   - ree-1.8.7-2010.02
   - ruby-1.8.6-p399
     Note: the examples require "ffi-ncurses/ord-shim" to add
     Integer#ord
-  - ruby-1.8.7-p299
+  - ruby-1.8.7-p302
   - ruby-1.9.2-p0
+* Sadly not compatible with Rubinius (rbx-1.0.0-20100514)
 * Removed attempt to load XCurses (PDCurses)
 * Removed dependency on bones
-  - no Rakefile any more - just use gem build ffi-ncurses.gemspec
+  - no Rakefile any more - just use
+      gem build ffi-ncurses.gemspec
 
 == 0.3.2 / 2009-02-16
 

data/README.rdoc

@@ -2,34 +2,67 @@
 
 Author: Sean O'Halpin
 
-A wrapper for ncurses 5.x. Tested on Ubuntu 8.04 to 10.04 and Mac OS X
-10.4 (Tiger) with ruby 1.8.6, 1.8.7 and 1.9.x using ffi (>= 0.6.3) and
-JRuby 1.5.1.
+A pure-ruby wrapper for {http://invisible-island.net/ncurses/ ncursesw
+5.x} using the {https://github.com/ffi/ffi ffi} library.
+
+All of the core ncursesw functions are supported along with the Panel
+library. The main things left to do are support for the Menu and Form
+libraries.
 
 The API is a transliteration of the C API rather than an attempt to
 provide an idiomatic Ruby object-oriented API. The intent is to
 provide a 'close to the metal' wrapper around the ncurses library upon
 which you can build your own abstractions.
 
-This is still very much a work-in-progress, so expect some rough
-edges. Having said that, you can do quite a lot with it as it is. The
-main things left to be done are tests, access to global variables and
-various macros.
+Please note that this documentation does not cover individual
+ncursesw methods. For that you'll need to refer to existing
+ncursesw documentation. For example, to find out about +addstr+,
+use:
+
+  $ man addstr
+
+One benefit of using a minimal wrapper approach is that you can use
+existing examples and man pages to find out how to use the library. To
+get an overview of ncurses, use:
+
+  $ man ncurses
+
+Having said that, this release also includes a wrapper that emulates
+the existing Ncurses library API. To use it, substitute
+
+  require 'ffi-ncurses/ncurses'
+
+for
+
+  require 'ncurses'
 
-Below are some very preliminary notes on usage. See the examples
-directory for real working examples.
+or create a file called 'ncurses.rb' on your +$LOAD_PATH+ ($:) that
+requires +ffi-ncurses/ncurses.rb+.
 
-== Install
+Below you'll find some very preliminary notes on usage. See the
+examples directory for real working examples, which among other things
+show how to input and output UTF-8, deal with pointers and handle wide
+characters.
 
-ruby 1.8.x:
+This version of ffi-ncurses defaults to loading ncursesw, the 'wide
+character' version which supports UTF-8 and double width characters.
 
-  $ sudo gem install ffi-ncurses
+Tested on Ubuntu 10.04 with ruby1.8.7 and 1.9.2 using ffi (>= 0.6.3)
+and JRuby 1.6.4 (head). A previous version of the library was tested
+on Mac OS X 10.04. Please let me know if anything has stopped working.
 
-jruby 1.5.1:
+Rubinius is not supported as its FFI does not provide the required
+API, especially for dealing with buffers and pointers.
 
-  $ jruby -S gem install ffi-ncurses
+This is still very much a work-in-progress, so expect some rough edges
+(and please {https://github.com/seanohalpin/ffi-ncurses/issues report
+them}). Having said that, you can do quite a lot with it as it is.
 
-== Usage
+= Install
+
+  $ [sudo] gem install ffi-ncurses
+
+= Usage
 
 Load the library with:
 
@@ -38,7 +71,7 @@ Load the library with:
 FFI::NCurses methods can be called as module methods:
 
   begin
-    stdscr = FFI::NCurses.initscr
+    FFI::NCurses.initscr
     FFI::NCurses.clear
     FFI::NCurses.addstr("Hello world!")
     FFI::NCurses.refresh
@@ -49,15 +82,13 @@ FFI::NCurses methods can be called as module methods:
 
 or as included methods:
 
-  require 'ffi-ncurses'
   include FFI::NCurses
+
   begin
-    stdscr = initscr
-    start_color
-    curs_set 0
-    raw
+    initscr
     cbreak
     noecho
+    curs_set 0
     clear
     move 10, 10
     standout
@@ -82,22 +113,23 @@ or as included methods:
 
 == Typical initialization
 
-  stdscr = FFI::NCurses.initscr
+  FFI::NCurses.initscr
   FFI::NCurses.start_color
   FFI::NCurses.curs_set 0
   FFI::NCurses.raw
-  FFI::NCurses.cbreak
   FFI::NCurses.noecho
-  FFI::NCurses.keypad(stdscr, true)
+  FFI::NCurses.keypad(FFI::NCurses.stdscr, true)
 
 == Colours
 
   start_color
   init_pair(1, FFI::NCurses::COLOR_BLACK, FFI::NCurses::COLOR_RED)
   attr_set FFI::NCurses::A_NORMAL, 1, nil
-  addch("A"[0].ord) # works in both 1.8.x and 1.9.x
+  addch("A"[0].ord) # works in both 1.8.7 and 1.9.x
   addch("Z"[0].ord | COLOR_PAIR(1))
 
+See +examples/color.rb+ for an example of use.
+
 == Cursor
 
 === Turn cursor off
@@ -123,25 +155,30 @@ or as included methods:
     ch = wgetch(inner_win)
     delwin(win)
 
-  rescue Object => e
+  rescue => e
     FFI::NCurses.endwin
-    puts e
+    raise
   ensure
     FFI::NCurses.endwin
   end
 
-== Mouse handling
+== Panels
 
-The ncurses mouse API is defined in a separate file. To include it use:
+See +examples/panel_simple.rb+ for how to use panels.
+
+== Mouse handling
 
-  require 'ffi-ncurses/mouse'
+NOTE: In previous versions of ffi-ncurses, the ncurses mouse API was
+included separately. You now no longer need to <tt>require
+'ffi-ncurses/mouse'</tt> to get mouse support.
 
-You need to specify that you want keypad translation with:
+To use the mouse with ffi-ncurses, you first need to specify that you
+want keypad translation with:
 
-  keypad stdscr, FFI::NCurses::TRUE
+  keypad stdscr, true
 
 otherwise your program will receive the raw mouse escape codes,
-instead of KEY_MOUSE mouse event codes.
+instead of +KEY_MOUSE+ mouse event codes.
 
 Specify which events you want to handle with:
 
@@ -169,31 +206,63 @@ or
 
   if FFI::NCurses.BUTTON_PRESS(mouse_event[:bstate], 1)
 
-The possible button states are: PRESS, RELEASE, CLICK, DOUBLE_CLICK
-and TRIPLE_CLICK.
+The possible button states are: +PRESS+, +RELEASE+, +CLICK+,
++DOUBLE_CLICK+ and +TRIPLE_CLICK+.
 
-= Experimental stuff
+See +examples/mouse.rb+ for a complete example.
 
 == Specifying which curses library to use
 
 You can specify which variant of curses you want to use by setting the
 environment variable +RUBY_FFI_NCURSES_LIB+ to the one you want. For
-example, to use PDCurses X11 curses lib, use:
+example, to use the PDCurses X11 curses lib, use:
+
+  RUBY_FFI_NCURSES_LIB=XCurses ruby examples/example.rb
+
+You could also use this to specify ncursesw-dbg for example to get
+access to the +trace+ functions.
+
+= Examples
+
++examples/acs_chars.rb+      :: How to display box drawing characters
++examples/attributes.rb+     :: How to set attributes
++examples/color.rb+          :: How to initialize and use colour
++examples/cursor.rb+         :: How to turn the cursor on and off
++examples/doc-eg1.rb+        :: Example 1 from the documentation
++examples/doc-eg2.rb+        :: Example 2 from the documentation
++examples/doc-eg3.rb+        :: Example 3 from the documentation
++examples/example.rb+        :: An example showing off the main features of ncurses
++examples/getkey.rb+         :: How to get Unicode input
++examples/getsetsyx.rb+      :: Shows how to use the getsetyx function
++examples/globals.rb+        :: Display ncurses global variables
++examples/hello.rb+          :: Hello world
++examples/hellowide.rb+      :: Hello world using wide characters
++examples/keys.rb+           :: How to use the getch function. See getkey for a more general solution
++examples/mouse.rb+          :: How to use the mouse
++examples/multiterm.rb+      :: How to display on more than one tty
++examples/newterm.rb+        :: How to use +newterm+ so you can pipe stdin into an ncurses program
++examples/panel_simple.rb+   :: How to use panels
++examples/printw-variadic.rb+:: How to call the +printw+ method
++examples/ripoffline.rb+     :: An example of the +ripoffline+ method
++examples/softkeys.rb+       :: How to set up soft keys (function key labels)
++examples/stdscr.rb+         :: Shows that +initscr+ returns same value as +stdscr+
++examples/temp_leave.rb+     :: How to temporarily shell out from an ncurses program
++examples/viewer.rb+         :: A simple file viewer (lesser than less) that shows how to use pads and pop up windows
++examples/wacs_chars.rb+     :: How to display wide (Unicode) box drawing characters
++examples/windows.rb+        :: Move a window about the screen
+
+= Issues
+
+Please report any issues on the {https://github.com/seanohalpin/ffi-ncurses/issues github issues} page.
 
-  RUBY_FFI_NCURSES_LIB=XCurses ruby examples/hello.rb
+= Trivia
 
-You can use this to specify +ncursesw+ for example. Please note that
-only the bog standard ncurses lib has been in any way tested as of
-yet.
+While researching ncurses on Google, I innocently entered "curses
+getsx" as a search term. NSFW and definitely not one for "I'm Feeling
+Lucky".
 
 = TO DO
 
-== Complete translation of core functions to Darwin (Mac OS X)
-
-There are some macros in darwin ncurses.h which I haven't
-implemented yet. I'm working on it but if there are any you
-desperately need let me know.
-
 == Tests
 
 This is tricky - I'm not sure exactly how to properly test a wrapper
@@ -209,17 +278,8 @@ the output. However, this is not really ready for prime time yet.
 Things got a bit messy as I switched between the Linux and Mac
 versions. The examples should be more focussed.
 
-== Scope implementation of Menu and Form interface wrappers
+= Credits
 
-I'm not particularly interested in the ncurses extension libraries for
-forms and menus. I would rather spend time implementing similar
-functionality on top of a portable text console library (or porting
-rbcurses). However, in the interests of completeness, I suppose I
-ought to at least scope it out.
-
-= Trivia
+Thanks to rahul and manveru for their support!
 
-While researching ncurses on Google, I innocently entered "curses
-getsx" as a search term. NSFW and definitely not one for "I'm Feeling
-Lucky".
 

data/Rakefile

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require 'ffi-ncurses/version'
+project = FFI::NCurses
+
+require 'rake/testtask'
+require 'yard'
+
+Rake::TestTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => %w(spec)
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = %w[--readme README.rdoc]
+end
+
+desc "Build #{project::NAME}-#{project::VERSION} gem"
+task :gem do
+  system "gem build #{project::NAME}.gemspec"
+end
+
+desc "Push #{project::NAME}-#{project::VERSION} gem to rubygems.org"
+task :release => :gem do
+  system "gem push #{project::NAME}-#{project::VERSION}.gem"
+end
+

data/examples/acs_chars.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8; -*-
+require 'ffi-ncurses'
+
+include FFI::NCurses
+
+def main
+  begin
+    initscr
+
+    addstr("Upper left corner           "); addch(ACS_ULCORNER); addstr("\n");
+    addstr("Lower left corner           "); addch(ACS_LLCORNER); addstr("\n");
+    addstr("Lower right corner          "); addch(ACS_LRCORNER); addstr("\n");
+    addstr("Tee pointing right          "); addch(ACS_LTEE); addstr("\n");
+    addstr("Tee pointing left           "); addch(ACS_RTEE); addstr("\n");
+    addstr("Tee pointing up             "); addch(ACS_BTEE); addstr("\n");
+    addstr("Tee pointing down           "); addch(ACS_TTEE); addstr("\n");
+    addstr("Horizontal line             "); addch(ACS_HLINE); addstr("\n");
+    addstr("Vertical line               "); addch(ACS_VLINE); addstr("\n");
+    addstr("Large Plus or cross over    "); addch(ACS_PLUS); addstr("\n");
+    addstr("Scan Line 1                 "); addch(ACS_S1); addstr("\n");
+    addstr("Scan Line 3                 "); addch(ACS_S3); addstr("\n");
+    addstr("Scan Line 7                 "); addch(ACS_S7); addstr("\n");
+    addstr("Scan Line 9                 "); addch(ACS_S9); addstr("\n");
+    addstr("Diamond                     "); addch(ACS_DIAMOND); addstr("\n");
+    addstr("Checker board (stipple)     "); addch(ACS_CKBOARD); addstr("\n");
+    addstr("Degree Symbol               "); addch(ACS_DEGREE); addstr("\n");
+    addstr("Plus/Minus Symbol           "); addch(ACS_PLMINUS); addstr("\n");
+    addstr("Bullet                      "); addch(ACS_BULLET); addstr("\n");
+    addstr("Arrow Pointing Left         "); addch(ACS_LARROW); addstr("\n");
+    addstr("Arrow Pointing Right        "); addch(ACS_RARROW); addstr("\n");
+    addstr("Arrow Pointing Down         "); addch(ACS_DARROW); addstr("\n");
+    addstr("Arrow Pointing Up           "); addch(ACS_UARROW); addstr("\n");
+    addstr("Board of squares            "); addch(ACS_BOARD); addstr("\n");
+    addstr("Lantern Symbol              "); addch(ACS_LANTERN); addstr("\n");
+    addstr("Solid Square Block          "); addch(ACS_BLOCK); addstr("\n");
+    addstr("Less/Equal sign             "); addch(ACS_LEQUAL); addstr("\n");
+    addstr("Greater/Equal sign          "); addch(ACS_GEQUAL); addstr("\n");
+    addstr("Pi                          "); addch(ACS_PI); addstr("\n");
+    addstr("Not equal                   "); addch(ACS_NEQUAL); addstr("\n");
+    addstr("UK pound sign               "); addch(ACS_STERLING); addstr("\n");
+
+    refresh
+    getch
+  rescue => e
+    endwin
+    raise
+  ensure
+    endwin
+  end
+end
+
+main