rack-accept 0.1.1 → 0.2

data/{rack-accept.gemspec → .gemspec}

@@ -1,11 +1,10 @@
 Gem::Specification.new do |s|
-
   s.name = 'rack-accept'
-  s.version = '0.1.1'
-  s.date = '2010-04-01'
+  s.version = '0.2'
+  s.date = '2010-04-02'
 
-  s.summary = 'HTTP Accept* tools for Rack'
-  s.description = 'HTTP Accept, Accept-Charset, Accept-Encoding, and Accept-Language tools for Rack'
+  s.summary = 'HTTP Accept* for Ruby/Rack'
+  s.description = 'HTTP Accept, Accept-Charset, Accept-Encoding, and Accept-Language for Ruby/Rack'
 
   s.author = 'Michael J. I. Jackson'
   s.email = 'mjijackson@gmail.com'
@@ -14,7 +13,8 @@ Gem::Specification.new do |s|
 
   s.files = Dir['lib/**/*.rb'] +
     Dir['test/*.rb'] +
-    %w< CHANGES rack-accept.gemspec Rakefile README >
+    Dir['doc/**/*'] +
+    %w< CHANGES .gemspec Rakefile README >
 
   s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/ }
 
@@ -25,6 +25,5 @@ Gem::Specification.new do |s|
   s.rdoc_options = %w< --line-numbers --inline-source --title Rack::Accept --main Rack::Accept >
   s.extra_rdoc_files = %w< CHANGES README >
 
-  s.homepage = 'http://github.com/mjijackson/rack-accept'
-
+  s.homepage = 'http://mjijackson.github.com/rack-accept'
 end

data/CHANGES

@@ -1,3 +1,12 @@
-## 0.1 / April 2010
+## 0.2 / April 2, 2010
+
+  * Moved all common header methods into Rack::Accept::Header module
+  * Many improvements to the documentation
+
+## 0.1.1 / April 1, 2010
+
+  * Whoops, forgot to require Rack. :]
+
+## 0.1 / April 1, 2010
 
   * Initial release

data/README

@@ -1,9 +1,17 @@
 Rack::Accept
 ============
 
-rack-accept is a suite of tools for Rack/Ruby applications that eases the
-complexity of reading and writing Accept, Accept-Charset, Accept-Encoding, and
-Accept-Language HTTP request headers.
+Rack::Accept is a suite of tools for Ruby/Rack applications that eases the
+complexity of building and interpreting the Accept* family of HTTP request
+headers.
+
+Some features of the library are:
+
+  * Strict adherence to RFC 2616, specifically section 14
+  * Full support for the Accept, Accept-Charset, Accept-Encoding, and
+    Accept-Language HTTP request headers
+  * May be used as Rack middleware or standalone
+  * A comprehensive test suite that covers many edge cases
 
 Installation
 ------------
@@ -15,12 +23,12 @@ Using RubyGems:
 From a local copy:
 
     $ git clone git://github.com/mjijackson/rack-accept.git
-    $ rake package && sudo rake install
+    $ sudo rake install
 
 Usage
 -----
 
-rack-accept implements the Rack middleware interface and may be used with any
+Rack::Accept implements the Rack middleware interface and may be used with any
 Rack-based application. Simply insert the Rack::Accept module in your Rack
 middleware pipeline and access the Rack::Accept::Request object in the
 "rack-accept.request" environment key, as in the following example:
@@ -30,22 +38,52 @@ middleware pipeline and access the Rack::Accept::Request object in the
     use Rack::Accept
 
     app = lambda {|env|
-        accept = env['rack-accept.request']
-        response = Rack::Response.new
-
-        if accept.media_type?('text/html')
-            response['Content-Type'] = 'text/html'
-            response.write "<p>Hello. You accept text/html!</p>"
-        else
-            response['Content-Type'] = 'text/plain'
-            response.write "Apparently you don't accept text/html. Too bad."
-        end
-
-        response.finish
+      accept = env['rack-accept.request']
+      response = Rack::Response.new
+
+      if accept.media_type?('text/html')
+        response['Content-Type'] = 'text/html'
+        response.write "<p>Hello. You accept text/html!</p>"
+      else
+        response['Content-Type'] = 'text/plain'
+        response.write "Apparently you don't accept text/html. Too bad."
+      end
+
+      response.finish
     }
 
     run app
 
