gravatar-ultimate 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,24 @@
+.idea
+tmp
+
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Colin MacKenzie IV
+
+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/README.rdoc

@@ -0,0 +1,100 @@
+= gravatar-ultimate
+
+The Ultimate Gravatar Gem!
+
+This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting
+to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself,
+rather than just a URL to that data. This saves you the extra step of having to do so.
+
+== Installation
+
+gem install gravitar-ultimate
+
+== Activate the gem...
+
+As with any gem, you have to type a few lines to tell Ruby to actually *use* it. Here's how to do that...
+
+==== ...in Ruby on Rails (v3.x)
+
+* This isn't ready yet, but it's in the works.
+
+==== ...in Ruby on Rails (v2.x)
+
+* Edit your config/environment.rb file
+* Add this line beneath "Rails::Initializer.run do |config|":
+   config.gem 'gravitar-ultimate'
+
+==== ...in vanilla Ruby
+
+  require 'rubygems'
+  gem 'gravitar-ultimate'
+  require 'gravitar-ultimate'
+
+== Usage
+Using the gem is actually pretty simple. Let's say you want the Gravatar image URL for "generic@example.com":
+  url = Gravatar.new("generic@example.com").image_url
+
+Cool, huh? Let's take it a step further and grab the actual image *data* so that we can render it on the screen:
+  data = Gravatar.new("generic@example.com").image_data
+
+Fine, but how about the rest of the API as advertised at http://en.gravatar.com/site/implement/xmlrpc? Well, for
+that you need either the user's Gravatar password, or their API key:
+
+  api = Gravatar.new("generic@example.com", :password => "helloworld")
+  api = Gravatar.new("generic@example.com", :api_key => "AbCdEfG1234")
+
+After you have that, things get a lot easier:
+
+  api.exists?                                   #=> true or false, depending on whether this user has an account.
+  api.addresses                                 #=> a list of email addresses and their corresponding images
+  api.save_data!(rating, image_data)            #=> saves an image to this user's account and returns a handle to it
+  api.use_user_image!(handle, an_email_address) #=> uses the specified image handle for the specified email address(es)
+  api.exists?("another@example.com")            #=> true or false, depending on whether the specified email exists.
+
+
+== Caching
+
+As you can see this is quite powerful. But it gets better. Gravatar Ultimate even manages caching of API responses for
+you! That way, if an error occurs, (such as the Gravatar site being offline), your code won't break. It'll instead
+gracefully fall back to the cached copy! By default, if you are using Rails, it'll use the Rails cache. Otherwise, it'll
+use whatever cache you're using with Gravatar (by default an instance of ActiveSupport::Cache::FileStore).
+
+This has obvious benefits when used for the API calls that do not result in changing the user's profile, but what you
+might not have thought of yet is that it also caches #image_data, so you can hook your application up to that method
+without fear of what might happen to all those Gravatar images if the Gravatar server should be unavailable!
+
+To customize exactly which cache is used, see the next section...
+
+=== Configuration
+
+To see settings and options you can give for a particular Gravatar instance, check out the Gravatar class documentation.
+There are a few things you can set for Gravatar on a system-wide basis, and that's what we'll go over next.
+
+For a non-Rails project, simply set these options before you start using Gravatar. For a Rails project, you should set
+them within an Initializer in config/initializers/any_filename.rb in order to ensure that the settings are applied
+(A) after Gravatar has been included into the project, and (B) before it is actually used by Rails.
+
+  # You can set the default cache for Gravatar to use:
+  Gravatar.cache = ActiveSupport::Cache::SynchronizedMemoryStore.new
+
+  # You can also set the length of time an item in the Gravatar cache is valid. Default is 24.hours
+  Gravatar.duration = 20.minutes
+
+  # You can also change the logger used by default. It's worth mentioning that, once again, Gravatar will use
+  # the Rails logger if it's available. Otherwise, the default is $stdout.
+  grav_log = ""
+  Gravatar.logger = StringIO.new(grav_log) # logs Gravatar output to a String
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Colin MacKenzie IV. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "gravatar-ultimate"
+    gem.summary = %Q{A gem for interfacing with the entire Gravatar API: not just images, but the XML-RPC API too!}
+    gem.description = %Q{The Ultimate Gravatar Gem!
+
+This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting
+to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself,
+rather than just a URL to that data. This saves you the extra step of having to do so.}
+    gem.email = "sinisterchipmunk@gmail.com"
+    gem.homepage = "http://github.com/sinisterchipmunk/gravatar"
+    gem.authors = ["Colin MacKenzie IV"]
+    gem.add_dependency "sc-core-ext", ">= 1.2.0"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+    gem.add_development_dependency "fakeweb", ">= 1.2.8"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:test) do |test|
+  test.libs << 'lib' << 'spec'
+  test.pattern = 'spec/**/*_spec.rb'
+  test.verbose = true
+end
+
+desc "Run all specs"
+task :spec => :test
+
+begin
+  gem 'rcov'
+  require 'rcov/rcovtask'
+  Spec::Rake::SpecTask.new(:coverage) do |test|
+    test.libs << 'lib' << 'spec'
+    test.pattern = "spec/**/*_spec.rb"
+    test.verbose = true
+    test.rcov = true
+    test.rcov_opts = ['--html', '--exclude spec']
+  end
+rescue LoadError
+  task :coverage do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "gravatar #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/gravatar-ultimate.gemspec

