narf 0.5.1

data/build.rb~

@@ -0,0 +1,314 @@
+#!/usr/bin/env ruby
+
+# require 'stringio'
+
+# GC.disable
+require 'ftools'
+require 'find'
+
+def temp_dir
+    (ENV["TEMP"] || "/tmp").gsub(/\\+/, "/")
+end
+
+def make_temp( path )
+  File.join( temp_dir, path)
+end
+
+
+
+def File.rm_rf( path )
+  if File.exists? path
+    doomed = []
+    Find.find( path ) { |filename|
+      doomed.push filename
+    }
+    doomed.reverse.each{ |filename|
+      if File.directory? filename
+        Dir.rmdir( filename )
+      else
+      File.delete( filename )
+      end
+    }
+  end
+end
+
+module Test
+    module Unit
+	class TestCase
+	    @@subclasses = []
+	    
+	    def TestCase.inherited(sub)
+		@@subclasses.push sub
+	    end
+	    
+	    def TestCase.all_suite
+		suite = Test::Unit::TestSuite.new
+		@@subclasses.each{ |sub|
+		    suite << sub.suite # te
+		}
+		suite
+	    end
+	end
+    end
+end
+
+class Target
+    @@targets = {}
+    def Target.run(name="")
+	if (keys.include? name)
+	    @@targets[name].run
+	else
+	    help_text
+	end
+    end
+
+    def Target.keys
+        @@targets.keys.sort
+    end
+
+    def Target.first
+	keys.first
+    end
+
+    def Target.justify
+	justify = 0
+
+	keys.each { |key|
+	    justify = key.length if (key.length > justify)
+	}
+
+	justify + 1
+    end
+
+    def Target.help_text
+	text  = "Usage:   ruby build.rb [ #{ keys.join( " | ") } ]" + $/
+	text += @@targets[keys.first].help_text( "Options: ", justify )
+	keys.slice(1...keys.length).each{ |key|
+	    text += @@targets[key].help_text( "         ", justify )
+	}
+	puts text
+    end
+
+    attr_reader :name, :description
+    def initialize( name, description, &run )
+	@name = name
+	@description = description
+	@run = run || Target.method(:help_text)
+	@@targets[name] = self
+    end
+
+    def run
+	$stderr.puts "Target: " + name + " | " + description
+	@run.call
+    end
+
+    def help_text( prefix, justify )
+	prefix + name.ljust(justify) + " -- " + description + $/
+    end
+end
+
+Target.new( "upload_doc", "upload doc" ) {
+    Target.run( "rdoc" )
+    `scp -r rdoc/* patsplat@ssh.narf-lib.org:~/narf-lib.org/doc`
+}
+
+  Target.new( "rdoc", "build rdoc" ) {
+    begin
+      require 'rdoc/rdoc'
+      
+      rdoc = RDoc::RDoc.new
+      rdoc.document( [  
+                       # set the output directory
+                       "-o", 
+                      "doc/rdoc/",
+                      
+                      # set the main page
+                      "--main",
+                      "README",
+                      
+                      # list the files to be excluded
+                      "--exclude",
+                      /htmltools|htmlparser|unit|writableio|tagparser|strscanparser|web\/action|assertinclude|buffer|formreader|forms|runner|simpledispatcher|traceoutput|linker|page|lib\/web\/sapi/,
+
+                      # list the files / dirs to be parsed for documentation
+                      "README",
+                      "examples/examples.rdoc",
+                      "lib/web.rb",
+                      "lib/web",
+                      "doc/apache_cgi.txt",
+                      "doc/fastcgi.txt",
+                      "doc/mod_ruby.txt",
+                      "doc/webrick.txt"
+                       
+			  ] )
+    rescue LoadError => error
+	puts "Building the rdocs will require 'rdoc/rdoc'"
+	puts "visit http://rdoc.sourceforge.net/ to obtain this library"
+    end
+}
+
+Target.new( "test", "run narf unit tests" ) {
+    require 'test/unit'
+    require 'test/unit/ui/console/testrunner'
+
+    $:.replace(['lib'].concat($:))
+
+    require 'web'
+
+    Dir["test/*.rb"].each { |test|
+	require test
+    }
+
+    # buffered test runner is a custom made test runner
+    # that lives in the test dir
+    Test::Unit::UI::Console::TestRunner.new(Test::Unit::TestCase.all_suite
+						    ).start
+}
+  
+  Target.new( "testwiki", "test narf wiki" ) {
+    require 'test/unit'
+    require 'test/unit/ui/console/testrunner'
+
+    $:.replace(['./lib/'].concat($:)) 
+
+    require 'web'
+    require 'web/wiki'
+
+    def setup_wiki
+      File.rm_rf( Web::Wiki::store_dir )
+    end
+    
+    alias :teardown_wiki :setup_wiki
+
+    Web::Wiki::set_pref(:store_dir  => make_temp("test.pages/"),
+                        :store_url  => "../test.pages/",
+                        :tarpit_dir => make_temp("tarpit/"),
+                        :vandals    => "vandals.test.txt",
+                        :baseurl    => "wiki.rb" )
+    Web.set_docroot( File.join(Dir.pwd,"examples") )
+
+    # a bunch of the illustration_page functions don't work on windows
+    #require 'test/wiki/test.illustration_page.rb'
+    Dir["test/wiki/*.rb"].each { |test|
+      require test
+    }
+    #require 'test/wiki/test.wiki.rb'
+
+    # buffered test runner is a custom made test runner
+    # that lives in the test dir
+    Test::Unit::UI::Console::TestRunner.new(Test::Unit::TestCase.all_suite).start
+
+}
+
+Target.new( "testwebunit", "test web unit" ) {
+    $: << "lib"
+    ENV['URLBASE'] = ARGV[1] || "http://www.hexane.org/webtest/"
+    
+    require 'web/unit/runtest'
+    
+    Web::Unit.runtest(Dir["test/webunit/test*.rb"])
+}
+
+Target.new( "testexamples", "test narf examples" ) {
+    require 'test/unit'
+    require 'test/unit/ui/console/testrunner'
+
+    $:.replace(['./lib/'].concat($:)) 
+
+    require 'web'
+    require 'web/wiki'
+
+    Web.set_docroot File.join(Dir.pwd,"examples")
+
+    Dir["examples/test/*.rb"].each { |test|
+        require test
+    }
+
+    # buffered test runner is a custom made test runner
+    # that lives in the test dir
+    Test::Unit::UI::Console::TestRunner.new(Test::Unit::TestCase.all_suite ).start
+}
+
+
+def install_dir
+    $:.find { |dir|
+        /site_ruby\/\d.\d\z/ =~ dir
+    } + "/"
+end
+
+FILES = [ "web",
+          "web.rb",
+          "web/action.rb",
+	  "web/assertinclude.rb",
+	  "web/buffer.rb",
+	  "web/request.rb",
+	  "web/session.rb",
+	  "web/template.rb",
+	  "web/writableio.rb",
+          "web/rhp.rb" ]
+
+OLD_FILES = [ "web",
+              "narf.rb",
+	      "narf/app.rb",
+	      "narf/assertinclude.rb",
+	      "narf/buffer.rb",
+	      "narf/request.rb",
+	      "narf/session.rb",
+	      "narf/template.rb",
+	      "narf/writableio.rb"	]
+
+Target.new( "uninstall", "delete narf files from site_ruby" ){
+
+    file_list = (FILES.reverse | OLD_FILES.reverse ).collect{|file|
+        install_dir + file
+    }
+
+    file_list.push( "/usr/bin/rhp")
+
+    file_list.each{ |file|
+	if File.exists? file
+	    if File.stat(file).directory?
+                Dir.delete file
+	    else
+                File.delete file
+            end
+	end
+    }
+}
+
+Target.new( "compile_narf_runner", "" ) {
+  Dir.mkdir "bin" unless File.exists? "bin"
+  narf_c = File.open( 'sapi/apache_cgi/src/narf.c', 'r' ) { |f|
+    f.read
+  }
+  require 'rbconfig'
+  narf_c.gsub!( /(ruby)/, Config::CONFIG["bindir"] + "/ruby" )
+  File.open( 'sapi/apache_cgi/src/narf-path_adjusted.c', 'wb') { |f|
+    f.write(narf_c)
+  }
+  `gcc sapi/apache_cgi/src/narf-path_adjusted.c -o sapi/apache_cgi/bin/narf`
+}
+
+Target.new( "install", "install narf in site ruby" ){
+
+    Target.run( "uninstall" )
+    Target.run( "compile_rhp" )
+
+    FILES.each{ |file|
+            from, to = "lib/" + file, install_dir + file
+
+            if (File.stat(from).directory?)
+	        unless File.exists? to
+		    puts "Creating #{to}"
+                    Dir.mkdir to 
+                end
+            else
+                puts "#{ from } => #{ to }...\n"
+	        File.copy( from, to )
+            end
+    }
+
+    File.copy( "rhp", "/usr/bin/rhp" )
+}
+
+Target.run( ARGV[0] ) if ($0 == __FILE__)