+Additionally, Rack::Accept may be used outside of a Rack context to provide
+any Ruby app the ability to construct and interpret Accept headers.
+
+    require 'rack/accept'
+
+    mtype = Rack::Accept::MediaType.new
+    mtype.qvalues = {
+      'text/html' => 1,
+      'text/*'    => 0.8,
+      '*/*'       => 0.5
+    }
+
+    mtype.to_s # => "Accept: text/html, text/*;q=0.8, */*;q=0.5"
+
+    cset = Rack::Accept::Charset.new('unicode-1-1, iso-8859-5;q=0.8')
+    cset.best_of(%w< iso-8859-5 unicode-1-1 >)  # => "unicode-1-1"
+    cset.accept?('iso-8859-1')                  # => true
+
+The very last line in this example may look like a mistake to someone not
+familiar with the intricacies of the spec, but it's actually correct. It
+just puts emphasis on the convenience of using this library.
+
+Four-letter Words
+-----------------
+
+  Spec: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+  Code: http://github.com/mjijackson/rack-accept
+  Docs: http://mjijackson.github.com/rack-accept
+  Bugs: http://github.com/mjijackson/rack-accept/issues
+
 License
 -------
 

data/Rakefile

@@ -3,7 +3,7 @@ require 'rake/testtask'
 
 task :default => :test
 
-CLEAN.include %w< doc/api >
+CLEAN.include %w< doc/api doc/*.html doc/*.css >
 CLOBBER.include %w< dist >
 
 # TESTS #######################################################################
@@ -14,63 +14,66 @@ end
 
 # DOCS ########################################################################
 
-desc "Generate all documentation"
-task :doc => %w< doc:api doc:etc >
-
-namespace :doc do
-
-  desc "Generate API documentation (in doc/api)"
-  task :api => FileList['lib/**/*.rb'] do |t|
-    rm_rf 'doc/api'
-    sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
-    hanna
-      --op doc/api
-      --promiscuous
-      --charset utf8
-      --fmt html
-      --inline-source
-      --line-numbers
-      --accessor option_accessor=RW
-      --main Rack::Accept
-      --title 'Rack::Accept API Documentation'
-      #{t.prerequisites.join(' ')}
-    SH
-  end
-
-  desc "Generate extra documentation"
-  task :etc do
+desc "Generate HTML documentation (in doc)"
+task :doc => FileList['doc/*.markdown'] do |t|
+  require 'erb' unless defined?(ERB)
+  require 'rdiscount' unless defined?(RDiscount)
+  layout = ERB.new(File.read('doc/assets/layout.html.erb'), 0, '%<>')
+  t.prerequisites.each do |path|
+    source = File.read(path)
+    content = Markdown.new(source, :smart).to_html
+    output = layout.result(binding)
+    File.open(path.sub('.markdown', '.html'), 'w') {|io| io.write(output) }
   end
+  cp 'doc/assets/style.css', 'doc'
+end
 
+desc "Generate API documentation (in doc/api)"
+task :api => FileList['lib/**/*.rb'] do |t|
+  rm_rf 'doc/api'
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --op doc/api
+    --promiscuous
+    --charset utf8
+    --fmt html
+    --inline-source
+    --line-numbers
+    --accessor option_accessor=RW
+    --main Rack::Accept
+    --title 'Rack::Accept API Documentation'
+    #{t.prerequisites.join(' ')}
+  SH
 end
 
-# PACKAGING ###################################################################
+# PACKAGING & INSTALLATION ####################################################
 
 if defined?(Gem)
-  $spec = eval("#{File.read('rack-accept.gemspec')}")
+  $spec = eval("#{File.read('.gemspec')}")
+
+  directory 'dist'
 
   def package(ext='')
     "dist/rack-accept-#{$spec.version}" + ext
   end
 
+  file package('.gem') => %w< dist > + $spec.files do |f|
+    sh "gem build .gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w< dist > + $spec.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
   desc "Build packages"
   task :package => %w< .gem .tar.gz >.map {|e| package(e) }
 
   desc "Build and install as local gem"
-  task :install => package('.gem') do
+  task :install => package('.gem') do |t|
     sh "gem install #{package('.gem')}"
   end
 
-  directory 'dist/'
-
-  file package('.gem') => %w< dist/ rack-accept.gemspec > + $spec.files do |f|
-    sh "gem build rack-accept.gemspec"
-    mv File.basename(f.name), f.name
-  end
-
-  file package('.tar.gz') => %w< dist/ > + $spec.files do |f|
-    sh "git archive --format=tar HEAD | gzip > #{f.name}"
-  end
-
   desc "Upload gem to rubygems.org"
   task :release => package('.gem') do |t|
     sh "gem push #{package('.gem')}"

