sidewalk 0.0.0 → 0.0.1

data/lib/sidewalk/redirect.rb

@@ -0,0 +1,78 @@
+require 'sidewalk/errors'
+
+module Sidewalk
+  # Base class for HTTP-level redirections.
+  #
+  # This, and its' subclasses are expected to be +raise+d.
+  class Redirect < HttpError
+    # Where to redirect to.
+    attr_reader :url
+
+    # Initialize a Redirect.
+    #
+    # You probably don't want to use this directly - use
+    # {PermanentRedirect} or {SeeOtherRedirect} instead.
+    #
+    # @param [String, URI] url is where to redirect to
+    # @param [Fixnum] status is a numeric HTTP status code
+    # @param [String] description is a short description of the status
+    #   code, such as 'Moved Permanently'
+    def initialize url, status, description
+      @url = url.to_s
+      super status, description
+    end
+  end
+
+  # Use if a resource has permanently moved.
+  #
+  # Does not change POST into GET.
+  #
+  # Uses a 301 Moved Permanently response.
+  class PermanentRedirect < Redirect
+    def initialize url
+      super url, 301, 'Moved Permanently'
+    end
+  end
+
+  # Use if the resource hasn't moved, but you want to redirect anyway.
+  #
+  # The new request will be a GET request.
+  #
+  # Standard usage is to redirect after a POST, to make the browser's
+  # Refresh and back/forward buttons work as expected.
+  #
+  # Defaults to a '303 See Other', but if you need to support pre-HTTP/1.1
+  # browsers, you might want to change this.
+  # 
+  # @example Supporting Legacy Browsers
+  class SeeOtherRedirect < Redirect
+    def initialize url
+      super url, nil, nil
+    end
+
+    # Return an appropriate status code.
+    #
+    # @return +303+ for HTTP/1.1 clients
+    # @return +302+ for HTTP/1.0 clients
+    def status request
+      if request.http_version == '1.1'
+        303
+      else
+        302
+      end
+    end
+
+    # Return an appropriate description.
+    #
+    # @return 'See Other' for HTTP/1.1 clients
+    # @return 'Found' for HTTP/1.0 clients
+    def description request
+      case status(request)
+      when 303
+        'See Other'
+      when 302
+        'Found'
+      end
+    end
+  end
+end

data/lib/sidewalk/regexp.rb

@@ -11,13 +11,40 @@ module Sidewalk
     end
   end
 
-  USING_ONIGURUMA = RUBY_VERSION.start_with?('1.8.')
-  if USING_ONIGURUMA
+  REGEXP_USING_ONIGURUMA = RUBY_VERSION.start_with?('1.8.')
+  if REGEXP_USING_ONIGURUMA
     require 'oniguruma'
-    Regexp = ::Oniguruma::ORegexp
-
+    REGEXP_BASE = ::Oniguruma::ORegexp
     ::MatchData.send(:include, Sidewalk::Oniguruma::MatchData)
   else
-    Regexp = ::Regexp
+    REGEXP_BASE = ::Regexp
+  end
+
+  # A Regexp class that supports named captures.
+  #
+  # This class exists just to give a portable class name to refer to.
+  #
+  # * On Ruby 1.9, this inherits +::Regexp+.
+  # * On Ruby 1.8, this inherits +Oniguruma::ORegexp+ (which is basically
+  #   the same library that Ruby 1.9 uses for +::Regexp+)
+  #
+  # @example Using named captures
+  #   regexp = Sidewalk::Regexp.new('(?<foo>bar)')
+  #   match = regexp.match(regexp)
+  #   match['foo'].should == 'bar'
+  class Regexp < REGEXP_BASE
+    # Whether we're using +Onigirumua::ORegexp+.
+    #
+    # Inverse of {#native?}.
+    def self.oniguruma?
+      Sidewalk::REGEXP_USING_ONIGURUMA
+    end
+
+    # Whether we're using +::Regexp+
+    #
+    # Inverse of {#native?}.
+    def self.native?
+      !self.oniguruma?
+    end
   end
 end

data/lib/sidewalk/relative_uri.rb

