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
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
Provides the MD5 signature (of the small caps version) of the email
address used to build the object.
Provides the (small caps version of) email
address used to build the object.
Public Class Methods
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 specifiedemail
address. - Raises
-
ArgumentError
, if the suppliedemail
address isnil
or not valid according to RFC 5322.
# File lib/gravaty/application.rb, line 73 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? unless Utils::Rfc5322::EMAIL.match email_address raise ArgumentError, I18n.t('error.invalid', value: email_address) end @email = email_address.strip.downcase @digest = Digest::MD5.hexdigest email @gravaty = email @parser = parser end
Public Instance Methods
# File lib/gravaty/application.rb, line 340 def <=>(other) @email <=> other.email end
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, line 129 def avatar(args = {}) secure = true type = nil array = [] unless args.nil? type = args.fetch(:type, nil) secure = args.fetch(:secure, secure) %i[pixelsize force default rating].each do |param| array << @parser.parse(param.to_s, args[param]) unless args[param].nil? end end build_uri(secure: secure) + digest + @parser.parse('type', type) + build_query_string(array) end
See avatar method. This banged version saves the resulting string as internal state.
# File lib/gravaty/application.rb, line 149 def avatar!(args = {}) @gravaty = avatar(args) end
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, line 206 def download(filename = nil) if filename.nil? filename = URI.parse(@gravaty).path.rpartition('/') .last end Utils::Downloader::Downloader .download_file @gravaty, filename # thanks Jon! end
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, line 266 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
See json method. This banged version saves the resulting string as internal state.
# File lib/gravaty/application.rb, line 280 def json!(args = {}) @gravaty = json(args) end
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, line 172 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? && (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: secure, avatar: false) + digest + @parser.parse(:format, format) + build_query_string(array) end
See profile method. This banged version saves the resulting string as internal state.
# File lib/gravaty/application.rb, line 194 def profile!(args = {}) @gravaty = profile(args) end
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, line 232 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
See qrcode method. This banged version saves the resulting string as internal state.
# File lib/gravaty/application.rb, line 246 def qrcode!(args = {}) @gravaty = qrcode(args) end
Restores the original status cleaning up the (possibly) previously saved URIs restoring the default to_s
.
# File lib/gravaty/application.rb, line 286 def reset @gravaty = email end
Returns a JSon object representing the Gravaty
object.
- Usage
-
a_json = new_gravaty.to_json
-
- Returns
-
a
JSON
containing theGravaty
object representation
with currently saved options and configuration parameters.
# File lib/gravaty/application.rb, line 322 def to_json(*_args) result = {} result[email] = digest result.to_json end
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
possible return values, depending on called method.
# File lib/gravaty/application.rb, line 304 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 if @rpc_connector.nil? @rpc_connector = Utils::RpcConnector::RpcConnector .new(digest, password) end @rpc_connector&.call a_method, args end
Private Instance Methods
Builds the query string with the array of parameters.
# File lib/gravaty/application.rb, line 349 def build_query_string(params_array = []) parameters = nil unless params_array.nil? parameters = params_array.reject { |p| p.nil? or p.empty? } .join('&') end return "?#{parameters}" unless parameters.nil? || parameters .empty? '' end
Return the basic URI structure according to type and security.
# File lib/gravaty/application.rb, line 364 def build_uri(secure: false, avatar: true) "#{@parser.parse('secure', secure)}.gravatar.com/#{@parser.parse('avatar', avatar)}" end