diff --git a/NEWS b/NEWS --- a/NEWS +++ b/NEWS @@ -3,6 +3,29 @@ +libravatar 0.2.0.0 -- 2015-12-08 +================================ + +General, build and documentation changes: + +* Add some background details to the docs + +New APIs, features and enhancements: + +* Provide dedicated datatypes and more type safety + +Bug fixes: + +* (none) + +Dependency changes: + +* (none) + + + + + libravatar 0.1.0.2 -- 2015-12-03 ================================ diff --git a/libravatar.cabal b/libravatar.cabal --- a/libravatar.cabal +++ b/libravatar.cabal @@ -1,5 +1,5 @@ name: libravatar -version: 0.1.0.2 +version: 0.2.0.0 synopsis: Use Libravatar, the decentralized avatar delivery service description: This package is a Haskell library for . @@ -17,7 +17,7 @@ source-repository head type: darcs - location: http://darcs.rel4tion.org/repos/libravatar/ + location: http://hub.darcs.net/fr33domlover/libravatar library exposed-modules: Network.Libravatar diff --git a/src/Network/Libravatar.hs b/src/Network/Libravatar.hs --- a/src/Network/Libravatar.hs +++ b/src/Network/Libravatar.hs @@ -14,7 +14,12 @@ -} module Network.Libravatar - ( avatarUrl + ( UserAddress (..) + , SpecialImage (..) + , DefaultImage (..) + , Size (..) + , AvatarOptions (..) + , avatarUrl ) where @@ -42,6 +47,76 @@ minAvatarSize = 1 maxAvatarSize = 512 +-- | User address for which to generate an avatar URL. Email or OpenID. +data UserAddress + = Email String -- ^ For example @john\@doe.org@ + | OpenID String -- ^ For example @https://example.org/accounts/john/id@ + +-- | 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 + -- | 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 + -- | 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 + -- | 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 + -- | A generated, 8-bit arcade-style pixelated face. + -- + -- Origin: I don't know :P + | SpecialRetro + +-- | 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 + -- | Return HTTP 404 error (i.e. file not found) instead of an image. + | ImgNotFound + -- | Use one of the available special images or image generators. + | ImgSpecial SpecialImage + -- | Use the given image URL as the default. + | ImgCustom String + +-- | 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 + -- | Use the default size, which is 80 pixels. + | DefaultSize + +-- | Avatar details in addition to the user address itself. +data AvatarOptions = AvatarOptions + { -- | Whether the avatar URL should be secure (use HTTPS). + optSecure :: Bool + -- | What to do if the user address isn't found in the Libravatar + -- database. + , optDefault :: DefaultImage + -- | Image size in pixels. + , optSize :: Size + } + -- Hash emails with MD5, I think it's faster than SHA256 hashMail :: String -> String hashMail = @@ -54,14 +129,14 @@ hashOpenid = show . sha256 . BLU.fromString -- From email or openid, generate avatar hash and get the relevant domain -parseUserAddress :: Either String String -> Maybe (String, String) -parseUserAddress (Left email) = +parseUserAddress :: UserAddress -> Maybe (String, String) +parseUserAddress (Email email) = let lowEmail = map toLower email d = dropWhile (/= '@') lowEmail domain = if null d then d else tail d hash = hashMail lowEmail in Just (hash, domain) -parseUserAddress (Right openid) = do +parseUserAddress (OpenID openid) = do uri <- parseAbsoluteURI openid auth <- uriAuthority uri let lower = map toLower @@ -72,12 +147,32 @@ } return (hashOpenid $ uriToString id openidl "", uriRegName authl) +-- Convert 'Size' to 'Maybe' for use with 'Maybe' functor +sizeToMaybe :: Size -> Maybe Int +sizeToMaybe (Size n) = Just n +sizeToMaybe DefaultSize = Nothing + +-- Get name string for special image +showSpecial :: SpecialImage -> String +showSpecial SpecialMysteryPerson = "mm" +showSpecial SpecialIdenticon = "identicon" +showSpecial SpecialMonsterID = "monsterid" +showSpecial SpecialWavatar = "wavatar" +showSpecial SpecialRetro = "retro" + +-- Get name string for default image +showDefault :: DefaultImage -> Maybe String +showDefault ImgLibravatarLogo = Nothing +showDefault ImgNotFound = Just "404" +showDefault (ImgSpecial img) = Just $ showSpecial img +showDefault (ImgCustom url) = Just url + -- Determine URL query parameters -buildParams :: Maybe String -> Maybe Int -> [(String, String)] +buildParams :: DefaultImage -> Size -> [(String, String)] buildParams def size = - let defParam = liftM ((,) "d") def - size' = liftM (max minAvatarSize . min maxAvatarSize) size - sizeParam = liftM ((,) "s" . show) size' + let defParam = fmap ((,) "d") $ showDefault def + size' = fmap (max minAvatarSize . min maxAvatarSize) $ sizeToMaybe size + sizeParam = fmap ((,) "s" . show) size' in catMaybes [defParam, sizeParam] -- Get the DNS service to query for a given domain and scheme @@ -170,49 +265,48 @@ -- | Return a URL to the avatar image. -- -- If an error occurs, return 'Nothing'. Currently, this happens only if the --- user address (first parameter) fails to be parsed. +-- user address fails to be parsed. -- -- Examples: -- -- Email, HTTP, default fallback image (the libravatar logo), -- default size (80): -- --- >>> avatarUrl (Left "john@doe.org") False Nothing Nothing +-- >>> avatarUrl (Email "john@doe.org") AvatarOptions +-- >>> { 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 (Left "fr33domlover@rel4tion.org") True Nothing (Just 100) +-- >>> avatarUrl (Email "fr33domlover@rel4tion.org") AvatarOptions +-- >>> { 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 (Right "https://examplibre.org/accounts/xyz/id") True (Just "retro") Nothing +-- >>> avatarUrl (OpenID "https://examplibre.org/accounts/xyz/id") AvatarOptions +-- >>> { 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 doesn't really run (at the time of writing) a Libravatar provider. --- This is just an example, the specific URL here will probably result with --- 404.) -avatarUrl - :: Either String String - -- ^ User address. Email or OpenID. - -> Bool - -- ^ Whether the generated URL should be secure (use HTTPS). - -> Maybe String - -- ^ Default image URL if the user address isn't found in the Libravatar - -- server's database. If you pass 'Nothing', the default image will be the - -- Libravatar logo. A few special values are available, such as @404@ - -- (return HTTP 404 error instead of an image) and @retro@ (one of the - -- several available simple default images). - -> Maybe Int - -- ^ Image size in pixels, default is 80. - -> IO (Maybe String) -avatarUrl address https def size = +-- 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) +avatarUrl address options = let (hash, domain) = fromMaybe ("", "") $ parseUserAddress address - params = buildParams def size + params = buildParams (optDefault options) (optSize options) + https = optSecure options in if null domain then return Nothing else do