@@ -0,0 +1,38 @@
+require 'sidewalk/controller'
+require 'sidewalk/rooted_uri'
+require 'sidewalk/request'
+
+module Sidewalk
+  # URI relative to the current request.
+  #
+  # For example, if your app lives at 'http://www.example.com/foo',
+  # the current request is to '/foo/bar', +RelativeUri.new('/baz').to_s+
+  # will return 'http://www.example.com/foo/bar/baz', whereas {AppUri}
+  # would give you 'http://www.example.com/foo/baz'.
+  #
+  # Existing query data is discarded.
+  #
+  # Not a real class as the +URI+ hierarchy doesn't lend itself to
+  # subclassing.
+  module RelativeUri
+    # Create a URI relative to the current request.
+    #
+    # If this is called, it _must_ have {Controller#call} in the call stack
+    # so that {Controller#current} works - otherwise it does not have
+    # enough information to construct the URI.
+    #
+    # Query string data is discarded.
+    #
+    # @param [String] path is the path relative to the current request.
+    # @param [Hash] query is a +Hash+ of key-value query data.
+    def self.new path, query = {}
+      context = Sidewalk::Controller.current
+      unless context
+        raise ScriptError.new("Only valid when called by a controller")
+      end
+      uri = context.request.uri
+
+      Sidewalk::RootedUri.new(uri, path, query)
+    end
+  end
+end

data/lib/sidewalk/request.rb

@@ -4,38 +4,135 @@ require 'rack/request'
 require 'uri'
 
 module Sidewalk
+  # An object representing an HTTP request.
+  #
+  # This is meant to provide convenient, high-level functions.
+  # You do have access to #{rack_environment} and #{rack_request} for
+  # lower-level information, but it's best avoided.
+  #
+  #
+  # Instances of this class are created by the {Application}.
   class Request
-    attr_reader :root_uri, :request_uri
+    # The environment array provided by Rack.
+    #
+    # Please don't use this directly unless you're sure you need to.
+    attr_reader :rack_environment
+    # An instance of +Rack::Request+.
+    #
+    # This is a lower-level wrapper around {#rack_environment}
+    #
+    # Please don't use this directly unless you're sure you need to.
+    attr_reader :rack_request
+
+    # Create a new instance from a Rack environment array
+    #
+    # @param [Array] env is the environment data provided by Rack.
     def initialize env
-      @env = env
+      @rack_environment = env
       @rack_version = env['rack.version']
 
       sanity_check!
-      @rack_request = Rack::Request.new(@env)
+      @rack_request = Rack::Request.new(rack_environment)
 
       initialize_uris
     end
 
+    # The HTTP headers.
+    #
+    # This does not include Rack/CGI variables - just real HTTP headers.
+    def headers
+      @headers ||= rack_environment.select{|k,v| k.start_with? 'HTTP_'}
+    end
+
+    # Cookies provided by the client.
+    #
+    # @returns [Hash]
+    def cookies
+      rack_request.cookies
+    end
+
+    # What version of HTTP the client is using.
+    #
+    # @return '1.1'
+    # @return '1.0'
+    # @return nil
+    def http_version
+      @http_version ||= [
+        'HTTP_VERSION',
+        'SERVER_PROTOCOL',
+      ].map{ |x| rack_environment[x] }.find.first.to_s.split('/').last
+    end
+
+    # The root URI of the application.
+    #
+    # If you're looking at this to construct an URI to another page, take a
+    # look at {Sidewalk::AppUri}.
+    #
+    # If you want to find out where the current request was to, see {#uri}.
+    #
+    # @return [URI::Common]
+    def root_uri
+      @root_uri.dup
+    end
+
+    # The URI of the current request.
+    #
+    # If you're looking at this to construct a relative URI, take a look at
+    # {Sidewalk::RelativeUri}.
+    #
+    # If you want to find out what the URI for the application is, see
+    # {#root_uri}.
+    #
+    # @return [URI::Common]
+    def uri
+      @request_uri.dup
+    end
+
+    # Whether or not this request came via HTTPS.
+    #
+    # @return [true, false]
     def secure?
       @secure
     end
 
+    # Parameters provided via the query string.
+    #
+    # Consider using {#params} instead.
+    #
+    # @return [Hash]
     def get_params
       @get_params ||= @rack_request.GET
     end
 
+    # The {UriMatch} created by {UriMapper}.
     def uri_match