data/config.save

@@ -0,0 +1,12 @@
+bin-dir=$prefix/bin
+site-ruby=$prefix/lib/ruby/site_ruby/1.8
+prefix=/usr/local
+ruby-path=/usr/local/bin/ruby
+make-prog=make
+rb-dir=$site-ruby
+without-ext=no
+ruby-prog=/usr/local/bin/ruby
+site-ruby-common=$prefix/lib/ruby/site_ruby
+std-ruby=$prefix/lib/ruby/1.8
+data-dir=$prefix/share
+so-dir=$prefix/lib/ruby/site_ruby/1.8/powerpc-darwin

data/doc/apache_cgi.txt

@@ -0,0 +1,17 @@
+The main advantage of this executable is that this runner can print syntax errors to the screen.  To compile, run this from the project root (/narf):
+
+    ruby build.rb compile_narf_runner
+
+The compiled binary will be in
+
+    /narf/apache_cgi/bin/narf
+
+Copy this file where ever you like, make it executable, and tell apache to run it with a shebang:
+
+    #!/usr/local/bin/narf
+
+This file may likely has a buffer overflow in it.  Please be cautious with this until I can get verification that it is ok.
+
+Cheers,
+
+patrick@hexane.org

data/doc/fastcgi.txt

@@ -0,0 +1,19 @@
+== FastCGI
+
+FastCGI support for narf requires the 'fcgi' libary:
+
+    http://raa.ruby-lang.org/list.rhtml?name=fcgi
+
+You can find a list of FastCGI servers here:
+
+    http://www.fastcgi.com
+
+After installing and configuring the appropriate libraries for your server, you will need to make sure that the cgi script executes in a Web::process block:
+
+    #!/usr/local/bin/ruby
+
+    Web::process{
+      Web << 'Hello World!'
+    }
+
+There is a neat continuation trick that matz discussed in [ruby-talk:13428] that makes the Web::process block unnecessary.  I've had some trouble getting it too work; when I do, I'll update these docs.

