httparty 0.2.10 → 0.3.0

data/lib/httparty.rb

@@ -2,12 +2,8 @@ $:.unshift(File.dirname(__FILE__))
 
 require 'net/http'
 require 'net/https'
-require 'rubygems'
-gem 'json', '>= 1.1.3'
-require 'json'
-
-require 'module_level_inheritable_attributes'
 require 'core_extensions'
+require 'httparty/module_inheritable_attributes'
 
 module HTTParty
   
@@ -23,36 +19,64 @@ module HTTParty
   
   def self.included(base)
     base.extend ClassMethods
-    base.send :include, ModuleLevelInheritableAttributes
+    base.send :include, HTTParty::ModuleInheritableAttributes
     base.send(:mattr_inheritable, :default_options)
     base.instance_variable_set("@default_options", {})
   end
   
   module ClassMethods
-    def default_options
-      @default_options
-    end
-
+    # Allows setting http proxy information to be used
+    #
+    #   class Foo
+    #     include HTTParty
+    #     http_proxy 'http://foo.com', 80
+    #   end
     def http_proxy(addr=nil, port = nil)
       default_options[:http_proxyaddr] = addr
       default_options[:http_proxyport] = port
     end
-
+    
+    # Allows setting a base uri to be used for each request.
+    # Will normalize uri to include http, etc.
+    #
+    #   class Foo
+    #     include HTTParty
+    #     base_uri 'twitter.com'
+    #   end
     def base_uri(uri=nil)
       return default_options[:base_uri] unless uri
       default_options[:base_uri] = HTTParty.normalize_base_uri(uri)
     end
-
+    
+    # Allows setting basic authentication username and password.
+    #
+    #   class Foo
+    #     include HTTParty
+    #     basic_auth 'username', 'password'
+    #   end
     def basic_auth(u, p)
       default_options[:basic_auth] = {:username => u, :password => p}
     end
     
+    # Allows setting default parameters to be appended to each request.
+    # Great for api keys and such.
+    #
+    #   class Foo
+    #     include HTTParty
+    #     default_params :api_key => 'secret', :another => 'foo'
+    #   end
     def default_params(h={})
       raise ArgumentError, 'Default params must be a hash' unless h.is_a?(Hash)
       default_options[:default_params] ||= {}
       default_options[:default_params].merge!(h)
     end
-
+    
+    # Allows setting a base uri to be used for each request.
+    #
+    #   class Foo
+    #     include HTTParty
+    #     headers 'Accept' => 'text/html'
+    #   end
     def headers(h={})
       raise ArgumentError, 'Headers must be a hash' unless h.is_a?(Hash)
       default_options[:headers] ||= {}
@@ -65,15 +89,46 @@ module HTTParty
       default_options[:cookies].add_cookies(h)
     end
     
+    # Allows setting the format with which to parse.
+    # Must be one of the allowed formats ie: json, xml
+    #
+    #   class Foo
+    #     include HTTParty
+    #     format :json
+    #   end
     def format(f)
       raise UnsupportedFormat, "Must be one of: #{AllowedFormats.values.join(', ')}" unless AllowedFormats.value?(f)
       default_options[:format] = f
     end
     
+    # Allows making a get request to a url.
+    #
+    #   class Foo
+    #     include HTTParty
+    #   end
+    #   
+    #   # Simple get with full url
+    #   Foo.get('http://foo.com/resource.json')
+    #   
+    #   # Simple get with full url and query parameters
+    #   # ie: http://foo.com/resource.json?limit=10
+    #   Foo.get('http://foo.com/resource.json', :query => {:limit => 10})
     def get(path, options={})
       perform_request Net::HTTP::Get, path, options
     end
-
+    
+    # Allows making a post request to a url.
+    #
+    #   class Foo
+    #     include HTTParty
+    #   end
+    #   
+    #   # Simple post with full url and setting the body
+    #   Foo.post('http://foo.com/resources', :body => {:bar => 'baz'})
+    #
+    #   # Simple post with full url using :query option, 
+    #   # which gets set as form data on the request.
+    #   Foo.post('http://foo.com/resources', :query => {:bar => 'baz'})
     def post(path, options={})
       perform_request Net::HTTP::Post, path, options
     end
