RubyGems - rackful - Versions diffs - 0.1.4 → 0.2.0 - Mend

rackful 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

checksums.yaml +7 -0
data/CHANGES.md +18 -8
data/RACKFUL.md +46 -34
data/README.md +11 -5
data/example/config.ru +19 -25
data/lib/rackful.rb +11 -2
data/lib/rackful/httpstatus.rb +250 -0
data/lib/rackful/middleware.rb +2 -3
data/lib/rackful/middleware/headerspoofing.rb +49 -0
data/lib/rackful/middleware/methodoverride.rb +136 -0
data/lib/rackful/parser.rb +315 -0
data/lib/rackful/request.rb +103 -53
data/lib/rackful/resource.rb +158 -221
data/lib/rackful/serializer.rb +133 -215
data/lib/rackful/server.rb +76 -86
data/lib/rackful/uri.rb +150 -0
data/mkdoc.sh +4 -2
data/rackful.gemspec +6 -5
metadata +66 -58
data/lib/rackful/http_status.rb +0 -285
data/lib/rackful/middleware/header_spoofing.rb +0 -72
data/lib/rackful/middleware/method_spoofing.rb +0 -101
data/lib/rackful/middleware/relative_location.rb +0 -71
data/lib/rackful/path.rb +0 -179

data/lib/rackful/serializer.rb CHANGED Viewed

@@ -1,240 +1,204 @@
-# Required for parsing:
-# Required for running:
-require 'rack/utils'
-require 'uri'
-require 'base64'
-require 'json'
-require 'time'
-#require 'json/pure'
+# encoding: utf-8
 module Rackful
