rack-accept-media-types 0.9

data/.gitignore

@@ -0,0 +1,3 @@
+doc/
+pkg/
+.yardoc

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2009 Martin Aumont (mynyml)
+
+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/Manifest

@@ -0,0 +1,11 @@
+.gitignore
+LICENSE
+Manifest
+README
+Rakefile
+examples.rb
+lib/rack/accept_media_types.rb
+rack-accept-media-types.gemspec
+specs.watchr
+test/test_accept_media_types.rb
+test/test_helper.rb

data/README

@@ -0,0 +1,25 @@
+===== Sumarry
+
+Rack convenience middleware for simplified handling of Accept header
+(env['HTTP_ACCEPT']). Allows ordering of its values (accepted media types)
+according to their "quality" (preference level).
+
+This wrapper is typically used to determine the request's prefered media
+type (see example below).
+
+===== Install
+
+  gem install rack-accept-media-types --source http://gemcutter.org
+
+===== Examples
+
+  env['HTTP_ACCEPT']  #=> 'application/xml;q=0.8,text/html,text/plain;q=0.9'
+
+  req = Rack::Request.new(env)
+  req.accept_media_types          #=> ['text/html', 'text/plain', 'application/xml']
+  req.accept_media_types.prefered #=>  'text/html'
+
+===== Links
+
+source:: http://github.com/mynyml/rack-accept-media-types
+rdocs::  http://docs.github.com/mynyml/rack-accept-media-types

data/Rakefile

@@ -0,0 +1,25 @@
+def gem_opt
+  defined?(Gem) ? "-rubygems" : ""
+end
+
+# --------------------------------------------------
+# Tests
+# --------------------------------------------------
+task(:default => :test)
+
+desc "Run tests"
+task(:test) do
+  system "ruby #{gem_opt} test/test_accept_media_types.rb"
+end
+
+# --------------------------------------------------
+# Docs
+# --------------------------------------------------
+desc "Generate YARD Documentation"
+task(:yardoc) do
+  require 'yard'
+  files   = %w( lib/**/*.rb )
+  options = %w( -o doc/yard --readme README --files LICENSE )
+  YARD::CLI::Yardoc.run *(options + files)
+end
+

data/examples.rb

@@ -0,0 +1,56 @@
+require 'pathname'
+require 'rubygems'
+require 'rack'
+require 'simple_example' # gem install mynyml-simple_example
+
+root = Pathname(__FILE__).dirname.expand_path
+require root + 'lib/rack/accept_media_types'
+
+include SimpleExample
+puts SimpleExample::Format.separator = '-'*10
+
+
+# simple
+env = {'HTTP_ACCEPT' => 'text/html,text/plain'}
+example do
+  types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'])
+  #=> ["text/html", "text/plain"]
+  types.prefered
+  #=> "text/html"
+end
+
+# with quality values
+env = {'HTTP_ACCEPT' => 'text/html;q=0.5,text/plain;q=0.9'}
+example do
+  types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'])
+  #=> ["text/plain", "text/html"]
+  types.prefered
+  #=> "text/plain"
+end
+
+# rejects types with invalid quality values
+env = {'HTTP_ACCEPT' => 'text/html;q=0,text/plain;q=1.1,application/xml'}
+example do
+  types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'])
+  #=> ["application/xml"]
+  types.prefered
+  #=> "application/xml"
+end
+
+# no accept header means client accepts all types (rfc2616-sec14.1)
+env = {'HTTP_ACCEPT' => nil}
+example do
+  types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'])
+  #=> ["*/*"]
+  types.prefered
+  #=> "*/*"
+end
+
+# to avoid getting a wildcard media-range, pass an empty string instead
+env = {'HTTP_ACCEPT' => nil}
+example do
+  types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'] || '')
+  #=> []
+  types.prefered
+  #=> nil
+end

data/lib/rack/accept_media_types.rb

