webbed 0.1.1 → 0.2.0

data/lib/webbed/method.rb

@@ -1,64 +1,94 @@
 module Webbed
+  # Representation of an HTTP Method.
   class Method
-    
-    attr_reader :name
-    alias :to_s :name
-    alias :inspect :name
-    
     DEFAULTS = {
       :safe => false,
       :idempotent => false,
-      :entities => [:request, :response]
+      :allowable_entities => [:request, :response]
     }
     
-    def self.new(name, options = {})
-      if const_defined? name
-        const_get(name)
+    # The allowable entities of a message.
+    # 
+    # It can contain any combination of `:request` and `:response`.
+    # 
+    # @return [Array<:request, :response>]
+    attr_reader :allowable_entities
+    
+    # Checks for a cached Method or creates a new one.
+    # 
+    # It caches the standard HTTP Methods that are in RFC 2616 as well as the
+    # new method `PATCH`. If the Method cannot be found, it calls `#initialize`.
+    # 
+    # @example
+    #   Webbed::Method.new('GET') # => Webbed::Method::GET
+    # 
+    # @param (see #initialize)
+    # @return [Method] the new or cached Method
+    # @see #initialize
+    def self.new(value, options = {})
+      if const_defined?(value)
+        const_get(value)
       else
-        super(name, options)
+        super(value, options)
       end
     end
     
+    # Creates a new Method.
+    # 
+    # @param [String] name the name of the Method to create
+    # @param [Hash] options the options to create the Method with
+    # @option options [Boolean] :safe (false) whether or not the Method is safe
+    # @option options [Boolean] :idempotent (false) whether or not the Method is
+    #   idempotent
+    # @option options [Array<:request, :response>] :allowable_entities
+    #   ([:request, :response]) the allowable entites of a message
     def initialize(name, options = {})
-      options = DEFAULTS.merge options
+      options = DEFAULTS.merge(options)
       @name = name
       @safe = options[:safe]
       @idempotent = options[:safe] || options[:idempotent]
-      @has_request_entity = options[:entities].include? :request
-      @has_response_entity = options[:entities].include? :response
+      @allowable_entities = options[:allowable_entities]
     end
     
+    # Whether or not the Method is safe.
+    # 
+    # @return [Boolean]
     def safe?
       @safe
     end
     
+    # Whether or not the Method is idempotent.
+    # 
+    # @return [Boolean]
     def idempotent?
       @idempotent
     end
     
-    def has_request_entity?
-      @has_request_entity
-    end
-    
-    def has_response_entity?
-      @has_response_entity
+    # Converts the Method to a string.
+    # 
+    # @return [String]
+    def to_s
+      @name
     end
     
+    # Compares the Method to another Method.
+    # 
+    # Two Methods are equal if they have the same name.
+    # 
+    # @param [#to_s] other_method the other Method
+    # @return [Boolean]
     def ==(other_method)
-      name == other_method.to_s
+      to_s == other_method.to_s
     end
     
-    # Common methods used and their settings. Most are defined in RFC 2616 with
-    # the exception of PATCH which is defined in RFC 5789. These are for caching
-    # purposes, so that new objects don't need to be created on each request.
-    OPTIONS = new 'OPTIONS', :safe => true,  :idempotent => true,  :entities => [:response]
-    GET     = new 'GET',     :safe => true,  :idempotent => true,  :entities => [:response]
-    HEAD    = new 'HEAD',    :safe => true,  :idempotent => true,  :entities => []
-    POST    = new 'POST',    :safe => false, :idempotent => false, :entities => [:request, :response]
-    PUT     = new 'PUT',     :safe => false, :idempotent => true,  :entities => [:request, :response]
-    DELETE  = new 'DELETE',  :safe => false, :idempotent => true,  :entities => [:response]
-    TRACE   = new 'TRACE',   :safe => true,  :idempotent => true,  :entities => [:response]
-    CONNECT = new 'CONNECT', :safe => false, :idempotent => false, :entities => [:request, :response]
-    PATCH   = new 'PATCH',   :safe => false, :idempotent => false, :entities => [:request, :response]
+    OPTIONS = new('OPTIONS', :safe => true,  :idempotent => true,  :allowable_entities => [:response])
+    GET     = new('GET',     :safe => true,  :idempotent => true,  :allowable_entities => [:response])
+    HEAD    = new('HEAD',    :safe => true,  :idempotent => true,  :allowable_entities => [])
+    POST    = new('POST',    :safe => false, :idempotent => false, :allowable_entities => [:request, :response])
+    PUT     = new('PUT',     :safe => false, :idempotent => true,  :allowable_entities => [:request, :response])
+    DELETE  = new('DELETE',  :safe => false, :idempotent => true,  :allowable_entities => [:response])
+    TRACE   = new('TRACE',   :safe => true,  :idempotent => true,  :allowable_entities => [:response])
+    CONNECT = new('CONNECT', :safe => false, :idempotent => false, :allowable_entities => [:request, :response])
+    PATCH   = new('PATCH',   :safe => false, :idempotent => false, :allowable_entities => [:request, :response])
   end
