gravaty 8.0.0

data/lib/gravaty.rb

@@ -0,0 +1,59 @@
+#
+# gravaty
+# Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+#
+# This file is part of gravaty.
+#
+# gravaty is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+#
+# gravaty is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with gravaty. If not, see
+# <http://www.gnu.org/licenses/>.
+#
+
+require 'digest/md5'
+require 'i18n'
+require 'uri'
+
+require_relative 'gravaty/application'
+require_relative 'gravaty/parser'
+require_relative 'gravaty/parsers/avatar'
+require_relative 'gravaty/parsers/callback'
+require_relative 'gravaty/parsers/default'
+require_relative 'gravaty/parsers/force'
+require_relative 'gravaty/parsers/format'
+require_relative 'gravaty/parsers/pixelsize'
+require_relative 'gravaty/parsers/rating'
+require_relative 'gravaty/parsers/secure'
+require_relative 'gravaty/parsers/type'
+
+# Author:: {Marco Bresciani}[mailto:m.bresciani@email.it]
+# Copyright:: Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+# License:: GNU General Public License version 3
+module Gravaty
+
+  # Creates a new Gravaty described by the user's +email+. Throws a <code>ArgumentError</code> exception if the supplied +email+ address is nil or not valid according to RFC5322.
+  #
+  # Usage::
+  #   - <tt>new_gravaty = Gravaty::gravatize email</tt>
+  #   - <tt>new_gravaty = Gravaty::gravatize(email)</tt>
+  # Params:: +email_address+, the user's email address (a syntactically valid one).
+  # 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.
+  def self.gravatize(email_address)
+    Gravaty.new email_address, parser
+  end
+
+# ------------------------------------------------------------------------------ here starts the list of private methods
+  private
+
+  # Provides the parameters' parsers object.
+  def self.parser
+    parsers = {avatar: Parsers::Avatar.new, callback: Parsers::Callback.new, default: Parsers::Default.new, force: Parsers::Force.new, format: Parsers::Format.new, pixelsize: Parsers::Pixelsize.new, rating: Parsers::Rating.new, secure: Parsers::Secure.new, type: Parsers::Type.new}
+
+    Parser.new parsers
+  end
+end

data/lib/gravaty/application.rb

