base64-1.0: A modern Base64 library

Copyright | (c) 2019-2023 Emily Pillmore
License | BSD-style
Maintainer | Emily Pillmore <emilypi@cohomolo.gy>
Stability | stable
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Data.Text.Lazy.Encoding.Base64

Contents

- Encoding
- Decoding
- Validation

Description

This module contains `Text`-valued combinators implementing the RFC 4648 specification for the Base64 encoding format. This includes lenient decoding variants, and external + internal validations for canonicity.

Synopsis

- encodeBase64 :: Text -> Base64 'StdPadded Text
- decodeBase64 :: forall (k :: Alphabet). StdAlphabet k => Base64 k Text -> Text
- decodeBase64Untyped :: Text -> Either Text Text
- decodeBase64UntypedWith :: (ByteString -> Either err Text) -> ByteString -> Either (Base64Error err) Text
- decodeBase64Lenient :: Text -> Text
- isBase64 :: Text -> Bool
- isValidBase64 :: Text -> Bool

# Encoding

encodeBase64 :: Text -> Base64 'StdPadded Text #

Encode a `Text` value in Base64 with padding.

See: RFC-4648 section 4

### Examples:

    >>> encodeBase64 "Sun"
    "U3Vu"

# Decoding

decodeBase64 :: forall (k :: Alphabet). StdAlphabet k => Base64 k Text -> Text #

Decode a padded Base64-encoded `Text` value

See: RFC-4648 section 4

### Examples:

    >>> decodeBase64 $ assertBase64 @'StdPadded "U3Vu"
    "Sun"

decodeBase64Untyped :: Text -> Either Text Text #

Decode a padded, untyped Base64-encoded `Text` value

See: RFC-4648 section 4

### Examples:

    >>> decodeBase64Untyped "U3Vu"
    Right "Sun"

    >>> decodeBase64Untyped "U3V"
    Left "Base64-encoded bytestring requires padding"

    >>> decodeBase64Untyped "U3V="
    Left "non-canonical encoding detected at offset: 2"

decodeBase64UntypedWith #

Arguments

:: (ByteString -> Either err Text) | convert a bytestring to text (e.g. `decodeUtf8'`)
-> ByteString | Input text to decode
-> Either (Base64Error err) Text |

Attempt to decode a `ByteString` value as Base64, converting from `ByteString` to `Text` according to some encoding function. In practice, This is something like `decodeUtf8'`, which may produce an error.

See: RFC-4648 section 4

### Example:

    decodeBase64UntypedWith decodeUtf8'
      :: ByteString -> Either (Base64Error UnicodeException) Text

decodeBase64Lenient :: Text -> Text #

Leniently decode an untyped Base64-encoded `Text` value. This function will not generate parse errors. If input data contains padding chars, then the input will be parsed up until the first pad character.

Note: This is not RFC 4648-compliant.

### Examples:

    >>> decodeBase64Lenient "U3Vu"
    "Sun"

    >>> decodeBase64Lenient "U3V"
    "Su"

    >>> decodeBase64Lenient "U3V="
    "Su"

# Validation

isBase64 :: Text -> Bool #

Tell whether an untyped `Text` value is Base64-encoded.

### Examples:

    >>> isBase64 "U3Vu"
    True

    >>> isBase64 "U3V"
    False

    >>> isBase64 "U3V="
    False

isValidBase64 :: Text -> Bool #

Tell whether an untyped `Text` value is a valid Base64 format.

This will not tell you whether or not this is a correct Base64 representation, only that it conforms to the correct shape. To check whether it is a true Base64 encoded `Text` value, use `isBase64`.

### Examples:

    >>> isValidBase64 "U3Vu"
    True

    >>> isValidBase64 "U3V"
    True

    >>> isValidBase64 "U3V="
    True

    >>> isValidBase64 "%"
    False