data/doc/assets/layout.html.erb

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+
+<html lang="en">
+
+<head>
+    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+    <title>Rack::Accept</title>
+    <link rel="stylesheet" href="style.css" type="text/css" media="all">
+</head>
+
+<body>
+    <div id="wrapper">
+        <div id="header">
+            <h1>rack-accept</h1>
+            <ul>
+                <li><a href="license.html">License</a></li>
+                <li><a href="api/index.html">API</a></li>
+                <li><a href="http://github.com/mjijackson/rack-accept/issues">Bugs</a></li>
+                <li><a href="http://github.com/mjijackson/rack-accept">Code</a></li>
+                <li><a href="index.html">Home</a></li>
+            </ul>
+        </div>
+        <div id="content"><%= content %></div>
+        <div id="footer">
+            <p class="rights">Copyright &copy; 2010 <a href="http://mjijackson.com/about" rel="me author">Michael J. I. Jackson</a></p>
+        </div>
+    </div>
+</body>
+
+</html>

data/doc/assets/style.css

@@ -0,0 +1,69 @@
+body {
+  background-color: #EEEEEE;
+  color: #333333;
+  font-family: "HelveticaNeue-Light","Helvetica Neue Light","Helvetica Neue",sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  font-weight: 300;
+  margin: 25px 25px 50px;
+}
+a {
+  color: inherit;
+  text-decoration: none;
+  background-color: #FDFDFD;
+  padding: 3px 5px;
+}
+a:hover {
+  color: #666666;
+}
+h1, h2, h3 {
+  font-weight: 300;
+}
+h1 {
+  font-size: 32px;
+}
+h1, h2, h3, p, pre, ul, ol {
+  margin: 0 0 18px 0;
+}
+ol, ul {
+  padding-left: 36px;
+}
+li {
+  margin: 0;
+  padding: 0;
+}
+code {
+  font-size: 12px;
+  font-family: Menlo, monospace;
+}
+pre {
+  background-color: #FDFDFD;
+  padding-left: 6px;
+}
+#wrapper {
+  position: relative;
+  width: 600px;
+  margin: 0 auto;
+}
+#header {
+  margin-bottom: 36px;
+}
+#header ul {
+  position: absolute;
+  top: 14px;
+  right: 0;
+  list-style-type: none;
+}
+#header ul li {
+  float: right;
+  margin-left: 10px;
+}
+#content {
+  min-height: 400px;
+}
+#footer {
+  margin-top: 36px;
+  text-align: right;
+  font-size: 12px;
+  color: #999999;
+}

data/doc/index.markdown