@@ -85,6 +140,10 @@ module HTTParty
     def delete(path, options={})
       perform_request Net::HTTP::Delete, path, options
     end
+    
+    def default_options #:nodoc:
+      @default_options
+    end
 
     private
       def perform_request(http_method, path, options) #:nodoc:
@@ -112,7 +171,7 @@ module HTTParty
     "http#{'s' if use_ssl}://#{url}"
   end
   
-  class Basement
+  class Basement #:nodoc:
     include HTTParty
   end
   
@@ -133,7 +192,8 @@ module HTTParty
   end
 end
 
+require 'httparty/cookie_hash'
 require 'httparty/exceptions'
 require 'httparty/request'
 require 'httparty/response'
-require 'httparty/cookie_hash'
+require 'httparty/parsers'

data/lib/httparty/cookie_hash.rb

@@ -1,4 +1,4 @@
-class HTTParty::CookieHash < Hash
+class HTTParty::CookieHash < Hash #:nodoc:
   def add_cookies(hash)
     merge!(hash)
   end

data/lib/httparty/exceptions.rb

@@ -1,4 +1,7 @@
 module HTTParty
+  # Exception raised when you attempt to set a non-existant format
   class UnsupportedFormat < StandardError; end
+  
+  # Exception that is raised when request has redirected too many times
   class RedirectionTooDeep < StandardError; end
 end

data/lib/httparty/module_inheritable_attributes.rb

