-- 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 <a>Libravatar</a>.
@package libravatar
@version 0.3.0.0

module Network.Libravatar

-- | User address for which to generate an avatar URL. Email or OpenID.
data UserAddress

-- | For example <tt>john@doe.org</tt>
Email :: String -> UserAddress

-- | For example <tt><a>https://example.org/accounts/john/id</a></tt>
OpenID :: String -> 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 :: String -> 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 <a>defOpts</a> and override fields using record syntax.
data AvatarOptions

-- | A default <a>AvatarOptions</a> value in which you can override fields.
--   It is simply a convenience wrapper of <a>def</a>, i.e. this is the
--   same as using the <a>Default</a> instance.
defOpts :: 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 <a>optDefault</a> parameter. This option sets whether
--   Libravatar should try gravatar or go straight to the <a>optDefault</a>
--   when an image isn't found.
optTryGravatar :: AvatarOptions -> Bool

-- | Return a URL to the avatar image.
--   
--   If an error occurs, return <a>Nothing</a>. Currently, this happens
--   only if the user address fails to be parsed.
--   
--   Examples:
--   
--   Email, HTTP, default fallback image (the libravatar logo), default
--   size (80):
--   
--   <pre>
--   &gt;&gt;&gt; avatarUrl (Email "john@doe.org") defOpts
--   
--   &gt;&gt;&gt; { optSecure  = False
--   
--   &gt;&gt;&gt; , optDefault = ImgLibravatarLogo
--   
--   &gt;&gt;&gt; , optSize    = DefaultSize
--   
--   &gt;&gt;&gt; }
--   Just "http://cdn.libravatar.org/avatar/bc6a715808d9aae0ddeefb1e47e482a6"
--   </pre>
--   
--   Email, HTTPS, default fallback image, size 100. But now use an email
--   with a domain which has SRV records for avatars:
--   
--   <pre>
--   &gt;&gt;&gt; avatarUrl (Email "fr33domlover@rel4tion.org") defOpts
--   
--   &gt;&gt;&gt; { optSecure  = True
--   
--   &gt;&gt;&gt; , optDefault = ImgLibravatarLogo
--   
--   &gt;&gt;&gt; , optSize    = Size 100
--   
--   &gt;&gt;&gt; }
--   Just "https://avatars.rel4tion.org:5679/avatar/e9e9ccabc2a166b1783bd7f4f9ceb376?s=100"
--   </pre>
--   
--   OpenID, HTTPS, specified fallback (special value "retro"), default
--   size (80):
--   
--   <pre>
--   &gt;&gt;&gt; avatarUrl (OpenID "https://examplibre.org/accounts/xyz/id") defOpts
--   
--   &gt;&gt;&gt; { optSecure  = True
--   
--   &gt;&gt;&gt; , optDefault = ImgSpecial SpecialRetro
--   
--   &gt;&gt;&gt; , optSize    = DefaultSize
--   
--   &gt;&gt;&gt; }
--   Just "https://seccdn.libravatar.org/avatar/c2cbc5f5a1784fa7105380e550360d73f15c4c1f9c7ca1ac436c45a33027fcd7?d=retro"
--   </pre>
--   
--   (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.)
avatarUrl :: UserAddress -> AvatarOptions -> IO (Maybe String)
instance Data.Default.Class.Default Network.Libravatar.DefaultImage
instance Data.Default.Class.Default Network.Libravatar.Size
instance Data.Default.Class.Default Network.Libravatar.AvatarOptions