sandi-0.5: Data encoding library

Copyright | (c) 2012 Magnus Therning
License | BSD3
Safe Haskell | None
Language | Haskell2010

Codec.Binary.Uu

Description

Uuencoding is notoriously badly specified. This implementation aims at being compatible with the GNU Sharutils (http://www.gnu.org/software/sharutils/).

Just like Base64 encoding uuencoding expands blocks of 3 bytes into blocks of 4 bytes. There is however no well defined ending to a piece of encoded data, instead uuencoded data is commonly transferred linewise where each line is prepended with the length of the data in the line.

This module currently only deals with the encoding. Chopping the encoded data into lines, and unchopping lines into encoded data is left as an exercise to the reader. (Patches are welcome.)

Synopsis

- uuEncodePart :: ByteString -> (ByteString, ByteString)
- uuEncodeFinal :: ByteString -> Maybe ByteString
- uuDecodePart :: ByteString -> Either (ByteString, ByteString) (ByteString, ByteString)
- uuDecodeFinal :: ByteString -> Maybe ByteString
- encode :: ByteString -> ByteString
- decode :: ByteString -> Either (ByteString, ByteString) ByteString

# Documentation

uuEncodePart :: ByteString -> (ByteString, ByteString) #

Encoding function.

This function encodes as large a portion of the input as possible and returns the encoded part together with the remaining part. Enough space is allocated for the encoding to make sure that the remaining part is less than 3 bytes long, which means it can be passed to `uu_encode_final` as is.

    >>> uuEncodePart $ Data.ByteString.Char8.pack "foo"
    ("9F]O","")
    >>> uuEncodePart $ Data.ByteString.Char8.pack "foob"
    ("9F]O","b")

uuEncodeFinal :: ByteString -> Maybe ByteString #

Encoding function for the final block.

The final block has to have a size less than 3.

    >>> uuEncodeFinal $ Data.ByteString.Char8.pack "r"
    Just "<@"

Trying to pass in too large a block result in failure:

    >>> uuEncodeFinal $ Data.ByteString.Char8.pack "foo"
    Nothing

uuDecodePart :: ByteString -> Either (ByteString, ByteString) (ByteString, ByteString) #

Decoding function.

Decode as large a portion of the input as possible. Enough data is allocated for the output to ensure that the remainder is less than 4 bytes in size. Success result in a `Right` value:

    >>> uuDecodePart $ Data.ByteString.Char8.pack "9F]O"
    Right ("foo","")
    >>> uuDecodePart $ Data.ByteString.Char8.pack "9F]O8F$"
    Right ("foo","8F$")

Failures occur on bad input and result in a `Left` value:

    >>> uuDecodePart $ Data.ByteString.Char8.pack "9F 0"
    Left ("","9F 0")

uuDecodeFinal :: ByteString -> Maybe ByteString #

Decoding function for the final block.

The final block has to have a size of 0 or 4:

    >>> uuDecodeFinal $ Data.ByteString.Char8.pack "9F\\"
    Just "fo"
    >>> uuDecodeFinal $ Data.ByteString.Char8.pack ""
    Just ""
    >>> uuDecodeFinal $ Data.ByteString.Char8.pack "9F¬"
    Nothing

But it must be the encoding of a block that is less than 3 bytes:

    >>> uuDecodeFinal $ encode $ Data.ByteString.Char8.pack "foo"
    Nothing

encode :: ByteString -> ByteString #

Convenience function that combines `uu_encode_part` and `uu_encode_final` to encode a complete string.

    >>> encode $ Data.ByteString.Char8.pack "foo"
    "9F]O"
    >>> encode $ Data.ByteString.Char8.pack "foobar"
    "9F]O8F%R"

decode :: ByteString -> Either (ByteString, ByteString) ByteString #

Convenience function that combines `uu_decode_part` and `uu_decode_final` to decode a complete string.

    >>> decode $ Data.ByteString.Char8.pack "9F]O"
    Right "foo"
    >>> decode $ Data.ByteString.Char8.pack "9F]O8F%R"
    Right "foobar"

Failures when decoding returns the decoded part and the remainder:

    >>> decode $ Data.ByteString.Char8.pack "9F]O8F¬R"
    Left ("foo","8F\172R")