-end
+end

data/lib/webbed/request.rb

@@ -1,44 +1,88 @@
 require 'addressable/uri'
 
 module Webbed
+  # Representation of an HTTP Request.
+  # 
+  # This class contains the absolute minimum for accessing the different parts
+  # of an HTTP Request. Helper modules provide far more functionality.
   class Request
+    include GenericMessage
     
-    include Webbed::GenericMessage
+    # The Request-URI of the Request.
+    #
+    # The method automatically converts the new value to an instance of
+    # `Addressable::URI` if it is not already one.
+    # 
+    # @return [Addressable::URI]
+    # @note {Helpers::RequestURIHelper} aliases this method to `#request_url`.
     attr_reader :request_uri
-    DEFAULTS = {
-      :method => 'GET',
-      :request_uri => '*',
-      :http_version => 'HTTP/1.1',
-      :headers => {},
-      :entity_body => ''
-    }
-    
-    def initialize(request_hash = {})
-      request_hash = DEFAULTS.merge(request_hash)
-      
-      self.method = request_hash[:method]
-      self.request_uri = request_hash[:request_uri]
-      self.http_version = request_hash[:http_version]
-      self.headers.merge!(request_hash[:headers])
-      self.entity_body = request_hash[:entity_body]
+    
+    def request_uri=(request_uri)
+      @request_uri = Addressable::URI.parse(request_uri)
+    end
+    
+    # The scheme of the Request.
+    # 
+    # @return ['http', 'https']
+    attr_accessor :scheme
+    
+    # Creates a new Request.
+    # 
+    # The method converts the values passed in to their proper types.
+    # 
+    # @example
+    #     Webbed::Request.new('GET', 'http://example.com', {}, '')
+    # 
+    # @param [Method, String] method
+    # @param [Addressable::URI, String] request_uri
+    # @param [Headers, Hash] headers
+    # @param [#to_s] entity_body
+    # @param [Array] options the options to create the Request with
+    # @option options [#to_s] :http_version (1.1) the HTTP-Version of the
+    #   Request
+    # @option options ['http', 'https'] :scheme ('http') the scheme of the
+    #   Request
+    def initialize(method, request_uri, headers, entity_body, options = {})
+      self.method       = method
+      self.request_uri  = request_uri
+      self.headers      = headers
+      self.entity_body  = entity_body
+      self.http_version = options[:http_version] || 1.1
+      self.scheme       = options[:scheme] || 'http'
     end
     
+    # The Method of the Request.
+    # 
+    # @return [Method]
     def method(*args)
       return super(*args) unless args.empty?
       @method
     end
     
+    # Sets the Method of the Request.
+    # 
+    # @param [Method] method
     def method=(method)
       @method = Webbed::Method.new(method)
     end
     
-    def request_uri=(uri)
-      @request_uri = Addressable::URI.parse(uri)
-    end
-    
+    # The Request-Line of the Request as defined in RFC 2616.
+    # 
+    # @example
+    #     request = Webbed::Request.new(['GET', 'http://example.com', {}, ''])
+    #     request.request_line # => "GET * HTTP/1.1\r\n"
+    # 
+    # @return [String]
     def request_line
       "#{method} #{request_uri} #{http_version}\r\n"
     end
     alias :start_line :request_line