@@ -0,0 +1,128 @@
+module Rack
+  class Request
+    # The media types of the HTTP_ACCEPT header ordered according to their
+    # "quality" (preference level), without any media type parameters.
+    #
+    # ===== Examples
+    #
+    #   env['HTTP_ACCEPT']  #=> 'application/xml;q=0.8,text/html,text/plain;q=0.9'
+    #
+    #   req = Rack::Request.new(env)
+    #   req.accept_media_types          #=> ['text/html', 'text/plain', 'application/xml']
+    #   req.accept_media_types.prefered #=>  'text/html'
+    #
+    # For more information, see:
+    # * Acept header:   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+    # * Quality values: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.9
+    #
+    # ===== Returns
+    # AcceptMediaTypes:: ordered list of accept header's media types
+    #
+    def accept_media_types
+       @accept_media_types ||= Rack::AcceptMediaTypes.new(@env['HTTP_ACCEPT'])
+    end
+  end
+
+  # AcceptMediaTypes is intended for wrapping env['HTTP_ACCEPT'].
+  #
+  # It allows ordering of its values (accepted media types) according to their
+  # "quality" (preference level).
+  #
+  # This wrapper is typically used to determine the request's prefered media
+  # type (see example below).
+  #
+  # ===== Examples
+  #
+  #   env['HTTP_ACCEPT']  #=> 'application/xml;q=0.8,text/html,text/plain;q=0.9'
+  #
+  #   types = Rack::AcceptMediaTypes.new(env['HTTP_ACCEPT'])
+  #   types               #=> ['text/html', 'text/plain', 'application/xml']
+  #   types.prefered      #=>  'text/html'
+  #
+  # ===== Notes
+  #
+  # For simplicity, media type parameters are striped, as they are seldom used
+  # in practice. Users who need them are excepted to parse the Accept header
+  # manually.
+  #
+  # ===== References
+  #
+  # HTTP 1.1 Specs:
+  # * http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+  # * http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.9
+  #
+  class AcceptMediaTypes < Array
+
+    #--
+    # NOTE
+    # Reason for special handling of nil accept header:
+    #
+    # "If no Accept header field is present, then it is assumed that the client
+    # accepts all media types."
+    #
+    def initialize(header)
+      if header.nil?
+        replace(['*/*'])
+      else
+        replace(order(header.split(',')))
+      end
+    end
+
+    # The client's prefered media type.
+    def prefered
+      first
+    end
+
+    private
+
+    # Order media types by quality values, remove invalid types, and return media ranges.
+    #
+    def order(types) #:nodoc:
+      types.map {|type| AcceptMediaType.new(type) }.reverse.sort.reverse.select {|type| type.valid? }.map {|type| type.range }
+    end
+
+    # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+    #
+    class AcceptMediaType #:nodoc:
+      include Comparable
+
+      # media-range = ( "*/*"
+      #               | ( type "/" "*" )
+      #               | ( type "/" subtype )
+      #               ) *( ";" parameter )
+      attr_accessor :range
+
+      # qvalue = ( "0" [ "." 0*3DIGIT ] )
+      #        | ( "1" [ "." 0*3("0") ] )
+      attr_accessor :quality
+
+      def initialize(type)
+        self.range, *params = type.split(';')
+        self.quality = extract_quality(params)
+      end
+
+      def <=>(type)
+        self.quality <=> type.quality
+      end
+
+      # "A weight is normalized to a real number in the range 0 through 1,
+      # where 0 is the minimum and 1 the maximum value. If a parameter has a
+      # quality value of 0, then content with this parameter is `not
+      # acceptable' for the client."
+      #
+      def valid?
+        self.quality.between?(0.1, 1)
+      end
+
+      private
+        # Extract value from 'q=FLOAT' parameter if present, otherwise assume 1
+        #
+        # "The default value is q=1."
+        #
+        def extract_quality(params)
+          q = params.detect {|p| p.match(/q=\d\.?\d{0,3}/) }
+          q ? q.split('=').last.to_f : 1.0
+        end
+    end
+  end
+end

data/rack-accept-media-types.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name                = 'rack-accept-media-types'
+  s.version             = "0.9"
+  s.summary             = "Rack middleware for simplified handling of Accept header"
+  s.description         = "Rack middleware for simplified handling of Accept header. Accept header parser."
+  s.author              = "mynyml"
+  s.email               = "mynyml@gmail.com"
+  s.homepage            = "http://github.com/mynyml/rack-accept-media-types"
+  s.rubyforge_project   = "rack-accept-media-types"
+  s.has_rdoc            =  false
+  s.require_path        = "lib"
+  s.files               =  File.read("Manifest").strip.split("\n")
+
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'rack'
+end

data/specs.watchr

@@ -0,0 +1,35 @@
+# Run me with:
+#
+#   $ watchr specs.watchr
+
+# --------------------------------------------------
+# Helpers
+# --------------------------------------------------
+def run(cmd)
+  puts(cmd)
+  system(cmd)
+end
+
+def run_all_tests
+  system( "rake -s test" )
+end
+
+# --------------------------------------------------
+# Watchr Rules
+# --------------------------------------------------
+watch( '^test/test_accept_media_types\.rb'   )  { run_all_tests }
+watch( '^lib/rack/accept_media_types\.rb'    )  { run_all_tests }
+watch( '^test/test_helper\.rb'               )  { run_all_tests }
+
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+# Ctrl-\
+Signal.trap('QUIT') do
+  puts " --- Running all tests ---\n\n"
+  run_all_tests
+end
+
+# Ctrl-C
+Signal.trap('INT') { abort("\n") }
+

data/test/test_accept_media_types.rb

