massive doc updates (#29)

* massive doc updates * small mistake
emilypi · Jul 3, 2020 · 3dd41cc · 3dd41cc
1 parent ceaf15c
commit 3dd41cc
Show file tree

Hide file tree

Showing 12 changed files with 855 additions and 38 deletions.
diff --git a/src/Data/ByteString/Base64.hs b/src/Data/ByteString/Base64.hs
@@ -16,10 +16,13 @@
 -- internal and external validation for canonicity.
 --
 module Data.ByteString.Base64
-( encodeBase64
+( -- * Encoding
+  encodeBase64
 , encodeBase64'
+  -- * Decoding
 , decodeBase64
 , decodeBase64Lenient
+  -- * Validation
 , isBase64
 , isValidBase64
 ) where
@@ -40,6 +43,11 @@ import System.IO.Unsafe
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64 "Sun"
+-- "U3Vu"
+--
 encodeBase64 :: ByteString -> Text
 encodeBase64 = T.decodeUtf8 . encodeBase64'
 {-# inline encodeBase64 #-}
@@ -48,6 +56,11 @@ encodeBase64 = T.decodeUtf8 . encodeBase64'
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64' "Sun"
+-- "U3Vu"
+--
 encodeBase64' :: ByteString -> ByteString
 encodeBase64' = encodeBase64_ base64Table
 {-# inline encodeBase64' #-}
@@ -56,6 +69,17 @@ encodeBase64' = encodeBase64_ base64Table
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64 "U3Vu"
+-- Right "Sun"
+--
+-- >>> decodeBase64 "U3V"
+-- Left "Base64-encoded bytestring requires padding"
+--
+-- >>> decodebase64 "U3V="
+-- Left "non-canonical encoding detected at offset: 2"
+--
 decodeBase64 :: ByteString -> Either Text ByteString
 decodeBase64 bs@(PS _ _ !l)
     | l == 0 = Right bs
@@ -74,6 +98,17 @@ decodeBase64 bs@(PS _ _ !l)
 --
 -- __Note:__ This is not RFC 4648-compliant.
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64Lenient "U3Vu"
+-- "Sun"
+--
+-- >>> decodeBase64Lenient "U3V"
+-- "Su"
+--
+-- >>> decodebase64Lenient "U3V="
+-- "Su"
+--
 decodeBase64Lenient :: ByteString -> ByteString
 decodeBase64Lenient = decodeBase64Lenient_ decodeB64Table
 {-# inline decodeBase64Lenient #-}
@@ -84,6 +119,17 @@ decodeBase64Lenient = decodeBase64Lenient_ decodeB64Table
 -- externally valid Base64url-encoded values, but are internally inconsistent "impossible"
 -- values.
 --
+-- === __Examples__:
+--
+-- >>> isBase64 "U3Vu"
+-- True
+--
+-- >>> isBase64 "U3V"
+-- False
+--
+-- >>> isBase64 "U3V="
+-- False
+--
 isBase64 :: ByteString -> Bool
 isBase64 bs = isValidBase64 bs && isRight (decodeBase64 bs)
 {-# inline isBase64 #-}
@@ -94,6 +140,20 @@ isBase64 bs = isValidBase64 bs && isRight (decodeBase64 bs)
 -- only that it conforms to the correct shape. To check whether it is a true
 -- Base64 encoded 'ByteString' value, use 'isBase64'.
 --
+-- === __Examples__:
+--
+-- >>> isValidBase64 "U3Vu"
+-- True
+--
+-- >>> isValidBase64 "U3V"
+-- True
+--
+-- >>> isValidBase64 "U3V="
+-- True
+--
+-- >>> isValidBase64 "%"
+-- False
+--
 isValidBase64 :: ByteString -> Bool
 isValidBase64 = validateBase64 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 {-# inline isValidBase64 #-}
diff --git a/src/Data/ByteString/Base64/URL.hs b/src/Data/ByteString/Base64/URL.hs
@@ -16,14 +16,17 @@
 -- variants, as well as internal and external validation for canonicity.
 --
 module Data.ByteString.Base64.URL
-( encodeBase64
+( -- * Encoding
+  encodeBase64
 , encodeBase64'
-, decodeBase64
 , encodeBase64Unpadded
 , encodeBase64Unpadded'
+  -- * Decoding
+, decodeBase64
 , decodeBase64Unpadded
 , decodeBase64Padded
 , decodeBase64Lenient
+  -- * Validation
 , isBase64Url
 , isValidBase64Url
 ) where
@@ -45,6 +48,11 @@ import System.IO.Unsafe
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-5 RFC-4648 section 5>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64 "<<?>>"
+-- "PDw_Pj4="
+--
 encodeBase64 :: ByteString -> Text
 encodeBase64 = T.decodeUtf8 . encodeBase64'
 {-# INLINE encodeBase64 #-}
@@ -53,6 +61,11 @@ encodeBase64 = T.decodeUtf8 . encodeBase64'
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-5 RFC-4648 section 5>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64' "<<?>>"
+-- "PDw_Pj4="
+--
 encodeBase64' :: ByteString -> ByteString
 encodeBase64' = encodeBase64_ base64UrlTable
 
@@ -64,6 +77,20 @@ encodeBase64' = encodeBase64_ base64UrlTable
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64 "PDw_Pj4="
+-- Right "<<?>>"
+--
+-- >>> decodeBase64 "PDw_Pj4"
+-- Right "<<?>>"
+--
+-- >>> decodeBase64 "PDw-Pg="
+-- Left "Base64-encoded bytestring has invalid padding"
+--
+-- >>> decodeBase64 "PDw-Pg"
+-- Right "<<>>"
+--
 decodeBase64 :: ByteString -> Either Text ByteString
 decodeBase64 bs@(PS _ _ !l)
     | l == 0 = Right bs
@@ -83,6 +110,11 @@ decodeBase64 bs@(PS _ _ !l)
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-3.2 RFC-4648 section 3.2>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64Unpadded "<<?>>"
+-- "PDw_Pj4"
+--
 encodeBase64Unpadded :: ByteString -> Text
 encodeBase64Unpadded = T.decodeUtf8 . encodeBase64Unpadded'
 {-# INLINE encodeBase64Unpadded #-}
@@ -93,6 +125,11 @@ encodeBase64Unpadded = T.decodeUtf8 . encodeBase64Unpadded'
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-3.2 RFC-4648 section 3.2>
 --
+-- === __Examples__:
+--
+-- >>> encodeBase64Unpadded' "<<?>>"
+-- "PDw_Pj4"
+--
 encodeBase64Unpadded' :: ByteString -> ByteString
 encodeBase64Unpadded' = encodeBase64Nopad_ base64UrlTable
 
@@ -105,6 +142,14 @@ encodeBase64Unpadded' = encodeBase64Nopad_ base64UrlTable
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64Unpadded "PDw_Pj4"
+-- Right "<<?>>"
+--
+-- >>> decodeBase64Unpadded "PDw_Pj4="
+-- Left "Base64-encoded bytestring has invalid padding"
+--
 decodeBase64Unpadded :: ByteString -> Either Text ByteString
 decodeBase64Unpadded bs@(PS _ _ !l)
     | l == 0 = Right bs
@@ -127,6 +172,14 @@ decodeBase64Unpadded bs@(PS _ _ !l)
 --
 -- See: <https://tools.ietf.org/html/rfc4648#section-4 RFC-4648 section 4>
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64Padded "PDw_Pj4="
+-- Right "<<?>>"
+--
+-- >>> decodeBase64Padded "PDw_Pj4"
+-- Left "Base64-encoded bytestring requires padding"
+--
 decodeBase64Padded :: ByteString -> Either Text ByteString
 decodeBase64Padded bs@(PS _ _ !l)
     | l == 0 = Right bs
@@ -145,6 +198,14 @@ decodeBase64Padded bs@(PS _ _ !l)
 --
 -- __Note:__ This is not RFC 4648-compliant.
 --
+-- === __Examples__:
+--
+-- >>> decodeBase64Lenient "PDw_Pj4="
+-- "<<?>>"
+--
+-- >>> decodeBase64Lenient "PDw_%%%$}Pj4"
+-- "<<?>>"
+--
 decodeBase64Lenient :: ByteString -> ByteString
 decodeBase64Lenient = decodeBase64Lenient_ decodeB64UrlTable
 {-# INLINE decodeBase64Lenient #-}
@@ -155,6 +216,17 @@ decodeBase64Lenient = decodeBase64Lenient_ decodeB64UrlTable
 -- externally valid Base64url-encoded values, but are internally inconsistent "impossible"
 -- values.
 --
+-- === __Examples__:
+--
+-- >>> isBase64Url "PDw_Pj4="
+-- True
+--
+-- >>> isBase64Url "PDw_Pj4"
+-- True
+--
+-- >>> isBase64Url "PDw_Pj"
+-- False
+--
 isBase64Url :: ByteString -> Bool
 isBase64Url bs = isValidBase64Url bs && isRight (decodeBase64 bs)
 {-# INLINE isBase64Url #-}
@@ -165,6 +237,17 @@ isBase64Url bs = isValidBase64Url bs && isRight (decodeBase64 bs)
 -- only that it conforms to the correct shape. To check whether it is a true
 -- Base64 encoded 'ByteString' value, use 'isBase64Url'.
 --
+-- === __Examples__:
+--
+-- >>> isValidBase64Url "PDw_Pj4="
+-- True
+--
+-- >>> isValidBase64Url "PDw_Pj"
+-- True
+--
+-- >>> isValidBase64Url "%"
+-- False
+--
 isValidBase64Url :: ByteString -> Bool
 isValidBase64Url = validateBase64Url "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
 {-# INLINE isValidBase64Url #-}