renee-core 0.0.1

data/README.md

@@ -0,0 +1,242 @@
+# Renee Core
+
+## Routing
+
+Routing in `Renee` is different from any web framework you are likely to have used in the past. The syntax is most familiar to Sinatra but allows
+for far more flexibility and freedom in the way that routes and actions are defined. In a Renee, routes are defined using the `path`, `var`, `query_string`, `extension`, `remainder` and request methods.
+
+**Request Methods**
+
+The bread and butter of Renee are the request verbs reminiscent of Sinatra:
+
+```ruby
+run Renee::Core.new {
+  get    { halt "a get!"  }
+  post   { halt "a post!" }
+  put    { halt "a put!"  }
+  delete { halt "a delete!" }
+}
+```
+
+These will declare the response to "/" for each of the common request types. Notice the use of the request method to
+specify the http verb and the use of `halt` inside the block to send back the body of the response.
+
+**Path**
+
+Path is how Renee describes the basic uri path for a route:
+
+```ruby
+run Renee::Core.new {
+  path('blog') { ... }
+}
+```
+
+All declarations inside that block will start with `/blog`. Paths can also be nested within one another:
+
+```ruby
+run Renee::Core.new {
+  path('blog') {
+    path('foo') { get { halt "path is /blog/foo" } }
+  }
+}
+```
+
+You can also use `exact_path` for more precise path matching and/or `part` which doesn't look for leading slashes.
+
+**Query String**
+
+In addition to defining paths, you may find yourself wanting to describe the state of the query string for a request within the path:
+
+```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
+```
+
+**Variables**
+
+In Renee, you specify parameters for your request as explicit variables. Variables are declared like this:
+
+```ruby
+path('blog') {
+  var { |id| get { halt "path is /blog/#{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 :type => Integer do |id|
+    get { halt "path is /blog/#{id} and id is an integer" }
+  end
+end
+```
+
+**Extensions**
+
+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'.
+
+**Remainder**
+
+In the event that no route has been matched, the `remainder` keyword makes defining the else case rather easy:
+
+```ruby
+path 'foo' do
+  path 'bar' do
+    halt "BAR!"
+  end
+
+  remainder do |rest|
+    halt "Rest was #{rest}"
+  end
+end
+```
+
+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.
+
+**Named Routes**
+
+Once you have defined your routes, you can then "register" a particular path mapping that to a symbol. This is useful for referencing routes without
+having to specify the entire path:
+
+```ruby
+run Renee::Core.new {
+  register(:test, '/test/time')
+  register(:test_var, '/test/:id')
+}
+```
+
+You can then access these using the `path` method in a route or template:
+
+```ruby
+path(:test) # => '/test/time'
+path(:test_var, :id => 123) # => '/test/123'
+```
+
+Using named routes makes referencing and modifying routes within an application much simpler to manage.
+
+## Responding
+
+Responding to a request within a route can be managed with the `respond`, `halt`, `redirect` commands:
+
+**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!" } }
+}
+```
+
+**Halt**
+
+Halting is the easiest way to render data within a route:
+
+```ruby
+run Renee::Core.new {
+  get { halt 'easy' }
+}
+```
+
+This will return a 200 status code and 'easy' as the body. You can also specify status code and header explicitly in the halt response:
+
+```ruby
+get { halt [200, {}, 'body'] }
+```
+
+This will set the status code to 200, pass no headers and return 'body'. You can also use several variations of halt:
+
+```ruby
+# Return just status code
+halt 200
+
+# Return status with symbol
+halt :not_found
+
+# Return 200 with body
+halt "hello!"
+
+# Return 500 with body
+halt 500, "hello!"
+```
+
+Halt is the most straightforward way to control the response for a request.
+
+**Redirect**
+
+A redirect is a common action within a web route and can be achieved with the convenience method `redirect` command:
+
+```ruby
+get {
+  halt redirect('/hello')
+}
+```
+
+You can also specify the status code for the redirect:
+
+```ruby
+get {
+  halt redirect('/hello', 303)
+}
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.test_files = FileList[File.expand_path('../test/**/*_test.rb', __FILE__)]
+  t.verbose = true
+end