@@ -0,0 +1,104 @@
+require 'test/test_helper'
+
+Accept = Rack::AcceptMediaTypes
+
+class AcceptMediaTypesTest < MiniTest::Unit::TestCase
+
+  test "media type list" do
+    header = 'text/html,text/plain'
+    assert_equal %w( text/html text/plain ).to_set, Accept.new(header).to_set
+  end
+
+  test "ordered by quality value (highest first)" do
+    header = 'text/html;q=0.5,text/plain;q=0.9'
+    assert_equal %w( text/plain text/html ), Accept.new(header)
+  end
+
+  test "default quality value is 1" do
+    header = 'text/plain;q=0.1,text/html'
+    assert_equal %w( text/html text/plain ), Accept.new(header)
+  end
+
+  test "equal quality types keep original order" do
+    header = 'text/html,text/plain;q=0.9,application/xml'
+    assert_equal %w( text/html application/xml text/plain ), Accept.new(header)
+  end
+
+  test "prefered type" do
+    header = 'text/html;q=0.2,text/plain;q=0.5'
+    assert_equal 'text/plain', Accept.new(header).prefered
+  end
+
+  test "types with out of range quality values are ignored" do
+    header = 'text/html,text/plain;q=1.1'
+    assert_equal %w( text/html ), Accept.new(header)
+
+    header = 'text/html,text/plain;q=0'
+    assert_equal %w( text/html ), Accept.new(header)
+  end
+
+  test "custom media types are NOT ignored" do
+    # verifying that the media types exist in Rack::Mime::MIME_TYPES is
+    # explicitly outside the scope of this library.
+    header = 'application/x-custom'
+    assert_equal %w( application/x-custom ), Accept.new(header)
+  end
+
+  test "media-range parameters are discarted" do
+    header = 'text/html;version=5;q=0.5,text/plain'
+    assert_equal %w( text/plain text/html ), Accept.new(header)
+  end
+
+  test "accept-extension parameters are discarted" do
+    header = 'text/html;q=0.5;token=value,text/plain'
+    assert_equal %w( text/plain text/html ), Accept.new(header)
+  end
+
+  test "nil accept header" do
+    header = nil
+    assert_equal %w( */* ), Accept.new(header)
+  end
+
+  test "empty accept header" do
+    header = ''
+    assert_equal [], Accept.new(header)
+  end
+
+  test "all accepted types are invalid" do
+    header = 'text/html;q=2,application/xml;q=0'
+    assert_equal [], Accept.new(header)
+  end
+
+  test "Request class integration" do
+    env = {'HTTP_ACCEPT' => 'text/html;q=0.5;token=value,text/plain'}
+    assert_equal %w( text/plain text/html ), Rack::Request.new(env).accept_media_types
+  end
+
+  test "memoizes request's accept_media_types" do
+    env = {'HTTP_ACCEPT' => 'text/html;q=0.5;token=value,text/plain'}
+    req = Rack::Request.new(env)
+    types1 = req.accept_media_types
+    types2 = req.accept_media_types
+    assert_same types1, types2
+  end
+end
+
+__END__
+http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+14.1 Accept
+
+  Accept         = "Accept" ":"
+                  #( media-range [ accept-params ] )
+
+  media-range    = ( "*/*"
+                  | ( type "/" "*" )
+                  | ( type "/" subtype )
+                  ) *( ";" parameter )
+  accept-params  = ";" "q" "=" qvalue *( accept-extension )
+  accept-extension = ";" token [ "=" ( token | quoted-string ) ]
+
+http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.9
+3.9 Quality Values
+
+  qvalue = ( "0" [ "." 0*3DIGIT ] )
+         | ( "1" [ "." 0*3("0") ] )

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'pathname'
+require 'minitest/autorun'
+require 'rack'
+begin
+  require 'phocus'
+  require 'redgreen' #http://gemcutter.org/gems/mynyml-redgreen
+  require 'ruby-debug'
+rescue LoadError, RuntimeError
+end
+
+root = Pathname(__FILE__).dirname.parent.expand_path
+$:.unshift(root.join('lib'))
+
+require 'rack/accept_media_types'
+
+class MiniTest::Unit::TestCase
+  def self.test(name, &block)
+    name = :"test_#{name.gsub(/\s/,'_')}"
+    define_method(name, &block)
+  end
+end
+

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: rack-accept-media-types
+version: !ruby/object:Gem::Version 
+  version: "0.9"
+platform: ruby
+authors: 
+- mynyml
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-21 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Rack middleware for simplified handling of Accept header. Accept header parser.
+email: mynyml@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- LICENSE
+- Manifest
+- README
+- Rakefile
+- examples.rb
+- lib/rack/accept_media_types.rb
+- rack-accept-media-types.gemspec
+- specs.watchr
+- test/test_accept_media_types.rb
+- test/test_helper.rb
+has_rdoc: false
+homepage: http://github.com/mynyml/rack-accept-media-types
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rack-accept-media-types
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Rack middleware for simplified handling of Accept header
+test_files: []
+