=== Purpose
  
NARF is a replacement for, and derivative of, the Ruby CGI
library. It exists one reason:

* To trivialize web development

We hope that these 3 lines of development will accomplish our task:

* To provide a clean API for writing Web applications.

* To make it very easy to write testable Web applications (using
  Web::Testing), and provide a template system (Web::Narflates).

* To test the above goals by developing integrated, high quality,
  configurable versions of common web apps in a simple and easy
  to use manner.  The heart of http://www.narf-lib.org, Web::Wiki
  is an easy to use wiki.  Not the only one, but it does make
  us eat our own dogfood :-)

NARF does all of this as a regular CGI application.  It also runs in-process under fastcgi, mod_ruby, and webrick.  View these files for details:

* sapi/fastcgi/INSTALL.txt
* sapi/mod_ruby/INSTALL.txt
* sapi/webrick/INSTALL.txt

=== Installation

Run the installer for NARF:

    ruby build.rb test (optional)

    ruby install.rb config
    ruby install.rb setup
    ruby install.rb install

=== Dependencies

NARF requires the following packages on ruby 1.6.  These packages are included in ruby 1.8:

testunit (unit testing framework):
http://testunit.talbott.ws/packages/testunit-0.1.6.tar.gz

strscan (string scanner library):
http://www.loveruby.net/archive/strscan/strscan-0.6.5.tar.gz

You can use raa-install (http://www.ruby-lang.org/raa/list.rhtml?id=729) for
this:
    raa-install -i testunit
    raa-install -i strscan 

=== Hello World

    # if installed via rubygems:
    # require 'rubygems'
    require 'web'
    Web::process do
      Web << 'Hello World'
    end

=== Testing an App

If you haven't noticed, NARF has a cgi style api.  It's also has a testing api.  Given these files:

    script.rb
    test.rb

where script.rb is:

    #!/usr/bin/ruby
    require 'web'

    Web::process do
      Web << "param is #{Web["param"]}"
    end

and test.rb is:
    
    require 'web'
    require 'test/unit'

    class MyAppTest < Test::Unit::TestCase
        include Web::Testing

        def test_prints_content
            do_request "script.rb", "param" => "THIS!"
            assert_content "param is THIS!"
	end
    end

Do this to run tests:

     ruby test.rb

See Web::Testing for more examples.

=== Websites

Home page:
http://www.narf-lib.org

Project info page, including downloads and CVS instructions:
http://www.sourceforge.net/projects/narf-lib
  
=== Credits

Narf was written by Tom Clarke and Patrick May, partly based on cgi.rb
written by Wakou Aoyama. It makes significant use of ruby-htmltools,
written by Ned Konz.  Also, Keunwoo Lee patched Request.read_multipart
to be cleaner.  

NARF contains code from the following projects, and we are in their debt:

ruby-htmltools::
    This is a Ruby library for building trees representing HTML structure.
    http://bike-nomad.com/ruby
sgml-parser::
    The html-parser package is a variant language implementation of the
    Python's SGML parser (sgmllib.py), HTML parser (htmllib.py) and
    Formatter (formatter.py).
    http://www.jin.gr.jp/%7Enahi/Ruby/html-parser/README.html
webunit::
    WebUnit is Ruby API for testing html/cgi without browser, and is
    idealy suited for automated unit testing of web sites when combined
    with a Ruby unit test framework such as RubyUnit. It was designed
    and implemented by Masaki Suketa.
    http://www.xpenguin.biz/download/webunit/index-en.html

Thanks also go to http://www.sourceforge.net for hosting the
project's CVS and website