There are two ways to use ruby-web: as a replacement for cgi.rb, and as an extension to the Ruby interpreter. Installing ruby-web as a library is simple, and gives one access to the useful functions of ruby-web. There are a few additional features which can be provided at a higher level.

Dependencies

Both the library and interpreter installations of ruby-web depend on Ruby 1.8.x.

Scaling options include:

Library Features

Interpreter Features

All of the above, plus:

ruby-web source code and binary distributions can be found at http://rubyforge.org/frs/?group_id=873.

Finally, please note that these install instructions are a work in progress. Please report any problems at http://rubyforge.org/tracker/?group_id=873, so that we can solve your problem, and improve.

The simplest way to install ruby-web is to install the gem:

% gem install ruby-web
     

Then, you can use ruby-web in your cgi programs:

#!/usr/bin/env ruby

require 'rubygems'
require_gem 'ruby-web'

Web::open do
  puts "Hello World"
end
			

Another way to install ruby-web as a library is to use the tar.gz distribution

% tar -xvzf ruby-web_x.x.x.tar.gz
% cd ruby-web_x.x.x
% ruby install.rb config
% ruby install.rb setup
% ruby install.rb install
       

Similar to above, you can now use ruby-web in your cgi programs:

#!/usr/bin/env ruby

require 'web'

Web::open do
  puts "Hello World"
end

Note: for compatibility with cgi.rb:

require "web/shim/cgi"

Note: this this does compile and install the ruby-web interpreter, but you are free to ignore it.

Note: these examples are compatible with FastCGI and mod_ruby. Configure your webserver, and in the case of fastcgi, install the fastcgi ruby libraries. Ruby-web will detect the server environment and run appropriately.

Download the latest ruby-web_x.x.x.tar.gz. Run the enclosed installer:

% cd ruby-web_x.x.x
% ruby install.rb config
% ruby install.rb setup
% ruby install.rb install

This will compile and install the ruby-web interpreter into the same directory as ruby. If you are running ruby-web as a cgi, all you need to do is swap ruby-web for ruby:

#!/usr/bin/ruby-web

puts 'Hello, World'

FastCGI

After configuring ruby-web as the interpreter, you need the library to run fastcgi.

You will still need to do the standard FastCGI config on your webserver. You can find a links to extensions for Apache and other web servers at http://www.fastcgi.com

Mod Ruby

To use the ruby-web interpreter with mod_ruby, there is a slightly different configuration for http.conf:

  <IfModule mod_ruby.c>
  RubySafeLevel 0
  # for Web::RubyRun
  RubyRequire web/sapi/apache

  <Location / >
      Options Indexes FollowSymLinks ExecCGI
      AddHandler ruby-object cgi rb rhtml
      RubyHandler Web::RubyRun.instance
  </Location>
  </IfModule>
  

Webrick

ruby-web provides a Web::RubyWebHandler, based on the CGIHandler, to run ruby-web scripts. You will need to add the Web::RubyWebHandler to webrick with a startup script like this, replacing :DocumentRoot with the appropriate value:

    #!/usr/local/bin/ruby
    $: << File.dirname($0)
    require 'webrick'
    require 'web/sapi/webrick'

    include WEBrick

		# These lines configure webrick to handle .rb and .rhtml files with ruby-web
    HTTPServlet::FileHandler.add_handler("rb", Web::RubyWebHandler)
    HTTPServlet::FileHandler.add_handler("rhtml", Web::RubyWebHandler)

    s = HTTPServer.new(:Port            => 80,
                       :DocumentRoot    => "./htdocs" )
    trap("INT"){ s.shutdown }
    s.start
 

The simplest way to install ruby-web is to use the installer found in the ruby-web.x.x.x-powerpc-darwin.dmg. This will install ruby-web and configure the default Apache with mod_ruby.

The installer has been tested on Mac OS X Tiger (10.4). Please let me know (install.help@hexane.org) if you have success or failure on other versions of Mac OS X.

If the installer does not work on your version of Mac OS X, use the unix instructions to install and configure ruby-web by hand.

Templates can be loaded using Web::load(filename). ruby-web loads .rb files as ruby, and assumes everything else is an erb template. Below is a short guide to erb templating:

The ruby-web interpreter will open a connection to the webserver and load the first command-line argument using Web::load. In a script, one can include additional files using Web::load.

In a ruby script, one can also open a Web::Connection using Web::open. This is not recommended, but is documented here for use in unsupported server environments.

Variables directly submitted by the client are parsed into hashes of { name => [ multiple, values ] } :

These hashes are merged together into Web::request, which also is a hash of { name => [ multiple, values ] }. Web[param] is a convenience method to return single values.

File uploads are parsed into Web::Upload objects, with the following methods:

Environment variables are copied into a case-insensitive, duck-typing hash (eg Web::env[:script_name])

Reference

Config directives are set using Web::config[:directive] = value. If desired, config directives can be set within 'site_lib/x.x/web/site-config.rb'.

Below is a list of available config directives:

ruby-web ships with the cgi.rb interface, adapted to use the ruby-web infrastructure.

require 'web/shim/cgi'
cgi = CGI.new
# ...

You can customize how ruby-web load templates:

require 'web/phprb'

Web::config['load_suffix']['rhtml'] = lambda do |scriptname|
  PHPRB::load(scriptname)
end
 
# or, if you really really love your templating language:
Web::config['load_suffix'].default = lambda do |scriptname|
  PHPRB::load(scriptname)
end

Web::load('template.rhtml') # <= will be processed by phprb

phprb is an experimental template parser derived from erb, but not as inspired by the systems invented by Sun and Microsoft. It has the following rules:

To access these functions, include Web::Testing in your testcase

require 'web/testing'
require 'web/unit/testcase'
class MyWebTest << Test::Unit::TestCase
  include Web::Testing
  #...
end

ruby-web is written by Patrick May and Tom Clarke, 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.

ruby-web contains code from the following projects, and we are in their debt:

Much of the installation portion of the manual has been derived from the PHP manual. Below are the many contributers to this great resource.

Authors and Contributors

We highlight the currently most active people on the manual frontpage, but there are many more contributors who currently help in our work or provided a great amount of help to the project in the past. There are a lot of unnamed people who help out with their user notes on manual pages, which continually get included in the references, the work of whom we are also very thankful for. All the lists provided below are in alphabetical order.

Authors and Editors

The following contributors should be recognized for the impact they have made and/or continue to make by adding content to the manual: Jouni Ahto, Alexander Aulbach, Daniel Beckham, Stig Bakken, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Rafael Martinez, Yasuo Ohgaki, Derick Rethans, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar and Andrei Zmievski.

The following contributors have done significant work editing the manual: Stig Bakken, Hartmut Holzgraefe and Egon Schmid.

User Note Maintainers

The currently most active maintainers are: Mehdi Achour, Friedhelm Betz, Vincent Gevers, Aidan Lister, Nuno Lopes and Tom Sommer.

These people have also put a lot of effort into managing user notes: Daniel Beckham, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, James Cox, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Rasmus Lerdorf, Andrew Lindeman, Maxim Maletsky, James Moore, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Jani Taskinen, Yasuo Ohgaki, Philip Olson, Lars Torben Wilson, Jim Winstead, Jared Wyles and Jeroen van Wolffelaar.