base64-0.4.2.4: A modern RFC 4648-compliant Base64 library

Copyright | (c) 2019-2020 Emily Pillmore
License | BSD-style
Maintainer | Emily Pillmore <emilypi@cohomolo.gy>
Stability | stable
Portability | non-portable
Safe Haskell | Safe
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 -> Text
- decodeBase64 :: Text -> Either Text Text
- decodeBase64With :: (ByteString -> Either err Text) -> ByteString -> Either (Base64Error err) Text
- decodeBase64Lenient :: Text -> Text
- isBase64 :: Text -> Bool
- isValidBase64 :: Text -> Bool

# Encoding

encodeBase64 :: Text -> Text #

Encode a `Text` value in Base64 with padding.

See: RFC-4648 section 4

### Examples:

    >>> encodeBase64 "Sun"
    "U3Vu"

# Decoding

decodeBase64 :: Text -> Either Text Text #

Decode a padded Base64-encoded `Text` value

See: RFC-4648 section 4

Note: This function makes sure that decoding is total by deferring to `decodeLatin1`. This will always round trip for any valid Base64-encoded text value, but it may not round trip for bad inputs. The onus is on the caller to make sure inputs are valid. If unsure, defer to `decodeBase64With` and pass in a custom decode function.

### Examples:

    >>> decodeBase64 "U3Vu"
    Right "Sun"

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

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

decodeBase64With #

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:

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

decodeBase64Lenient :: Text -> Text #

Leniently decode a 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 a `Text` value is Base64-encoded.

### Examples:

    >>> isBase64 "U3Vu"
    True

    >>> isBase64 "U3V"
    False

    >>> isBase64 "U3V="
    False

isValidBase64 :: Text -> Bool #

Tell whether a `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