@@ -0,0 +1,25 @@
+module HTTParty
+  module ModuleInheritableAttributes #:nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods #:nodoc:
+      def mattr_inheritable(*args)
+        @mattr_inheritable_attrs ||= [:mattr_inheritable_attrs]
+        @mattr_inheritable_attrs += args
+        args.each do |arg|
+          module_eval %(class << self; attr_accessor :#{arg} end)
+        end
+        @mattr_inheritable_attrs
+      end
+
+      def inherited(subclass)
+        @mattr_inheritable_attrs.each do |inheritable_attribute|
+          instance_var = "@#{inheritable_attribute}" 
+          subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+        end
+      end
+    end
+  end
+end

data/lib/httparty/parsers.rb

@@ -0,0 +1,4 @@
+Dir[File.dirname(__FILE__) + "/parsers/*.rb"].sort.each do |path|
+  filename = File.basename(path)
+  require "httparty/parsers/#{filename}"
+end

data/lib/httparty/parsers/json.rb

@@ -0,0 +1,67 @@
+# Copyright (c) 2004-2008 David Heinemeier Hansson
+# 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.
+
+require 'yaml'
+require 'strscan'
+
+module HTTParty
+  module Parsers #:nodoc:
+    module JSON #:nodoc:
+      class ParseError < StandardError #:nodoc:
+      end
+
+      def self.decode(json)
+        YAML.load(convert_json_to_yaml(json))
+      rescue ArgumentError => e
+        raise ParseError, "Invalid JSON string"
+      end
+
+      protected
+        # matches YAML-formatted dates
+        DATE_REGEX = /^\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[ \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?(([ \t]*)Z|[-+]\d{2}?(:\d{2})?)?$/
+
+        # Ensure that ":" and "," are always followed by a space
+        def self.convert_json_to_yaml(json) #:nodoc:
+          scanner, quoting, marks, pos, times = StringScanner.new(json), false, [], nil, []
+          while scanner.scan_until(/(\\['"]|['":,\\]|\\.)/)
+            case char = scanner[1]
+            when '"', "'"
+              if !quoting
+                quoting = char
+                pos = scanner.pos
+              elsif quoting == char
+                if json[pos..scanner.pos-2] =~ DATE_REGEX
+                  # found a date, track the exact positions of the quotes so we can remove them later.
+                  # oh, and increment them for each current mark, each one is an extra padded space that bumps
+                  # the position in the final YAML output
+                  total_marks = marks.size
+                  times << pos+total_marks << scanner.pos+total_marks
+                end
+                quoting = false
+              end
+            when ":",","
+              marks << scanner.pos - 1 unless quoting
+            end
+          end
+
+          if marks.empty?
+            json.gsub(/\\\//, '/')
+          else
+            left_pos  = [-1].push(*marks)
+            right_pos = marks << json.length
+            output    = []
+            left_pos.each_with_index do |left, i|
+              output << json[left.succ..right_pos[i]]
+            end
+            output = output * " "
+
+            times.each { |i| output[i-1] = ' ' }
+            output.gsub!(/\\\//, '/')
+            output
+          end
+        end
+    end
+  end
+end

data/lib/httparty/parsers/xml.rb

@@ -0,0 +1,209 @@
+require 'rexml/parsers/streamparser'
+require 'rexml/parsers/baseparser'
+require 'rexml/light/node'
+
+# This is a slighly modified version of the XMLUtilityNode from
+# http://merb.devjavu.com/projects/merb/ticket/95 (has.sox@gmail.com)
+# It's mainly just adding vowels, as I ht cd wth n vwls :)
+# This represents the hard part of the work, all I did was change the
+# underlying parser.
+class REXMLUtilityNode #:nodoc:
+  attr_accessor :name, :attributes, :children, :type
+
+  def self.typecasts
+    @@typecasts
+  end
+
+  def self.typecasts=(obj)
+    @@typecasts = obj
+  end
+
+  def self.available_typecasts
+    @@available_typecasts
+  end
+
+  def self.available_typecasts=(obj)
+    @@available_typecasts = obj
+  end
+
+  self.typecasts = {}
+  self.typecasts["integer"]       = lambda{|v| v.nil? ? nil : v.to_i}
+  self.typecasts["boolean"]       = lambda{|v| v.nil? ? nil : (v.strip != "false")}
+  self.typecasts["datetime"]      = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
+  self.typecasts["date"]          = lambda{|v| v.nil? ? nil : Date.parse(v)}
+  self.typecasts["dateTime"]      = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
+  self.typecasts["decimal"]       = lambda{|v| v.nil? ? nil : BigDecimal(v.to_s)}
+  self.typecasts["double"]        = lambda{|v| v.nil? ? nil : v.to_f}
+  self.typecasts["float"]         = lambda{|v| v.nil? ? nil : v.to_f}
+  self.typecasts["symbol"]        = lambda{|v| v.nil? ? nil : v.to_sym}
+  self.typecasts["string"]        = lambda{|v| v.to_s}
+  self.typecasts["yaml"]          = lambda{|v| v.nil? ? nil : YAML.load(v)}
+  self.typecasts["base64Binary"]  = lambda{|v| v.unpack('m').first }
+
+  self.available_typecasts = self.typecasts.keys
+
+  def initialize(name, attributes = {})
+    @name         = name.tr("-", "_")
+    # leave the type alone if we don't know what it is
+    @type         = self.class.available_typecasts.include?(attributes["type"]) ? attributes.delete("type") : attributes["type"]
+
+    @nil_element  = attributes.delete("nil") == "true"
+    @attributes   = undasherize_keys(attributes)
+    @children     = []
+    @text         = false
+  end
+
+  def add_node(node)
+    @text = true if node.is_a? String
+    @children << node
+  end
+
+  def to_hash
+    if @type == "file"
+      f = StringIO.new((@children.first || '').unpack('m').first)
+      class << f
+        attr_accessor :original_filename, :content_type
+      end
+      f.original_filename = attributes['name'] || 'untitled'
+      f.content_type = attributes['content_type'] || 'application/octet-stream'
+      return {name => f}
+    end
+
+    if @text
+      return { name => typecast_value( translate_xml_entities( inner_html ) ) }
+    else
+      #change repeating groups into an array
+      groups = @children.inject({}) { |s,e| (s[e.name] ||= []) << e; s }
+
+      out = nil
+      if @type == "array"
+        out = []
+        groups.each do |k, v|
+          if v.size == 1
+            out << v.first.to_hash.entries.first.last
+          else
+            out << v.map{|e| e.to_hash[k]}
+          end
+        end
+        out = out.flatten
+
+      else # If Hash
+        out = {}
+        groups.each do |k,v|
+          if v.size == 1
+            out.merge!(v.first)
+          else
+            out.merge!( k => v.map{|e| e.to_hash[k]})
+          end
+        end
+        out.merge! attributes unless attributes.empty?
+        out = out.empty? ? nil : out
+      end
+
+      if @type && out.nil?
+        { name => typecast_value(out) }
+      else
+        { name => out }
+      end
+    end
+  end
+
+  # Typecasts a value based upon its type. For instance, if
+  # +node+ has #type == "integer",
+  # {{[node.typecast_value("12") #=> 12]}}
+  #
+  # @param value<String> The value that is being typecast.
+  #
+  # @details [:type options]
+  #   "integer"::
+  #     converts +value+ to an integer with #to_i
+  #   "boolean"::
+  #     checks whether +value+, after removing spaces, is the literal
+  #     "true"
+  #   "datetime"::
+  #     Parses +value+ using Time.parse, and returns a UTC Time
+  #   "date"::
+  #     Parses +value+ using Date.parse
+  #
+  # @return <Integer, TrueClass, FalseClass, Time, Date, Object>
+  #   The result of typecasting +value+.
+  #
+  # @note
+  #   If +self+ does not have a "type" key, or if it's not one of the
+  #   options specified above, the raw +value+ will be returned.
+  def typecast_value(value)
+    return value unless @type
+    proc = self.class.typecasts[@type]
+    proc.nil? ? value : proc.call(value)
+  end
+
+  # Convert basic XML entities into their literal values.
+  #
+  # @param value<#gsub> An XML fragment.
+  #
+  # @return <#gsub> The XML fragment after converting entities.
+  def translate_xml_entities(value)
+    value.gsub(/&lt;/,   "<").
+          gsub(/&gt;/,   ">").
+          gsub(/&quot;/, '"').
+          gsub(/&apos;/, "'").
+          gsub(/&amp;/,  "&")
+  end
+
+  # Take keys of the form foo-bar and convert them to foo_bar
+  def undasherize_keys(params)
+    params.keys.each do |key, value|
+      params[key.tr("-", "_")] = params.delete(key)
+    end
+    params
+  end
+
+  # Get the inner_html of the REXML node.
+  def inner_html
+    @children.join
+  end
+
+  # Converts the node into a readable HTML node.
+  #
+  # @return <String> The HTML node in text form.
+  def to_html
+    attributes.merge!(:type => @type ) if @type
+    "<#{name}#{attributes.to_xml_attributes}>#{@nil_element ? '' : inner_html}</#{name}>"
+  end
+
+  # @alias #to_html #to_s
+  def to_s
+    to_html
+  end
+end
+
+module HTTParty
+  module Parsers #:nodoc:
+    module XML #:nodoc:
+      def self.parse(xml)
+        stack = []
+        parser = REXML::Parsers::BaseParser.new(xml)
+
+        while true
+          event = parser.pull
+          case event[0]
+          when :end_document
+            break
+          when :end_doctype, :start_doctype
+            # do nothing
+          when :start_element
+            stack.push REXMLUtilityNode.new(event[1], event[2])
+          when :end_element
+            if stack.size > 1
+              temp = stack.pop
+              stack.last.add_node(temp)
+            end
+          when :text, :cdata
+            stack.last.add_node(event[1]) unless event[1].strip.length == 0 || stack.empty?
+          end
+        end
+        stack.pop.to_hash
+      end
+    end
+  end
+end