+    
+    include Helpers::MethodHelper
+    include Helpers::RequestURIHelper
+    include Helpers::RackRequestHelper
+    include Helpers::SchemeHelper
+    include Helpers::RequestHeadersHelper
+    include Helpers::EntityHeadersHelper
   end
 end

data/lib/webbed/response.rb

@@ -1,42 +1,83 @@
 module Webbed
+  # Representation of an HTTP Response.
+  # 
+  # This class contains the absolute minimum for accessing the different parts
+  # of an HTTP Response. Helper modules provide far more functionality.
   class Response
+    include GenericMessage
     
-    include Webbed::GenericMessage
+    STATUS_CODE_REGEX = /^(\d{3}) (.*)$/
+    
+    # The Status Code of the Response.
+    # 
+    # The method automatically converts the new value to an instance of
+    # {StatusCode} if it is not already one.
+    # 
+    # @return [#to_i]
     attr_reader :status_code
-    attr_writer :reason_phrase
-    DEFAULTS = {
-      :http_version => 'HTTP/1.1',
-      :status_code => 200,
-      :reason_phrase => nil,
-      :headers => {},
-      :entity_body => ''
-    }
-    
-    def initialize(response_hash = {})
-      response_hash = DEFAULTS.merge(response_hash)
-      
-      self.http_version = response_hash[:http_version]
-      self.status_code = response_hash[:status_code]
-      self.reason_phrase = response_hash[:reason_phrase]
-      self.headers.merge!(response_hash[:headers])
-      self.entity_body = response_hash[:entity_body]
+    
+    def status_code=(status_code)
+      @status_code = Webbed::StatusCode.new(status_code)
     end
     
+    # The Reason Phrase of the Response.
+    # 
+    # The method returns the Status Code's default reason phrase if the Reason
+    # Phrase has not already been set.
+    # 
+    # @return [String]
     def reason_phrase
-      @reason_phrase || default_reason_phrase
+      defined?(@reason_phrase) ? @reason_phrase : @status_code.default_reason_phrase
     end
     
-    def default_reason_phrase
-      @status_code.default_reason_phrase
-    end
+    attr_writer :reason_phrase
     
-    def status_code=(status_code)
-      @status_code = Webbed::StatusCode.new(status_code)
+    # Creates a new Response.
+    # 
+    # The Status Code may be passed in as a string with a Reason Phrase or just
+    # a number. If a number is provided, the default Reason Phrase for that
+    # Status Code is used.
+    # 
+    # The method converts the values passed in to their proper types.
+    # 
+    # @example
+    #     Webbed::Response.new(200, {}, '')
+    #     Webbed::Response.new('404 Missing File', {}, '')
+    # 
+    # @param [Fixnum, String] status_code
+    # @param [Headers, Hash] headers
+    # @param [#to_s] entity_body
+    # @param [Array] options the options to create the Response with @option
+    # @options options [#to_s] :http_version (1.1) the HTTP-Version of the
+    #   Response
+    def initialize(status_code, headers, entity_body, options = {})
+      if STATUS_CODE_REGEX =~ status_code.to_s
+        self.status_code = $1
+        self.reason_phrase = $2
+      else
+        self.status_code = status_code
+      end
+      
+      self.headers = headers
+      self.entity_body = entity_body
+      
+      self.http_version = options.delete(:http_version) || 1.1
     end
     
+    # The Status-Line of the Response.
+    # 
+    # @example
+    #     response = Webbed::Response.new([200, {}, ''])
+    #     response.status_line # => "HTTP/1.1 200 OK\r\n"
+    # 
+    # @return [String]
     def status_line
       "#{http_version} #{status_code} #{reason_phrase}\r\n"
     end
     alias :start_line :status_line
+    
+    include Helpers::RackResponseHelper
+    include Helpers::ResponseHeadersHelper
+    include Helpers::EntityHeadersHelper
   end
 end

data/lib/webbed/status_code.rb

@@ -1,9 +1,7 @@
 module Webbed
+  # Representation of an HTTP Status Code.
   class StatusCode
-    
     include Comparable
