rackful 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9219f743c670f4a149826fcf581a97e7c08251d6
-  data.tar.gz: 10ec5c1eb9c59f3d7adda6ed9be9518773311ba9
+  metadata.gz: b3ca6f8649b19811edf97934421a559a7737c0e4
+  data.tar.gz: 7ca6cbcbd870d257c2e05de94ff612b43802bbf7
 SHA512:
-  metadata.gz: f3d112684686175bc973cd240cce7bf899684fe115184ea94b0cd4797d49aa45a1b939983f5af12f9cc3702a03eb541030023319205996bae5b951711e2fd783
-  data.tar.gz: a44bd266844173251e1c0a4ac35c9b7a3be32a77bfd4e369773cb6b49cecc47867e766e04cc8d0bf3eb0f2cbe28779dda4a7b52823b9104ce9e585ad0fec342b
+  metadata.gz: ebe348706302e4f09e1cc9670135f87ab8092b397514fa049164cd0e6a9880d3418c1c1f456d9e8a54aac9f650b297bc0ff76a8ea10275eeafd2d28e4a49315a
+  data.tar.gz: dc046d625255efb54558810c9069ee89856963fac75b1672b7b3877dc5ff4647ffdd3937d086d509479b91ccecffc6e67111582021458f88bd02d1e401a39d31

data/example/config.ru

@@ -1,24 +1,26 @@
 # Load core functionality:
 require 'rackful'
 
+
 # Load extra middlewares: ({Rackful::MethodOverride}, {Rackful::HeaderSpoofing})
 require 'rackful/middleware'
-
 require 'digest/md5'
 
+
 # The class of the object we're going to serve:
-class Root < Rackful::Resource
-  attr_reader :to_rackful
+class MyResource
+  include Rackful::Resource
+  attr_accessor :to_rackful
+
   def initialize
-    super( 'http://localhost:9292/hallo_wereld' )
+    self.uri = '/hello_world'
     @to_rackful = {
       :a => 'Hello',
       :b => Time.now,
-      :c => URI('http://www.example.com/some/path') }
-  end
-  def do_PUT request, response
-    @to_rackful = self.parser(request).parse
+      :c => URI('http://www.example.com/some/path')
+    }
   end
+
   def get_etag
     '"' + Digest::MD5.new.update(to_rackful.inspect).to_s + '"'
   end
@@ -27,12 +29,11 @@ class Root < Rackful::Resource
   add_parser Rackful::Parser::XHTML
   add_parser Rackful::Parser::JSON
 end
-$root_resource = nil
 
 use Rack::Reloader
 use Rackful::MethodOverride
 use Rackful::HeaderSpoofing
 
 run Rackful::Server.new { |uri|
-  $root_resource ||= Root.new
+  $root_resource ||= MyResource.new
 }

data/lib/rackful.rb

@@ -1,4 +1,6 @@
-require 'uri'
+# encoding: utf-8
+
+# External requirements:
 require 'nokogiri'
 require 'rack'
 require 'rack/utils'
@@ -6,10 +8,12 @@ require 'base64'
 require 'time'
 require 'json'
 
-require 'rackful/uri.rb'
-require 'rackful/request.rb'
-require 'rackful/serializer.rb'
+# Internal “core” files, in alphabetic order:
+require 'rackful/global.rb'
+require 'rackful/httpstatus.rb'
 require 'rackful/parser.rb'
+require 'rackful/request.rb'
 require 'rackful/resource.rb'
-require 'rackful/httpstatus.rb'
+require 'rackful/serializer.rb'
 require 'rackful/server.rb'
+require 'rackful/uri.rb'

data/lib/rackful/global.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+# This file is required by all other files.
+
+# Required for parsing:
+
+# Required for running:
+
+# @todo Documentation
+module Rackful
+module StatusCodes
+end
+end

data/lib/rackful/httpstatus.rb

@@ -1,63 +1,58 @@
 # encoding: utf-8
+
 # Required for parsing:
+require 'rackful/global.rb'
 require 'rackful/resource.rb'
 require 'rackful/serializer.rb'
 
+# Required for running:
 
 module Rackful
 
-=begin markdown
-Exception which represents an HTTP Status response.
-@abstract
-=end
-class HTTPStatus < RuntimeError
+# Groups together class {HTTPStatus} and its many subclasses into one namespace.
+#
+# For code brevity and legibility, this module is included in {Rackful},
+# {Resource}, {Serializer}, and {Parser}. So class
+# {HTTP404NotFound Rackful::StatusCodes::HTTP404NotFound}
+# can also be addressed as {HTTP404NotFound} in any of those contexts.
+module StatusCodes
 
+  # Exception which represents an HTTP Status response.
+  # @abstract
+class HTTPStatus < RuntimeError
 
