gravatar

README

gravatar

gravatar is a library to ease access to Gravatar API. It implements a functionality to get avatars and decode JSON profiles.

Documentation.

Documentation

Overview

Package gravatar implements a functionality to get avatars and decode JSON profiles from Gravatar (http://gravatar.com).

Index

• Constants
• func EmailHash(email string) string
• func GetAvatar(scheme, emailHash string, opts ...interface{}) (data []byte, err error)
• func GetAvatarURL(scheme, emailHash string, opts ...interface{}) *url.URL
• func SetAvatarURLOptions(u *url.URL, opts ...interface{}) *url.URL
• type GravatarProfile
  • func GetProfile(scheme, emailHash string) (g GravatarProfile, err error)

Examples

• GetAvatar
• GetAvatarURL
• GetProfile
• SetAvatarURLOptions

Constants

const (
	// DefaultBlank defaults to a transparent PNG image.
	DefaultBlank = "blank"

	// DefaultError defaults to an error.
	DefaultError = "404"

	// DefaultIdentIcon defaults to a generated geometric pattern.
	DefaultIdentIcon = "identicon"

	// DefaultMonster defaults to a generated 'monster' with different colors
	// and faces.
	DefaultMonster = "monsterid"

	// DefaultMysteryMan defaults to a simple, cartoon-style silhouetted outline
	// of a person.
	DefaultMysteryMan = "mm"

	// DefaultRetro defaults to a generated 8-bit arcade-style pixelated faces.
	DefaultRetro = "retro"

	// DefaultWavatar defaults to a generated faces with differing features and
	// backgrounds.
	DefaultWavatar = "wavatar"
)

List of (optional) values for a "default action" option for GetAvatar. Each option defines what GetAvatar has to do in case of non-existing user.

const (
	// RatingG is suitable for display on all websites with any audience type.
	RatingG = rating("g")

	// RatingPG may contain rude gestures, provocatively dressed individuals, the
	// lesser swear words, or mild violence.
	RatingPG = rating("pg")

	// RatingR may contain such things as harsh profanity, intense violence,
	// nudity, or hard drug use.
	RatingR = rating("r")

	// RatingX may contain hardcore sexual imagery or extremely disturbing
	// violence.
	RatingX = rating("x")
)

List of (optional) values to specify allowed rating (up to and including that). If the requested email doesn't have any image of allowed level, a default image will be used.

Functions

func EmailHash

func EmailHash(email string) string

EmailHash converts an email to lowercase and returns its MD5 hash as hex string.

func GetAvatar

func GetAvatar(scheme, emailHash string, opts ...interface{}) (data []byte, err error)

GetAvatar does a HTTP(S) request and returns an avatar image.

Optional arguments include Default* (default actions), image size and Rating* (rating level, default is RatingG).

Instead of Default* predefined constants you may also use a direct URL to an image.

Example

package main

import (
	"bytes"
	"fmt"

	gr "git.sr.ht/~ft/gravatar"
	"image"

	_ "image/png"
)

func main() {
	// get avatar image (128x128) using HTTP transport
	emailHash := gr.EmailHash("ftrvxmtrx@gmail.com")
	raw, err := gr.GetAvatar("http", emailHash, 128)

	// get avatar image (32x32) using HTTP transport
	// allow images of any rating level
	raw, err = gr.GetAvatar("http", emailHash, gr.RatingX, 32)

	// get avatar image (default size, png format) with fallback to "retro"
	// generated avatar.
	// use HTTPS transport
	emailHash = "cfcd208495d565ef66e7dff9f98764da.png"
	raw, err = gr.GetAvatar("https", emailHash, gr.DefaultRetro)

	if err == nil {
		var cfg image.Config
		var format string

		rawb := bytes.NewReader(raw)
		cfg, format, err = image.DecodeConfig(rawb)
		fmt.Println(cfg, format)
	}
}

func GetAvatarURL

func GetAvatarURL(scheme, emailHash string, opts ...interface{}) *url.URL

GetAvatarURL returns an URL to avatar image.

Optional arguments include Default* (default actions), image size and Rating* (rating level, default is RatingG).

Instead of Default* predefined constants you may also use a direct URL to an image.

Example

package main

import (
	"fmt"

	gr "git.sr.ht/~ft/gravatar"

	_ "image/png"
)

func main() {
	// get URL to avatar image of size 256x256
	// fall back to "monster" generated avatar
	emailHash := gr.EmailHash("ftrvxmtrx@gmail.com")
	url := gr.GetAvatarURL("https", emailHash, gr.DefaultMonster, 256)
	fmt.Println(url.String())
}

func SetAvatarURLOptions

func SetAvatarURLOptions(u *url.URL, opts ...interface{}) *url.URL

SetAvatarURLOptions sets options for an URL to avatar image.

Options include Default* (default actions), image size and Rating* (rating level, default is RatingG).

Instead of Default* predefined constants you may also use a direct URL to an image.

Calling SetAvatarURLOptions(url), e.g. without any options, resets the options.

Example

package main

import (
	"fmt"

	gr "git.sr.ht/~ft/gravatar"

	_ "image/png"
)

func main() {
	// get URL to avatar image of default size
	emailHash := gr.EmailHash("ftrvxmtrx@gmail.com")
	url := gr.GetAvatarURL("https", emailHash)
	fmt.Printf("default URL: %s", url.String())
	// set size to 256x256
	// fall back to "monster" generated avatar
	gr.SetAvatarURLOptions(url, gr.DefaultMonster, 256)
	fmt.Printf("modified URL: %s", url.String())
	// reset back to the default one
	gr.SetAvatarURLOptions(url)
	fmt.Printf("URL after reset: %s", url.String())
}

Types

type GravatarProfile

type GravatarProfile struct {
	AboutMe string

	Accounts []struct {
		ShortName string
		Domain    string
		Url       string
		Verified  bool `json:",string"`
		Username  string
		Display   string
	}

	CurrentLocation string

	DisplayName string

	Emails []struct {
		Primary bool `json:",string"`
		Value   string
	}

	Hash string

	Id int `json:",string"`

	Ims []struct {
		Type  string
		Value string
	}

	Name struct {
		Family    string
		Formatted string
		Given     string
	}

	PhoneNumbers []struct {
		Type  string
		Value string
	}

	Photos []struct {
		Type  string
		Value string
	}

	PreferredUsername string

	ProfileBackground struct {
		Color    string
		Position string
		Repeat   string
		Url      string
	}

	ProfileUrl string

	ThumbnailUrl string

	Urls []struct {
		Title string
		Value string
	}
}

GravatarProfile stores profile information associated with an email.

func GetProfile

func GetProfile(scheme, emailHash string) (g GravatarProfile, err error)

GetProfile does a HTTP(S) request and returns gravatar profile.

Example

package main

import (
	"fmt"

	gr "git.sr.ht/~ft/gravatar"

	_ "image/png"
)

func main() {
	// get profile using HTTPS transport
	emailHash := gr.EmailHash("ftrvxmtrx@gmail.com")
	profile, err := gr.GetProfile("https", emailHash)

	if err == nil {
		fmt.Println(profile.PreferredUsername)
		fmt.Println(profile.ProfileUrl)
	}
}