README

= Rum, the gRand Unified Mapper

Rum is a powerful mapper for your Rack applications that can be used
as a microframework.  Just throw in a template engine and a data
backend, and get started!

== Mappings

Rum apps use a small DSL to set up the mappings:

  MyApp = Rum.new {
    on get, path('greet') do
      on param("name") do |name|
        puts "Hello, #{Rack::Utils.escape_html name}!"
      end
      on default do
        puts "Hello, world!"
      end
    end
  }

This will map GET /greet to the hello world, and GET /greet?name=X to
a personal greeting.

Mappings are declared by nested "on"-calls.  When one matched, the
block is called and other "on"-calls are ignored on that level.  (But
note you can use "also" to reset this.)

Multiple "on"-calls can be collapsed to one:

  on a do |x|
    on b do |y|
      ...
    end
  end

is the same as 

  on a, b do |x, y|
    ...
  end

Every predicate returns data which is passed to the block.  Use _ to
ignore data you don't need when using the collapsed calling method:

  on get, path('foo'), param('bar') do |_, _, bar| ... end

== Predicates

These predicates are predefined for your mappings:

path(rx): match rx against the PATH_INFO beginning and try to match a
  path segment.  (path('foo') will match '/foo/bar', but not '/foobar').
  PATH_INFO and SCRIPT_NAME are adjusted appropriately.

number: match a number segment in path.

segment: match any single segment in path.  (i.e. no '/'.)

extension(e=...): match (if given) and yield the file extension.

param(p, default=...): check if parameter p is given, else use default
  if passed.

header(p, default=...): check if HTTP header h exists, else yield default
  if passed.

default: always match.

host(h): check if the request was meant for host (useful for virtual
  servers).

method(m): check if the request used m as HTTP method.

get, post, put, delete: shortcuts for method(m).

accept(m): check if the request accepts MIME-type m.  This is a very
  simple check that doesn't handle parameters or globs for now.

check{block}: general check whether block returns a trueish value.

any(...): meta-predicate to check if any argument matches.

== Helpers

For convenience, Rum provides a few helpers:

env, req, res: The current Rack env, Rack::Request, Rack::Response.

also: Reset state of matching, that is, the next on() will be checked,
  even if one before already matched.

run(app): directly transfer to the Rack application app (which can be
  another Rum app.)

print, puts: wrappers for res.write.

== Copyright

Copyright (C) 2008, 2009 Christian Neukirchen <http://purl.org/net/chneukirchen>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

== Links

Rack:: <http://rack.rubyforge.org/>
Christian Neukirchen:: <http://chneukirchen.org/>