-  class Resource < ::Rackful::Resource
-    class XHTML < Serializer::XHTML
+  include Resource
+  
+  class XHTML < Serializer::XHTML
 
 
-      def header
-        retval = super
-        retval += "<h1>HTTP/1.1 #{Rack::Utils.escape_html(resource.title)}</h1>\n"
-        unless resource.message.empty?
-          retval += "<div id=\"rackful-description\">#{resource.message}</div>\n"
-        end
-        retval
+    def header
+      retval = super
+      retval += "<h1>HTTP/1.1 #{Rack::Utils.escape_html(resource.title)}</h1>\n"
+      unless resource.message.empty?
+        retval += "<div id=\"rackful-description\">#{resource.message}</div>\n"
       end
+      retval
+    end
 
 
-      def headers; self.resource.headers; end
-
-
-    end # class Rackful::HTTPStatus::XHTML
-
-
-    add_serializer XHTML, 1.0
-
-    extend Forwardable
-    def_delegators :@http_status_object, :headers, :to_rackful, :title, :message
-
+    def headers; self.resource.headers; end
 
-    def initialize(uri, http_status_object)
-      super(uri)
-      @http_status_object = http_status_object
-    end
 
+  end # class Rackful::StatusCodes::HTTPStatus::XHTML
 
-  end # class Rackful::HTTPStatus::Resource
 
+  add_serializer XHTML, 1.0
+  add_serializer Serializer::JSON, 0.5
 
   attr_reader :status, :headers, :to_rackful
 
 
-=begin markdown
-@param status [Symbol, Integer] e.g. `404` or `:not_found`
-@param message [String] XHTML
-@param info [ { Symbol => Object, String => String } ]
-    *   **Objects** indexed by **Symbols** are returned in the response body.
-    *   **Strings** indexed by **Strings** are returned as response headers.
-=end
+  # @param status [Symbol, Integer] e.g. `404` or `:not_found`
+  # @param message [String] XHTML
+  # @param info [ { Symbol => Object, String => String } ]
+  #     *   **Objects** indexed by **Symbols** are returned in the response body.
+  #     *   **Strings** indexed by **Strings** are returned as response headers.
   def initialize status, message = nil, info = {}
     @status = Rack::Utils.status_code status
     raise "Wrong status: #{status}" if 0 === @status
@@ -86,24 +81,20 @@ class HTTPStatus < RuntimeError
     end
     super message
   end
-  
-  def serializer request
-    Resource.new( request.url, self ).serializer( request )
-  end
 
+
+  # @api private
   def title
     "#{status} #{Rack::Utils::HTTP_STATUS_CODES[status]}"
   end
 
 
  
-end # class Rackful::HTTPStatus
+end # class Rackful::StatusCodes::HTTPStatus
 
 
-=begin markdown
-@abstract Base class for HTTP status codes with only a simple text message, or
-  no message at all.
-=end
+  # @abstract Base class for HTTP status codes with only a simple text message, or
+  #   no message at all.
 class HTTPSimpleStatus < HTTPStatus
 
   def initialize message = nil
@@ -117,9 +108,12 @@ end
 
 class HTTP201Created < HTTPStatus
 
+  # @param locations [URI::Generic, String, Array<URI::Generic, String>]
   def initialize locations
     locations = [ locations ] unless locations.kind_of? Array
-    locations = locations.collect { |l| URI(l) }
+    locations = locations.collect do |location|
+      location.kind_of?( URI::Generic ) ? location : URI(location).normalize
+    end
     if locations.size > 1
       super( 201, 'New resources were created:', :locations => locations )
     else
@@ -136,9 +130,10 @@ end
 
 class HTTP202Accepted < HTTPStatus
 
+  # @param location [URI::Generic, String]
   def initialize location = nil
     if location
