class Gravaty::Gravaty

This class is a simple API to retrieve an URL with specified options from Gravatar site. It can be used to read data for avatars, profiles or for XML-RPC APi calls. The only needed parameter to create a Gravaty object is the reference email address.

Author

Marco Bresciani

rubocop:disable Style/AsciiComments

Copyright

Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Marco Bresciani

rubocop:enable Style/AsciiComments

License

GNU General Public License version 3

Attributes

digest[R]

Provides the MD5 signature (of the small caps version) of the email address used to build the object.

email[R]

Provides the (small caps version of) email address used to build the object.

Public Class Methods

new(email_address, parser) click to toggle source

Creates a Gravaty object described by the user's email. Throws an ArgumentError exception if the supplied email address is nil or not valid according to RFC5322.

Usage

new_gravaty = Gravaty.new email, parser

Params
  • email_address, the user's email address (a syntactically

valid one).

- +parser+, a parser duck-responding to the +parse+ method with

two parameters, method name and value string

Returns

a Gravaty object for the specified email address.

Raises

ArgumentError, if the supplied email address is nil

or not valid according to RFC 5322.

   # File lib/gravaty/application.rb
73 def initialize(email_address, parser)
74   I18n.load_path = Dir[File.join(File.dirname(__FILE__),
75                                  '/locales/', '*.yml')]
76 
77   raise ArgumentError, I18n.t('error.nil') if email_address.nil?
78   unless Utils::Rfc5322::EMAIL.match email_address
79     raise ArgumentError, I18n.t('error.invalid', value: email_address)
80   end
81 
82   @email = email_address.strip.downcase
83   @digest = Digest::MD5.hexdigest email
84   @gravaty = email
85   @parser = parser
86 end

Public Instance Methods

<=>(other) click to toggle source
    # File lib/gravaty/application.rb
340 def <=>(other)
341   @email <=> other.email
342 end
avatar(args = {}) click to toggle source

Returns a string containing the URI of the gravatar associated to internal (provided) email address. Valid keys for the args hash are: :type, :pixel_size, :force, :secure, :rating, :default.

Usage
  • a_string = new_gravaty.avatar

  • a_string = new_gravaty.avatar

  • a_string = new_gravaty.avatar pixel_size: 42

  • <tt>a_string = new_gravaty.avatar pixel_size: 42, type:

png'</tt>

- <tt>a_string = new_gravaty.avatar secure: false</tt>
- <tt>a_string = new_gravaty.avatar type: 'jpg', force:

true</tt>

- <tt>a_string = new_gravaty.avatar secure: true, pixel_size:

42, type: 'png'</tt>

- <tt>a_string = new_gravaty.avatar rating: pg, type: 'gif'</tt>
- <tt>a_string = new_gravaty.avatar default: monsterid,

pixel_size: 42</tt>

Params
  • type: [String] is the possibly desired specific image

format. Valid formats are jp(e)g, png or gif. Default to no extension. Will be downcased. Raises ArgumentError for invalid formats.

- +pixel_size+: [Integer] is the size in pixel of the image.

From 1 to 2048. Default to no value. Raises ArgumentError for invalid sizes.

- +force+: [TrueClass || FalseClass] is a boolean to specify if

the default has to be forced when no image is found. Default to false.

- +secure+: [TrueClass || FalseClass] is a boolean to specify

whether the resulting URL shall be HTTPS or HTTP type. Default to true (HTTPS).

- +rating+: [String] is the rating type of the image. Valid

values are 'g', 'pg', 'r' and 'x'.

- +default+: [String] is the default type of the image (valid

values are '404', 'mm', 'identicon', 'monsterid', 'wavatar', 'retro' and 'blank'), or the URI for an own default image. For the URI validation see: it.gravatar.com/site/implement/images/#default-image .

Returns

a String containing the Gravatar site URI with

specified options and configuration parameters.

    # File lib/gravaty/application.rb
129 def avatar(args = {})
130   secure = true
131   type = nil
132 
133   array = []
134   unless args.nil?
135     type = args.fetch(:type, nil)
136     secure = args.fetch(:secure, secure)
137 
138     %i[pixelsize force default rating].each do |param|
139       array << @parser.parse(param.to_s, args[param]) unless args[param].nil?
140     end
141   end
142 
143   build_uri(secure: secure) + digest +
144     @parser.parse('type', type) + build_query_string(array)
145 end
avatar!(args = {}) click to toggle source

See avatar method. This banged version saves the resulting string as internal state.

    # File lib/gravaty/application.rb
149 def avatar!(args = {})
150   @gravaty = avatar(args)
151 end
download(filename = nil) click to toggle source

Saves a file, with specified filename, that contains the current gravaty configuration. Uses the internal state to retrieve data from the URI. Defaults to 'gravaty' with no specific extension.

Usage
  • a_string = new_gravaty.download filename

Params
  • filename: [String] is the filename to be saved.

    # File lib/gravaty/application.rb
206 def download(filename = nil)
207   if filename.nil?
208     filename = URI.parse(@gravaty).path.rpartition('/')
209                   .last
210   end
211   Utils::Downloader::Downloader
212     .download_file @gravaty, filename # thanks Jon!
213 end
json(args = {}) click to toggle source

See profile method. Customized version for JSON-specific requests.

Usage
  • a_string = new_gravaty.json

  • a_string = new_gravaty.json callback: 'alert'

  • <tt>a_string = new_gravaty.qrcode secure: false, callback:

'alert'</tt>

Params
  • secure: [TrueClass || FalseClass] is a boolean to specify

whether the resulting URL shall be HTTPS or HTTP type. Default to true (HTTPS).

- +callback+: [String] See

secure.gravatar.com/site/implement/profiles/json/#request-options. No check on parameter meaning or validity, except for nil.

