README.markdown

   1 Nfoiled
   2 =======
   3 The Rubyist's interface to [Ncurses][].
   4
   5   [Ncurses]: <http://www.gnu.org/software/ncurses/> "ncurses - terminal text handling library"
   6
   7 History
   8 -------
   9 As in, "Ncurses, Nfoiled Nagain!". Nfoiled is an object-oriented Ruby wrapper
  10 for [ncurses-ruby][], and therefore, Ncurses. I really got tired of the
  11 idiosyncrasies of Ncurses' API (it's written in a C style, not very clean, and
  12 definitely not object-oriented)... since ncurses-ruby does nothing more than
  13 make the C API available to Ruby as methods, it's no better. While working on
  14 [rat][], I set out to abstract the ncurses-ruby API to a system of objects and
  15 classes, in the truly Ruby style I'm used to. Now I've decided to abstract
  16 this code out and make it available separately... hence Nfoiled!
  17
  18   [ncurses-ruby]: <http://ncurses-ruby.berlios.de/> "ncurses-ruby - access the ncurses library in Ruby"
  19   [rat]: <http://github.com/elliottcable/rat> "rat - terminal chat client"
  20
  21 Installing
  22 ----------
  23 You can install Nfoiled as a pre-built gem, or as a gem generated directly
  24 from the source.
  25
  26 The easiest way to install Nfoiled is to use [RubyGems][] to acquire the
  27 latest 'release' version from [RubyForge][], using the `gem` command line tool:
  28
  29     sudo gem install nfoiled # You'll be asked for your account password.
  30
  31 Alternatively, you can acquire it (possibly slightly more up-to-date,
  32 depending on how often I update the gemspec) from GitHub as follows:
  33
  34     # If you've ever done this before, you don't need to do it now - see http://gems.github.com
  35     gem sources -a http://gems.github.com
  36     sudo gem install elliottcable-nfoiled # You'll be asked for your account password.
  37
  38 Finally, you can build a gem from the latest source yourself. You need [git][],
  39 as well as [rake][]:
  40
  41     git clone git://github.com/elliottcable/nfoiled.git
  42     cd nfoiled
  43     rake install # You'll be asked for your account password.
  44
  45   [git]: <http://git-scm.com/> "git - Fast Version Control System"
  46   [RubyGems]: <http://rubyforge.org/projects/rubygems/> "RubyGems - Ruby package manager"
  47   [RubyForge]: <http://rubyforge.org/projects/nfoiled/> "Nfoiled on RubyForge"
  48
  49 Contributing
  50 ------------
  51 You can contribute bug fixes or new features to Nfoiled by forking the project
  52 on GitHub (you'll need to register for an account first), and sending me a
  53 pull request once you've committed your changes.
  54
  55 Links
  56 -----
  57 - [GitHub](http://github.com/elliottcable/nfoiled "Nfoiled on GitHub")
  58     is the project's primary repository host, and currently also the project's
  59     home page
  60 - [RubyForge](http://rubyforge.org/projects/nfoiled "Nfoiled on RubyForge")
  61     is out primary RubyGem host, as well as an alternative repository host
  62 - [integrity](http://integrit.yreality.net/nfoiled "Nfoiled on yreality's integrity server")
  63     is out continuous integration server - if the top build on that page is
  64     green, you can assume the latest git HEAD is safe to run/install/utilize.
  65 - [Gitorious](http://gitorious.org/projects/nfoiled "Nfoiled on Gitorious")
  66     is an alternative repository host
  67 - [repo.or.cz](http://repo.or.cz/w/nfoiled.git "Nfoiled on repo.or.cz")
  68     is an alternative repository host
  69
  70 Goals & Todo
  71 ------------
  72 1. Manage tiling, to some extent, for the user:
  73    a. Automatically align windows to the proper locations
  74    b. Automatically resize existing windows to accomodate newly created ones
  75    c. Manage the handling window resizing, and allow user to specify how each
  76       window should handle resizing
  77 2. Manage efficient updating as much as possible:
  78    a. Maintain an "event loop" of updates, and ensure that quickly-sequential
  79       window updates correspond to a single `update!` call
  80    b. Allow users actions' to schedule updates in sequence
  81 3. Handle keys/input for the user:
  82    a. Run a loop that tracks all input, automatically handling key sequences
  83       without Ncurses' signature blocking delay bullshit
  84    b. Provide default callbacks for common operations, such as navigating in
  85       an input area
  86    c. Allow user to override callbacks with their own blocks, to be run on the
  87       input of specific keys
  88 4. Never, ever touch Ncurses' horrid GUI-emulation bits (mouse handling,
  89    overlapping panels, window borders, widgets). People who want that retarded
  90    shit can call directly out to Ncurses, or even just suck it. Seriously,
  91    people, stop trying to emulate GUIs in a terminal! Textmode UI is a totally
  92    different art. Learn it, take a look at `irssi` or `rat` some time. </rant>
  93
  94 License
  95 -------
  96 Nfoiled is copyright 2008 by elliott cable.
  97
  98 Nfoiled is released under the [GNU General Public License v3.0][gpl], which
  99 allows you to freely utilize, modify, and distribute all Nfoiled's source code
 100 (subject to the terms of the aforementioned license).
 101
 102   [gpl]: <http://www.gnu.org/licenses/gpl.txt> "The GNU General Public License v3.0"