BSD-3-Clause licensed by Emily Pillmore
Maintained by [email protected]
This version can be pinned in stack with:base64-lens-0.3.0@sha256:f57483b5f1b4974c8b90f03a45f67c766d65c6de97d86bacd48a859209633b76,1715

Module documentation for 0.3.0

Base64-lens

Build Status Hackage

This package provides optics and convenient pattern synonyms for the base64 library.

Patterns

The pattern synonyms provided in this library are:

pattern Base64 :: ByteString -> ByteString
pattern Base64Url :: ByteString -> ByteString
pattern Base64UrlUnpadded :: ByteString -> ByteString
pattern Base64Lenient :: ByteString -> ByteString
pattern Base64UrlLenient :: ByteString -> ByteString

-- and 

pattern Base64 :: Text -> Text
pattern Base64Url :: Text -> Text
pattern Base64UrlUnpadded :: Text -> Text
pattern Base64Lenient :: Text -> Text
pattern Base64UrlLenient :: Text -> Text

These provide a convenient high level interface for passing Base64 encoded values.

Optics

Prisms for encoding and decoding Text and ByteString values are given as part of the library:

_Base64 :: Prism' ByteString ByteString
_Base64Url :: Prism' ByteString ByteString
_Base64UrlUnpadded :: Prism' ByteString ByteString
_Base64Lenient :: Iso' ByteString ByteString
_Base64UrlLenient :: Iso' ByteString ByteString

-- and

_Base64 :: Prism' Text Text
_Base64Url :: Prism' Text Text
_Base64UrlUnpadded :: Prism' Text Text
_Base64Lenient :: Iso' Text Text
_Base64UrlLenient :: Iso' Text Text

If a particular structure has a Lens into some Text or ByteString value they might want to encode (or decode), then composing such a Lens with these Prisms yields an affine Traversal, resulting in a structure which has the focus of its Lens encoded as or decoded from Base64(-url). All one needs to do is compose their optics:


data MyStruct = MyStruct
  { _a :: Int
  , _b :: Text
  } deriving Show

b :: Lens' MyStruct Text
b = lens _b (\t b_ -> t { _b = b_ })

myB64Struct :: Traversal' s Text
myB64Struct = b . _Base64

-- >>> MyStruct 3 "U3Vu" ^? b . _Base64
-- MyStruct {_a = 3, _b = "Sun"}

bRe :: Review MyStruct Text
bRe = unto (\b -> MyStruct 0 b)

-- >>> bRe . _Base64 # "Sun"
-- MyStruct {_a = 0, _b = "UV3u"}

The data of a Prism naturally conforms to this “encoding/decoding” dichotomy, where the Review, or “builder” half of the Prism of type b -> t is an encoding, and the “Matcher” half of the prism, of type s -> Either t a, represents a decoding of a similar structure. Hence, Prism is the most appropriate structure.

Changes

Revision history for base64-lens

0.3

  • Instead of focusing on the Base64Lenient Iso as a Lens (which swaps its focus compared to its sibling Prisms), change it to be symmetrical with the other Prisms so that it can be used as a generalized Prism.

0.2

  • Bump base64 dependency to settle on 0.4 with the “finalized” api.
  • Remove _Base64Unpadded prism and Base64Unpadded patterns from ByteString and Text
  • Kill all CPP

0.1.0.0

  • First version. Released on an unsuspecting world.