@@ -0,0 +1,77 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{gravatar-ultimate}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Colin MacKenzie IV"]
+  s.date = %q{2010-06-16}
+  s.description = %q{The Ultimate Gravatar Gem!
+
+This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting
+to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself,
+rather than just a URL to that data. This saves you the extra step of having to do so.}
+  s.email = %q{sinisterchipmunk@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "gravatar-ultimate.gemspec",
+     "lib/gravatar-ultimate.rb",
+     "lib/gravatar.rb",
+     "lib/gravatar/cache.rb",
+     "lib/gravatar/dependencies.rb",
+     "lib/gravatar_ultimate.rb",
+     "spec/credentials.yml.example",
+     "spec/fixtures/image.jpg",
+     "spec/lib/gravatar/cache_and_logger_spec.rb",
+     "spec/lib/gravatar/cache_setup_spec.rb",
+     "spec/lib/gravatar/dependencies_spec.rb",
+     "spec/lib/gravatar_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/sinisterchipmunk/gravatar}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A gem for interfacing with the entire Gravatar API: not just images, but the XML-RPC API too!}
+  s.test_files = [
+    "spec/spec_helper.rb",
+     "spec/lib/gravatar_spec.rb",
+     "spec/lib/gravatar/dependencies_spec.rb",
+     "spec/lib/gravatar/cache_and_logger_spec.rb",
+     "spec/lib/gravatar/cache_setup_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sc-core-ext>, [">= 1.2.0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_development_dependency(%q<fakeweb>, [">= 1.2.8"])
+    else
+      s.add_dependency(%q<sc-core-ext>, [">= 1.2.0"])
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
+    end
+  else
+    s.add_dependency(%q<sc-core-ext>, [">= 1.2.0"])
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
+  end
+end
+

data/lib/gravatar-ultimate.rb

@@ -0,0 +1 @@
+require File.expand_path("../gravatar", __FILE__)

data/lib/gravatar.rb

@@ -0,0 +1,282 @@
+require File.expand_path('../gravatar/dependencies', __FILE__)
+require File.expand_path("../gravatar/cache", __FILE__)
+
+# ==== Errors ====
+#
+# Errors usually come with a number and human readable text. Generally the text should be followed whenever possible,
+# but a brief description of the numeric error codes are as follows:
+#
+#     -7	Use secure.gravatar.com
+#     -8	Internal error
+#     -9	Authentication error
+#     -10	Method parameter missing
+#     -11	Method parameter incorrect
+#     -100	Misc error (see text)
+#
+class Gravatar
+  attr_reader :email
+
+  # Creates a new instance of Gravatar. Valid options include:
+  #   :password                   => the password for this account, to be used instead of :api_key (don't supply both)
+  #   :api_key or :apikey or :key => the API key for this account, to be used instead of :password (don't supply both)
+  #   :duration                   => the cache duration to use for this instance
+  #   :logger                     => the logger to use for this instance
+  #
+  # Note that :password and :api_key are both optional. If omitted, no web services will be available but this
+  # user's Gravatar image can still be constructed using #image_uri or #image_data.
+  #
+  def initialize(email, options = {})
+    raise ArgumentError, "Expected :email" unless email
+    @options = options || {}
+    @email = email
+
+    pw_or_key = auth.keys.first || :none
+    @cache = Gravatar::Cache.new(self.class.cache, options[:duration] || self.class.duration,
+                                 "gravatar-#{email_hash}-#{pw_or_key}", options[:logger] || self.class.logger)
+    
+    if !auth.empty?
+      @api = XMLRPC::Client.new("secure.gravatar.com", "/xmlrpc?user=#{email_hash}", 443, nil, nil, nil, nil, true)
+    end
+  end
+
+  # The duration of the cache for this instance of Gravatar, independent of any other instance
+  def cache_duration
+    @cache.duration
+  end
+
+  # Sets the duration of the cache for this instance of Gravatar, independent of any other instance
+  def cache_duration=(time)
+    @cache.duration = time
+  end
+
+  # Check whether one or more email addresses have corresponding avatars. If no email addresses are
+  # specified, the one associated with this object is used.
+  #
+  # Returns: Boolean for a single email address; a hash of emails => booleans for multiple addresses.
+  #
+  # This method is cached for up to the value of @duration or Gravatar.duration.
+  def exists?(*emails)
+    hashed_emails = normalize_email_addresses(emails)
+    cache('exists', hashed_emails) do
+      hash = call('grav.exists', :hashes => hashed_emails)
+      if hash.length == 1
+        boolean(hash.values.first)
+      else
+        dehashify_emails(hash, emails) { |value| boolean(value) }
+      end
+    end
+  end
+
+  # Gets a list of addresses for this account, returning a hash following this format:
+  #  {
+  #    address => {
+  #      :rating => rating,
+  #      :userimage => userimage,
+  #      :userimage_url => userimage_url
+  #    }
+  #  }
+  #
+  # This method is cached for up to the value of @duration or Gravatar.duration.
+  def addresses
+    cache('addresses') do
+      call('grav.addresses').inject({}) do |hash, (address, info)|
+        hash[address] = info.merge(:rating => rating(info[:rating]))
+        hash
+      end
+    end
+  end
+
+  # Returns a hash of user images for this account in the following format:
+  #   { user_img_hash => [rating, url] }
+  #
+  # This method is cached for up to the value of @duration or Gravatar.duration.
+  def user_images
+    cache('user_images') do
+      call('grav.userimages').inject({}) do |hash, (key, array)|
+        hash[key] = [rating(array.first), array.last]
+        hash
+      end
+    end
+  end
+
+  # Saves binary image data as a userimage for this account and returns the ID of the image.
+  #
+  # This method is not cached.
+  def save_data!(rating, data)
+    call('grav.saveData', :data => Base64.encode64(data), :rating => _rating(rating))
+  end
+  alias save_image! save_data!
+
+  # Read an image via its URL and save that as a userimage for this account, returning true or false
+  #
+  # This method is not cached.
+  def save_url!(rating, url)
+    call('grav.saveUrl', :url => url, :rating => _rating(rating))
+  end
+
+  # Use a userimage as a gravatar for one or more addresses on this account. Returns a hash:
+  #   { email_address => true/false }
+  #
+  # This method is not cached.
+  #
+  # This method will clear out the cache, since it may have an effect on what the API methods respond with.
+  def use_user_image!(image_hash, *email_addresses)
+    hashed_email_addresses = normalize_email_addresses(email_addresses)
+    hash = call('grav.useUserimage', :userimage => image_hash, :addresses => hashed_email_addresses)
+    returning dehashify_emails(hash, email_addresses) { |value| boolean(value) } do
+      expire_cache!
+    end
+  end
+  alias use_image! use_user_image!
+
+  # Remove the userimage associated with one or more email addresses. Returns a hash of booleans.
+  #   NOTE: This appears to always return false, even when it is really removing an image. If you
+  #   know what the deal with that is, drop me a line so I can update this documentation!
+  #
+  # This method is not cached.
+  #
+  # This method will clear out the cache, since it may have an effect on what the API methods respond with.
+  def remove_image!(*emails)
+    hashed_email_addresses = normalize_email_addresses(emails)
+    hash = call('grav.removeImage', :addresses => hashed_email_addresses)
+    returning dehashify_emails(hash, emails) { |value| boolean(value) } do
+      expire_cache!
+    end
+  end
+
+  # Remove a userimage from the account and any email addresses with which it is associated. Returns
+  # true or false.
+  #
+  # This method is not cached.
+  #
+  # This method will clear out the cache, since it may have an effect on what the API methods respond with.
+  def delete_user_image!(userimage)
+    returning boolean(call('grav.deleteUserimage', :userimage => userimage)) do
+      expire_cache!
+    end
+  end
+
+  # Runs a simple Gravatar test. Useful for debugging. Gravatar will echo back any arguments you pass.
+  # This method is not cached.
+  def test(hash)
+    call('grav.test', hash)
+  end
+
+  # Returns the MD5 hash for the specified email address, or the one associated with this object.
+  def email_hash(email = self.email)
+    Digest::MD5.hexdigest(email.downcase.strip)
+  end
+
+  # Returns the URL for this user's gravatar image. Options include:
+  #
+  #   :ssl     or :secure    if true, HTTPS will be used instead of HTTP. Default is false.
+  #   :rating  or :r         a rating threshold for this image. Can be one of [ :g, :pg, :r, :x ]. Default is :g.
+  #   :size    or :s         a size for this image. Can be anywhere between 1 and 512. Default is 80.
+  #   :default or :d         a default URL for this image to display if the specified user has no image;
+  #                          or this can be one of [ :identicon, :monsterid, :wavatar, 404 ]. By default a generic
+  #                          Gravatar image URL will be returned.
+  #   :filetype              an extension such as :jpg or :png. Default is omitted.
+  #
+  # See http://en.gravatar.com/site/implement/url for much more detailed information.
+  def image_url(options = {})
+    secure = options[:ssl] || options[:secure]
+    proto = "http#{secure ? 's' : ''}"
+    sub = secure ? "secure" : "www"
+
+    "#{proto}://#{sub}.gravatar.com/avatar/#{email_hash}#{extension_for_image(options)}#{query_for_image(options)}"
+  end
+
+  # Returns the image data for this user's gravatar image. This is the same as reading the data at #image_url. See
+  # that method for more information.
+  #
+  # This method is cached for up to the value of @duration or Gravatar.duration.
+  def image_data(options = {})
+    url = image_url(options)
+    cache(url) { OpenURI.open_uri(URI.parse(url)).read }
+  end
+
+  def self.version
+    @version ||= File.read(File.join(File.dirname(__FILE__), "../VERSION")).chomp
+  end
+
+  private
+  def cache(*key, &block)
+    @cache.call(*key, &block)
+  end
+
+  def expire_cache!
+    @cache.clear!
+  end
+
+  def dehashify_emails(response, emails)
+    hashed_emails = emails.collect { |email| email_hash(email) }
+    response.inject({}) do |hash, (hashed_email, value)|
+      value = yield(value) if value
+      email = emails[hashed_emails.index(hashed_email)]
+      hash[email] = value
+      hash
+    end
+  end
+
+  def normalize_email_addresses(addresses)
+    addresses.flatten!
+    addresses << @email if addresses.empty?
+    addresses.map { |email| email_hash(email) }
+  end
+
+  def rating(i)
+    case i
+      when 0, '0' then :g
+      when 1, '1' then :pg
+      when 2, '2' then :r
+      when 3, '3' then :x
+      when :g  then 0
+      when :pg then 1
+      when :r  then 2
+      when :x  then 3
+      else raise ArgumentError, "Unexpected rating index: #{i} (expected between 0..3)"
+    end
+  end
+  alias _rating rating
+
+  def boolean(i)
+    i.kind_of?(Numeric) ? i != 0 : i
+  end
+
+  def call(name, args_hash = {})
+    r = @api.call(name, auth.merge(args_hash))
+    r = r.with_indifferent_access if r.kind_of?(Hash)
+    r
+  end
+
+  def auth
+    api_key ? {:apikey => api_key} : (password ? {:password => password} : {})
+  end
+
+  def api_key
+    options[:apikey] || options[:api_key] || options[:key]
+  end
+
+  def password
+    options[:password]
+  end
+
+  def options
+    @options
+  end
+
+  def query_for_image(options)
+    query = ''
+    [:rating, :size, :default, :r, :s, :d].each do |key|
+      if options.key?(key)
+        query.blank? ? query.concat("?") : query.concat("&")
+        query.concat("#{key}=#{CGI::escape options[key].to_s}")
+      end
+    end
+    query
+  end
+
+  def extension_for_image(options)
+    options.key?(:filetype) ? "." + (options[:filetype] || "jpg").to_s : ""
+  end
+end

data/lib/gravatar/cache.rb

@@ -0,0 +1,133 @@
+class Gravatar
+  # A wrapper around any given Cache object which provides Gravatar-specific helpers. Used internally.
+  class Cache
+    attr_reader :real_cache, :namespace
+    attr_accessor :duration, :logger
+
+    def initialize(real_cache, duration, namespace = nil, logger = Gravatar.logger)
+      @duration = duration
+      @real_cache = real_cache
+      @namespace = namespace
+      @logger = logger
+    end
+
+    # Provide a series of arguments to be used as a cache key, and a block to be executed when the cache
+    # is expired or needs to be populated.
+    #
+    # Example:
+    #   cache = Gravatar::Cache.new(Rails.cache, 30.minutes)
+    #   cache.call(:first_name => "Colin", :last_name => "MacKenzie") { call_webservice(with_some_args) }
+    #
+    def call(*key, &block)
+      cached_copy = read_cache(*key)
+      if expired?(*key) && block_given?
+        begin
+          returning(yield) do |object|
+            write_cache(object, *key)
+          end
+        rescue
+          log_error($!)
+          cached_copy.nil? ? nil : cached_copy[:object]
+        end
+      else
+        cached_copy.nil? ? nil : cached_copy[:object]
+      end
+    end
+
+    # Clears out the entire cache for this object's namespace. This actually removes the objects,
+    # instead of simply marking them as expired, so it will be as if the object never existed.
+    def clear!
+      @real_cache.delete_matched(/^#{Regexp::escape @namespace}/)
+    end
+
+    # forces the specified key to become expired
+    def expire!(*key)
+      unless expired?(*key)
+        @real_cache.write(cache_key(*key), { :expires_at => 1.minute.ago, :object => read_cache(*key)[:object] })
+      end
+    end
+
+    # Returns true if the cached copy is nil or expired based on @duration.
+    def expired?(*key)
+      cached_copy = read_cache(*key)
+      cached_copy.nil? || cached_copy[:expires_at] < Time.now
+    end
+
+    # Reads an object from the cache based on the cache key constructed from *key.
+    def read_cache(*key)
+      @real_cache.read(cache_key(*key))
+    end
+
+    # Writes an object to the cache based on th cache key constructed from *key.
+    def write_cache(object, *key)
+      @real_cache.write(cache_key(*key), { :expires_at => Time.now + duration, :object => object })
+    end
+
+    # Constructs a cache key from the specified *args and @namespace.
+    def cache_key(*args)
+      ActiveSupport::Cache.expand_cache_key(args, @namespace)
+    end
+
+    # Logs an error message, as long as self.logger responds to :error or :write.
+    # Otherwise, re-raises the error.
+    def log_error(error)
+      if logger.respond_to?(:error)
+        logger.error error.message
+        error.backtrace.each { |line| logger.error "  #{line}" }
+      elsif logger.respond_to?(:write)
+        logger.write(([error.message]+error.backtrace).join("\n  "))
+        logger.write("\n")
+      else raise error
+      end
+    end
+  end
+
+  class << self
+    def default_cache_instance
+      if defined?(Rails)
+        Rails.cache
+      else
+        ActiveSupport::Cache::FileStore.new("tmp/cache")
+      end
+    end
+
+    def default_logger_instance
+      if defined?(Rails)
+        Rails.logger
+      else
+        $stdout
+      end
+    end
+
+    def cache
+      @cache ||= default_cache_instance
+    end
+
+    def cache=(instance)
+      @cache = instance
+    end
+
+    def logger
+      @logger ||= default_logger_instance
+    end
+
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # How long is a cached object good for? Default is 30 minutes.
+    def duration
+      @duration ||= 24.hours
+    end
+
+    def duration=(duration)
+      @duration = duration
+    end
+
+    # Resets any changes to the cache and initializes a new cache. If using Rails, the
+    # new cache will be the Rails cache.
+    def reset_cache!
+      @cache = nil
+    end
+  end
+end

data/lib/gravatar/dependencies.rb

@@ -0,0 +1,16 @@
+if defined?(Rails)
+  Rails.configuration.gem "sc-core-ext", ">= 1.2.0"
+elsif !defined?(Gem)
+  require 'rubygems'
+  gem 'sc-core-ext', '>= 1.2.0'
+end
+
+unless defined?(ScCoreExt) || defined?(Rails) # because Rails will load it later and we don't really need it quite yet.
+  require 'sc-core-ext'
+end
+
+# The rest of this is core Ruby stuff so it's safe to load immediately, even if Rails is running the show.
+require 'open-uri'
+require "digest/md5"
+require 'xmlrpc/client'
+require 'base64'

data/lib/gravatar_ultimate.rb

@@ -0,0 +1 @@
+require File.expand_path("../gravatar", __FILE__)

data/spec/credentials.yml.example

@@ -0,0 +1,11 @@
+# To run this test suite, we need to set up some credentials because we're running real HTTP requests.
+# Make sure you have a working Gravatar account, and enter the following options:
+primary_email: email@example.com
+email: email@example.com
+api_key: YOUR_API_KEY
+
+# The primary email is the one that's marked 'primary' on your Gravatar account page. Both emails can
+# be the same. The API Key is your Gravatar API key, which you can optionally replace with:
+#   password: YOUR_GRAVATAR_PASSWORD
+#
+# Take care not to commit your credentials!

data/spec/lib/gravatar/cache_and_logger_spec.rb

@@ -0,0 +1,94 @@
+require 'spec_helper'
+
+describe Gravatar::Cache do
+  subject { Gravatar::Cache.new(new_cache, 30.minutes, "gravatar-specs") }
+
+  context "with a nonexistent cache item" do
+    it "should be expired" do
+      subject.expired?(:nothing).should be_true
+    end
+
+    it "should fire the block" do
+      subject.call(:nothing) { @fired = 1 }
+      @fired.should == 1
+    end
+
+    it "should return nil if no block given" do
+      subject.call(:nothing).should be_nil
+    end
+
+    it "should return the block value" do
+      subject.call(:nothing) { 1 }.should == 1
+    end
+  end
+
+  context "with a pre-existing cache item" do
+    before(:each) { subject.call(:nothing) { 1 } }
+
+    it "should not be expired" do
+      subject.expired?(:nothing).should be_false
+    end
+
+    it "should not fire the block" do
+      subject.call(:nothing) { @fired = 1 }
+      @fired.should_not == 1
+    end
+
+    it "should return the cached value" do
+      subject.call(:nothing) { raise "Block expected not to fire" }.should == 1
+    end
+
+    context "that is expired" do
+      before(:each) { subject.expire!(:nothing) }
+
+      it "should be expired" do
+        subject.expired?(:nothing).should be_true
+      end
+
+      it "should fire the block" do
+        subject.call(:nothing) { @fired = 1 }
+        @fired.should == 1
+      end
+
+      context "in the event of an error while refreshing" do
+        before(:each) { subject.logger = StringIO.new("") }
+        
+        it "should recover" do
+          proc { subject.call(:nothing) { raise "something bad happened" } }.should_not raise_error(RuntimeError)
+        end
+
+        it "should return the cached copy" do
+          subject.call(:nothing) { raise "something bad happened" }.should == 1
+        end
+
+        context "its logger" do
+          before(:each) { subject.logger = Object.new }
+
+          it "should log it if #error is available" do
+            subject.logger.stub!(:error => nil)
+            subject.logger.should_receive(:error).and_return(nil)
+            subject.call(:nothing) { raise "something bad happened" }
+          end
+
+          it "should log it if #write is available" do
+            subject.logger.stub!(:write => nil)
+            subject.logger.should_receive(:write).and_return(nil)
+            subject.call(:nothing) { raise "something bad happened" }
+          end
+
+          it "should re-raise the error if no other methods are available" do
+            proc { subject.call(:nothing) { raise "something bad happened" } }.should raise_error(RuntimeError)
+          end
+        end
+      end
+
+      it "should return the block value" do
+        subject.call(:nothing) { 2 }.should == 2
+      end
+
+      it "should return the cached value if there is no block value" do
+        subject.call(:nothing).should == 1
+      end
+    end
+  end
+end

data/spec/lib/gravatar/cache_setup_spec.rb

@@ -0,0 +1,42 @@
+describe "gravatar cache setup" do
+  context "within Rails" do
+    before(:each) do
+      # We reset it here because we've already set it to MemoryStore for the sake of the majority.
+      Gravatar.reset_cache!
+      module Rails
+      end
+    end
+
+    it "should get the default cache instance from Rails" do
+      Rails.should_receive(:cache).and_return("a cache object")
+      Gravatar.cache
+    end
+
+    it "should get the current cache from cache assignment, if any" do
+      Gravatar.cache = "a cache object"
+      Gravatar.cache.should == "a cache object"
+    end
+  end
+
+  context "out of Rails" do
+    it "should get the default cache from ActiveSupport" do
+      Gravatar.cache.should be_kind_of(ActiveSupport::Cache::FileStore)
+    end
+
+    it "should get the current cache from cache assignment, if any" do
+      Gravatar.cache = "a cache object"
+      Gravatar.cache.should == "a cache object"
+    end
+  end
+
+  after(:each) do
+    # We reset it here because we've already fubarred it with the Rails tests.
+    Gravatar.reset_cache!
+
+    silence_warnings do
+      if defined?(Rails)
+        Object.send :remove_const, :Rails
+      end
+    end
+  end
+end

data/spec/lib/gravatar/dependencies_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+describe "Dependencies" do
+  context "within Rails" do
+    before(:each) do
+      module ::Rails
+        def self.configuration
+          return @config if @config
+          @config = Object.new
+          klass = class << @config; self; end
+          klass.instance_eval do
+            def gem(*a, &b); end
+            public :gem
+          end
+          @config
+        end
+      end
+    end
+
+    it "should set a Rails gem dependency" do
+      Rails.configuration.should_receive(:gem, :with => ["sc-core-ext", ">= 1.2.0"])
+      load File.expand_path("../../../../lib/gravatar/dependencies.rb", __FILE__)
+    end
+
+    after(:each) { silence_warnings { Object.send(:remove_const, :Rails) } }
+  end
+
+  # Don't know how to test the inclusion of sc-core-ext via rubygems, but I suppose there's no reason that should fail.
+end

data/spec/lib/gravatar_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+
+describe Gravatar do
+  it "should have a valid version number" do
+    Gravatar.version.should =~ /^\d+\.\d+\.\d+$/
+  end
+
+  it "should allow setting cache duration by instance" do
+    grav = Gravatar.new($credentials[:primary_email])
+    grav.cache_duration = 10.minutes
+    grav.cache_duration.should == 10.minutes
+  end
+
+  it "should allow setting cache duration globally" do
+    Gravatar.duration = 10.minutes
+    Gravatar.new($credentials[:primary_email]).cache_duration.should == 10.minutes
+    Gravatar.duration = 30.minutes
+  end
+
+  it "should require :email" do
+    proc { subject }.should raise_error(ArgumentError)
+  end
+
+  context "given :email and :key" do
+    subject { Gravatar.new($credentials[:primary_email], $credentials)}
+
+    context "varying image ratings" do
+      [:g, :pg, :r, :x].each do |rating|
+        it "should save #{rating}-rated URLs and delete them" do
+          subject.save_url!(rating, "http://jigsaw.w3.org/css-validator/images/vcss").should ==
+                  "2df7db511c46303983f0092556a1e47c"
+          subject.delete_user_image!("2df7db511c46303983f0092556a1e47c").should == true
+        end
+      end
+
+      it "should raise an ArgumentError given an invalid rating" do
+        proc { subject.save_url!(:invalid_rating, "http://jigsaw.w3.org/css-validator/images/vcss") }.should \
+          raise_error(ArgumentError)
+      end
+    end
+
+    it "should return addresses" do
+      subject.addresses.should_not be_empty
+    end
+
+    it "should test successfully" do
+      subject.test(:greeting => 'hello').should have_key(:response)
+    end
+
+    it "should save URLs and delete them" do
+      subject.save_url!(:g, "http://jigsaw.w3.org/css-validator/images/vcss").should == "2df7db511c46303983f0092556a1e47c"
+      subject.delete_user_image!("2df7db511c46303983f0092556a1e47c").should == true
+    end
+
+    # Not really the ideal approach but it's a valid test, at least
+    it "should save and delete images and associate/unassociate them with accounts" do
+      begin
+        subject.save_data!(:g, image_data).should == "23f086a793459fa25aab280054fec1b2"
+        subject.use_user_image!("23f086a793459fa25aab280054fec1b2", $credentials[:email]).should ==
+                { $credentials[:email] => false }
+        # See rdoc for #remove_image! for why we're not checking this.
+        subject.remove_image!($credentials[:email])#.should == { $credentials[:email] => true }
+        subject.delete_user_image!("23f086a793459fa25aab280054fec1b2").should == true
+      ensure
+        subject.remove_image!($credentials[:email])
+        begin
+          subject.delete_user_image!("23f086a793459fa25aab280054fec1b2")
+        rescue XMLRPC::FaultException
+        end
+      end
+    end
+
+    it "should return user images" do
+      subject.user_images.should == {"fe9dee44a1df19967db30a04083722d5"=>
+              [:g, "http://en.gravatar.com/userimage/14612723/fe9dee44a1df19967db30a04083722d5.jpg"]}
+    end
+
+    it "should determine that the user exists" do
+      subject.exists?.should be_true
+    end
+
+    it "should determine that a fake user does not exist" do
+      subject.exists?("not-even-a-valid-email").should be_false
+    end
+
+    it "should determine that multiple fake users do not exist" do
+      subject.exists?("invalid-1", "invalid-2").should == { "invalid-1" => false, "invalid-2" => false }
+    end
+  end
+
+  context "given :email" do
+    subject { Gravatar.new("sinisterchipmunk@gmail.com") }
+
+    it "should not raise an error" do
+      proc { subject }.should_not raise_error(ArgumentError)
+    end
+
+    it "should return email_hash" do
+      subject.email_hash.should == "5d8c7a8d951a28e10bd7407f33df6d63"
+    end
+
+    it "should return gravatar image_url" do
+      subject.image_url.should == "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63"
+    end
+
+    it "should return gravitar image data" do
+      subject.image_data.should == image_data
+    end
+
+    it "should return gravatar image_url with SSL" do
+      subject.image_url(:ssl => true).should == "https://secure.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63"
+    end
+
+    it "should return gravatar image_url with size" do
+      subject.image_url(:size => 512).should == "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?size=512"
+    end
+
+    it "should return gravatar image_url with rating" do
+      subject.image_url(:rating => 'pg').should == "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?rating=pg"
+    end
+
+    it "should return gravatar image_url with file type" do
+      subject.image_url(:filetype => 'png').should == "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63.png"
+    end
+
+    it "should return gravatar image_url with default image" do
+      subject.image_url(:default => "http://example.com/images/example.jpg").should ==
+              "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?default=http%3A%2F%2Fexample.com%2Fimages%2Fexample.jpg"
+    end
+
+    it "should return gravatar image_url with SSL and default and size and rating" do
+      combinations = %w(
+        https://secure.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?default=identicon&size=80&rating=g
+        https://secure.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?size=80&rating=g&default=identicon
+        https://secure.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?size=80&default=identicon&rating=g
+        https://secure.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63?rating=g&size=80&default=identicon
+      )
+      combinations.should include(subject.image_url(:ssl => true, :default => "identicon", :size => 80, :rating => :g))
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+-c
+-b

data/spec/spec_helper.rb

@@ -0,0 +1,30 @@
+require File.expand_path("../../lib/gravatar", __FILE__)
+unless defined?(Spec)
+  gem 'rspec'
+  require 'spec'
+end
+
+def image_data
+  File.read(File.expand_path("../fixtures/image.jpg", __FILE__))
+end
+
+require 'fakeweb'
+FakeWeb.register_uri(:get, "http://www.gravatar.com/avatar/5d8c7a8d951a28e10bd7407f33df6d63", :response =>
+        "HTTP/1.1 200 OK\nContent-Type: image/jpg\n\n" +image_data)
+
+def new_cache
+  ActiveSupport::Cache::MemoryStore.new
+end
+
+Gravatar.cache = new_cache
+
+class Net::HTTP
+  alias_method :original_initialize, :initialize
+  def initialize(*args, &block)
+    original_initialize(*args, &block)
+    @ssl_context = OpenSSL::SSL::SSLContext.new
+    @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  end
+end
+
+$credentials = YAML::load(File.read(File.expand_path("../credentials.yml", __FILE__))).with_indifferent_access

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification 
+name: gravatar-ultimate
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Colin MacKenzie IV
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-16 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sc-core-ext
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 0
+        version: 1.2.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 8
+        version: 1.2.8
+  type: :development
+  version_requirements: *id003
+description: |-
+  The Ultimate Gravatar Gem!
+  
+  This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting
+  to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself,
+  rather than just a URL to that data. This saves you the extra step of having to do so.
+email: sinisterchipmunk@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- gravatar-ultimate.gemspec
+- lib/gravatar-ultimate.rb
+- lib/gravatar.rb
+- lib/gravatar/cache.rb
+- lib/gravatar/dependencies.rb
+- lib/gravatar_ultimate.rb
+- spec/credentials.yml.example
+- spec/fixtures/image.jpg
+- spec/lib/gravatar/cache_and_logger_spec.rb
+- spec/lib/gravatar/cache_setup_spec.rb
+- spec/lib/gravatar/dependencies_spec.rb
+- spec/lib/gravatar_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/sinisterchipmunk/gravatar
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: "A gem for interfacing with the entire Gravatar API: not just images, but the XML-RPC API too!"
+test_files: 
+- spec/spec_helper.rb
+- spec/lib/gravatar_spec.rb
+- spec/lib/gravatar/dependencies_spec.rb
+- spec/lib/gravatar/cache_and_logger_spec.rb
+- spec/lib/gravatar/cache_setup_spec.rb