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.Short.Encoding.Base64

Contents

- Encoding
- Decoding
- Validation

Description

This module contains `ShortText`-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 :: ShortText -> Base64 'StdPadded ShortText
- decodeBase64 :: forall (k :: Alphabet). StdAlphabet k => Base64 k ShortText -> ShortText
- decodeBase64Untyped :: ShortText -> Either Text ShortText
- decodeBase64UntypedWith :: (ShortByteString -> Either err ShortText) -> ShortByteString -> Either (Base64Error err) ShortText
- decodeBase64Lenient :: ShortText -> ShortText
- isBase64 :: ShortText -> Bool
- isValidBase64 :: ShortText -> Bool

# Encoding

encodeBase64 :: ShortText -> Base64 'StdPadded ShortText Source #

Encode a `ShortText` value in Base64 with padding.

See: RFC-4648 section 4

### Examples:

    >>> encodeBase64 "Sun"
    "U3Vu"

# Decoding

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

Decode a padded Base64-encoded `ShortText` value

See: RFC-4648 section 4

### Examples:

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

decodeBase64Untyped :: ShortText -> Either Text ShortText Source #

Decode a padded Base64-encoded `ShortText` 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 Source #

Arguments

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

Attempt to decode an untyped `ShortByteString` value as Base64, converting from `ByteString` to `ShortText` 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'
      :: ShortByteString -> Either (Base64Error UnicodeException) ShortText

decodeBase64Lenient :: ShortText -> ShortText Source #

Leniently decode an untyped Base64-encoded `ShortText` 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 :: ShortText -> Bool Source #

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

### Examples:

    >>> isBase64 "U3Vu"
    True

    >>> isBase64 "U3V"
    False

    >>> isBase64 "U3V="
    False

isValidBase64 :: ShortText -> Bool Source #

Tell whether an untyped `ShortText` 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 `ShortText` value, use `isBase64`.

### Examples:

    >>> isValidBase64 "U3Vu"
    True

    >>> isValidBase64 "U3V"
    True

    >>> isValidBase64 "U3V="
    True

    >>> isValidBase64 "%"
    False