base64-lens: Optics for the Base64 library

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Prisms and pattern synonyms for the Base64 library

[Skip to Readme]

Properties

Versions	0.1.0.0, 0.1.0.1, 0.1.0.3, 0.2.0, 0.2.0, 0.3.0, 0.3.1
Change log	CHANGELOG.md
Dependencies	base (>=4.10 && <5), base64 (>=0.4 && <0.5), bytestring (>=0.10 && <0.11), lens (>=4.0 && <4.19), text (>=1.2 && <1.3) [details]
License	BSD-3-Clause
Copyright	(c) 2019 Emily Pillmore
Author	Emily Pillmore
Maintainer	emilypi@cohomolo.gy
Category	Data
Home page	https://github.com/emilypi/base64-lens
Bug tracker	https://github.com/emilypi/base64-lens/issues
Source repo	head: git clone https://github.com/emilypi/base64.git
Uploaded	by topos at 2020-01-29T21:22:44Z

Modules

[Index] [Quick Jump]

Data
- ByteString
  - Base64
    - Data.ByteString.Base64.Lens
- Text
  - Encoding
    - Base64
      - Data.Text.Encoding.Base64.Lens

Downloads

base64-lens-0.2.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

topos

For package maintainers and hackage trustees

edit package information

Readme for base64-lens-0.2.0

[back to package description]

Base64-lens

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

-- and

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

-- additionally if using >=base64-0.3

pattern Base64Lenient :: ByteString -> ByteString
pattern Base64UrlLenient :: ByteString -> ByteString

-- and

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

-- and

_Base64 :: Prism' Text Text
_Base64Url :: Prism' Text Text
_Base64UrlUnpadded :: Prism' Text Text

-- additionally if using >=base64-0.3

_Base64Lenient :: Iso' ByteString ByteString
_Base64UrlLenient :: Iso' ByteString ByteString

-- and

_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.