data/ideal.rb

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'benchmark'
+
+$: << 'lib'
+require 'renee'
+
+router = Renee::Core.new {
+  path 'test/time' do
+    query_string 'ok' do
+      get { halt "ok" }
+      post { halt [200, {}, ['POSTED!']] }
+    end
+  end
+  variable do |id1, id2|
+    path 'more' do
+      get {
+        halt [200, {}, "this is the id1: #{id1} id2: #{id2}" ]
+      }
+    end
+  end
+  remainder do |rest|
+    halt "the rest is #{rest}"
+  end
+}.setup {
+  view_path('views')
+  environment(:development)
+}
+
+app = Renee do
+  path "add" do
+    variable Integer do |first, second|
+      "#{first} + #{second} = #{first + second}"
+    end
+  end
+end
+
+p router.call(Rack::MockRequest.env_for('/add/3/4')) # => "3 + 4 = 7"
+
+p router.call(Rack::MockRequest.env_for('/test/time?ok'))
+p router.call(Rack::MockRequest.env_for('/test/josh/more'))
+p router.call(Rack::MockRequest.env_for('/'))
+
+
+#puts Benchmark.measure {
+  #50_000.times do
+#    router.call(Rack::MockRequest.env_for('/test/josh/more'))
+    #router.call(Rack::MockRequest.env_for('/test/time?ok', :method => 'POST' ))  
+  #end
+#}

data/lib/renee-core/application/rack_interaction.rb

@@ -0,0 +1,39 @@
+class Renee
+  class Core
+    class Application
+      # A module that defines useful Rack interaction methods.
+      module RackInteraction
+
+        # Creates an ad-hoc Rack application within the context of a Rack::Builder.
+        # @example
+        #     get { halt build { use Rack::ContentLength; run proc { |env| Rack::Response.new("Hello!").finish } } }
+        #
+        def build(&blk)
+          run Rack::Builder.new(&blk).to_app
+        end
+
+        def build!(&blk)
+          run! build(&blk)
+        end
+
+        # Runs a rack application
+        # @example
+        #     get { halt run proc { |env| Renee::Core::Response.new("Hello!").finish } }
+        #
+        def run(app = nil, &blk)
+          (app || blk).call(env)
+        end
+
+        # Runs a rack application and responds immediately.
+        #
+        # @see #run
+        # @example
+        #     get { run proc { |env| Renee::Core::Response.new("Hello!").finish } }
+        #
+        def run!(*args)
+          halt! run(*args)
+        end
+      end
+    end
+  end
+end

data/lib/renee-core/application/request_context.rb

@@ -0,0 +1,22 @@
+class Renee
+  class Core
+    class Application
+      # This module deals with the Rack#call compilance. It defines #call and also defines several critical methods
+      # used by interaction by other application modules.
+      module RequestContext
+        attr_reader :env, :request, :detected_extension, :is_index_request
+        alias_method :is_index_request?, :is_index_request
+
+        # Provides a rack interface compliant call method.
+        # @param[Hash] env The rack environment.
+        def call(env)
+          @env, @request = env, Rack::Request.new(env)
+          @detected_extension = env['PATH_INFO'][/\.([^\.\/]+)$/, 1]
+          @is_index_request = env['PATH_INFO'][/^\/?$/]
+          # TODO clear template cache in development? `template_cache.clear`
+          catch(:halt) { instance_eval(&application_block); Renee::Core::Response.new("Not found", 404).finish }
+        end # call
+      end
+    end
+  end
+end

data/lib/renee-core/application/responding.rb

