base64-1.0: A modern Base64 library

Copyright | (c) 2019-2023 Emily Pillmore
License | BSD-style
Maintainer | Emily Pillmore <emilypi@cohomolo.gy>, sofia-m-a <https://github.com/sofia-m-a>
Stability | stable
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Data.Base64.Types

Description

This module contains the `Base64` type definition, `Alphabet` datatype, alphabet constraints, and various quality of life combinators for working with `Base64`-wrapped data.

Synopsis

- data Alphabet
  - = StdPadded
  - | UrlPadded
  - | UrlUnpadded
  - | NonStandard
- data Base64 (k :: Alphabet) a
- assertBase64 :: forall (k :: Alphabet) a. a -> Base64 k a
- extractBase64 :: forall (k :: Alphabet) a. Base64 k a -> a
- coerceBase64 :: forall (j :: Alphabet) (k :: Alphabet) a. Base64 k a -> Base64 j a
- type family UrlAlphabet (k :: Alphabet) where ...
- type family StdAlphabet (k :: Alphabet) where ...
- type family NonStandardAlphabet (k :: Alphabet) where ...

# Documentation

data Alphabet #

The different kinds of supported Base64 encodings

Constructors

StdPadded | Standard base64 according to RFC 4648 §4 Padding is always inserted when encoding, and required when decoding
UrlPadded | Standard base64 according to RFC 4648 §4 Padding is never inserted when encoding, and optional when decoding per RFC 7049.
UrlUnpadded | URL-safe base64 according to RFC 4648 §5 aka base64url Padding is never inserted when encoding, and optional when decoding
NonStandard | Any non-standard, non RFC 4648-compliant base64 encoding. Can only be decoded using lenient decoders.

data Base64 (k :: Alphabet) a #

Wraps a value, asserting that it is or is intended to be in a particular kind of Base64 encoding use `extractBase64` to extract the value, and `assertBase64` to tag a value as base64-encoded

#### Instances

Instances details

Applicative (Base64 k) # |
Instance details Defined in Data.Base64.Types.Internal Methods pure :: a -> Base64 k a # (<*>) :: Base64 k (a -> b) -> Base64 k a -> Base64 k b # liftA2 :: (a -> b -> c) -> Base64 k a -> Base64 k b -> Base64 k c # (*>) :: Base64 k a -> Base64 k b -> Base64 k b # (<*) :: Base64 k a -> Base64 k b -> Base64 k a #
Functor (Base64 k) # |
Instance details Defined in Data.Base64.Types.Internal Methods fmap :: (a -> b) -> Base64 k a -> Base64 k b # (<$) :: a -> Base64 k b -> Base64 k a #
Monad (Base64 k) # |
Instance details Defined in Data.Base64.Types.Internal Methods (>>=) :: Base64 k a -> (a -> Base64 k b) -> Base64 k b # (>>) :: Base64 k a -> Base64 k b -> Base64 k b # return :: a -> Base64 k a #
NFData a => NFData (Base64 k a) # |
Instance details Defined in Data.Base64.Types.Internal Methods rnf :: Base64 k a -> () #
Show a => Show (Base64 k a) # |
Instance details Defined in Data.Base64.Types.Internal Methods showsPrec :: Int -> Base64 k a -> ShowS # show :: Base64 k a -> String # showList :: [Base64 k a] -> ShowS #
Eq a => Eq (Base64 k a) # |
Instance details Defined in Data.Base64.Types.Internal Methods (==) :: Base64 k a -> Base64 k a -> Bool # (/=) :: Base64 k a -> Base64 k a -> Bool #

assertBase64 :: forall (k :: Alphabet) a. a -> Base64 k a #

Assert the provenance of a value encoded in a particular base64 alphabet.

Warning: This is a blind assertion that a particular value is base64 encoded in some alphabet. If you are not sure of the provenance of the value, you may experience odd behavior when attempting to decode. Use at your own risk. If I see any issues logged on this project from negligent use of this or `coerceBase64`, I will smite you.

extractBase64 :: forall (k :: Alphabet) a. Base64 k a -> a #

Forget the provenance of a base64-encoded value.

coerceBase64 :: forall (j :: Alphabet) (k :: Alphabet) a. Base64 k a -> Base64 j a #

Coerce the alphabet of a base64-encoded bytestring

Warning: This is a blind assertion that a particular value is base64 encoded in some alphabet. If you are not sure of the provenance of the value, you may experience odd behavior when attempting to decode. Use at your own risk. If I see any issues logged on this project from negligent use of this or `assertBase64`, I will smite you.

type family UrlAlphabet (k :: Alphabet) where ... #

The type family of Url-safe alphabets

This type family defines the union of compatible Url-safe base64 types. To write a function that is parametric over such types, issue a constraint like `forall k. UrlAlphabet k`.

Equations

UrlAlphabet 'UrlPadded = () |
UrlAlphabet 'UrlUnpadded = () |
UrlAlphabet _1 = TypeError ('Text "Cannot prove base64 value is encoded using the url-safe alphabet. Please re-encode using the url-safe encoders, or use a lenient decoder for the url-safe alphabet instead.") :: Constraint |

type family StdAlphabet (k :: Alphabet) where ... #

The type family of standard alphabets

This type family defines the union of compatible standard alphabet base64 types

Equations

StdAlphabet 'StdPadded = () |
StdAlphabet _1 = TypeError ('Text "Cannot prove base64 value is encoded using the std alphabet. Please re-encode using the std encoders, or use a lenient decoder for the std alphabet instead.") :: Constraint |

type family NonStandardAlphabet (k :: Alphabet) where ... #

The type family of non-standard alphabets

Only untyped variants of encodeBase64/decodeBase64 can interact with this type family, in addition to assertion/coercion/extraction of these types of values.

Equations

NonStandardAlphabet 'NonStandard = () |
NonStandardAlphabet _1 = TypeError ('Text "Cannot prove base64 value is encoded using a non-standard alphabet. Please re-encode and assert/coerce the alphabet, and use a lenient decoder.") :: Constraint |