rackful 0.1.2 → 0.1.3

data/lib/{rackful_request.rb → rackful/request.rb}

@@ -8,7 +8,6 @@ module Rackful
 
 =begin markdown
 Subclass of {Rack::Request}, augmented for Rackful requests.
-@since 0.0.1
 =end
 class Request < Rack::Request
 
@@ -17,7 +16,6 @@ class Request < Rack::Request
 The resource factory for the current request.
 @return [#[]]
 @see Server#initialize
-@since 0.0.1
 =end
   def resource_factory; self.env['rackful.resource_factory']; end
   def base_path
@@ -31,18 +29,15 @@ The resource factory for the current request.
 Similar to the HTTP/1.1 `Content-Location:` header. Contains the canonical path
 to the requested resource, which may differ from {#path}
 @return [Path]
-@since 0.1.0
 =end
   def content_path; self.env['rackful.content_path'] ||= self.path; end
 =begin markdown
 Set by {Rackful::Server#call!}
 @return [Path]
-@since 0.1.0
 =end
   def content_path= bp; self.env['rackful.content_path'] = bp.to_path; end
 =begin markdown
 @return [Path]
-@since 0.1.0
 =end
   def path; super.to_path; end
 
@@ -60,7 +55,6 @@ In a multi-threaded server, multiple requests can be handled at one time.
 This method returns the request object, created (and registered) by
 {Server#call!}
 @return [Request]
-@since 0.0.1
 =end
   def self.current
     Thread.current[:rackful_request]
@@ -82,7 +76,6 @@ Assert all <tt>If-*</tt> request headers.
 @see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616, section 13.3.3
   for details about weak and strong validator comparison.
 @todo Implement support for the `If-Range:` header.
-@since 0.0.1
 =end
   def assert_if_headers resource
     #raise HTTP501NotImplemented, 'If-Range: request header is not supported.' \
@@ -113,11 +106,15 @@ Assert all <tt>If-*</tt> request headers.
       elsif cond[:unmodified_since]
         raise HTTP412PreconditionFailed, 'If-Unmodified-Since'
       elsif cond[:modified_since]
-        raise HTTP404NotFound
+        raise HTTP404NotFound, resource.path
       end
     else
       if cond[:none_match] && self.validate_etag( etag, cond[:none_match] )
-        raise HTTP412PreconditionFailed, 'If-None-Match'
+        if allow_weak
+          raise HTTP304NotModified
+        else
+          raise HTTP412PreconditionFailed, 'If-None-Match'
+        end
       elsif cond[:match] && ! self.validate_etag( etag, cond[:match] )
         raise HTTP412PreconditionFailed, 'If-Match'
       elsif cond[:unmodified_since]
@@ -145,7 +142,6 @@ Hash of acceptable media types and their qualities.
 This method parses the HTTP/1.1 `Accept:` header. If no acceptable media
 types are provided, an empty Hash is returned.
 @return [Hash{media_type => quality}]
-@since 0.0.1
 =end
   def accept
     @env['rackful.accept'] ||= begin
@@ -172,7 +168,6 @@ Parses the HTTP/1.1 `If-Match:` header.
 @return [nil, Array<String>]
 @see http://tools.ietf.org/html/rfc2616#section-14.24 RFC2616, section 14.24
 @see #if_none_match
-@since 0.0.1
 =end
   def if_match none = false
     header = @env["HTTP_IF_#{ none ? 'NONE_' : '' }MATCH"]
@@ -192,7 +187,6 @@ Parses the HTTP/1.1 `If-None-Match:` header.
 @return [nil, Array<String>]
 @see http://tools.ietf.org/html/rfc2616#section-14.26 RFC2616, section 14.26
 @see #if_match
-@since 0.0.1
 =end
   def if_none_match
     self.if_match true
@@ -204,7 +198,6 @@ Parses the HTTP/1.1 `If-None-Match:` header.
 @return [nil, Time]
 @see http://tools.ietf.org/html/rfc2616#section-14.25 RFC2616, section 14.25
 @see #if_unmodified_since
-@since 0.0.1
 =end
   def if_modified_since unmodified = false
     header = @env["HTTP_IF_#{ unmodified ? 'UN' : '' }MODIFIED_SINCE"]
@@ -222,7 +215,6 @@ Parses the HTTP/1.1 `If-None-Match:` header.
 @return [nil, Time]
 @see http://tools.ietf.org/html/rfc2616#section-14.28 RFC2616, section 14.28
 @see #if_modified_since
-@since 0.0.1
 =end
   def if_unmodified_since
     self.if_modified_since true
@@ -241,7 +233,6 @@ Does any of the tags in `etags` match `etag`?
 @return [Boolean]
 @see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616 section 13.3.3
   for details about weak and strong validator comparison.
-@since 0.0.1
 =end
   def validate_etag etag, etags
     etag = etag.to_s

data/lib/{rackful_resource.rb → rackful/resource.rb}

@@ -15,7 +15,6 @@ Classes that include this module may implement a method `content_types`
 for content negotiation. This method must return a Hash of
 `media-type => quality` pairs. 
 @see Server, ResourceFactory
-@since 0.0.1
 =end
 module Resource
 
@@ -23,6 +22,14 @@ module Resource
   include Rack::Utils
 
 
+=begin
+Normally, when a module is included, all the instance methods of the included
+module become available as instance methods to the including module/class. But
+class methods of the included module don't become available as class methods to
+the including class.
+
+
+=end
   def self.included(base)
     base.extend ClassMethods
   end
@@ -30,21 +37,21 @@ module Resource
 
   module ClassMethods
 
-
-    #Meta-programmer method.
-    #@example Have your resource rendered in XML and JSON
-    #  class MyResource
-    #    add_serializer MyResource2XML
-    #    add_serializer MyResource2JSON, 0.5
-    #  end
-    #@param serializer [Serializer]
-    #@param quality [Float]
-    #@return [self]
+=begin
+Meta-programmer method.
+@example Have your resource rendered in XML and JSON
+  class MyResource
+    add_serializer MyResource2XML
+    add_serializer MyResource2JSON, 0.5
+  end
+@param serializer [Serializer]
+@param quality [Float]
+@return [self]
+=end
     def add_serializer serializer, quality = 1.0
       quality = quality.to_f
       quality = 1.0 if quality > 1.0
       quality = 0.0 if quality < 0.0
-      # The single '@' on the following line is on purpose!
       s = [serializer, quality]
       serializer::CONTENT_TYPES.each {
         |content_type|
@@ -55,11 +62,13 @@ module Resource
 
 
     def serializers
+      # The single '@' on the following line is on purpose!
       @rackful_resource_serializers ||= {}
     end
 
 
     def all_serializers
+      # The single '@' on the following line is on purpose!
       @rackful_resource_all_serializers ||=
         if self.superclass.respond_to?(:all_serializers)
           self.superclass.all_serializers.merge( self.serializers ) do
@@ -72,28 +81,36 @@ module Resource
     end
 
 
-    #Meta-programmer method.
-    #@example Have your resource accept XML and JSON in `PUT` requests
-    #  class MyResource
-    #    add_parser XML2MyResource, :PUT
-    #    add_parser JSON2MyResource, :PUT
-    #  end
-    #@param parser [Parser]
-    #@param method [#to_sym]
-    #@return [self]
+=begin
+Meta-programmer method.
+@example Have your resource accept XML and JSON in `PUT` requests
+  class MyResource
+    add_media_type 'text/xml', :PUT
+    add_media_type 'application/json', :PUT
+  end
+@param [#to_s] media_type
+@param [#to_sym] method
+@return [self]
+=end
     def add_media_type media_type, method = :PUT
       method = method.to_sym
       self.media_types[method] ||= []
-      self.media_types[method] << media_type
+      self.media_types[method] << media_type.to_s
       self
     end
 
 
+=begin
+@todo Documentation
+=end
     def media_types
       @rackful_resource_media_types ||= {}
     end
 
 
+=begin
+@todo Documentation
+=end
     def all_media_types
       @rackful_resource_all_media_types ||=
         if self.superclass.respond_to?(:all_media_types)
@@ -113,7 +130,6 @@ The best media type for the response body, given the current HTTP request.
 @param require_match [Boolean]
 @return [String] content-type
 @raise [HTTP406NotAcceptable] if `require_match` is `true` and no match was found.
-@since 0.1.0
 =end
     def best_content_type accept, require_match = true
       if accept.empty?
@@ -142,18 +158,6 @@ The best media type for the response body, given the current HTTP request.
     end
 
 
-    #~ # @param content_type [String]
-    #~ # @param method [#to_s]
-    #~ # @return [Serializer]
-    #~ def parser request
-      #~ method = request.request_method.upcase.to_sym
-      #~ if !parsers[method] || !parsers[method][request.media_type]
-        #~ raise HTTP415UnsupportedMediaType, ( parsers[method] ? parsers[method].keys : [] )
-      #~ end
-      #~ parsers[method][request.media_type].new( request )
-    #~ end
-
-
   end # module ClassMethods
 
 
@@ -167,39 +171,33 @@ The best media type for the response body, given the current HTTP request.
   end
 
 
-=begin markdown
-@!method to_struct()
-@return [#to_json, #each_pair]
-=end
-
+=begin
+@!method do_METHOD( Request, Rack::Response )
+  HTTP/1.1 method handler.
 
-# @!method do_METHOD( Request, Rack::Response )
-# HTTP/1.1 method handler.
-#
-# To handle certain HTTP/1.1 request methods, resources must implement methods
-# called `do_<HTTP_METHOD>`.
-# @example Handling `PATCH` requests
-#   def do_PATCH request, response
-#     response['Content-Type'] = 'text/plain'
-#     response.body = [ 'Hello world!' ]
-#   end
-# @abstract
-# @return [void]
-# @raise [HTTPStatus, RuntimeError]
-# @since 0.0.1
+  To handle certain HTTP/1.1 request methods, resources must implement methods
+  called `do_<HTTP_METHOD>`.
+  @example Handling `PATCH` requests
+    def do_PATCH request, response
+      response['Content-Type'] = 'text/plain'
+      response.body = [ 'Hello world!' ]
+    end
+  @abstract
+  @return [void]
+  @raise [HTTPStatus, RuntimeError]
+=end
 
 
 =begin markdown
 The path of this resource.
 @return [Rackful::Path]
 @see #initialize
-@since 0.0.1
 =end
-  attr_reader :path
+  def path; @rackful_resource_path; end
 
 
   def path= path
-    @path = path.to_s.to_path
+    @rackful_resource_path = Path.new(path)
   end
 
 
@@ -214,6 +212,7 @@ The path of this resource.
     self.path.slashify == Request.current.path.slashify
   end
 
+
 =begin markdown
 Does this resource _exists_?
 
@@ -223,13 +222,15 @@ produce an empty resource to to handle the `PUT` request. `HEAD` and `GET`
 requests will still yield `404 Not Found`.
 
 @return [Boolean] The default implementation returns `false`.
-@since 0.0.1
 =end
   def empty?
     false
   end
 
 
+=begin markdown
+
+=end
   def to_rackful
     self
   end
@@ -237,48 +238,46 @@ requests will still yield `404 Not Found`.
 
 =begin markdown
 @!attribute [r] get_etag
-The ETag of this resource.
+  The ETag of this resource.
 
-If your classes implement this method, then an `ETag:` response
-header is generated automatically when appropriate. This allows clients to
-perform conditional requests, by sending an `If-Match:` or
-`If-None-Match:` request header. These conditions are then asserted
-for you automatically.
+  If your classes implement this method, then an `ETag:` response
+  header is generated automatically when appropriate. This allows clients to
+  perform conditional requests, by sending an `If-Match:` or
+  `If-None-Match:` request header. These conditions are then asserted
+  for you automatically.
 
-Make sure your entity tag is a properly formatted string. In ABNF:
+  Make sure your entity tag is a properly formatted string. In ABNF:
 
-    entity-tag    = [ "W/" ] quoted-string
-    quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
-    qdtext        = <any TEXT except <">>
-    quoted-pair   = "\" CHAR
+      entity-tag    = [ "W/" ] quoted-string
+      quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
+      qdtext        = <any TEXT except <">>
+      quoted-pair   = "\" CHAR
 
-@abstract
-@return [String]
-@see http://tools.ietf.org/html/rfc2616#section-14.19 RFC2616 section 14.19
-@since 0.0.1
+  @abstract
+  @return [String]
+  @see http://tools.ietf.org/html/rfc2616#section-14.19 RFC2616 section 14.19
 =end
 
 
 =begin markdown
 @!attribute [r] get_last_modified
-Last modification of this resource.
-
-If your classes implement this method, then a `Last-Modified:` response
-header is generated automatically when appropriate. This allows clients to
-perform conditional requests, by sending an `If-Modified-Since:` or
-`If-Unmodified-Since:` request header. These conditions are then asserted
-for you automatically.
-@abstract
-@return [Array<(Time, Boolean)>] The timestamp, and a flag indicating if the
-  timestamp is a strong validator.
-@see http://tools.ietf.org/html/rfc2616#section-14.29 RFC2616 section 14.29
-@since 0.0.1
+  Last modification of this resource.
+
+  If your classes implement this method, then a `Last-Modified:` response
+  header is generated automatically when appropriate. This allows clients to
+  perform conditional requests, by sending an `If-Modified-Since:` or
+  `If-Unmodified-Since:` request header. These conditions are then asserted
+  for you automatically.
+  @abstract
+  @return [Array<(Time, Boolean)>] The timestamp, and a flag indicating if the
+    timestamp is a strong validator.
+  @see http://tools.ietf.org/html/rfc2616#section-14.29 RFC2616 section 14.29
 =end
 
 
 =begin markdown
 @!method destroy()
-@return [Hash, nil] an optional header hash.
+  @return [Hash, nil] an optional header hash.
 =end
 
 
@@ -287,7 +286,6 @@ List of all HTTP/1.1 methods implemented by this resource.
 
 This works by inspecting all the {#do_METHOD} methods this object implements.
 @return [Array<Symbol>]
-@since 0.0.1
 @private
 =end
   def http_methods
@@ -295,10 +293,10 @@ This works by inspecting all the {#do_METHOD} methods this object implements.
     if self.empty?
       self.class.all_media_types
     else
-      r.merge! [ :OPTIONS, :HEAD, :GET ]
+      r.push( :OPTIONS, :HEAD, :GET )
       r << :DELETE if self.respond_to?( :destroy )
     end
-    self.public_instance_methods.each do
+    self.class.public_instance_methods.each do
       |instance_method|
       if /\Ado_([A-Z])+\z/ === instance_method
         r << $1.to_sym
@@ -319,10 +317,9 @@ returned (without an entity body).
 Feel free to override this method at will.
 @return [void]
 @raise [HTTP404NotFound] `404 Not Found` if this resource is empty.
-@since 0.0.1
 =end
   def http_OPTIONS request, response
-    raise HTTP404NotFound if self.empty?
+    raise HTTP404NotFound, path if self.empty?
     response.status = status_code :no_content
     response.header['Allow'] = self.http_methods.join ', '
   end
@@ -336,7 +333,6 @@ then strips off the response body.
 
 Feel free to override this method at will.
 @return [self]
-@since 0.0.1
 =end
   def http_HEAD request, response
     self.http_GET request, response
@@ -352,12 +348,13 @@ Feel free to override this method at will.
 
 =begin markdown
 @private
+@param [Rackful::Request] request
+@param [Rack::Response] response
 @return [void]
 @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
-@since 0.0.1
 =end
   def http_GET request, response
-    raise HTTP404NotFound if self.empty?
+    raise HTTP404NotFound, path if self.empty?
     # May throw HTTP406NotAcceptable:
     content_type = self.class.best_content_type( request.accept )
     response['Content-Type'] = content_type
@@ -377,12 +374,12 @@ Wrapper around {#do_METHOD #do_GET}
 @private
 @return [void]
 @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
-@since 0.0.1
 =end
   def http_DELETE request, response
-    raise HTTP404NotFound if self.empty?
+    raise HTTP404NotFound, path if self.empty?
+    raise HTTP405MethodNotAllowed unless self.respond_to?( :destroy )
     response.status = status_code( :no_content )
-    if headers = self.destroy
+    if headers = self.destroy( request, response )
       response.headers.merge! headers
     end
   end
@@ -391,8 +388,7 @@ Wrapper around {#do_METHOD #do_GET}
 =begin markdown
 @private
 @return [void]
-@raise [HTTP415UnsupportedMediaType] `405 Method Not Allowed` if the resource doesn't implement the `PUT` method.
-@since 0.0.1
+@raise [HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the resource doesn't implement the `PUT` method.
 =end
   def http_PUT request, response
     raise HTTP405MethodNotAllowed unless self.respond_to? :do_PUT
@@ -411,7 +407,6 @@ Wrapper around {#do_METHOD #do_PUT}
 @private
 @return [void]
 @raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement the `PUT` method.
-@since 0.0.1
 =end
   def http_method request, response
     method = request.request_method.to_sym
@@ -430,7 +425,6 @@ Wrapper around {#do_METHOD #do_PUT}
 
 =begin markdown
 Adds `ETag:` and `Last-Modified:` response headers.
-@since 0.0.1
 =end
   def default_headers
     r = {}
@@ -444,4 +438,34 @@ Adds `ETag:` and `Last-Modified:` response headers.
 
 end # module Resource
 
+
+=begin unused
+module Collection
+
+
+  include Enumerable
+
+
+  def self.included( modul )
+    unless modul.kind_of? Resource
+      raise "module #{self} included in #{modul}, which isn't a Rackful::Resource"
+    end
+  end
+  
+  
+  def recurse?; false; end
+  
+  
+  def each_pair
+    self.each do
+      |path|
+      yield [ path, Request.current.resource_factory( path ) ]
+    end
+  end
+
+
+end # module Collection
+=end
+
+
 end # module Rackful