README

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 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): testunit.talbott.ws/packages/testunit-0.1.6.tar.gz

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

You can use raa-install (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: www.narf-lib.org

Project info page, including downloads and CVS instructions: 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. 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). 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. www.xpenguin.biz/download/webunit/index-en.html

Thanks also go to www.sourceforge.net for hosting the project’s CVS and website