-      @uri_match ||= @env['sidewalk.urimatch']
+      @uri_match ||= rack_environment['sidewalk.urimatch']
     end
 
+    # Paramters provided via POST.
+    #
+    # Consider using {#params} instead.
+    #
+    # @return [Hash]
     def post_params
       @post_params ||= @rack_request.POST
     end
 
+    # Paramters provided via named captures in the URL.
+    #
+    # Consider using {#params} instead.
+    #
+    # @return [Hash]
     def uri_params
       uri_match.parameters
     end
 
+    # Parameters provided by any means.
+    #
+    # Precedence:
+    # * URL captures first
+    # * Then query string parameters
+    # * Then POST parameters
     def params
       # URI parameters take precendence
       @params ||= post_params.merge(get_params.merge(uri_params))
@@ -44,7 +141,7 @@ module Sidewalk
     private
 
     def initialize_uris
-      case @env['rack.url_scheme']
+      case rack_environment['rack.url_scheme']
       when 'http'
         @secure = false
         uri_class = URI::HTTP
@@ -52,36 +149,42 @@ module Sidewalk
         @secure = true
         uri_class = URI::HTTPS
       else
-        raise "Unknown URL scheme: #{@env['rack.url_scheme'].inspect}"
+        raise ArgumentError.new(
+          "Unknown URL scheme: #{rack_environment['rack.url_scheme'].inspect}"
+        )
       end
 
-      root = @env['SCRIPT_NAME']
+      root = rack_environment['SCRIPT_NAME']
       unless root.start_with? '/'
         root[0,0] = '/' # no prepend on 1.8
       end
 
       @root_uri = uri_class.build(
-        :host => @env['SERVER_NAME'],
-        :port => @env['SERVER_PORT'].to_i,
+        :host => rack_environment['SERVER_NAME'],
+        :port => rack_environment['SERVER_PORT'].to_i,
         :path => root
       ).freeze
-      path_info = @env['PATH_INFO']
+      path_info = rack_environment['PATH_INFO']
       if root.end_with? '/' and path_info.start_with? '/'
         path_info = path_info[1..-1]
       end
       @request_uri = @root_uri.dup
       @request_uri.path += path_info
-      @request_uri.query = @env['QUERY_STRING']
+      @request_uri.query = rack_environment['QUERY_STRING']
       @request_uri.freeze
     end
 
     def sanity_check!
       # Sanity checks
       unless @rack_version
-        raise ArgumentError.new "env doesn't specify a Rack version"
+        raise ArgumentError.new(
+          "env doesn't specify a Rack version"
+        )
       end
       if @rack_version != [1, 1]
-        raise "Expected Rack version [1, 1], got #{@rack_version}"
+        raise ArgumentError.new(
+          "Expected Rack version [1, 1], got #{@rack_version}"
+        )
       end
     end
   end

data/lib/sidewalk/rooted_uri.rb

@@ -0,0 +1,32 @@
+require 'rack/utils'
+
+module Sidewalk
+  # A URI relative to a specified root URI.
+  #
+  # You probably don't want to use this directly - see {AppUri} and
+  # {RelativeUri} for examples.
+  module RootedUri
+    # Create a new URI, relative to the specified root.
+    #
+    # @param [URI::Common] root is the uri that you want to use as the base
+    # @param [String] path is the sub-path to add
+    # @param [Hash] query is a +Hash+ of key-values to add to the query
+    #   string.
+    def self.new root, path, query = {}
+      uri = root.dup
+      root_path = uri.path
+      root_path = root_path[0..-2] if root_path.end_with? '/'
+      uri.path = root_path + path
+
+      query_string = query.map do |k,v|
+        '%s=%s' % [
+          Rack::Utils.escape(k.to_s),
+          Rack::Utils.escape(v.to_s),
+        ]
+      end.join('&')
+      uri.query = query_string unless query.empty?
+
+      uri
+    end
+  end
+end

data/lib/sidewalk/template_handlers/base.rb