@@ -0,0 +1,272 @@
+#--
+# gravaty
+# Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+#
+# This file is part of gravaty.
+#
+# gravaty is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+#
+# gravaty is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with gravaty. If not, see
+# <http://www.gnu.org/licenses/>.
+#++
+
+require 'digest/md5'
+require 'i18n'
+require 'json'
+require 'uri'
+require 'xmlrpc/client'
+
+require_relative 'utils/downloader'
+require_relative 'utils/rfc5322'
+require_relative 'utils/rpc_connector'
+
+module 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}[mailto:m.bresciani@email.it]
+  # Copyright:: Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+  # License:: GNU General Public License version 3
+  class Gravaty
+    include Comparable
+
+    # Provides the MD5 signature (of the small caps version) of the +email+ address used to build the object.
+    attr_reader :digest
+
+    # Provides the (small caps version of) +email+ address used to build the object.
+    attr_reader :email
+
+    # 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:: <tt>new_gravaty = Gravaty.new email, parser</tt>
+    # 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.
+    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
+
+    # 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::
+    #   - <tt>a_string = new_gravaty.avatar</tt>
+    #   - <tt>a_string = new_gravaty.avatar</tt>
+    #   - <tt>a_string = new_gravaty.avatar pixel_size: 42</tt>
+    #   - <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 <code>ArgumentError</code> for invalid formats.
+    #   - +pixel_size+: [Integer] is the size in pixel of the image. From 1 to 2048. Default to no value. Raises <code>ArgumentError</code> 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: http://it.gravatar.com/site/implement/images/#default-image .
+    # Returns:: a +String+ containing the Gravatar site URI with specified options and configuration parameters.
+    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
+
+    # See avatar method. This banged version saves the resulting string as internal state.
+    def avatar!(args = {})
+      @gravaty = avatar(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::
+    #   - <tt>a_string = new_gravaty.profile</tt>
+    #   - <tt>a_string = new_gravaty.profile secure: false</tt>
+    #   - <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.
+    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
+
+    # See profile method. This banged version saves the resulting string as internal state.
+    def profile!(args = {})
+      @gravaty = profile(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::
+    #   - <tt>a_string = new_gravaty.download filename</tt>
+    # Params::
+    #   - +filename+: [String] is the filename to be saved.
+    def download(filename = nil)
+      filename = URI.parse(@gravaty).path.rpartition('/').last if filename.nil?
+      Utils::Downloader::Downloader.download_file @gravaty, filename # thanks Jon!
+    end
+
+    # See profile method. Customized version for QRCode-specific requests.
+    #
+    # Usage::
+    #   - <tt>a_string = new_gravaty.qrcode</tt>
+    #   - <tt>a_string = new_gravaty.qrcode pixel_size: 42</tt>
+    #   - <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 <code>ArgumentError</code> for invalid sizes.
+    # Returns:: a +String+ containing the Gravatar site URI with specified options and configuration parameters, in QRCode format.
+    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.
+    def qrcode!(args = {})
+      @gravaty = qrcode(args)
+    end
+
+    # See profile method. Customized version for JSON-specific requests.
+    #
+    # Usage::
+    #   - <tt>a_string = new_gravaty.json</tt>
+    #   - <tt>a_string = new_gravaty.json callback: 'alert'</tt>
+    #   - <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 https://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.
+    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.
+    def json!(args = {})
+      @gravaty = json(args)
+    end
+
+    # Restores the original status cleaning up the (possibly) previously saved URIs restoring the default +to_s+.
+    def reset
+      @gravaty = email
+    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 https://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 https://en.gravatar.com/site/implement/xmlrpc/ for possible return values, depending on called method.
+    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
+    end
+
+    # Returns a JSon object representing the Gravaty object.
+    #
+    #
+    # Usage::
+    #   - <tt>a_json = new_gravaty.to_json</tt>
+    # Returns:: a +JSON+ containing the Gravaty object representation with currently saved options and configuration parameters.
+    def to_json
+      result = Hash.new
+      result[email] = digest
+
+      result.to_json
+    end
+
+    # Returns a string representing the Gravaty object.
+    #
+    #
+    # Usage::
+    #   - <tt>a_string = new_gravaty.to_s</tt>
+    # Returns:: a +String+ containing the Gravaty object representation with currently saved options and configuration parameters.
+    def to_s
+      @gravaty.to_s
+    end
+
+    def <=>(other_gravaty)
+      @email <=> other_gravaty.email
+    end
+
+# ------------------------------------------------------------------------------ here starts the list of private methods
+    private
+
+    # Builds the query string with the array of parameters.
+    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? or parameters.empty?
+      ''
+    end
+
+    # Return the basic URI structure according to type and security.
+    def build_uri(secure = false, avatar = true)
+      @parser.parse('secure', secure) + '.gravatar.com/' + @parser.parse('avatar', avatar)
+    end
+  end
+end

data/lib/gravaty/constants.rb

@@ -0,0 +1,53 @@
+#--
+# gravaty
+# Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+#
+# This file is part of gravaty.
+#
+# gravaty is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+#
+# gravaty is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with gravaty. If not, see
+# <http://www.gnu.org/licenses/>.
+#++
+
+module Gravaty
+  # Allowed sizes (in pixels) for images requests. Currently a range from 1 to 2048 (included).
+  ALLOWED_SIZES = (1...2048)
+
+  # Allowed parameters names. Currently: avatar, callback, default, force, format, pixelsize, rating, secure and type.
+  ALLOWED_PARAMS = [:avatar, :callback, :default, :force, :format, :pixelsize, :rating, :secure, :type]
+
+  # Allowed formats (extensions) for avatar requests. Currently: jp(e)g, png and gif.
+  AVATAR_FORMATS = %w(jpg jpeg png gif)
+
+  # Currently allowed default builtin options. Currently: 404, mm, identicon, monsterid,wavatar, retro and blank.
+  DEFAULT_OPTIONS = %w(404 mm identicon monsterid wavatar retro blank)
+
+  # Allowed formats (extensions) for default own images. Currently: jp(e)g, png and gif.
+  IMAGES_FORMATS = %w(jpg jpeg png gif)
+
+  # Allowed formats (extensions) for profile requests. Currently: json, xml, php, vcf and qr.
+  PROFILE_FORMATS = %w(json xml php vcf qr)
+
+  # Formats allowing supplemental options for profile requests. Currently json and qr.
+  PROFILES = %w(json qr)
+
+  # Allowed rating options. Currently: g, pg, r and x.
+  RATING_OPTIONS = %w(g pg r x)
+
+  # Possible XML-RPC API errors.
+  RPC_ERRORS = [-7, -8, -9, -10, -11, -100]
+
+  # Allowed XML-RPC API methods.
+  RPC_METHODS = %w(grav.exists grav.addresses grav.userimages grav.saveData grav.saveUrl grav.useUserimage grav.removeImage grav.deleteUserimage grav.test)
+
+  # Default test method for XML-RPC API.
+  RPC_TEST_METHOD = 'grav.test'
+
+  # Reference URI for XML-RPC API.
+  RPC_URI = 'secure.gravatar.com'
+end

data/lib/gravaty/locales/en.yml

@@ -0,0 +1,34 @@
+# gravaty
+# Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+#
+# This file is part of gravaty.
+#
+# gravaty is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+#
+# gravaty is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with gravaty. If not, see
+# <http://www.gnu.org/licenses/>.
+
+en:
+  error:
+    invalid: "Invalid parameter %{value} according to RFC822 at later updates."
+    nil: nil parameter not allowed.
+    param: "Parameter %{value} is not valid."
+    type: "Type %{value} is not a known extension."
+    uri: "URI %{value} is not valid."
+    value: "Value %{value} is not in allowed range."
+  warn:
+    deprecated: This method has been deprecated.
+  test:
+    test: test data
+  gravatar:
+    errors:
+      -7: Use secure.gravatar.com
+      -8: Internal error
+      -9: Authentication error
+      -10: Method parameter missing
+      -11: Method parameter incorrect
+      -100: Misc error (see text)

data/lib/gravaty/locales/it.yml

@@ -0,0 +1,34 @@
+# gravaty
+# Copyright © 2013, 2014, 2015, 2016  Marco Bresciani
+#
+# This file is part of gravaty.
+#
+# gravaty is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+#
+# gravaty is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with gravaty. If not, see
+# <http://www.gnu.org/licenses/>.
+
+it:
+  error:
+    invalid: "Parametro %{value} non valido rispetto a RFC822 e modifiche successive."
+    nil: Parametro nil non consentito.
+    param: "Il parametro %{value} non è valido."
+    type: "Il tipo %{value} non è un'estensione conosciuta."
+    uri: "L'URI %{value} non è valido."
+    value: "Il valore %{value} non è nell'intervallo previsto."
+  warn:
+    deprecated: Questo metodo è obsoleto.
+  test:
+    test: dato di prova
+  gravatar:
+    errors:
+      -7: Utilizzare secure.gravatar.com
+      -8: Errore interno
+      -9: Errore di autenticazione
+      -10: Parametro metodo mancante
+      -11: Parametro metodo non corretto
+      -100: Errore di altro tipo (vedi testo)