data/doc/mod_ruby.txt

@@ -0,0 +1,7 @@
+== mod_ruby
+
+Just configure mod_ruby to run your ruby scripts:
+
+    http://modruby.net/en/index.rbx/mod_ruby/install.html
+
+Narf will detect that mod_ruby is running and use the proper apis.

data/doc/rdoc/classes/Web.html

@@ -0,0 +1,366 @@
+
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Module: Web</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <link rel=StyleSheet href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript" language="JavaScript">
+  <!--
+  function popCode(url) {
+    window.open(url, "Code", 
+          "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+  //-->
+  </script>
+</head>
+
+<body bgcolor="white">
+
+<table summary="Information on class" width="100%" border="0" cellspacing="0">
+ <tr class="title-row">
+ <td class="big-title-font">
+   <sup><font color="aqua">Module</font></sup> Web
+ </td>
+ <td align="right">
+   <table summary="layout" cellspacing="0" cellpadding="2">
+     <tr valign="top">
+      <td class="small-title-font">In:</td>
+      <td class="small-title-font">
+        <a href="../files/lib/web_rb.html" class="aqua">
+lib/web.rb
+         </a>
+<br />
+        <a href="../files/lib/web/wiki_rb.html" class="aqua">
+lib/web/wiki.rb
+         </a>
+<br />
+        <a href="../files/lib/web/upload_rb.html" class="aqua">
+lib/web/upload.rb
+         </a>
+<br />
+        <a href="../files/lib/web/testing_rb.html" class="aqua">
+lib/web/testing.rb
+         </a>
+<br />
+        <a href="../files/lib/web/template_rb.html" class="aqua">
+lib/web/template.rb
+         </a>
+<br />
+        <a href="../files/lib/web/session_rb.html" class="aqua">
+lib/web/session.rb
+         </a>
+<br />
+        <a href="../files/lib/web/parser_rb.html" class="aqua">
+lib/web/parser.rb
+         </a>
+<br />
+        <a href="../files/lib/web/mime_rb.html" class="aqua">
+lib/web/mime.rb
+         </a>
+<br />
+        <a href="../files/lib/web/cgi_rb.html" class="aqua">
+lib/web/cgi.rb
+         </a>
+<br />
+      </td>
+     </tr>
+   </table>
+  </td>
+  </tr>
+</table>
+  <!-- banner header -->
+
+
+
+<div class="description"><h2>Purpose</h2>
+<p>
+<a href="Web.html">Web</a> provides an infrastructure for building and
+testing web applications.
+</p>
+<h2>Usage</h2>
+<p>
+Use the <a href="Web.html">Web</a> module to interact with the client. The
+module delegates to a <a href="Web/CGI.html">Web::CGI</a> object, which
+does the actual work.
+</p>
+<pre>
+    #!/usr/bin/narf
+    Web[&quot;field&quot;]                      # access parameters
+    Web.cookies[&quot;muppet&quot;]             # access cookies
+    Web.session[&quot;key&quot;] ||= &quot;value&quot;    # get and set session values
+    Web.set_cookie( &quot;muppet&quot;, &quot;cookie monster&quot; ) # set cookies
+    Web.puts &quot;something&quot;              # print 'something' out
+</pre>
+<p>
+If the request contained multipart/form-data, uploaded files are returned
+as <a href="Web/Upload.html">Web::Upload</a> objects. Other parameters are
+treated as strings.
+</p>
+<h2>Output</h2>
+<p>
+You write output as if it were an IO:
+</p>
+<pre>
+    Web &lt;&lt; &quot;&lt;h1&gt;Hello World!&lt;/h1&gt;&quot;
+    Web.print &quot;&lt;p&gt;We have lots of tricks for you.&lt;br&gt;&quot;
+    Web.write &quot;From kungfu to jiujitsu&lt;br&gt;&quot;
+    Web.puts  &quot;anything and everything works&lt;/p&gt;.&quot;
+</pre>
+<p>
+or even:
+</p>
+<pre>
+    puts &quot;hello world&quot;
+</pre>
+<p>
+Narf buffers output by default. Buffered output allows you to set headers
+(cookies, redirects, status, etc.) at any point before the cgi is flushed.
+You can force this by calling:
+</p>
+<pre>
+    Web.flush
+</pre>
+<p>
+Once the headers are sent to the client, you cannot set any more headers.
+</p>
+<h2>Error Handling</h2>
+<p>
+For cgi-scripts under Apache, one can use the &#8216;bin/narf&#8217; script
+instead of using the ruby executable. This little c program doesn&#8217;t
+do much fancy, but it can trap syntax errors and send them back to the
+browser. <em>I would especially appreciate security-related feedback;
+narf.c is contributed and I am not a c programmer.</em>
+</p>
+<h2>Sessions:</h2>
+<p>
+Sessions provide a way of storing data between <a href="Web.html">Web</a>
+requests. Anything that can be marshalled can be stored in the session.
+</p>
+<h3>Getting and Setting values in a session</h3>
+<pre>
+     Web.session[&quot;key&quot;] = &quot;value&quot;
+     Web.session[&quot;key&quot;]             # =&gt; &quot;value&quot;
+</pre>
+<h3>Deleting session values</h3>
+<pre>
+     Web.session[&quot;key&quot;] = &quot;value&quot;
+     Web.session[&quot;key&quot;].delete      # =&gt; &quot;value&quot;
+     Web.session[&quot;key&quot;]             # =&gt; &quot;nil&quot;
+</pre>
+<h3>Iterating through session keys</h3>
+<pre>
+     Web.session.each do |key, val|
+         Web.puts &quot;#{key} =&gt; #{val}&lt;br&gt;&quot;
+     end
+</pre>
+<h3>Resetting the Session</h3>
+<p>
+Reseting the session to an empty hash is simple:
+</p>
+<pre>
+    Web.session.reset
+</pre>
+<h3>Testing</h3>
+<p>
+Narf takes testing very seriously. I consider supporting testing to be part
+of the contract when writing a IO library. See <a
+href="Web/Testing.html">Web::Testing</a> for more details.
+</p>
+</div>
+
+
+<table summary="Methods" cellpadding="5" width="100%">
+<tr><td class="tablesubtitle">Methods</td></tr>
+</table>
+<div class="name-list">
+<a href="#M000007">escape</a>&nbsp; &nbsp;
+<a href="#M000004">get_cgi</a>&nbsp; &nbsp;
+<a href="#M000011">get_docroot</a>&nbsp; &nbsp;
+<a href="#M000012">get_mime_type</a>&nbsp; &nbsp;
+<a href="#M000006">html_encode</a>&nbsp; &nbsp;
+<a href="#M000002">method_missing</a>&nbsp; &nbsp;
+<a href="#M000005">process</a>&nbsp; &nbsp;
+<a href="#M000009">rfc1123_date</a>&nbsp; &nbsp;
+<a href="#M000003">set_cgi</a>&nbsp; &nbsp;
+<a href="#M000010">set_docroot</a>&nbsp; &nbsp;
+<a href="#M000008">unescape</a>&nbsp; &nbsp;
+</div>
+
+
+
+<table summary="List of classes" cellpadding="5" width="100%">
+<tr><td class="tablesubtitle">Classes and Modules</td></tr>
+</table>
+<div class="classlist">
+Module <a href="Web/Parser.html" class="link">Web::Parser</a><br />
+Module <a href="Web/Testing.html" class="link">Web::Testing</a><br />
+Class <a href="Web/CGD.html" class="link">Web::CGD</a><br />
+Class <a href="Web/CGI.html" class="link">Web::CGI</a><br />
+Class <a href="Web/Mime.html" class="link">Web::Mime</a><br />
+Class <a href="Web/Narflates.html" class="link">Web::Narflates</a><br />
+Class <a href="Web/Session.html" class="link">Web::Session</a><br />
+Class <a href="Web/Upload.html" class="link">Web::Upload</a><br />
+Class <a href="Web/Wiki.html" class="link">Web::Wiki</a><br />
+
+</div>
+
+
+<table summary="Method list" cellpadding="5" width="100%">
+<tr><td class="tablesubtitle">Public Class methods</td></tr>
+</table>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000002"></a>
+<a href="Web.src/M000002.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000002.html');return false;">
+<b>method_missing</b>(method, *args, &amp;block)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+<a href="Web.html">Web</a> delegates to the current cgi object. This is the
+recommended way to use narf:
+</p>
+<pre>
+   Web[&quot;param&quot;]
+   Web &lt;&lt; &quot;hello world&quot;
+   Web.set_redirect( &quot;http://www.narf-lib.org&quot; )
+   ...
+</pre>
+<p>
+The documentation for these methods is on the <a
+href="Web/CGI.html">Web::CGI</a> object.
+</p>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000003"></a>
+<a href="Web.src/M000003.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000003.html');return false;">
+<b>set_cgi</b>( cgi )
+</a>
+</td></tr>
+</table>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000004"></a>
+<a href="Web.src/M000004.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000004.html');return false;">
+<b>get_cgi</b>()
+</a>
+</td></tr>
+</table>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000005"></a>
+<a href="Web.src/M000005.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000005.html');return false;">
+<b>process</b>(options={}, &amp;block)
+</a>
+</td></tr>
+</table>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000006"></a>
+<a href="Web.src/M000006.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000006.html');return false;">
+<b>html_encode</b>(string)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+this is a bit incomplete &#8212; only encodes ampersands
+</p>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000007"></a>
+<a href="Web.src/M000007.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000007.html');return false;">
+<b>escape</b>(string)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+Escape URL encode
+</p>
+<pre>
+    url_encoded_string = Web::escape(&quot;string&quot;)
+</pre>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000008"></a>
+<a href="Web.src/M000008.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000008.html');return false;">
+<b>unescape</b>(string)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+Unescape URL encoded
+</p>
+<pre>
+    string = Web::unescape(&quot;url encoded string&quot;)
+</pre>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000009"></a>
+<a href="Web.src/M000009.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000009.html');return false;">
+<b>rfc1123_date</b>(time)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+Make RFC1123 date string
+</p>
+<pre>
+    Web::rfc1123_date(Time.now) # =&gt; Sat, 01 Jan 2000 00:00:00 GMT
+</pre>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000010"></a>
+<a href="Web.src/M000010.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000010.html');return false;">
+<b>set_docroot</b>(docroot)
+</a>
+</td></tr>
+</table>
+<div class="description">
+<p>
+When testing, this is a useful method to tell NARF where to find your
+scripts
+</p>
+</div>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000011"></a>
+<a href="Web.src/M000011.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000011.html');return false;">
+<b>get_docroot</b>()
+</a>
+</td></tr>
+</table>
+<table summary="method"  width="100%" cellspacing="0" cellpadding="5" border="0">
+<tr><td class="methodtitle">
+<a name="M000012"></a>
+<a href="Web.src/M000012.html" target="Code" class="methodtitle"
+ onClick="popCode('Web.src/M000012.html');return false;">
+<b>get_mime_type</b>( filename )
+</a>
+</td></tr>
+</table>
+
+</body>
+</html>