Returns

a String containing the Gravatar site URI with

specified options and configuration parameters, in JSON format.

    # File lib/gravaty/application.rb
266 def json(args = {})
267   secure = true
268   callback = nil
269 
270   unless args.nil?
271     callback = args.fetch(:callback, nil)
272     secure = args.fetch(:secure, secure)
273   end
274 
275   profile format: 'json', secure: secure, callback: callback
276 end
json!(args = {}) click to toggle source

See json method. This banged version saves the resulting string as internal state.

    # File lib/gravaty/application.rb
280 def json!(args = {})
281   @gravaty = json(args)
282 end
profile(args = {}) click to toggle source

Returns a string containing the URI of the gravatar profile associated to internal (provided) email address. Valid keys for the args hash are: :secure, :format.

Usage
  • a_string = new_gravaty.profile

  • a_string = new_gravaty.profile secure: false

  • <tt>a_string = new_gravaty.profile format: 'php', secure:

true</tt>

Params
  • format: [String] is the possibly desired specific profile

format. Valid formats are 'json', 'xml', 'php', 'vcf' and 'qr'. Default to no extension. Will be downcased. Defaults to no extension for invalid formats.

- +secure+: [TrueClass || FalseClass] is a boolean to specify

whether the resulting URL shall be HTTPS or HTTP type. Default to true (HTTPS).

Returns

a String containing the Gravatar site URI with

specified options and configuration parameters.

    # File lib/gravaty/application.rb
172 def profile(args = {})
173   secure = true
174   format = nil
175 
176   array = []
177   unless args.nil?
178     format = args[:format].downcase unless args[:format].nil?
179     secure = args.fetch(:secure, secure)
180 
181     unless format.nil? && (PROFILES.include? format)
182       selected = (format == 'json' ? 'callback' : 'pixelsize')
183 
184       array << @parser.parse(selected, args[selected.to_sym]) unless args[selected.to_sym].nil?
185     end
186   end
187 
188   build_uri(secure: secure, avatar: false) + digest +
189     @parser.parse(:format, format) + build_query_string(array)
190 end
profile!(args = {}) click to toggle source

See profile method. This banged version saves the resulting string as internal state.

    # File lib/gravaty/application.rb
194 def profile!(args = {})
195   @gravaty = profile(args)
196 end
qrcode(args = {}) click to toggle source

See profile method. Customized version for QRCode-specific requests.

Usage
  • a_string = new_gravaty.qrcode

  • a_string = new_gravaty.qrcode pixel_size: 42

  • <tt>a_string = new_gravaty.qrcode secure: false, pixel_size:

42</tt>

Params
  • secure: [TrueClass || FalseClass] is a boolean to specify

whether the resulting URL shall be HTTPS or HTTP type. Default to true (HTTPS).

- +pixel_size+: [Integer] is the size in pixel of the image.

From 1 to 2048. Default to no value. Raises ArgumentError for invalid sizes.

Returns

a String containing the Gravatar site URI with

specified options and configuration parameters, in QRCode format.

    # File lib/gravaty/application.rb
232 def qrcode(args = {})
233   secure = true
234   size = nil
235 
236   unless args.nil?
237     size = args.fetch(:pixelsize, nil)
238     secure = args.fetch(:secure, secure)
239   end
240 
241   profile format: 'qr', secure: secure, pixelsize: size
242 end
qrcode!(args = {}) click to toggle source

See qrcode method. This banged version saves the resulting string as internal state.

    # File lib/gravaty/application.rb
246 def qrcode!(args = {})
247   @gravaty = qrcode(args)
248 end
reset() click to toggle source

Restores the original status cleaning up the (possibly) previously saved URIs restoring the default to_s.

    # File lib/gravaty/application.rb
286 def reset
287   @gravaty = email
288 end
to_json(*_args) click to toggle source

Returns a JSon object representing the Gravaty object.

Usage
  • a_json = new_gravaty.to_json

Returns

a JSON containing the Gravaty object representation

with currently saved options and configuration parameters.

    # File lib/gravaty/application.rb
322 def to_json(*_args)
323   result = {}
324   result[email] = digest
325 
326   result.to_json
327 end
to_s() click to toggle source

Returns a string representing the Gravaty object.

Usage
  • a_string = new_gravaty.to_s

Returns

a String containing the Gravaty object representation

with currently saved options and configuration parameters.

    # File lib/gravaty/application.rb
336 def to_s
337   @gravaty.to_s
338 end
xmlrpc(a_method = RPC_TEST_METHOD, password = nil, args = {}) click to toggle source

Interfaces with the Gravatar XML-RPC API.

Usage
  • <tt>response = new_gravaty.xmlrpc 'grav.test',

my_password</tt>

Params
  • a_method: [String] is a valid method supported by Gravatar

XML-RPC API. See en.gravatar.com/site/implement/xmlrpc/ .

- +password+: [String] is a valid password associated to user's

email_address specified to build the Gravaty object.

- +args+: See https://en.gravatar.com/site/implement/xmlrpc/ for

possible parameters, depending on called method.

Returns

See en.gravatar.com/site/implement/xmlrpc/ for

possible return values, depending on called method.

    # File lib/gravaty/application.rb
304 def xmlrpc(a_method = RPC_TEST_METHOD, password = nil, args = {})
305   raise ArgumentError, I18n.t('error.nil') if password.nil?
306   raise ArgumentError, I18n.t('error.invalid', value: a_method) unless RPC_METHODS.include? a_method
307 
308   if @rpc_connector.nil?
309     @rpc_connector = Utils::RpcConnector::RpcConnector
310                      .new(digest, password)
311   end
312   @rpc_connector&.call a_method, args
313 end