-    attr_reader :status_code, :default_reason_phrase
-    CACHED = {}
     
     UNKNOWN_REASON_PHRASE = 'Unknown Status Code'
     REASON_PHRASES = {
@@ -49,54 +47,123 @@ module Webbed
       505 => 'HTTP Version not supported'
     }
     
+    @@cached = {}
+    
+    # The default Reason Phrase of the Status Code.
+    # 
+    # @return [String]
+    attr_reader :default_reason_phrase
+    
+    # Retrieves a Status Code from the cache or creates a new one.
+    # 
+    # All created Status Codes are cached forever.
+    # 
+    # @param (see #initialize)
+    # @return [StatusCode] the new or cached StatusCode
+    # @see #initialize
     def self.new(status_code)
-      CACHED[status_code] ||= super(status_code)
+      status_code = status_code.to_i
+      @@cached[status_code] ||= super(status_code)
     end
     
+    # Creates a new Status Code.
+    # 
+    # @param [Fixnum] status_code
     def initialize(status_code)
-      status_code = status_code.to_i
       @status_code = status_code
-      @default_reason_phrase = REASON_PHRASES[status_code] || UNKNOWN_REASON_PHRASE
+      @default_reason_phrase = REASON_PHRASES[@status_code] || UNKNOWN_REASON_PHRASE
     end
     
+    # Comparse the Status Code to another Status Code.
+    # 
+    # @param [#to_i] other_status_code the other Status Code
+    # @return [Fixnum] the sign of the comparison (either `1`, `0`, or `-1`)
     def <=>(other_status_code)
-      status_code <=> other_status_code.to_i
+      @status_code <=> other_status_code.to_i
     end
     
+    # Converts the Status Code to an integer.
+    # 
+    # @return [Fixnum]
     def to_i
-      status_code
+      @status_code
     end
     
+    # Converts the Status Code to a string.
+    # 
+    # @return [String]
     def to_s
-      '%03d' % status_code
+      @status_code.to_s
     end
     
+    # Whether or not the Status Code is informational.
+    # 
+    # According to RFC 2616, informational status codes are in the range of 100
+    # to 199, inclusive.
+    # 
+    # @return [Boolean]
     def informational?
-      (100...200).include? status_code
+      (100...200).include?(@status_code)
     end
     
-    def success?
-      (200...300).include? status_code
+    # Whether or not the Status Code is successful.
+    # 
+    # According to RFC 2616, successful status codes are in the range of 200 to
+    # 299, inclusive.
+    # 
+    # @return [Boolean]
+    def successful?
+      (200...300).include?(@status_code)
     end
     
+    # Whether or not the Status Code is a redirection.
+    # 
+    # According to RFC 2616, redirection status codes are in the range of 300 to
+    # 399, inclusive.
+    # 
+    # @return [Boolean]
     def redirection?
-      (300...400).include? status_code
+      (300...400).include?(@status_code)
     end
     
+    # Whether or not the Status Code is a client error.
+    # 
+    # According to RFC 2616, client error status codes are in the range of 400
+    # to 499, inclusive.
+    # 
+    # @return [Boolean]
     def client_error?
-      (400...500).include? status_code
+      (400...500).include?(@status_code)
     end
     
+    # Whether or not the Status Code is a server error.
+    # 
+    # According to RFC 2616, server error status codes are in the range of 500
+    # to 599, inclusive.
+    # 
+    # @return [Boolean]
     def server_error?
-      (500...600).include? status_code
+      (500...600).include?(@status_code)
     end
     
+    # Whether or not the Status Code is unknown.
+    # 
+    # According to RFC 2616, the only defined Status Code ranges are from 100 to
+    # 599, inclusive. Anything outside that range is an unknown Status Code.
+    # 
+    # @return [Boolean]
     def unknown?
-      !(100...600).include? status_code
+      !(100...600).include?(@status_code)
     end
     
+    # Whether or not the Status Code is an error.
+    # 
+    # According to RFC 2616, Status Codes that signify errors are in the range
+    # of 400 to 599, inclusive.
+    # 
+    # @return [Boolean]
     def error?
-      (400...600).include? status_code
+      (400...600).include?(@status_code)
     end
   end
 end