base64: RFC 4648-compliant padded and unpadded base64 and base64url encodings

[ bsd3, data, library ] [ Propose Tags ]

RFC 4648-compliant padded and unpadded base64 and base64url encoding and decoding.


[Skip to Readme]
Versions [RSS] [faq] 0.0.1.0, 0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.1.0, 0.3.1.1, 0.4.0, 0.4.1, 0.4.2, 0.4.2.1, 0.4.2.2, 0.4.2.3 (info)
Change log CHANGELOG.md
Dependencies base (>=4.9 && <5), bytestring, deepseq, lens (==4.18.*), text [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
Bug tracker https://github.com/emilypi/base64/issues
Source repo head: git clone https://github.com/emilypi/base64.git
Uploaded by topos at 2020-01-05T03:02:21Z
Distributions LTSHaskell:0.4.2.3, NixOS:0.4.2.3, Stackage:0.4.2.3
Downloads 9584 total (393 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs uploaded by user
Build status unknown [no reports yet]

Modules

[Index] [Quick Jump]

Flags

NameDescriptionDefaultType
optics

Enable optics for base64-encoding text and bytestrings

EnabledManual
perf-flags

Performance tuning flags and information

DisabledManual

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Candidates


Readme for base64-0.0.1.0

[back to package description]

Base64

Build Status

Padded and unpadded base64 and base64url encodings for Text and ByteString values, along with their optics.

Why?

Haskell has two main libraries for Base64: memory, and base64-bytestring.

Of these, memory is geared towards integration with other memory primitives in the library, without much of an eye towards performance, while base64-bytestring is built to exclusively address ByteString encoding and decoding, and is very performant. Many great strides have been made in the realm of Base64 performance and vectorization just in the past 5 years, which this library attempts to capture. Additionally, we attempt to fix percieved shortcomings with both APIs in the support of unpadded Base64 and Base64-url support (which memory provides, but not base64-bytestring), as well as supporting Text values (neither libraries provide), and also supplying some nice compositional optics for composing structures with Base64-encodable/decodable focii (neither libraries provide).

Optics

Structs may want to support encoding and decoding their substructures, which is supported with the following prismatic typeclass:

class AsBase64 s where
    type Base64 s
    -- | A prism into a base64-encoded focus of
    -- some type
    --
    _Base64 :: Prism' s (Base64 s)

    -- | A prism into the base64url-encoded focus of
    -- some type
    --
    _Base64Url :: Prism' s (Base64 s)

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. Monomorphizing for t ~ s and a ~ b, a simple Prism is formed:

>>> _Base64 @Text # "<<???>>"
"PDw/Pz8+Pg=="

>>> "PDw/Pz8+Pg==" ^? _Base64 @Text
Just "<<???>>"

The two most obvious types for which we have an instance are those that are supported natively by the library: ByteString and Text. Trivially, their instances consist of the functions provided here in this library.

Summary

What does this library provide? Here is the summary:

  • Better performance over existing Base64 libraries (2x and 3x for most use-cases - see PERFORMANCE.md)
  • Support for unpadded Base64 and Base64-url
  • Support for Text encodings and decodings
  • Classy optics for handling more complex structures with Base64 representations