@@ -0,0 +1,30 @@
+module Sidewalk
+  module TemplateHandlers
+    # Base class for TemplateHandlers.
+    #
+    # This currently just defines an interface - see {ErbHandler} for an
+    # example.
+    #
+    # Instances of this class may be re-used between requests. Anything
+    # request-specific needs to go in the {#render} method.
+    class Base
+      # Actually render a template.
+      #
+      # @param {Controller} controller is the controller that wants the
+      #   template. Instance variables should be available to the template,
+      #   and the handler should not change the scope. See {BaseDelegate}
+      #   and {ErbHandler::Delegate} for an approach to this.
+      #
+      # @return [String]
+      def render controller
+        raise NotImplementedError.new
+      end
+
+      # A new instance of the controller.
+      #
+      # @param [String] path a full path to a template source file.
+      def initialize path
+      end
+    end
+  end
+end

data/lib/sidewalk/template_handlers/base_delegate.rb

@@ -0,0 +1,39 @@
+module Sidewalk
+  module TemplateHandlers
+    # A delegate scope to run templates in.
+    #
+    # Used to provide templates access to the controller's instance
+    # variables, and extra helper functions, without polluting the
+    # controller with them. For example, {ErbHandler::Delegate} will also
+    # include the standard +ERB::Util+ helper functions like +#h+ (aka
+    # +#html_escape+)
+    class BaseDelegate
+      # A new instance of delegate.
+      #
+      # Copies all instance variables from controller to object.
+      #
+      # @param [Controller] controller
+      def initialize controller
+        controller.instance_variables.each do |name|
+          self.instance_variable_set(
+            name,
+            controller.instance_variable_get(name)
+          )
+        end
+      end
+
+      # Render the template in the scope.
+      #
+      # The default implementation raises a NotImplementedError.
+      #
+      # @example {ErbDelegate#render}
+      #   def render
+      #     # @template is set by {ErbDelegate}'s constructor.
+      #     @template.result binding
+      #   end
+      def render
+        raise NotImplementedError.new
+      end
+    end
+  end
+end

data/lib/sidewalk/template_handlers/erb_handler.rb

@@ -0,0 +1,40 @@
+require 'sidewalk/template_handlers/base'
+require 'sidewalk/template_handlers/base_delegate'
+
+require 'erb'
+
+module Sidewalk
+  module TemplateHandlers
+    # Handler for ERB Templates.
+    class ErbHandler < Base
+      def initialize path
+        super path
+        @template = ERB::new(File.read(path))
+        @template.filename = path
+      end
+
+      def render controller
+        Delegate.new(@template, controller).render
+      end
+
+      # Class representing the controller to ERB.
+      #
+      # Using a delegate so we can add extra methods to the binding
+      # without polluting the class - for example, most people expect an
+      # ERB template to have access to ERB::Util#h
+      class Delegate < BaseDelegate
+        # Pull in '#html_escape' aka '#h
+        include ERB::Util
+
+        def initialize template, controller
+          @template = template
+          super controller
+        end
+
+        def render
+          @template.result binding
+        end
+      end
+    end
+  end
+end

data/lib/sidewalk/template_handlers/haml_handler.rb

@@ -0,0 +1,19 @@
+require 'sidewalk/template_handlers/base'
+require 'sidewalk/template_handlers/base_delegate'
+
+require 'haml'
+
+module Sidewalk
+  module TemplateHandlers
+    class HamlHandler < Base
+      def initialize path
+        super path
+        @engine = Haml::Engine.new(File.read(path))
+      end
+
+      def render controller
+        @engine.render(BaseDelegate.new(controller))
+      end
+    end
+  end
+end

data/lib/sidewalk/template_handlers/rxhp_handler.rb

@@ -0,0 +1,32 @@
+require 'sidewalk/template_handlers/base'
+require 'sidewalk/template_handlers/base_delegate'
+
+require 'rxhp'
+require 'rxhp/html'
+
+module Sidewalk
+  module TemplateHandlers
+    class RxhpHandler < Base
+      def initialize path
+        @path = path
+        @template = File.read(path)
+      end
+
+      def render controller
+        Delegate.new(@path, @template, controller).render
+      end
+
+      class Delegate < BaseDelegate
+        include Rxhp::Html
+        def initialize path, template, controller
+          @path, @template, @controller = path, template, controller
+          super controller
+        end
+
+        def render
+          eval(@template, binding, @path).render
+        end
+      end
+    end
+  end
+end

data/lib/sidewalk/uri.rb

