Cleaned up some documentation on `Key`, and working harder to coerce `Key#initialize...
[nfoiled.git] / README.markdown
blob7b71461f0b3331079643bab4a586e25f5f72eac0
1 Nfoiled
2 =======
3 The Rubyist's interface to [Ncurses][].
5   [Ncurses]: <http://www.gnu.org/software/ncurses/> "ncurses - terminal text handling library"
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!
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"
21 Installing
22 ----------
23 You can install Nfoiled as a pre-built gem, or as a gem generated directly
24 from the source.
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:
29     sudo gem install nfoiled # You'll be asked for your account password.
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:
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.
38 Finally, you can build a gem from the latest source yourself. You need [git][],
39 as well as [rake][]:
41     git clone git://github.com/elliottcable/nfoiled.git
42     cd nfoiled
43     rake install # You'll be asked for your account password.
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"
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.
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
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>
94 License
95 -------
96 Nfoiled is copyright 2008 by elliott cable.
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).
102   [gpl]: <http://www.gnu.org/licenses/gpl.txt> "The GNU General Public License v3.0"