-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Use Libravatar, the decentralized avatar delivery service
--
-- This package is a Haskell library for Libravatar.
@package libravatar
@version 0.4
-- | Libravatar is a decentralized avatar delivery system. Instead of
-- relying on a single centralized provider, it can use DNS records to
-- detect the host of the avatar image. There is a server implementation
-- which anyone can run and host their avatars and there are client
-- libraries for many languages, all free-as-in-freedom software.
--
-- This module is a Haskell client library for Libravatar.
--
-- Note that this library doesn't actually fetch the image over HTTP.
-- That part is left to the various HTTP client packages, such as
-- http-client. What this library does is construct the image
-- URL, possibly using DNS queries when needed for the decentralization.
-- You can then fetch the image over HTTP or use the URL in your web
-- app's HTML page templates, in which case the user's web brower will be
-- downloading the image.
--
-- Now let's see how it works.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
-- import Data.Default.Class (def)
-- import Network.Libravatar
--
--
-- Examples:
--
-- Email, HTTP, default fallback image (the libravatar logo), default
-- size (80):
--
--
-- >>> avatarUrl (Email "john@doe.org") def
--
-- >>> { optSecure = False
--
-- >>> , optDefault = ImgLibravatarLogo
--
-- >>> , optSize = DefaultSize
--
-- >>> }
-- Just "http://cdn.libravatar.org/avatar/bc6a715808d9aae0ddeefb1e47e482a6"
--
--
-- Email, HTTPS, default fallback image, size 100. But now use an email
-- with a domain which has SRV records for avatars:
--
--
-- >>> avatarUrl (Email "fr33domlover@rel4tion.org") def
--
-- >>> { optSecure = True
--
-- >>> , optDefault = ImgLibravatarLogo
--
-- >>> , optSize = Size 100
--
-- >>> }
-- Just "https://avatars.rel4tion.org:5679/avatar/e9e9ccabc2a166b1783bd7f4f9ceb376?s=100"
--
--
-- OpenID, HTTPS, specified fallback (special value "retro"), default
-- size (80):
--
--
-- >>> avatarUrl (OpenID "https://examplibre.org/accounts/xyz/id") def
--
-- >>> { optSecure = True
--
-- >>> , optDefault = ImgSpecial SpecialRetro
--
-- >>> , optSize = DefaultSize
--
-- >>> }
-- Just "https://seccdn.libravatar.org/avatar/c2cbc5f5a1784fa7105380e550360d73f15c4c1f9c7ca1ac436c45a33027fcd7?d=retro"
--
--
-- (Note that the 2nd example uses dummy SRV records created by the
-- author, and he isn't really running a Libravatar provider. This is
-- just an example, the specific URL here will probably result with 404.)
module Network.Libravatar
-- | User address for which to generate an avatar URL. Email or OpenID.
data UserAddress
-- | For example john@doe.org
Email :: Text -> UserAddress
-- | For example https://example.org/accounts/john/id
OpenID :: Text -> UserAddress
-- | Special values available for the default image. The comments briefly
-- explain the origin of the image/technique.
data SpecialImage
-- | A very simple outline of a person (constant image, does not vary by
-- user address). Sometimes referred to as “mystery man”.
SpecialMysteryPerson :: SpecialImage
-- | Geometric pattern based on a user address hash.
--
-- Origin: A visual representation of a hash value, usually of an IP
-- address, that serves to identify a user of a computer system as a form
-- of avatar while protecting the users' privacy.
SpecialIdenticon :: SpecialImage
-- | A generated monster image with different colors, faces, etc.
--
-- Origin: A method to generate a unique monster image based upon a
-- certain identifier (IP address, email address, etc.). It can be used
-- to automatically provide personal avatar images in blog comments or
-- other community services.
SpecialMonsterID :: SpecialImage
-- | A generated face with differing features and backgrounds.
--
-- Origin: Wavatars is a Wordpress plugin that will generate and assign
-- icons to the visitors leaving comments at your site. The icons are
-- based on email, so a given visitor will get the same icon each time
-- they comment. It livens up comment threads and gives people memorable
-- “faces” to aid in following conversation threads. It’s also fun.
SpecialWavatar :: SpecialImage
-- | A generated, 8-bit arcade-style pixelated face.
--
-- Origin: I don't know :P
SpecialRetro :: SpecialImage
-- | What to do if the user's address isn't found in the Libravatar
-- server's database.
data DefaultImage
-- | Don't specify a default image, let the server send its default image,
-- which is the Libravatar logo (the orange butterfly).
ImgLibravatarLogo :: DefaultImage
-- | Return HTTP 404 error (i.e. file not found) instead of an image.
ImgNotFound :: DefaultImage
-- | Use one of the available special images or image generators.
ImgSpecial :: SpecialImage -> DefaultImage
-- | Use the given image URL as the default.
ImgCustom :: Text -> DefaultImage
-- | Image size in pixels.
data Size
-- | Use the given size. Acceptable values are between 1 and 512. Note that
-- this library doesn't check the size you pass here, so make sure you
-- pass a size within that range.
Size :: Int -> Size
-- | Use the default size, which is 80 pixels.
DefaultSize :: Size
-- | Avatar details in addition to the user address itself. Define by
-- starting with defOpts and override fields using record
-- syntax.
data AvatarOptions
-- | Whether the avatar URL should be secure (use HTTPS).
optSecure :: AvatarOptions -> Bool
-- | What to do if the user address isn't found in the Libravatar database.
optDefault :: AvatarOptions -> DefaultImage
-- | Image size in pixels.
optSize :: AvatarOptions -> Size
-- | If an image is not found in the Libravatar database, it can first
-- redirect to gravatar in case the image exists there, and only then
-- honour the optDefault parameter. This option sets whether
-- Libravatar should try gravatar or go straight to the optDefault
-- when an image isn't found.
optTryGravatar :: AvatarOptions -> Bool
-- | Return a URL to the avatar image.
--
-- If an error occurs, return Nothing. Currently, this happens
-- only if the user address fails to be parsed.
--
-- See examples at the top of the page.
avatarUrl :: UserAddress -> AvatarOptions -> IO (Maybe Text)
instance Data.Default.Class.Default Network.Libravatar.DefaultImage
instance Data.Default.Class.Default Network.Libravatar.Size
instance Data.Default.Class.Default Network.Libravatar.AvatarOptions