Class: Gravaty::Gravaty

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/gravaty/application.rb

Overview

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

Copyright

Copyright © 2013, 2014, 2015, 2016, 2017, 2018,

2019 Marco Bresciani

License

GNU General Public License version 3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(email_address, parser) ⇒ Gravaty

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.

Raises:

  • (ArgumentError) 


65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/gravaty/application.rb', line 65

def initialize(email_address, parser)
  I18n.load_path = Dir[File.join(File.dirname(__FILE__),
                                 '/locales/', '*.yml')]

  raise ArgumentError, I18n.t('error.nil') if email_address.nil?
  raise ArgumentError, I18n.t('error.invalid', value: email_address) unless Utils::Rfc5322::EMAIL.match email_address # thanks Peter!

  @email = email_address.strip.downcase
  @digest = Digest::MD5.hexdigest email
  @gravaty = email
  @parser = parser
end

Instance Attribute Details

#digest ⇒ Object (readonly)

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



46
47
48
 
# File 'lib/gravaty/application.rb', line 46

def digest
  @digest
end

#email ⇒ Object (readonly)

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



50
51
52
 
# File 'lib/gravaty/application.rb', line 50

def email
  @email
end

Instance Method Details

#<=>(other_gravaty) ⇒ Object 



326
327
328
 
# File 'lib/gravaty/application.rb', line 326

def <=>(other_gravaty)
  @email <=> other_gravaty.email
end

#avatar(args = {}) ⇒ Object

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.



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/gravaty/application.rb', line 119

def avatar(args = {})
  secure = true
  type = nil

  array = []
  unless args.nil?
    type = args.fetch(:type, nil)
    secure = args.fetch(:secure, secure)

    [:pixelsize, :force, :default, :rating].each do |param|
      array << @parser.parse(param.to_s, args[param]) unless args[param].nil?
    end
  end

  build_uri(secure, true) + digest +
      @parser.parse('type', type) + build_query_string(array)
end

#avatar!(args = {}) ⇒ Object

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



139
140
141
 
# File 'lib/gravaty/application.rb', line 139

def avatar!(args = {})
  @gravaty = avatar(args)
end

#download(filename = nil) ⇒ Object

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.



196
197
198
199
200
201
 
# File 'lib/gravaty/application.rb', line 196

def download(filename = nil)
  filename = URI.parse(@gravaty).path.rpartition('/')
                 .last if filename.nil?
  Utils::Downloader::Downloader
      .download_file @gravaty, filename # thanks Jon!
end

#json(args = {}) ⇒ Object

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.



254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/gravaty/application.rb', line 254

def json(args = {})
  secure = true
  callback = nil

  unless args.nil?
    callback = args.fetch(:callback, nil)
    secure = args.fetch(:secure, secure)
  end

  profile format: 'json', secure: secure, callback: callback
end

#json!(args = {}) ⇒ Object

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



268
269
270
 
# File 'lib/gravaty/application.rb', line 268

def json!(args = {})
  @gravaty = json(args)
end

#profile(args = {}) ⇒ Object

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.



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/gravaty/application.rb', line 162

def profile(args = {})
  secure = true
  format = nil

  array = []
  unless args.nil?
    format = args[:format].downcase unless args[:format].nil?
    secure = args.fetch(:secure, secure)

    unless (format.nil?) and (PROFILES.include? format)
      selected = (format == 'json' ? 'callback' : 'pixelsize')

      array << @parser.parse(selected, args[selected.to_sym]) unless args[selected.to_sym].nil?
    end
  end

  build_uri(secure, false) + digest +
      @parser.parse('format', format) + build_query_string(array)
end

#profile!(args = {}) ⇒ Object

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



184
185
186
 
# File 'lib/gravaty/application.rb', line 184

def profile!(args = {})
  @gravaty = profile(args)
end

#qrcode(args = {}) ⇒ Object

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.



220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/gravaty/application.rb', line 220

def qrcode(args = {})
  secure = true
  size = nil

  unless args.nil?
    size = args.fetch(:pixelsize, nil)
    secure = args.fetch(:secure, secure)
  end

  profile format: 'qr', secure: secure, pixelsize: size
end

#qrcode!(args = {}) ⇒ Object

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



234
235
236
 
# File 'lib/gravaty/application.rb', line 234

def qrcode!(args = {})
  @gravaty = qrcode(args)
end

#reset ⇒ Object

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



274
275
276
 
# File 'lib/gravaty/application.rb', line 274

def reset
  @gravaty = email
end

#to_json ⇒ Object

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.



308
309
310
311
312
313
 
# File 'lib/gravaty/application.rb', line 308

def to_json
  result = Hash.new
  result[email] = digest

  result.to_json
end

#to_s ⇒ Object

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.



322
323
324
 
# File 'lib/gravaty/application.rb', line 322

def to_s
  @gravaty.to_s
end

#xmlrpc(a_method = RPC_TEST_METHOD, password = nil, args = {}) ⇒ Object

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.

Raises:

  • (ArgumentError) 


292
293
294
295
296
297
298
299
 
# File 'lib/gravaty/application.rb', line 292

def xmlrpc(a_method = RPC_TEST_METHOD, password = nil, args = {})
  raise ArgumentError, I18n.t('error.nil') if password.nil?
  raise ArgumentError, I18n.t('error.invalid', value: a_method) unless RPC_METHODS.include? a_method

  @rpc_connector = Utils::RpcConnector::RpcConnector
                       .new(digest, password) if @rpc_connector.nil?
  @rpc_connector.call a_method, args unless @rpc_connector.nil?
end