-      location = URI(location)
+      location = location.kind_of?( URI::Generic ) ? location : URI(location).normalize
       super(
         202, "The request body you sent has been accepted for processing.",
         :"Job status location:" => location, 'Location' => location
@@ -153,8 +148,9 @@ end
 
 class HTTP301MovedPermanently < HTTPStatus
 
+  # @param location [URI::Generic, String]
   def initialize location
-    location = URI(location)
+    location = location.kind_of?( URI::Generic ) ? location : URI(location).normalize
     super( 301, '', :'New location:' => location, 'Location' => location )
   end
 
@@ -163,8 +159,9 @@ end
 
 class HTTP303SeeOther < HTTPStatus
 
+  # @param location [URI::Generic, String]
   def initialize location
-    location = URI(location)
+    location = location.kind_of?( URI::Generic ) ? location : URI(location).normalize
     super( 303, '', :'See:' => location, 'Location' => location )
   end
 
@@ -182,8 +179,9 @@ end
 
 class HTTP307TemporaryRedirect < HTTPStatus
 
+  # @param location [URI::Generic, String]
   def initialize location
-    location = URI(location)
+    location = location.kind_of?( URI::Generic ) ? location : URI(location).normalize
     super( 301, '', :'Current location:' => location, 'Location' => location )
   end
 
@@ -247,4 +245,5 @@ class HTTP501NotImplemented < HTTPSimpleStatus; end
 
 class HTTP503ServiceUnavailable < HTTPSimpleStatus; end
 
+end # module Rackful::StatusCodes
 end # module Rackful

data/lib/rackful/middleware.rb

@@ -1,2 +1,7 @@
+# encoding: utf-8
+
+# Required for parsing:
+
+# Required for running:
 require 'rackful/middleware/headerspoofing.rb'
 require 'rackful/middleware/methodoverride.rb'

data/lib/rackful/middleware/headerspoofing.rb

@@ -1,9 +1,14 @@
 # encoding: utf-8
+
 # Required for parsing:
+
+# This requirement is only made explicit in source files that aren’t
+# included in the rackful “core”.
 require 'rackful'
 
 # Required for running:
 
+module Rackful
 
 # Rack middleware that provides header spoofing.
 #
@@ -18,7 +23,7 @@ require 'rackful'
 # @example Using this middleware
 #   require 'rackful/middleware/header_spoofing'
 #   use Rackful::HeaderSpoofing
-class Rackful::HeaderSpoofing
+class HeaderSpoofing
 
 def initialize app
   @app = app
@@ -47,3 +52,4 @@ def call env
 end
 
 end # Rackful::HeaderSpoofing
+end # module Rackful

data/lib/rackful/middleware/methodoverride.rb

@@ -1,9 +1,14 @@
 # encoding: utf-8
+
 # Required for parsing:
+
+# This requirement is only made explicit in source files that aren’t
+# included in the rackful “core”.
 require 'rackful'
 
 # Required for running:
-require 'set'
+
+module Rackful
 
 
 # Middleware that provides method spoofing, like {Rack::MethodOverride}.
@@ -47,7 +52,7 @@ require 'set'
 # @example Using this middleware
 #   require 'rackful/middleware/method_override'
 #   use Rackful::MethodOverride
-class Rackful::MethodOverride
+class MethodOverride
 
   METHOD_OVERRIDE_PARAM_KEY = '_method'.freeze
   
@@ -134,3 +139,4 @@ class Rackful::MethodOverride
   end
 
 end # Rackful::MethodOverride
+end # module Rackful

data/lib/rackful/parser.rb

@@ -1,77 +1,80 @@
 # encoding: utf-8
 
+# Required for parsing:
+require 'rackful/global.rb'
 
-module Rackful
+# Required for running:
 
+module Rackful
 
-=begin markdown
-Base class for all parsers.
-@abstract Subclasses must implement method `#parse`, and define constant
-  {MEDIA_TYPES} as an array of media types this parser accepts.
-@example Subclassing this class
-  class MyTextParser < Rackful::Parser
-    MEDIA_TYPES = [ 'text/plain' ]
-    def parse
-      # YOUR CODE HERE...
-    end
-  end
-=end
+# Base class for all concrete parsers defined in this library. You’ll probably
+# want to use this class as the base class for your own parsers, too.
+#
+# This class mixes in module `StatusCodes` for convenience, as explained in the
+# {StatusCodes StatusCodes documentation}.
+# @abstract Subclasses must implement classmethod `::parse` with signature
+#   `(void) parse( Request, Response, Resource )`
+#   explained in {Resource::ClassMethods::add_parser}
+# @example Subclassing this class
+#   class MyTextParser < Rackful::Parser
+#     parses 'text/*', 'application/xhtml+xml'
+#     def self.parse request, response, resource
+#       # YOUR CODE HERE...
+#     end
+#   end
 class Parser
+  include StatusCodes
+  class << self
+    # @api private
+    def media_types
+      @media_types ||= begin
+        retval = rackful_parser_media_types
+        if superclass.respond_to?(:media_types)
+          retval += superclass.media_types
+        end
+        retval.uniq
+      end
+    end
+    
+    # @overload parses( media_type, ... )
+    #   @param media_type [String]
+    def parses *args
+      rackful_parser_media_types.unshift(
+        *( args.map { |mt| mt.to_s }.reverse )
+      )
+      rackful_parser_media_types.uniq!
+      self
+    end
+    
+    private
+    def rackful_parser_media_types
+      @rackful_parser_media_types ||= []
+    end
+  end # class << self # Rackful::Parser
 
+end # class Rackful::Parser
 
-=begin markdown
-  An array of media type strings.
-  @!parse MEDIA_TYPES = [ 'example/type1', 'example/type2' ]
-=end
-
-
-  # @return [Request]
-  attr_reader :request
-  # @return [Resource]
-  attr_reader :resource
-
-
-=begin markdown
-@param request [Request]
-@param resource [Resource]
-=end
-  def initialize request, resource
-    @request, @resource = request, resource
-  end
-
-
-end # class Parser
-
-
-=begin markdown
-Parent class of all XML-parsing parsers.
-@abstract
-@since 0.2.0
-=end
+# Parent class of all XML-parsing parsers.
+# @abstract
+# @since 0.2.0
 class Parser::DOM < Parser
 
+  # The media types parsed by this parser.
+  # @see Parser
+  parses 'text/xml', 'application/xml'
 
-=begin markdown
-The media types parsed by this parser.
-@see Parser
-=end
-  MEDIA_TYPES = [
-    'text/xml',
-    'application/xml'
-  ]
 
+  def self.parse request, response, resource
+    self.new(request).parse( response, resource )
+  end
 
-=begin markdown
-@return [Nokogiri::XML::Document]
-=end
+  # @return [Nokogiri::XML::Document]
   attr_reader :document
+  attr_reader :request
 
-
-=begin markdown
-@raise [HTTP400BadRequest] if the document is malformed.
-=end
-  def initialize request, resource
-    super request, resource
+  # @raise [HTTP400BadRequest] if the document is malformed.
+  def initialize request
+    @request = request
     # TODO Is ISO-8859-1 indeed the default encoding for XML documents? If so,
     # that fact must be documented and referenced.
     encoding = self.request.media_type_params['charset'] || 'ISO-8859-1'
@@ -88,31 +91,21 @@ The media types parsed by this parser.
     end
     raise( HTTP400BadRequest, $!.to_s ) unless @document.root
   end
+  
+end # class Rackful::Parser::DOM
 
 
-end # class Parser::DOM
 
 
-=begin markdown
-Parses XHTML as generated by {Serializer::XHTML}.
-=end
+# Parses XHTML as generated by {Serializer::XHTML}.
 class Parser::XHTML < Parser::DOM
 
 
-=begin markdown
-The media types parsed by this parser.
-@see Parser
-=end
-  MEDIA_TYPES = Parser::DOM::MEDIA_TYPES + [
-    'application/xhtml+xml',
-    'text/html'
-  ]
+  parses 'application/xhtml+xml', 'text/html'
 
 
-=begin markdown
-@see Parser#parse
-=end
-  def parse
+  # @see Parser#parse
+  def parse response, resource
     # Try to find the actual content:
     content = self.document.root.xpath(
       '//html:div[@id="rackful-content"]',
@@ -139,13 +132,11 @@ The media types parsed by this parser.
       end
     end
     # Parse the f*cking thing:
-    self.parse_recursive content.first
+    resource.to_rackful = self.parse_recursive content.first
   end
 
 
-=begin markdown
-@api private
-=end
+  # @api private
   def parse_recursive node
 
     # A URI:
@@ -181,9 +172,7 @@ The media types parsed by this parser.
   end
 
 
-=begin markdown
-@api private
-=end
+  # @api private
   def parse_simple_type node, typename
     case typename
     when 'boolean'
@@ -208,9 +197,7 @@ The media types parsed by this parser.
   end
 
 
-=begin markdown
-@api private
-=end
+  # @api private
   def parse_object node
     current_property = nil
     r = {}
@@ -234,9 +221,7 @@ The media types parsed by this parser.
   end
 
 
-=begin markdown
-@api private
-=end
+  # @api private
   def parse_object_list node
     properties = node.xpath(
       'html:thead/html:tr/html:th',
@@ -273,22 +258,18 @@ end # class Parser::XHTML
 class Parser::JSON < Parser
 
 
-  MEDIA_TYPES = [
-    'application/json',
-    'application/x-json'
-  ]
+  parses 'application/json', 'application/x-json'
 
-
-  def parse
+  def self.parse request, response, resource
     r = ::JSON.parse(
-      self.request.env['rack.input'].read,
+      request.env['rack.input'].read,
       :symbolize_names => true
     )
-    self.recursive_datetime_parser r
+    resource.to_rackful = self.recursive_datetime_parser r
   end
 
 
-  def recursive_datetime_parser p
+  def self.recursive_datetime_parser p
     if p.kind_of?(String)
       begin
         return Time.xmlschema(p)
@@ -297,12 +278,12 @@ class Parser::JSON < Parser
     elsif p.kind_of?(Hash)
       p.keys.each do
         |key|
-        p[key] = self.recursive_datetime_parser( p[key] )
+        p[key] = recursive_datetime_parser( p[key] )
       end
     elsif p.kind_of?(Array)
       (0 ... p.size).each do
         |i|
-        p[i] = self.recursive_datetime_parser( p[i] )
+        p[i] = recursive_datetime_parser( p[i] )
       end
     end
     p
@@ -310,6 +291,4 @@ class Parser::JSON < Parser
 
 
 end # class Parser::JSON
-
-
 end # module Rackful