-=begin markdown
-Base class for all serializers.
-The default serializers defined in this library ({Rackful::XHTML} and {Rackful::JSON})
-depend on the availability of method {Rackful::Resource#to_rackful}.
-@abstract Subclasses must implement method `#each` end define constant
-  `CONTENT_TYPES`
-=end
+# Base class for all serializers.
+#
+# The serializers {Serializer::XHTML} and {Serializer::JSON} defined in this
+# library depend on the presence of method
+# {Rackful::Resource#to_rackful resource.to_rackful}.
+# @abstract Subclasses must implement method `#each` end define constant
+#   `CONTENT_TYPES`
+# @!attribute [r] request
+#   @return [Request]
+# @!attribute [r] resource
+#   @return [Resource]
+# @!attribute [r] content_type
+#   @return [String] The content type to be served by this Serializer. This will
+#     always be one of the content types listed in constant `CONTENT_TYPES`.
 class Serializer
   include Enumerable
-  attr_reader :resource, :content_type
+  attr_reader :request, :resource, :content_type
-  def initialize resource, content_type
-    @resource, @content_type = resource, content_type
-  end
-=begin markdown
-Every serializer must implement this method.
-@abstract
-@yield [data] the entity body
-=end
-  def each
-    raise "Class #{self.class} doesn't implement #each()."
+  # @param request [Request]
+  # @param resource [Resource]
+  # @param content_type [String]
+  def initialize request, resource, content_type
+    @request, @resource, @content_type =
+      request, resource, content_type
   end
-=begin markdown
-@!method headers()
-  Extra response headers that a serializer likes to return.
+  # @!method headers()
+  #   Extra response headers that a serializer likes to return.
+  #
+  #   You don't have to include the `Content-Type` header, as this is done
+  #   _for_ you.
+  #
+  #   This method is optional.
+  #   @return [Hash]
+  #   @abstract
-  You don't have to include the `Content-Type` header, as this is done _for_ you.
-  This method is optional.
-  @return [Hash, nil]
-  @abstract
-=end
+  # @abstract Every serializer must implement this method.
+  # @yieldparam block [String] (part of) the entity body
+  def each
+    raise NotImplementedError
+  end
 end # class Serializer
-=begin markdown
-=end
-class XHTML < Serializer
+class Serializer::XHTML < Serializer
   # The content types served by this serializer.
   # @see Serializer::CONTENT_TYPES
   CONTENT_TYPES = [
-    'application/xhtml+xml; charset=UTF-8',
-    'text/html; charset=UTF-8',
+    'application/xml; charset=UTF-8',
     'text/xml; charset=UTF-8',
-    'application/xml; charset=UTF-8'
+    'text/html; charset=UTF-8',
+    'application/xhtml+xml; charset=UTF-8',
   ]
+  # @api private
+  # @return [URI::HTTP]
+  def html_base_uri
+    @html_base_uri ||= begin
+      retval = self.request.canonical_uri.dup
+      retval.path = retval.path.sub( %r{[^/]+\z}, '' )
+      retval.query = nil
+      retval
+    end
+  end
-=begin
-@yieldparam xhtml [String]
-=end
+  # @yieldparam xhtml [String]
   def each &block
-    request = Request.current
+    tmp = ''
+    # The XML header is only sent for XML media types:
     if /xml/ === self.content_type
-      yield <<EOS
+      tmp += <<EOS
 <?xml version="1.0" encoding="UTF-8"?>
 EOS
     end
-    yield <<EOS
+    tmp += <<EOS
 <!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <head>
-<title>#{ Rack::Utils.escape_html(resource.title) }</title>
+<title>#{ Rack::Utils.escape_html(self.resource.title) }</title>
+<base href="#{self.html_base_uri}"/>
 EOS
-    #~ unless request.path == request.content_path
-      yield <<EOS
-<base href="#{request.base_path.relative request.path}"/>
-EOS
-    #~ end
-    unless '/' == request.path
-      yield <<EOS
-<link rel="contents" href="#{'/' === request.content_path[-1] ? '../' : './' }"/>
+    unless '/' == self.request.canonical_uri.path
+      tmp += <<EOS
+<link rel="contents" href="#{'/' === self.request.canonical_uri.path[-1] ? '../' : './' }"/>
 EOS
     end
-    yield header + '<div id="rackful_content">'
-    each_nested &block
+    r = self.resource.to_rackful
+    tmp += self.header + '<div id="rackful-content"' + self.xsd_type( r ) + '>'
+    yield tmp
+    each_nested( r, &block )
     yield '</div>' + footer
   end
-  # Look at the source code!
+  # @api private
   def header
     self.class.class_variable_defined?( :@@header ) && @@header ?
       @@header.call( self ) :
       "</head><body>"
   end
+  # Set a header generator.
+  # @yieldparam serializer [Serializer::XHTML] This serializer
+  # @yieldreturn [String] some XHTML
   def self.header &block
     @@header = block
     self
   end
-  # Look at the source code!
+  # @api private
   def footer
     self.class.class_variable_defined?( :@@footer ) && @@footer ?
       @@footer.call( self ) :
-      '<div class="rackful_powered">Powered by <a href="http://github.com/pieterb/Rackful">Rackful</a></div></body></html>'
+      '<div class="rackful-powered">Powered by <a href="http://github.com/pieterb/Rackful">Rackful</a></div></body></html>'
   end
+  # Set a footer generator.
+  # @yieldparam serializer [Serializer::XHTML] This serializer
+  # @yieldreturn [String] some XHTML
   def self.footer &block
     @@footer = block
     self
   end
-=begin markdown
-Serializes many kinds of objects to XHTML.
-How an object is serialized, depends:
-*   A *{Resource}* will be serialized by its own
-    {Resource#serializer serializer}.
-*   A *{Path}* will be serialized as a hyperlink.
-*   An Object responding to *`#each_pair`* (i.e. something {Hash}-like) will
-    be represented by
-    *   a descriptive list, with
-*   An Object responding to *`#each`* (i.e. something {Enumerable}) will
-    be represented as a JSON array.
-*   A *binary encoded {String}* (i.e. a blob} is represented by a JSON string,
-    containing the base64 encoded version of the data.
-*   A *{Time}* is represented by a string containing a dateTime as defined by
-    XMLSchema.
-*   On *all the rest,* method `#to_json` is invoked.
-@overload each_nested
-  @yieldparam xhtml[String]
-=end
+  # Serializes many kinds of objects to XHTML.
+  #
+  # How an object is serialized, depends:
+  #
+  # * A *{Resource}* will be serialized by its own {Resource#serializer serializer}.
+  # * A *{URI}* will be serialized as a hyperlink.
+  # * An Object responding to *`#each_pair`* (i.e. something {Hash}-like) will
+  #   be represented by
+  #   * a descriptive list, with
+  # * An Object responding to *`#each`* (i.e. something {Enumerable}) will
+  #   be represented as a JSON array.
+  # * A *binary encoded {String}* (i.e. a blob} is represented by a JSON string,
+  #   containing the base64 encoded version of the data.
+  # * A *{Time}* is represented by a string containing a dateTime as defined by
+  #   XMLSchema.
+  # * On *all the rest,* method `#to_json` is invoked.
+  # @overload each_nested
+  #   @yieldparam xhtml [String]
+  # @api private
   def each_nested p = self.resource.to_rackful, &block
+    # A Resource:
     if p.kind_of?( Resource ) && ! p.equal?( self.resource )
-      p.serializer( self.content_type ).each_nested &block
-    elsif p.kind_of?( Path )
-      yield "<a href=\"#{p.relative}\">" +
-        Rack::Utils.escape_html( Rack::Utils.unescape(
-          File::basename(p.unslashify)
-        ) ) + '</a>'
-#     elsif p.kind_of?( Collection )
-#       if p.recurse?
-#         yield '<dl class="rackful-resources">'
-#         p.each_pair do
-#           |path, child|
-#           yield '<dt>'
-#           self.each_nested path, &block
-#           yield "</dt><dd#{self.xsd_type(child)}>"
-#           self.each_nested child, &block
-#           yield "</dd>\n"
-#         end
-#         yield '</dl>'
-      #~ elsif ( q = p.first ) and
-            #~ q.kind_of?( Enumerable )
-              #~ q.respond_to?( :keys ) && ( keys = q.keys ) &&
-              #~ p.all? { |r| r.respond_to?( :keys ) && r.keys == keys }
-            #~ )
-        #~ yield '<table class="rackful-objects"><thead><tr>' +
-          #~ keys.collect {
-            #~ |column|
-            #~ '<th>' +
-            #~ Rack::Utils.escape_html( column.to_s.split('_').join(' ') ) +
-            #~ "</th>\n"
-          #~ }.join + '</tr></thead><tbody>'
-        #~ p.each do
-          #~ |h|
-          #~ yield '<tr>'
-          #~ h.each_pair do
-            #~ |key, value|
-            #~ yield "<td class=\"rackful-objects-#{Rack::Utils.escape_html( key.to_s )}\"#{self.xsd_type(value)}>"
-            #~ self.each_nested value, &block
-            #~ yield "</td>\n"
-          #~ end
-          #~ yield '</tr>'
-        #~ end
-        #~ yield "</tbody></table>"
-#       else
-#         yield '<ul class="rackful-resources">'
-#         p.each do
-#           |value|
-#           yield "<li#{self.xsd_type(value)}>"
-#           self.each_nested value, &block
-#           yield "</li>\n"
-#         end
-#         yield '</ul>'
-#       end
+      p.serializer( self.request, self.content_type ).each_nested( &block )
+    # A URI:
+    elsif p.kind_of?( URI )
+      rel_path = p.relative? ? p : p.route_from( self.html_base_uri )
+      yield "<a href=\"#{rel_path}\">" +
+        Rack::Utils.escape_html( Rack::Utils.unescape( rel_path.to_s ) ) + '</a>'
+    # An Object:
     elsif p.respond_to?( :each_pair )
-      yield '<br/><dl class="rackful-object">'
+      yield '<br/><dl>'
       p.each_pair do
         |key, value|
-        yield "<dt#{self.xsd_type(key)}>"
-        self.each_nested key, &block
-        yield "</dt><dd#{self.xsd_type(value)}>"
+        yield '<dt xs:type="xs:string">' +
+          Rack::Utils.escape_html( key.to_s.split('_').join(' ') ) +
+          "</dt><dd#{self.xsd_type(value)}>"
         self.each_nested value, &block
         yield "</dd>\n"
       end
       yield '</dl>'
+    # A List of Objects with identical keys:
     elsif p.kind_of?( Enumerable ) and
           ( q = p.first ) and
           (
             q.respond_to?( :keys ) && ( keys = q.keys ) &&
             p.all? { |r| r.respond_to?( :keys ) && r.keys == keys }
           )
-      yield '<table class="rackful-objects"><thead><tr>' +
+      yield '<table><thead><tr>' +
         keys.collect {
           |column|
-          '<th>' +
+          '<th xs:type="xs:string">' +
           Rack::Utils.escape_html( column.to_s.split('_').join(' ') ) +
           "</th>\n"
         }.join + '</tr></thead><tbody>'
@@ -243,16 +207,17 @@ How an object is serialized, depends:
         yield '<tr>'
         h.each_pair do
           |key, value|
-          yield "<td class=\"rackful-objects-#{Rack::Utils.escape_html( key.to_s )}\"#{self.xsd_type(value)}>"
+          yield "<td#{self.xsd_type(value)}>"
           self.each_nested value, &block
           yield "</td>\n"
         end
         yield '</tr>'
       end
       yield "</tbody></table>"
+    # A List:
     elsif p.kind_of?( Enumerable )
-      yield '<ul class="rackful-array">'
+      yield '<ul>'
       p.each do
         |value|
         yield "<li#{self.xsd_type(value)}>"
@@ -260,21 +225,24 @@ How an object is serialized, depends:
         yield "</li>\n"
       end
       yield '</ul>'
+    # A Time:
     elsif p.kind_of?( Time )
       yield p.utc.xmlschema
+    # A Blob:
     elsif p.kind_of?( String ) && p.encoding == Encoding::BINARY
       yield Base64.encode64(p).chomp
+    # Something serializable (including nil, true, false, Numeric):
     else
       yield Rack::Utils.escape_html( p.to_s )
     end
   end
-  # @private
+  # @api private
   def xsd_type v
     if v.respond_to? :to_rackful
       v = v.to_rackful
@@ -289,7 +257,7 @@ How an object is serialized, depends:
       ' xs:type="xs:dateTime"'
     elsif v.kind_of?( String ) && v.encoding == Encoding::BINARY
       ' xs:type="xs:base64Binary"'
-    elsif v.kind_of?( String ) && !v.kind_of?( Path )
+    elsif v.kind_of?( String )
       ' xs:type="xs:string"'
     else
       ''
@@ -297,10 +265,10 @@ How an object is serialized, depends:
   end
-end # class XHTML
+end # class Serializer::XHTML
-class JSON < Serializer
+class Serializer::JSON < Serializer
   CONTENT_TYPES = [
@@ -309,31 +277,11 @@ class JSON < Serializer
   ]
-=begin markdown
-Serializes many kinds of objects to JSON.
-How an object is serialized, depends:
-*   A *{Resource}* will be serialized by its own
-    {Resource#serializer serializer}.
-*   A *{Path}* will be serialized by a string, containing the relative path.
-*   An Object responding to *`#each_pair`* (i.e. something {Hash}-like) will
-    be represented as a JSON object.
-*   An Object responding to *`#each`* (i.e. something {Enumerable}) will
-    be represented as a JSON array.
-*   A *binary encoded {String}* (i.e. a blob} is represented by a JSON string,
-    containing the base64 encoded version of the data.
-*   A *{Time}* is represented by a string containing a dateTime as defined by
-    XMLSchema.
-*   On *all the rest,* method `#to_json` is invoked.
-@overload each
-  @yieldparam json [String]
-=end
+  # @yield [json]
+  # @yieldparam json [String]
   def each thing = self.resource.to_rackful, &block
     if thing.kind_of?( Resource ) && ! thing.equal?( self.resource )
-      thing.serializer( self.content_type ).each &block
-    elsif thing.kind_of?( Path )
-      yield thing.relative.to_json
+      thing.serializer( self.content_type ).each( &block )
     elsif thing.respond_to? :each_pair
       first = true
       thing.each_pair do
@@ -362,37 +310,7 @@ How an object is serialized, depends:
   end
-  def self.parse input
-    r = ::JSON.parse(
-      input.read,
-      :symbolize_names => true
-    )
-    self.recursive_datetime_parser r
-  end
-  def self.recursive_datetime_parser p
-    if p.kind_of?(String)
-      begin
-        return Time.xmlschema(p)
-      rescue
-      end
-    elsif p.kind_of?(Hash)
-      p.keys.each do
-        |key|
-        p[key] = self.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] )
-      end
-    end
-    p
-  end
-end # class HTTPStatus::JSON
+end # class Serializer::JSON
 end # module Rackful