gravaty

Gravaty

This gem automagically prepares complete URIs for Gravatar, for both avatars and profiles, with all currently supported options, included the XML-RPC API, as of 2019-04-23, starting from a single email address!

It's my first Ruby gem, hoping it will be useful for someone (let me know if you use it, please!). GNU GPLv3 license; source code available through anonymous checkout: hg clone http://hg.savannah.nongnu.org/hgweb/gravaty/ or write me, and I'll send it. You can even decide to contribute to this little free software project by registering to Savannah and ask to be part of the gravaty project!

Table of Contents

• Background
• Install
  • Savannah
  • RubyGems
• Usage
• Maintainers
• Thanks
• Contributing
• License

Background

This gem automagically prepares complete URIs for Gravatar, for both avatars and profiles, with all currently supported options, included the XML-RPC API, as of 2019-04-23, starting from a single email address!

It's my first Ruby gem, hoping it will be useful for someone (let me know if you use it, please!).

GNU GPLv3 license; source code available through anonymous checkout: hg clone http://hg.savannah.nongnu.org/hgweb/gravaty/ or write me, and I'll send it.

You can even decide to contribute to this little free software project by registering to Savannah and ask to be part of the gravaty project!

With great contributions from: 新部裕, Peter R. Marreck, Jon Maken, Łukasz Niemier.

Install

RubyGems is the preferred easy install method for Gravaty. Gravaty should be installed via the RubyGems system. To get the latest version, simply enter the following into your command prompt: gem install gravaty.

Because Gravaty is pure Ruby, it should run pretty much anywhere, including Rubinius, JRuby, MacRuby, etc. Officially the support is for >= 2.7 YARV/KRI.

Savannah

• Project page: https://savannah.nongnu.org/projects/gravaty/
• Source code (Mercurial) repository: http://hg.savannah.gnu.org/hgweb/gravaty/
• Known Bugs: https://savannah.nongnu.org/bugs/?group=gravaty
• Users Mailing List: https://savannah.nongnu.org/mail/?group=gravaty
• News: https://savannah.nongnu.org/news/?group=gravaty

RubyGems

• Gem page: https://rubygems.org/gems/gravaty
• Online RDoc: http://rubydoc.info/gems/gravaty/
• Gem updates Atom Feed: https://rubygems.org/gems/gravaty/versions.atom

Usage

See examples folder. To run the examples just run ruby {EXAMPLE_NAME}.rb.

NOTE: for both examples and tests, you need to set a SSL certificate file. In Microsoft Windows environment, the easiest way is the one described by the downloader gist I'm using: you can download valid certificates from http://curl.haxx.se/ca/cacert.pem and put the downloaded file in the gravaty home directory. Then set SSL_CERT_FILE={FULL FILE PATH HERE}cacert.pem and finally run ruby avatar.rb or ruby profiles.rb from the examples directory; both examples should download two files each! The same environment variable would be needed to run the tests against the XML-RPC API. Running the examples you'll see both the example description and correct code usage to perform such action.

Using this API is pretty simple. First, remember that this API maintains a context, so you can save your preferred configuration of server, dictionary, output formats, ... by assigning those value to your object. Get a reference to the Gravaty object, through its factory method, with my_gravaty = Gravaty::gravatize [e-mail] using your email address as parameter. This will save a Gravaty instance in your my_gravaty object. At this point the object does contain a default configuration in terms of avatar, profile, ...

You can take a look at the current status/configuration of your my_gravaty object using the email method my_gravaty.email that shows the email currently in use, or using the digest method my_gravaty.digest that shows the MD5 digest of the downcased email address in use. Also, to_s method is also available to print the current status of the my_gravaty object and each Gravaty is a Comparable object, based on my_gravaty.email data, your email address in small capital letters.

The avatar method provides the configuration-specific URI for your avatar: my_gravaty.avatar returns https://secure.avatar.com/avatar/HASH (where HASH is your my_gravaty.digest email address MD5 digest) ● The method allows an Hash, with avatar configuration parameters: type, pixel_size, force, secure, rating, default. (see https://en.gravatar.com/site/implement/images/ for details) ● The avatar! method saves the provided configuration for your Gravaty object's to_s output.

The profile content feature ● With your Gravaty object available, the profile method provides the configuration-specific URI for your ( registered) user: – a_gravaty.profile returns https://secure.avatar.com/HASH (where HASH is your a_gravaty.digest email address MD5 digest) ● The method allows an Hash, with profile configuration parameters: format, secure. (see https://en.gravatar.com/site/implement/profiles/ for details) ● The profile! method saves the provided configuration for your Gravaty object's to_s output.