@@ -0,0 +1,122 @@
+class Renee
+  class Core
+    class Application
+      # Collection of useful methods for responding within a {Renee::Core} app.
+      module Responding
+
+        # Codes used by Symbol lookup in interpret_response.
+        # @example
+        #   halt! :unauthorized # would return a 401.
+        #
+        HTTP_CODES = {
+          :ok => 200,
+          :created => 201,
+          :accepted => 202,
+          :no_content => 204,
+          :no_content => 204,
+          :bad_request => 400,
+          :unauthorized => 401,
+          :payment_required => 403,
+          :not_found => 404,
+          :method_not_found => 405,
+          :not_acceptable => 406,
+          :gone => 410,
+          :error => 500,
+          :not_implemented => 501}.freeze
+
+        # Halts current processing to the top-level calling Renee application and uses that as a response. This method requies that
+        # the PATH_INFO be completely consumed.
+        # @param [Object...] response The response to use.
+        # @see #interpret_response
+        def halt(*response)
+          raise "PATH_INFO hasn't been entirely consumed, you still have #{env['PATH_INFO'].inspect} left. Try putting a #remainder block around it. " if env['PATH_INFO'] != ''
+          halt! *response
+        end
+
+        # Halts current processing to the top-level calling Renee application and uses that as a response. Unlike #halt, this does
+        # not require the path to be consumed.
+        # @param [Object...] response The response to use.
+        # @see #interpret_response
+        def halt!(*response)
+          throw :halt, interpret_response(response.size == 1 ? response.first : response)
+        end
+
+        ##
+        # Creates a response by allowing the response header, body and status to be passed into the block.
+        #
+        # @param [Array] body The contents to return.
+        # @param [Integer] status The status code to return.
+        # @param [Hash] header The headers to return.
+        # @param [Proc] &blk The response options to specify
+        #
+        # @example
+        #  respond { status 200; body "Yay!" }
+        #  respond("Hello", 200, "foo" => "bar")
+        #
+        def respond(body=[], status=200, header={}, &blk)
+          Renee::Core::Response.new(body, status, header).tap { |r| r.instance_eval(&blk) if block_given? }.finish
+        end
+
+        ##
+        # Creates a response by allowing the response header, body and status to be passed into the block.
+        #
+        # @example
+        #  respond! { status 200; body "Yay!" }
+        #
+        # @param  (see #respond)
+        # @see #respond
+        def respond!(*args, &blk)
+          halt respond(*args, &blk)
+        end
+
+        # Interprets responses returns by #halt.
+        #
+        # * If it is a Symbol, it will be looked up in {HTTP_CODES}.
+        # * If it is a Symbol, it will use Rack::Response to return the value.
+        # * If it is a Symbol, it will either be used as a Rack response or as a body and status code.
+        # * If it is an Integer, it will use Rack::Response to return the status code.
+        # * Otherwise, #to_s will be called on it and it will be treated as a Symbol.
+        #
+        # @param [Object] response This can be either a Symbol, String, Array or any Object.
+        #
+        def interpret_response(response)
+          case response
+          when Array   then
+            case response.size
+            when 3 then response
+            when 2 then Renee::Core::Response.new(response[1], HTTP_CODES[response[0]] || response[0]).finish
+            else raise "I don't know how to render #{response.inspect}"
+            end
+          when String  then Renee::Core::Response.new(response).finish
+          when Integer then Renee::Core::Response.new("Status code #{response}", response).finish
+          when Symbol  then interpret_response(HTTP_CODES[response] || response.to_s)
+          else              interpret_response(response.to_s)
+          end
+        end
+
+        # Returns a rack-based response for redirection.
+        # @param [String] path The URL to redirect to.
+        # @param [Integer] code The HTTP code to use.
+        # @example
+        #     r = Renee::Core.new { get { halt redirect '/index' } }
+        #     r.call(Rack::MockResponse("/")) # => [302, {"Location" => "/index"}, []]
+        def redirect(path, code = 302)
+          response = ::Rack::Response.new
+          response.redirect(path, code)
+          response.finish
+        end
+
+        # Halts with a rack-based response for redirection.
+        # @see #redirect
+        # @param [String] path The URL to redirect to.
+        # @param [Integer] code The HTTP code to use.
+        # @example
+        #     r = Renee::Core.new { get { redirect! '/index' } }
+        #     r.call(Rack::MockResponse("/")) # => [302, {"Location" => "/index"}, []]
+        def redirect!(path, code = 302)
+          halt redirect(path, code)
+        end
+      end
+    end
+  end
+end