renee 0.3.11 → 0.4.0.pre1

data/site/views/layouts/app.haml

@@ -0,0 +1,16 @@
+!!!
+%html
+  %head
+    %title Renee #{title_part}
+    %link{ :href => "/css/app.css", :rel => "stylesheet" }
+    %link{ :rel => 'icon', :href => "/img/favicon.ico" }
+    %script{ :type => 'text/javascript', :src => "/js/jquery-1.6.4.min.js" }
+    %script{ :type => 'text/javascript', :src => "/js/app.js" }
+  %body
+    %a{ :href => "https://github.com/renee-project/renee" }
+      %img{ :src => '/img/russiangithub.png', :style => 'position: absolute; top: 0; left: 0; border: 0;'}
+    .container
+      .logo
+        %a{ :href => "/" }
+          %img{ :src => "/img/reneeclean.png", :title => 'IN COMMUNIST RUSSIA RENEE FRAMEWORK YOU'}
+      = preserve(yield)

data/site/views/rack-integration.md

@@ -0,0 +1,51 @@
+# Rack integration
+
+Renee loves Rack. To create a new Renee application, create a rackup file (typically `config.ru`) and load it using [shotgun](https://rubygems.org/gems/shotgun).
+
+    :::ruby
+    # config.ru
+    run Renee do
+      # ...
+    end
+
+From here, you can start consuming parts of the path. Consider:
+
+    :::ruby
+    # config.ru
+    run Renee do
+      puts env['SCRIPT_NAME'] # /
+      puts env['PATH_INFO'] # /blog/something
+      path 'blog' do
+        puts env['SCRIPT_NAME'] # /blog
+        puts env['PATH_INFO'] # /something
+        # .. 
+      end
+    end
+
+The path is being shifted from PATH_INFO and onto the SCRIPT_NAME. This makes it easy to stop what you're doing, and call into a Rack application, as your `env` will be in the correct state for dispatching to another Rack application. To dispatch at any point you can use `#run!`. Example:
+
+    :::ruby
+    # config.ru
+    OtherApp = proc { |env| [200, {}, [env['SCRIPT_NAME'], env['PATH_INFO']]]}
+
+    run Renee do
+      path 'blog' do
+        run! OtherApp
+      end
+    end
+
+Now, any request starting with `/blog` will be dispatched to `OtherApp`.
+
+If you'd like to use a full Rack::Builder, you can use `#build!`.
+
+    :::ruby
+    run Renee do
+      path 'blog' do
+        build! do
+          use SomeMiddleware
+          run SomeRackApplication
+        end
+      end
+    end
+    
+Full documentation can be found under the YARD docs for  [`Renee::Core::Application::RackIntegration`](http://reneerb.com/doc/core/Renee/Core/Application/RackInteraction.html).

data/site/views/responding.md

@@ -0,0 +1,103 @@
+# Responding
+
+## A note about bang methods
+
+Any method that ends with ! (a bang method) will do whatever the non-bang version of that method will do,
+but in addition, it will halt with that response.
+
+## `#halt`
+
+Halt will immediately stop processing and respond with the value passed to it. It will respond
+in different ways depending on what was passed to it.
+
+### `Symbol`
+
+If it's a symbol, it will attempt to look it up in [`Renee::Core::Application::Responding::HTTP_CODES`](http://reneerb.com/doc/core/Renee/Core/Application/Responding.html).
+
+    :::ruby
+    # Return status with symbol
+    halt :not_found
+
+### `String`
+
+It will use this to create a Rack::Response object and call `#finish` on it.
+
+    :::ruby
+    # Return 200 with body
+    halt "hello!"
+
+### `Array`
+
+It will attempt to interpret this as a Rack response.
+
+    :::ruby
+    # Return 200 with body
+    halt [200, {}, 'body']
+
+### `Integer`
+
+It will return this as a status code.
+    
+    :::ruby
+    # Return just 200 status code
+    halt 200
+
+## `#respond` (and `#respond!`)
+
+The `respond` command makes returning a rack response very explicit,
+you can respond as if you were constructing a Rack::Response
+
+    :::ruby
+    run Renee {
+      get { respond!("hello!", 403, "foo" => "bar") }
+    }
+
+or use the block DSL for convenience:
+
+    :::ruby
+    run Renee {
+      get { respond! { status 403; headers :foo => "bar"; body "hello!" } }
+    }
+
+## `#redirect` (and `#redirect!`)
+
+This will return a rack-response to the path supplied and an optional HTTP status code.
+
+    :::ruby
+    get {
+      redirect!('/hello')
+    }
+
+You can also specify the status code for the redirect:
+
+    :::ruby
+    get {
+      redirect!('/hello', 303)
+    }
+
+## `#render` (and `#render!`)
+
+This will render a template based on the rendering options supplied. The simplest render is just:
+
+    :::ruby
+    render! "index"
+
+Assuming you have a views_path setup (see [Settings](/settings)), this will render the first template named `index`.
+You can also specify the template engine explicitly with:
+
+    :::ruby
+    render! "index.haml"
+
+This will locate and render the haml template (`index.haml`) within views. You can also pass local variables to
+the template:
+
+    :::ruby
+    render! "index", :locals => { :foo => "bar" }
+
+and then access them as expected within the template. Using a layout is also as simple as specifying the
+layout template with a render:
+
+    :::ruby
+    render! "index", :layout => "base"
+
+This will render the index template within the base template in the views folder.

data/site/views/route-generation.md

@@ -0,0 +1,82 @@
+# Route generation
+
+To register paths for later generation, you have four methods at your disposal: `#register`, `#prefix`, `#path`, and `#url`.
+
+## `#register`
+
+This allows you to register a route for later generation:
+
+    :::ruby
+    app = Renee.new
+    app.register(:path, '/path')
+    app.path(:path) # Would return '/path'
+
+This also allows for named variables in the path:
+
+    :::ruby
+    app = Renee.new
+    app.register(:path, '/path/:id')
+    app.path(:path, 123)        # Would return '/path/123'
+    app.path(:path, :id => 123) # This would also return '/path/123'
+
+If you have default values for variables, you can pass them in on the `#register` call:
+
+    :::ruby
+    app = Renee.new
+    app.register(:blog_get, '/blog/:page', :page => 1)
+    app.path(:blog_get)    # Would return '/blog/1'
+    app.path(:blog_get, 5) # Would return '/blog/5'
+
+## `#prefix`
+
+This allows you to define common parts for nicer re-use:
+
+    :::ruby
+    app = Renee.new
+    app.prefix("http://mydomain.com") {
+      app.register(:test, "/test")
+      app.register(:test2, "/test2")
+    }
+    app.url(:test) # Would return http://mydomain.com/test
+    app.url(:test2) # Would return http://mydomain.com/test2
+
+You can even store the objects created by `#prefix` and use them later. In the above example, this would also be equivalent:
+
+    :::ruby
+    app = Renee.new
+    domain_prefix = app.prefix("http://mydomain.com")
+    domain_prefix.register(:test, "/test")
+    domain_prefix.register(:test, "/test2")
+
+This makes registering similar routes more concise.
+
+## `#path`
+
+This creates paths for the paths you have registered. The first parameter is the name of the route. After that an optional hash can be
+supplied to dictate the value of variables in the path. Any key-values not consumed by the path will be appended as a query string to
+the generated path.
+
+Example:
+
+    :::ruby
+    app = Renee.new
+    app.register(:blog, '/blog')
+    app.path(:blog)    # Would return '/blog'
+    app.path(:blog, :page => 1) # Would return '/blog?page=1'
+
+## `#url`
+
+This is identical to path with one special consideration. If the registered path had a scheme, host or port, it will be added to the generated path:
+
+    :::ruby
+    app = Renee.new
+    app.register(:blog, 'http://localhost/blog')
+    app.url(:blog)    # Would return 'http://localhost/blog'
+
+If you leave off the scheme, this will create scheme in-variant URLs:
+
+    :::ruby
+    app = Renee.new
+    app.register(:blog, '://localhost/blog')
+    app.url(:blog)    # Would return '://localhost/blog',
+                      # did I mention, these are awesome?

data/site/views/routing.md

@@ -0,0 +1,261 @@
+# Routing
+
+## Rack integration
+
+### `#run` (and `#run!`)
+
+This method will take whatever is passed to it and send `#call` to it.
+
+### `#build` (and `#build!`)
+
+This method will take run the code block passed to it and wrap it with a Rack::Builder, then run it.
+
+Example:
+
+    :::ruby
+    Renee {
+      build! {
+        use Rack::ContentLength
+        run proc {|env| [200, {}, ["hello rack!"]]}
+      }
+    }
+
+## Request context
+
+The most basic part of Renee is the request context. This gives you access to the current env,
+a Rack::Request wrapped version of the env.
+
+## Path-based
+
+All path based routing proceeds by removing the matched part from `PATH_INFO`, and adding it to the end of
+`SCRIPT_NAME` before executing the block passed to it. Therefore, only the path based routing method mutate
+the rack environment, and they are the only methods that do so.
+
+### `#path`
+
+This will match the part supplied to it.
+
+Example:
+
+    :::ruby
+    Renee {
+      path('test') {
+        halt 'i got /test!' # your path must start with /test to get here.
+      }
+    }
+
+Paths can also be nested within one another:
+
+    :::ruby
+    Renee {
+      path('blog') {
+        path('foo') { get { halt "path is /blog/foo" } }
+      }
+    }
+
+If the part supplied doesn't start with a `/`, one will be added. If there is a trailing slash, and consuming it would
+cause `PATH_INFO` to be empty, it will be consumed as well. In the above example, `/test/` would also match.
+
+### `#exact_path`
+
+This is identical to `#path`, except trailing slashes will not be matched. For example:
+
+    :::ruby
+    Renee {
+      exact_path('test') {
+        halt 'i got /test!' # your path must be /test to get here.
+      }
+    }
+
+### `#whole_path`
+
+This is identical to `#path`, except it will not execute the block unless it consumes the entire path.
+Trailing slashes will be ignored.
+
+    :::ruby
+    Renee {
+      whole_path('test') {
+        halt 'i got /test!' # your path must be exactly /test to get here.
+      }
+    }
+
+### `#part`
+
+This is similar to `#path`, except it's used for parts of the path instead of a whole part delimited by `/`'s. For example:
+
+    :::ruby
+    Renee {
+      part('one') {
+        part('two') {
+          part('three') {
+            halt "onetwothree" # this will only match /onetwothree
+          }
+        }
+      }
+    }
+
+### `#extension`
+
+You can also use `extension` as a way to define formats:
+
+    :::ruby
+    path '/test' do
+      extension 'html' do
+        halt 'html'
+      end
+      extension 'json' do
+        halt 'json'
+      end
+    end
+
+This will have `test.html` respond with 'html' and `test.json` respond with 'json'.
+
+### `#var` (also `#variable`)
+
+This will match a part of path (delimited by `/`'s) and yield that value back to the block passed to it. Example:
+
+    :::ruby
+    Renee {
+      var { |id|
+        # this will match /one and return "the id is `one'"
+        halt "the id is `#{id}'"
+      }
+    }
+
+You can access the variables (passed into the request) using the local variables yielded to the block. Variables are a powerful
+way to express expected parameters for a given set of requests. You can specify variables that match a regex:
+
+    :::ruby
+    path('blog') {
+      var(/\d+/) { |id| get { halt "path is /blog/#{id}" } }
+    }
+
+and even explicitly cast your variable types:
+
+    :::ruby
+    path('blog') {
+      var :integer do |id|
+        get { halt "path is /blog/#{id} and id is an integer" }
+      end
+    end
+
+### `#part_var` (also `#partial_variable`)
+
+This will match a part of path and yield that value back to the block passed to it.
+It will consume partial parts of the path like `#part`.
+
+### `#remainder`
+
+This will consume the remaining part of the path and yield that value to the block passed to it. Example:
+
+    :::ruby
+    Renee {
+      remainder {|p|
+        # this will match anything and yield the result.
+        halt "I got #{p} back."
+      }
+    }
+
+Notice this allows you to handle the cases within a particular route scope and manage them based on the "rest" of the uri yielded in the `remainder` block. You
+can handle different remainders in all the different path blocks.
+
+### `#complete`
+
+This will only match if the `PATH_INFO` has been entirely consumed. If the PATH_INFO was only `/`, it
+will be consumed by this method. Example:
+
+    :::ruby
+    Renee {
+      complete {
+        halt "consumption is complete" # this will only match '/' and ''
+      }
+    }
+
+## Request method-based
+
+Request methods can be defined easily:
+
+    :::ruby
+    run Renee {
+      get    { halt "a get!"  }
+      post   { halt "a post!" }
+      put    { halt "a put!"  }
+      delete { halt "a delete!" }
+    }
+
+### `#get`
+
+This will match if the path is complete and the request method is `GET`. Optionally,
+you can pass it a path, which will match using `complete_path` and then perform the request method matching.
+
+### `#put`
+
+This is the same as `#get`, except for the request method `PUT`.
+
+### `#post`
+
+This is the same as `#get`, except for the request method `POST`.
+
+### `#delete`
+
+This is the same as `#get`, except for the request method `DELETE`.
+
+## Query-based
+
+### `#query`
+
+Query allows you either match a hash of key-value pairs from the query path.
+Or, it will match a list of keys. If one of the keys is not present, this this will not yield
+the values corresponding to the keys supplied.
+
+Example:
+
+    :::ruby
+    Renee {
+      query(:key => 'value') {
+        halt "The query string contained key=value"
+      }
+
+      query :key, :secret { |key_value, secret_value|
+        halt "Key is #{key_value}, secret_value is
+          #{secret_value} (and these will never be nil)"
+      }
+    }
+
+### `#query_string`
+
+This will match an exact query string. It's equivalent to `match === env['QUERY_STRING']`
+where match is the value passed in.
+
+    :::ruby
+    path 'foo' do
+      query_string 'bar' do
+        get { halt 'BAR!' }
+      end
+
+      query_string 'baz' do
+        get { halt 'BAZ!' }
+      end
+    end
+
+This will respond to `/foo?bar` with "BAR!" and `/foo?baz` with "BAZ!".
+You can also specify query_string in a variety of other ways:
+
+    :::ruby
+    # Check key and value of query param
+    query_string 'foo=bar' do
+      post { halt [200,{},'foo'] }
+    end
+
+    # Declare query params as a hash
+    query :foo => "bar" do
+      halt 200
+    end
+
+    # Switch based on a query parameter
+    query :foo do |var|
+      case var
+      when 'bar' then halt 200
+      when 'bar2' then halt 500
+      end
+    end