The XML-RPC API content feature ● With your Gravaty object available, the xmlrpc method provides a reference to the remote Gravatar XML-RPC AP, for your (registered) user: – a_gravaty.xmlrpc requires the method name (grav.test, by default), your password and possible method parameters (whether needed) via a Hash. ● In order to increase security, the password is not saved inside the Gravaty object but has to be provided for each call; (see https://en.gravatar.com/site/implement/xmlrpc/ for details) ● Communication happens through SSL: certificate might be required (see gravaty README.md file).

Additional features (1/2) ● Since QRCode and JSON are becoming popular formats, qr and json methods (together with qr! and json!) allows to directly retrieve the user's profile data URI, in QRCode or JSON format, with format-specific parameters. Examples: – a_gravaty.qr pixel_size: 42 – a_gravaty.json! callback: 'my_method' ● The qr! and json! methods save the provided configuration for your Gravaty object's to_s output. ● a_gravaty.qr corresponds to a_gravaty.profile format: 'qr' while a_gravaty.json corresponds to a_gravaty.profile format: ' json' and they both filtered the allowed parameters according to the output type.

Additional features (2/2) ● When using the 'banged' (!) methods (avatar! or profile!, same for qr! and json!), the built URI is saved inside the Gravaty object and is read-only available through to_s. ● The download method, simply specifying a filename as parameter, retrieves whatever resource is indicate by such internal status and saves its content in the specified file. Example: – a_gravaty.qr! – a_gravaty.download 'myQr.png' ● The reset method clears the internal status restoring the email address output of to_s.

Maintainers

• Marco Bresciani

Thanks

• Contributor*: Jim Breen

• Author: Peter R. Marreck, RFC 5322 Email Validation Regex in Ruby Regular Expressions. About RFC 5322 Email Validation Regex in Ruby Regular Expressions, please note that "This work is released under the BSD 3-Clause License". This license is GNU GPLv3 compatible according to http://www.gnu.org/licenses/license-list.en.html#ModifiedBSD.

• Author: Jon Maken, An HTTP/HTTPS/FTP file downloader library/CLI based upon MiniPortile's HTTP implementation.. About An HTTP/HTTPS/FTP file downloader library/CLI based upon MiniPortile's HTTP implementation, please note that "License: 3-clause BSD". This license is GNU GPLv3 compatible according to http://www.gnu.org/licenses/license-list.en.html#ModifiedBSD.

FSIJ理事会の理事長、新部裕さんの日本語の翻訳。 Japanese translation by Yutaka Niibe, President of Free Software Initiative of Japan.

Thanks to Marc Heiligers for the note about Peter R. Marreck's gist.

Thanks to Łukasz Niemier for his suggestions on possible improvements.

Contributing

Gravaty tries to follow semantic versioning (see http://semver.org/). There may be backward incompatible changes each time minor version number changes, but that any tiny version number change should be bug fixes and internal changes only. Be sure to read the CHANGELOG each time we cut a new release and lock your gems accordingly.

RDoc documentation available in the html folder.

The easiest way to get help with Gravaty is to post a message to the mailing list: http://lists.nongnu.org/mailman/listinfo/gravaty-users.

Feel free to post any question there, developers are responsive and will be happy to help you figure out how to use Gravaty, or help you determine whether it's the right tool for the task you are working on.

Please make your posts to the list as specific as possible, including code samples and output where relevant. Do not post any information that should not be shared publicly, and be sure to reduce your example code as much as possible so that those who are responding to your question can more easily see what the issue might be.

If you've found a bug, want to submit a patch, or have a feature request, please enter a ticket into our bug tracker: https://savannah.nongnu.org/bugs/?func=additem&group=gravaty.

We strongly encourage adding bug reports with failing tests or at least a reduced example that demonstrates the problem.

Similarly, patches should include tests, API documentation, and an update to the manual where relevant. Feel free to clone early though and participate in the project, if you just want some feedback, or a code review before preparing your code to be merged.

If you are unsure about whether you've found a bug, or want to check to see whether we'd be interested in the feature you want to add before you start working on it, feel free to post to our mailing list.

License

SPDX-FileCopyrightText: 2013 Marco Bresciani

SPDX-License-Identifier: GFDL-1.3-or-later

Copyright © 2013-2021 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/.