@@ -0,0 +1,86 @@
+__Rack::Accept__ is a suite of tools for Ruby/Rack applications that eases the
+complexity of building and interpreting the Accept* family of [HTTP request
+headers][rfc].
+
+Some features of the library are:
+
+  * Strict adherence to [RFC 2616][rfc], specifically [section 14][sec14]
+  * Full support for the [Accept][sec14-1], [Accept-Charset][sec14-2],
+    [Accept-Encoding][sec14-3], and [Accept-Language][sec14-4] HTTP request
+    headers
+  * May be used as [Rack][rack] middleware or standalone
+  * A comprehensive [test suite][test] that covers many edge cases
+
+Installation
+------------
+
+Using [RubyGems][rubygems]:
+
+    $ sudo gem install rack-accept
+
+From a local copy:
+
+    $ git clone git://github.com/mjijackson/rack-accept.git
+    $ sudo rake install
+
+Usage
+-----
+
+Rack::Accept implements the Rack middleware interface and may be used with any
+Rack-based application. Simply insert the Rack::Accept module in your Rack
+middleware pipeline and access the [Rack::Accept::Request][req] object in the
+"rack-accept.request" environment key, as in the following example:
+
+    require 'rack/accept'
+
+    use Rack::Accept
+
+    app = lambda {|env|
+      accept = env['rack-accept.request']
+      response = Rack::Response.new
+
+      if accept.media_type?('text/html')
+        response['Content-Type'] = 'text/html'
+        response.write "<p>Hello. You accept text/html!</p>"
+      else
+        response['Content-Type'] = 'text/plain'
+        response.write "Apparently you don't accept text/html. Too bad."
+      end
+
+      response.finish
+    }
+
+    run app
+
+Additionally, Rack::Accept may be used outside of a Rack context to provide
+any Ruby app the ability to construct and interpret Accept headers.
+
+    require 'rack/accept'
+
+    mtype = Rack::Accept::MediaType.new
+    mtype.qvalues = {
+      'text/html' => 1,
+      'text/*'    => 0.8,
+      '*/*'       => 0.5
+    }
+
+    mtype.to_s # => "Accept: text/html, text/*;q=0.8, */*;q=0.5"
+
+    cset = Rack::Accept::Charset.new('unicode-1-1, iso-8859-5;q=0.8')
+    cset.best_of(%w< iso-8859-5 unicode-1-1 >)  # => "unicode-1-1"
+    cset.accept?('iso-8859-1')                  # => true
+
+The very last line in this example may look like a mistake to someone not
+familiar with the intricacies of [the spec][sec14-3], but it's actually
+correct. It just puts emphasis on the convenience of using this library.
+
+[rfc]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
+[sec14]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+[sec14-1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+[sec14-2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2
+[sec14-3]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+[sec14-4]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
+[rack]: http://rack.rubyforge.org/
+[test]: http://github.com/mjijackson/rack-accept/tree/master/test/
+[rubygems]: http://rubygems.org/
+[req]: api/classes/Rack/Accept/Request.html

data/doc/license.markdown

@@ -0,0 +1,19 @@
+Copyright 2010 Michael J. I. Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/rack/accept.rb

@@ -3,7 +3,7 @@ require 'rack'
 module Rack::Accept
 
   # The current version of rack-accept.
-  VERSION = [0, 1, 1]
+  VERSION = [0, 2]
 
   # Returns the current version of rack-accept as a string.
   def self.version

data/lib/rack/accept/charset.rb

@@ -10,28 +10,11 @@ module Rack::Accept
 
     include Header
 
-    attr_reader :qvalues
-
-    def initialize(header)
-      @qvalues = parse(header)
-    end
-
     # The name of this header.
     def name
       'Accept-Charset'
     end
 
-    # The value of this header, built from its internal representation.
-    def value
-      join(@qvalues)
-    end
-
-    # Returns an array of all character set values that were specified in the
-    # original header, in no particular order.
-    def values
-      @qvalues.keys
-    end
-
     # Determines the quality factor (qvalue) of the given +charset+,
     # according to the specifications of the original header.
     def qvalue(charset)
@@ -54,10 +37,5 @@ module Rack::Accept
       }
     end
 
-    # Returns a string representation of this header.
-    def to_s
-      [name, value].join(': ')
-    end
-
   end
 end

data/lib/rack/accept/encoding.rb

@@ -10,28 +10,11 @@ module Rack::Accept
 
     include Header
 
-    attr_reader :qvalues
-
-    def initialize(header)
-      @qvalues = parse(header)
-    end
-
     # The name of this header.
     def name
       'Accept-Encoding'
     end
 
-    # The value of this header, built from its internal representation.
-    def value
-      join(@qvalues)
-    end
-
-    # Returns an array of all encoding values that were specified in the
-    # original header, in no particular order.
-    def values
-      @qvalues.keys
-    end
-
     # Determines the quality factor (qvalue) of the given +encoding+,
     # according to the specifications of the original header.
     def qvalue(encoding)
@@ -54,10 +37,5 @@ module Rack::Accept
       }
     end
 
-    # Returns a string representation of this header.
-    def to_s
-      [name, value].join(': ')
-    end
-
   end
 end

data/lib/rack/accept/header.rb

@@ -46,13 +46,36 @@ module Rack::Accept
     module_function :parse_media_type
 
     module PublicInstanceMethods
-      # Returns the quality factor (qvalue) of the given +value+. This method
-      # is the only method that must be overridden in child classes in order
-      # for them to be able to use all other methods of this module.
+      # A table of all values of this header to their respective quality
+      # factors (qvalues).
+      attr_accessor :qvalues
+
+      def initialize(header='')
+        @qvalues = parse(header)
+      end
+
+      # The name of this header. Should be overridden in classes that mixin
+      # this module.
+      def name
+        ''
+      end
+
+      # Returns the quality factor (qvalue) of the given +value+. Should be
+      # overridden in classes that mixin this module.
       def qvalue(value)
         1
       end
 