@@ -0,0 +1,2 @@
+require 'sidewalk/app_uri'
+require 'sidewalk/relative_uri'

data/lib/sidewalk/uri_mapper.rb

@@ -1,16 +1,83 @@
 require 'sidewalk/regexp'
 require 'sidewalk/uri_match'
 
+require 'active_support/inflector'
+
 module Sidewalk
+  autoload :Application, 'sidewalk/application'
+
+  # Maps URIs to Controllers.
+  #
+  # Used to decide how to respond to a given HTTP request.
   class UriMapper
-    attr_reader :uri_map
+    # Initialize a UriMapper.
+    #
+    # This converts a convenient-to-write map into a fast-to-lookup map.
+    #
+    # The input hash takes +String+ regular expression patterns as keys,
+    # and values can either be another map, a {Controller} class (not an
+    # instance), a +Symbol+ or +String+ that is the name of a {Controller}
+    # class, or a +Proc+.
+    #
+    # If the value is a +String+, it will:
+    # * see if a +Class+ with the same name exists; if so, use that.
+    # * try to +require+ +foo_bar_controller.rb+ for 'FooBarController'
+    # * see if a +Class+ now exists with the same name
+    # * if so, done; if not, bail out.
+    #
+    # It looks for controller files in
+    # {Application#local_root}+/controllers+
+    #
+    # You usually won't interact with this class directly - instead you'll
+    # usually pass the input hash to {Sidewalk::Application}.
+    #
+    # Keys are required to be +String+s instead of +Regexp+s because they
+    # are converted to a +Sidewalk::+{Regexp} behind the scenes; this is
+    # is the same thing as a +::Regexp+ on Ruby 1.9, but on Ruby 1.8 it
+    # adds several additional features such as named captures.
+    #
+    # @example A Simple Map
+    #   urimap = {
+    #     '$' => :IndexController,
+    #     'hello$' => :HelloController,
+    #   }
+    #   run Sidewalk::Application.new(urimap)
+    #
+    # @example A Nested Map
+    #   urimap = {
+    #     '$' => :IndexController,
+    #     'foo/' => {
+    #       '$' => :FooController,
+    #       'bar$' => :FooBarController,
+    #     },
+    #   }
+    #   run Sidewalk::Application.new(urimap)
+    #
+    # @example A Map With Named Captures
+    #   urimap = {
+    #     '$' => :IndexController,
+    #     'foo/$' => :FooController,
+    #     '~(?<username>[^/]+)/$' => :UserController
+    #   }
+    #   run Sidewalk::Application.new(urimap)
+    #
+    # @param [Hash] uri_map
     def initialize uri_map = {}
       unless uri_map.is_a? Hash
         raise ArgumentError.new('URI map must be a Hash')
       end
+      $LOAD_PATH.push File.join(
+        Sidewalk::Application.local_root,
+        'controllers'
+      )
       @uri_map = Sidewalk::UriMapper.convert_map(uri_map)
+      $LOAD_PATH.pop
     end
 
+    # Given a path, find what should respond to it.
+    #
+    # @return [UriMatch] if something was found.
+    # @return [nil] if there is no match.
     def map path
       Sidewalk::UriMapper.map(
         [], #stack
@@ -19,7 +86,17 @@ module Sidewalk
       )
     end
 
-    # Replace string keys with Sidewalk::Regexp instances
+    # The normalized URI map.
+    #
+    # @return [Hash<Regexp,(Controller|Proc)>]
+    attr_reader :uri_map
+
+    private
+
+    # Convert uri_map from easy-to-write to fast-to-use.
+    #
+    # - Replace string keys with Sidewalk::Regexp instances
+    # - Attempt to load classes for symbols
     def self.convert_map uri_map
       out = {}
       uri_map.each do |key, value|
@@ -36,6 +113,16 @@ module Sidewalk
         key = Sidewalk::Regexp.new(key)
         if value.is_a? Hash
           out[key] = convert_map(value)
+        elsif value.is_a? Class
+          out[key] = value
+        elsif value.to_s.end_with? 'Controller'
+          # Attempt to load the class
+          begin
+            out[key] = value.to_s.constantize
+          rescue NameError
+            require value.to_s.underscore
+            retry
+          end
         else
           out[key] = value
         end