renee-core 0.2.0 → 0.3.0

data/README.md

@@ -10,7 +10,7 @@ for far more flexibility and freedom in the way that routes and actions are defi
 The bread and butter of Renee are the request verbs reminiscent of Sinatra:
 
 ```ruby
-run Renee::Core.new {
+run Renee.core {
   get    { halt "a get!"  }
   post   { halt "a post!" }
   put    { halt "a put!"  }
@@ -26,7 +26,7 @@ specify the http verb and the use of `halt` inside the block to send back the bo
 Path is how Renee describes the basic uri path for a route:
 
 ```ruby
-run Renee::Core.new {
+run Renee.core {
   path('blog') { ... }
 }
 ```
@@ -34,7 +34,7 @@ run Renee::Core.new {
 All declarations inside that block will start with `/blog`. Paths can also be nested within one another:
 
 ```ruby
-run Renee::Core.new {
+run Renee.core {
   path('blog') {
     path('foo') { get { halt "path is /blog/foo" } }
   }
@@ -152,7 +152,7 @@ Once you have defined your routes, you can then "register" a particular path map
 having to specify the entire path:
 
 ```ruby
-run Renee::Core.new {
+run Renee.core {
   register(:test, '/test/time')
   register(:test_var, '/test/:id')
 }
@@ -194,7 +194,7 @@ run Renee {
 Halting is the easiest way to render data within a route:
 
 ```ruby
-run Renee::Core.new {
+run Renee.core {
   get { halt 'easy' }
 }
 ```

data/lib/renee_core.rb

@@ -0,0 +1,91 @@
+require 'rack'
+require 'renee_core/matcher'
+require 'renee_core/chaining'
+require 'renee_core/response'
+require 'renee_core/url_generation'
+require 'renee_core/exceptions'
+require 'renee_core/rack_interaction'
+require 'renee_core/request_context'
+require 'renee_core/transform'
+require 'renee_core/routing'
+require 'renee_core/responding'
+require 'renee_core/env_accessors'
+
+# Top-level Renee constant
+module Renee
+  # @example
+  #     Renee.core { path('/hello') { halt :ok } }
+  def self.core(&blk)
+    cls = Class.new(Renee::Core)
+    cls.app(&blk) if blk
+    cls
+  end
+
+  # The top-level class for creating core application.
+  # For convience you can also used a method named #Renee
+  # for decalaring new instances.
+  class Core
+    # Class methods that are included in new instances of {Core} 
+    module ClassMethods
+      include URLGeneration
+
+      # The application block used to create your application.
+      attr_reader :application_block
+
+      # Provides a rack interface compliant call method. This method creates a new instance of your class and calls
+      # #call on it.
+      def call(env)
+        new.call(env)
+      end
+
+      # Allows you to set the #application_block on your class.
+      # @yield The application block
+      def app(&app)
+        @application_block = app
+        setup do
+          register_variable_type :integer, IntegerMatcher
+          register_variable_type :int, :integer
+        end
+        self
+      end
+
+      # Runs class methods on your application.
+      def setup(&blk)
+        instance_eval(&blk)
+        self
+      end
+
+      # The currently available variable types you've defined.
+      def variable_types
+        @variable_types ||= {}
+      end
+
+      # Registers a new variable type for use within {Renee::Core::Routing#variable} and others.
+      # @param [Symbol] name The name of the variable.
+      # @param [Regexp] matcher A regexp describing what part of an arbitrary string to capture.
+      # @return [Renee::Core::Matcher] A matcher
+      def register_variable_type(name, matcher)
+        matcher = case matcher
+        when Matcher then matcher
+        when Array   then Matcher.new(matcher.map{|m| variable_types[m]})
+        when Symbol  then variable_types[matcher]
+        else              Matcher.new(matcher)
+        end
+        matcher.name = name
+        variable_types[name] = matcher
+      end
+    end
+
+    include Chaining
+    include RequestContext
+    include Routing
+    include Responding
+    include RackInteraction
+    include Transform
+    include EnvAccessors
+
+    class << self
+      include ClassMethods
+    end
+  end
+end

data/lib/renee_core/chaining.rb

@@ -0,0 +1,71 @@
+module Renee
+  class Core
+    # Module for creating chainable methods. To use this within your own modules, first `include Chaining`, then,
+    # mark methods you want to be available with `chain_method :method_name`.
+    # @example
+    #    module MoreRoutingMethods
+    #      include Chaining
+    #      def other_routing_method
+    #        # ..
+    #      end
+    #      chain_method :other_routing_method
+    #
+    module Chaining
+      # @private
+      class ChainingProxy
+        def initialize(target, proxy_blk)
+          @target, @proxy_blk, @calls = target, proxy_blk, []
+        end
+
+        def method_missing(m, *args, &blk)
+          @calls << [m, args]
+          if blk.nil? && @target.class.private_method_defined?(:"#{m}_without_chain")
+            self
+          else
+            ret = nil
+            @proxy_blk.call(proc do |*inner_args|
+              callback = proc do |*callback_args|
+                inner_args.concat(callback_args)
+                if @calls.size == 0
+                  return blk.call(*inner_args) if blk
+                else
+                  call = @calls.shift
+                  ret = @target.send(call.at(0), *call.at(1), &callback)
+                end
+              end
+              call = @calls.shift
+              ret = @target.send(call.at(0), *call.at(1), &callback)
+            end)
+            ret
+          end
+        end
+      end
+
+      # @private
+      module ClassMethods
+        def chain_method(*methods)
+          methods.each do |m|
+            class_eval <<-EOT, __FILE__, __LINE__ + 1
+              alias_method :#{m}_without_chain, :#{m}
+              def #{m}(*args, &blk)
+                chain(blk) do |subblk|
+                  #{m}_without_chain(*args, &subblk)
+                end
+              end
+              private :#{m}_without_chain
+            EOT
+          end
+        end
+      end
+
+      private
+      def chain(blk, &proxy)
+        blk ? yield(blk) : ChainingProxy.new(self, proxy)
+      end
+
+      def self.included(o)
+        o.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/renee_core/env_accessors.rb

@@ -0,0 +1,72 @@
+module Renee
+  class Core
+    # Defines class-level methods for creating accessors for variables in your environment.
+    module EnvAccessors
+
+      # Exception for attempting to define an env accessor cannot be written as a method name.
+      # @example
+      #   env_accessor "current.user" # raises InvalidEnvName
+      #   env_accessor "current.user" => :current_user # this works
+      InvalidEnvName = Class.new(RuntimeError)
+
+      # Class-methods included by this module.
+      module ClassMethods
+
+        # Defines getters and setters for a list of attributes. If the attributes cannot easily be expressed, use the
+        # hash-syntax for defining them.
+        # @example
+        #   env_accessor "some_value" # will define methods to read and write env['some_value']
+        #   env_accessor "current.user" => :current_user will define methods to read and write env['current.user']
+        def env_accessor(*attrs)
+          env_reader(*attrs)
+          env_writer(*attrs)
+        end
+
+        # Defines getters for a list of attributes.
+        # @see env_accessor
+        def env_reader(*attrs)
+          instance_eval do
+            env_attr_iter(*attrs) do |key, meth|
+              define_method(meth) do
+                env[key]
+              end
+            end
+          end
+        end
+
+        # Defines setters for a list of attributes.
+        # @see env_accessor
+        def env_writer(*attrs)
+          instance_eval do
+            env_attr_iter(*attrs) do |key, meth|
+              define_method("#{meth}=") do |val|
+                env[key] = val
+              end
+            end
+          end
+        end
+
+        private
+        def env_attr_iter(*attrs)
+          attrs.each do |a|
+            case a
+            when Hash
+              a.each do |k, v|
+                yield k, v
+              end
+            else
+              raise InvalidEnvName, "Called env attr for #{a.inspect}, to use this, call your env method like this. env_reader #{a.inspect} => #{a.to_s.gsub(/-\./, '_').to_sym.inspect}" if a.to_s[/[-\.]/]
+              yield a, a.to_sym
+            end
+          end
+        end
+      
+      end
+
+      # @private
+      def self.included(o)
+        o.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/{renee-core → renee_core}/exceptions.rb

@@ -1,4 +1,4 @@
-class Renee
+module Renee
   class Core
     # Used to indicate a client-error has occurred (e.g. 4xx)
     class ClientError < StandardError

data/lib/{renee-core → renee_core}/matcher.rb

@@ -1,4 +1,4 @@
-class Renee
+module Renee
   class Core
     # Class used for variable matching.
     class Matcher

data/lib/renee_core/rack_interaction.rb

@@ -0,0 +1,50 @@
+module Renee
+  class Core
+    # A module that defines useful Rack interaction methods.
+    module RackInteraction
+      # Creates an ad-hoc Rack application within the context of a Rack::Builder.
+      # @yield The block to be used to instantiate the `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
+
+      # Creates an ad-hoc Rack application within the context of a Rack::Builder that immediately halts when done.
+      # @param (see #build)
+      #
+      # @example
+      #     get { halt build { use Rack::ContentLength; run proc { |env| Rack::Response.new("Hello!").finish } } }
+      #
+      def build!(&blk)
+        run! build(&blk)
+      end
+
+      # Runs a rack application. You must either use `app` or `blk`.
+      # @param [#call] app The application to call.
+      # @yield [env] The block to yield to
+      #
+      #
+      # @example
+      #     get { halt run proc { |env| Renee::Core::Response.new("Hello!").finish } }
+      #
+      def run(app = nil, &blk)
+        raise "You cannot supply both a block and an app" unless app.nil? ^ blk.nil?
+        (app || blk).call(env)
+      end
+
+      # Runs a rack application and halts immediately.
+      # @param (see #run)
+      #
+      # @see #run!
+      # @example
+      #     get { run proc { |env| Renee::Core::Response.new("Hello!").finish } }
+      #
+      def run!(app = nil, &blk)
+        halt run(app, &blk)
+      end
+    end
+  end
+end

data/lib/renee_core/request_context.rb

@@ -0,0 +1,25 @@
+module Renee
+  class Core
+    # 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
+
+      # 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]
+        # TODO clear template cache in development? `template_cache.clear`
+        catch(:halt) do
+          begin
+            instance_eval(&self.class.application_block)
+          rescue ClientError => e
+            e.response ? instance_eval(&e.response) : halt("There was an error with your request", 400)
+          end
+          Renee::Core::Response.new("Not found", 404).finish
+        end
+      end # call
+    end
+  end
+end

data/lib/renee_core/responding.rb

@@ -0,0 +1,110 @@
+module Renee
+  class Core
+    # 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.
+      # @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)
+        when Proc    then instance_eval(&response)
+        else              raise "Unable to render #{response.inspect}"
+        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 { 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 { get { redirect! '/index' } }
+      #     r.call(Rack::MockResponse("/")) # => [302, {"Location" => "/index"}, []]
+      def redirect!(path, code = 302)
+        halt redirect(path, code)
+      end
+    end
+  end
+end