+      # Returns the value of this header as a string.
+      def value
+        join(@qvalues)
+      end
+
+      # Returns an array of all values of this header, in no particular order.
+      def values
+        @qvalues.keys
+      end
+
       # Determines if the given +value+ is acceptable (does not have a qvalue
       # of 0) according to this header.
       def accept?(value)
@@ -88,6 +111,11 @@ module Rack::Accept
         s.reject! {|q, v| q == 0 } unless keep_unacceptables
         s.first && s.first[1]
       end
+
+      # Returns a string representation of this header.
+      def to_s
+        [name, value].join(': ')
+      end
     end
 
     include PublicInstanceMethods

data/lib/rack/accept/language.rb

@@ -10,28 +10,11 @@ module Rack::Accept
 
     include Header
 
-    attr_reader :qvalues
-
-    def initialize(header)
-      @qvalues = parse(header)
-    end
-
     # The name of this header.
     def name
       'Accept-Language'
     end
 
-    # The value of this header, built from its internal representation.
-    def value
-      join(@qvalues)
-    end
-
-    # Returns an array of all language values that were specified in the
-    # original header, in no particular order.
-    def values
-      @qvalues.keys
-    end
-
     # Determines the quality factor (qvalue) of the given +language+,
     # according to the specifications of the original header.
     def qvalue(language)
@@ -52,10 +35,5 @@ module Rack::Accept
       }.reverse
     end
 
-    # Returns a string representation of this header.
-    def to_s
-      [name, value].join(': ')
-    end
-
   end
 end

data/lib/rack/accept/media_type.rb

@@ -10,28 +10,11 @@ module Rack::Accept
 
     include Header
 
-    attr_reader :qvalues
-
-    def initialize(header)
-      @qvalues = parse(header)
-    end
-
     # The name of this header.
     def name
       'Accept'
     end
 
-    # The value of this header, built from its internal representation.
-    def value
-      join(@qvalues)
-    end
-
-    # Returns an array of all media type values that were specified in the
-    # original header, in no particular order.
-    def values
-      @qvalues.keys
-    end
-
     # Determines the quality factor (qvalue) of the given +media_type+,
     # according to the specifications of the original header.
     def qvalue(media_type)
@@ -58,10 +41,5 @@ module Rack::Accept
       }.reverse
     end
 
-    # Returns a string representation of this header.
-    def to_s
-      [name, value].join(': ')
-    end
-
   end
 end

data/lib/rack/accept/request.rb

@@ -1,13 +1,13 @@
 module Rack::Accept
 
-  # A container class for convenience methods when rack-accept is used on the
-  # request level (as a Rack middleware, for example). This class manages a
+  # A container class for convenience methods when Rack::Accept is used on the
+  # request level (as Rack middleware, for example). This class manages a
   # lightweight cache of various header instances to speed up execution.
   #
-  # This class currently does not extend Rack::Request because that class
+  # Request currently does not extend Rack::Request because that class
   # currently provides some limited functionality when it comes to determining
-  # the proper encoding to use with a request and I didn't want to confuse the
-  # user.
+  # the proper encoding to use with a request and I didn't want to confuse
+  # users.
   class Request
 
     attr_reader :env

metadata

@@ -4,9 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Michael J. I. Jackson
@@ -14,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-01 00:00:00 -06:00
+date: 2010-04-02 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,7 +41,7 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id002
-description: HTTP Accept, Accept-Charset, Accept-Encoding, and Accept-Language tools for Rack
+description: HTTP Accept, Accept-Charset, Accept-Encoding, and Accept-Language for Ruby/Rack
 email: mjijackson@gmail.com
 executables: []
 
@@ -67,12 +66,16 @@ files:
 - test/language_test.rb
 - test/media_type_test.rb
 - test/request_test.rb
+- doc/assets/layout.html.erb
+- doc/assets/style.css
+- doc/index.markdown
+- doc/license.markdown
 - CHANGES
-- rack-accept.gemspec
+- .gemspec
 - Rakefile
 - README
 has_rdoc: true
-homepage: http://github.com/mjijackson/rack-accept
+homepage: http://mjijackson.github.com/rack-accept
 licenses: []
 
 post_install_message: 
@@ -105,7 +108,7 @@ rubyforge_project:
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: HTTP Accept* tools for Rack
+summary: HTTP Accept* for Ruby/Rack
 test_files: 
 - test/charset_test.rb
 - test/encoding_test.rb