Class: Gravatar
- Inherits:
-
Object
- Object
- Gravatar
- Defined in:
- lib/gravatar.rb,
lib/gravatar/cache.rb,
lib/gravatar/version.rb
Overview
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)
Defined Under Namespace
Modules: TestCase, Version Classes: Cache
Constant Summary collapse
- API_METHODS =
[ :exists?, :addresses, :user_images, :save_data!, :save_image!, :save_url!, :use_image!, :use_user_image!, :remove_image!, :delete_user_image!, :test, :image_url, :image_data ]
- VERSION =
Version::STRING
Instance Attribute Summary collapse
-
#api ⇒ Object
readonly
Returns the value of attribute api.
-
#email ⇒ Object
readonly
Returns the value of attribute email.
Class Method Summary collapse
- .cache ⇒ Object
- .cache=(instance) ⇒ Object
- .default_cache_instance ⇒ Object
- .default_logger_instance ⇒ Object
-
.duration ⇒ Object
How long is a cached object good for? Default is 30 minutes.
- .duration=(duration) ⇒ Object
- .logger ⇒ Object
- .logger=(logger) ⇒ Object
-
.reset_cache! ⇒ Object
Resets any changes to the cache and initializes a new cache.
Instance Method Summary collapse
-
#addresses ⇒ Object
Gets a list of addresses for this account, returning a hash following this format: { address => { :rating => rating, :userimage => userimage, :userimage_url => userimage_url } }.
- #api_key ⇒ Object
- #auth ⇒ Object
-
#auth_with(options) ⇒ Object
Authenticates with the given API key or password, returning self.
- #boolean(i) ⇒ Object
-
#cache(*key, &block) ⇒ Object
If no arguments are given, the cache object for this instance is returned.
-
#cache_duration ⇒ Object
The duration of the cache for this instance of Gravatar, independent of any other instance.
-
#cache_duration=(time) ⇒ Object
Sets the duration of the cache for this instance of Gravatar, independent of any other instance.
- #call(name, args_hash = {}) ⇒ Object
- #dehashify_emails(response, emails) ⇒ Object
-
#delete_user_image!(userimage) ⇒ Object
Remove a userimage from the account and any email addresses with which it is associated.
-
#email_hash(email = self.email) ⇒ Object
Returns the MD5 hash for the specified email address, or the one associated with this object.
-
#exists?(*emails) ⇒ Boolean
Check whether one or more email addresses have corresponding avatars.
- #expire_cache! ⇒ Object
- #extension_for_image(options) ⇒ Object
- #host ⇒ Object
-
#image_data(options = {}) ⇒ Object
Returns the image data for this user’s gravatar image.
-
#image_url(options = {}) ⇒ Object
Returns the URL for this user’s gravatar image.
-
#initialize(email, options = {}) ⇒ Gravatar
constructor
Creates a new instance of Gravatar.
- #normalize_email_addresses(addresses) ⇒ Object
- #options ⇒ Object
- #password ⇒ Object
- #path ⇒ Object
- #query_for_image(options) ⇒ Object
- #rating(i) ⇒ Object (also: #_rating)
-
#remove_image!(emails) ⇒ Object
Remove the userimage associated with one or more email addresses.
-
#save_data!(rating, data) ⇒ Object
(also: #save_image!)
Saves binary image data as a userimage for this account and returns the ID of the image.
-
#save_url!(rating, url) ⇒ Object
Read an image via its URL and save that as a userimage for this account, returning true or false.
-
#test(hash) ⇒ Object
Runs a simple Gravatar test.
- #url ⇒ Object
-
#use_user_image!(image_hash, emails) ⇒ Object
(also: #use_image!)
Use a userimage as a gravatar for one or more addresses on this account.
-
#user_images ⇒ Object
Returns a hash of user images for this account in the following format: { user_img_hash => [rating, url] }.
Constructor Details
#initialize(email, options = {}) ⇒ Gravatar
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.
38 39 40 41 42 43 44 45 46 47 48 49 |
# File 'lib/gravatar.rb', line 38 def initialize(email, = {}) raise ArgumentError, "Expected :email" unless email @options = || {} @email = email pw_or_key = auth.keys.first || :none @cache = Gravatar::Cache.new(self.class.cache, [:duration] || self.class.duration, "gravatar-#{email_hash}-#{pw_or_key}", [:logger] || self.class.logger) self.rescue_errors = [:rescue_errors] self.auth_with auth unless auth.empty? end |
Instance Attribute Details
#api ⇒ Object (readonly)
Returns the value of attribute api.
25 26 27 |
# File 'lib/gravatar.rb', line 25 def api @api end |
#email ⇒ Object (readonly)
Returns the value of attribute email.
25 26 27 |
# File 'lib/gravatar.rb', line 25 def email @email end |
Class Method Details
.cache ⇒ Object
108 109 110 |
# File 'lib/gravatar/cache.rb', line 108 def cache @cache ||= default_cache_instance end |
.cache=(instance) ⇒ Object
112 113 114 |
# File 'lib/gravatar/cache.rb', line 112 def cache=(instance) @cache = instance end |
.default_cache_instance ⇒ Object
100 101 102 |
# File 'lib/gravatar/cache.rb', line 100 def default_cache_instance defined?(Rails) ? Rails.cache : ActiveSupport::Cache::FileStore.new("tmp/cache") end |
.default_logger_instance ⇒ Object
104 105 106 |
# File 'lib/gravatar/cache.rb', line 104 def default_logger_instance defined?(Rails) ? Rails.logger : $stderr end |
.duration ⇒ Object
How long is a cached object good for? Default is 30 minutes.
125 126 127 |
# File 'lib/gravatar/cache.rb', line 125 def duration @duration ||= 24.hours end |
.duration=(duration) ⇒ Object
129 130 131 |
# File 'lib/gravatar/cache.rb', line 129 def duration=(duration) @duration = duration end |
.logger ⇒ Object
116 117 118 |
# File 'lib/gravatar/cache.rb', line 116 def logger @logger ||= default_logger_instance end |
.logger=(logger) ⇒ Object
120 121 122 |
# File 'lib/gravatar/cache.rb', line 120 def logger=(logger) @logger = logger end |
.reset_cache! ⇒ Object
Resets any changes to the cache and initializes a new cache. If using Rails, the new cache will be the Rails cache.
135 136 137 |
# File 'lib/gravatar/cache.rb', line 135 def reset_cache! @cache = nil end |
Instance Method Details
#addresses ⇒ Object
Gets a list of addresses for this account, returning a hash following this format:
{
address => {
:rating => ,
:userimage => userimage,
:userimage_url => userimage_url
}
}
This method is cached for up to the value of @duration or Gravatar.duration.
101 102 103 104 105 106 107 108 |
# File 'lib/gravatar.rb', line 101 def addresses cache('addresses') do call('grav.addresses').inject({}) do |hash, (address, info)| hash[address] = info.merge(:rating => (info[:rating])) hash end end end |
#api_key ⇒ Object
293 294 295 |
# File 'lib/gravatar.rb', line 293 def api_key [:apikey] || [:api_key] || [:key] end |
#auth ⇒ Object
289 290 291 |
# File 'lib/gravatar.rb', line 289 def auth api_key ? {:apikey => api_key} : (password ? {:password => password} : {}) end |
#auth_with(options) ⇒ Object
Authenticates with the given API key or password, returning self.
278 279 280 281 282 283 284 285 286 287 |
# File 'lib/gravatar.rb', line 278 def auth_with() @options.delete(:apikey) @options.delete(:api_key) @options.delete(:key) @options.merge! if !auth.empty? @api = XMLRPC::Client.new(host, path, 443, nil, nil, nil, nil, true) end self end |
#boolean(i) ⇒ Object
266 267 268 |
# File 'lib/gravatar.rb', line 266 def boolean(i) i.kind_of?(Numeric) ? i != 0 : i end |
#cache(*key, &block) ⇒ Object
If no arguments are given, the cache object for this instance is returned. Otherwise, the arguments are passed into Gravatar::Cache#cache.
221 222 223 224 225 226 227 |
# File 'lib/gravatar.rb', line 221 def cache(*key, &block) if key.empty? and not block_given? @cache else @cache.call(*key, &block) end end |
#cache_duration ⇒ Object
The duration of the cache for this instance of Gravatar, independent of any other instance
64 65 66 |
# File 'lib/gravatar.rb', line 64 def cache_duration cache.duration end |
#cache_duration=(time) ⇒ Object
Sets the duration of the cache for this instance of Gravatar, independent of any other instance
69 70 71 |
# File 'lib/gravatar.rb', line 69 def cache_duration=(time) cache.duration = time end |
#call(name, args_hash = {}) ⇒ Object
270 271 272 273 274 275 |
# File 'lib/gravatar.rb', line 270 def call(name, args_hash = {}) raise "No authentication data given" unless @api r = @api.call(name, auth.merge(args_hash)) r = r.with_indifferent_access if r.kind_of?(Hash) r end |
#dehashify_emails(response, emails) ⇒ Object
233 234 235 236 237 238 239 240 241 |
# File 'lib/gravatar.rb', line 233 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 |
#delete_user_image!(userimage) ⇒ Object
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.
172 173 174 175 176 |
# File 'lib/gravatar.rb', line 172 def delete_user_image!(userimage) boolean(call('grav.deleteUserimage', :userimage => userimage)).tap do expire_cache! end end |
#email_hash(email = self.email) ⇒ Object
Returns the MD5 hash for the specified email address, or the one associated with this object.
185 186 187 |
# File 'lib/gravatar.rb', line 185 def email_hash(email = self.email) Digest::MD5.hexdigest(email.downcase.strip) end |
#exists?(*emails) ⇒ Boolean
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.
79 80 81 82 83 84 85 86 87 88 89 |
# File 'lib/gravatar.rb', line 79 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 |
#expire_cache! ⇒ Object
229 230 231 |
# File 'lib/gravatar.rb', line 229 def expire_cache! cache.clear! end |
#extension_for_image(options) ⇒ Object
316 317 318 |
# File 'lib/gravatar.rb', line 316 def extension_for_image() .key?(:filetype) || .key?(:ext) ? "." + ([:filetype] || [:ext] || "jpg").to_s : "" end |
#host ⇒ Object
51 52 53 |
# File 'lib/gravatar.rb', line 51 def host "secure.gravatar.com" end |
#image_data(options = {}) ⇒ Object
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.
214 215 216 217 |
# File 'lib/gravatar.rb', line 214 def image_data( = {}) url = image_url() cache(url) { OpenURI.open_uri(URI.parse(url)).read } end |
#image_url(options = {}) ⇒ Object
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 or :ext an extension such as :jpg or :png. Default is omitted.
:forcedefault or :f force a default image and ignore the user's specified image. Can be one of
[ :identicon, :monsterid, :wavatar, 404 ].
See en.gravatar.com/site/implement/url for much more detailed information.
202 203 204 205 206 207 208 |
# File 'lib/gravatar.rb', line 202 def image_url( = {}) secure = [:ssl] || [:secure] proto = "http#{secure ? 's' : ''}" sub = secure ? "secure" : "www" "#{proto}://#{sub}.gravatar.com/avatar/#{email_hash}#{extension_for_image()}#{query_for_image()}" end |
#normalize_email_addresses(addresses) ⇒ Object
243 244 245 246 247 |
# File 'lib/gravatar.rb', line 243 def normalize_email_addresses(addresses) addresses.flatten! addresses << @email if addresses.empty? addresses.map { |email| email_hash(email) } end |
#options ⇒ Object
301 302 303 |
# File 'lib/gravatar.rb', line 301 def @options end |
#password ⇒ Object
297 298 299 |
# File 'lib/gravatar.rb', line 297 def password [:password] end |
#path ⇒ Object
59 60 61 |
# File 'lib/gravatar.rb', line 59 def path "/xmlrpc?user=#{email_hash}" end |
#query_for_image(options) ⇒ Object
305 306 307 308 309 310 311 312 313 314 |
# File 'lib/gravatar.rb', line 305 def query_for_image() query = '' [:rating, :size, :default, :forcedefault, :r, :s, :d, :f].each do |key| if .key?(key) query.blank? ? query.concat("?") : query.concat("&") query.concat("#{key}=#{CGI::escape [key].to_s}") end end query end |
#rating(i) ⇒ Object Also known as: _rating
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 |
# File 'lib/gravatar.rb', line 249 def (i) case i when -1, '-1' then :unknown when 0, '0' then :g when 1, '1' then :pg when 2, '2' then :r when 3, '3' then :x when :unknown then -1 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 |
#remove_image!(emails) ⇒ Object
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.
159 160 161 162 163 164 |
# File 'lib/gravatar.rb', line 159 def remove_image!(emails) emails = [emails] unless emails.is_a?(Array) hash = call('grav.removeImage', :addresses => emails) expire_cache! return hash end |
#save_data!(rating, data) ⇒ Object Also known as: save_image!
Saves binary image data as a userimage for this account and returns the ID of the image.
This method is not cached.
126 127 128 |
# File 'lib/gravatar.rb', line 126 def save_data!(, data) call('grav.saveData', :data => Base64.encode64(data), :rating => ()) end |
#save_url!(rating, url) ⇒ Object
Read an image via its URL and save that as a userimage for this account, returning true or false
This method is not cached.
134 135 136 |
# File 'lib/gravatar.rb', line 134 def save_url!(, url) call('grav.saveUrl', :url => url, :rating => ()) end |
#test(hash) ⇒ Object
Runs a simple Gravatar test. Useful for debugging. Gravatar will echo back any arguments you pass. This method is not cached.
180 181 182 |
# File 'lib/gravatar.rb', line 180 def test(hash) call('grav.test', hash) end |
#url ⇒ Object
55 56 57 |
# File 'lib/gravatar.rb', line 55 def url File.join("https://#{host}", path) end |
#use_user_image!(image_hash, emails) ⇒ Object Also known as: use_image!
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.
144 145 146 147 148 149 |
# File 'lib/gravatar.rb', line 144 def use_user_image!(image_hash, emails) emails = [emails] unless emails.is_a?(Array) hash = call('grav.useUserimage', :userimage => image_hash, :addresses => emails) expire_cache! return hash end |
#user_images ⇒ Object
Returns a hash of user images for this account in the following format:
{ user_img_hash => [, url] }
This method is cached for up to the value of @duration or Gravatar.duration.
114 115 116 117 118 119 120 121 |
# File 'lib/gravatar.rb', line 114 def user_images cache('user_images') do call('grav.userimages').inject({}) do |hash, (key, array)| hash[key] = [(array.first), array.last] hash end end end |