Package COM.INFORMATIMAGO.COMMON-LISP.RFC3548.RFC3548


This packages exports functions to encode an decode text blocks
according to the encoding described in:
RFC3548: The Base16, Base32, and Base64 Data Encodings

base64-encode     (read-byte write-char)
base64-decode     (read-char write-byte &key (ignore-invalid-input nil))
filebase64-encode (read-byte write-char)
filebase64-decode (read-char write-byte &key (ignore-invalid-input nil))
base32-encode     (read-byte write-char)
base32-decode     (read-char write-byte &key (ignore-invalid-input nil))
base16-encode     (read-byte write-char)
base16-decode     (read-char write-byte &key (ignore-invalid-input nil))

READ-BYTE:  A function taking no argument and returning a
            byte (integer 0 255) or nil for eof.  It may be
            called several times after eof and should keep
            returning nil.

WRITE-BYTE: A function taking one byte (integer 0 255) argument
            used to collect decoded bytes.

READ-CHAR:  A function taking no argument and returning a
            character or nil for eof.  It may be called
            several times after eof and should keep returning
            nil.  Only characters whose code is between 0 and
            255 should be returned.

WRITE-CHAR: A function taking one character argument, used to
            collect encoded bytes.

IGNORE-INVALID-INPUT:
            When true, any invalid character or padding is ignored
            and processing continues as if it did not occur.
            When nil, such an occurence would raise an error.


base64-encode-bytes     (bytes   &key line-width (new-line +new-line+))
base64-decode-bytes     (encoded &key ignore-crlf ignore-invalid-input)
filebase64-encode-bytes (bytes   &key line-width (new-line +new-line+))
filebase64-decode-bytes (encoded &key ignore-crlf ignore-invalid-input)
base32-encode-bytes     (bytes   &key line-width (new-line +new-line+))
base32-decode-bytes     (encoded &key ignore-crlf ignore-invalid-input)
base16-encode-bytes     (bytes   &key line-width (new-line +new-line+))
base16-decode-bytes     (encoded &key ignore-crlf ignore-invalid-input)

BYTES:      A vector of (unsigned-byte 8).
ENCODED:    A string.
LINE-WIDTH: NIL or an integer indicating the line width.
            the string new-line will be inserted after that
            many characters have been written on a given line.
NEW-LINE:   A string contaiing the new-line character or characters.
            the default +new-line+ is (format nil "~%").
IGNORE-CRLF:
            When true, ASCII characters LF and CR are not passed to
            the decoding function. When NIL, they're passed, and
            if invalid input is not ignored, an error would be raised.
IGNORE-INVALID-INPUT:
            Passed to the decoding function. See above.


The encoding functions take a vector of bytes
and return an encoded string.

The decoding functions take an encoded string
and return a vector of bytes.

To encode a string, characters must be converted to bytes, and
to decode a string, bytes must be converted to characters.
This must be done accordingly to the characeter set encoding.



License:

    AGPL3

    Copyright Pascal J. Bourguignon 2004 - 2012

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.
    If not, see <http://www.gnu.org/licenses/>

(base16-decode read-char write-byte &key ignore-invalid-input)
function
DO:         Decode the BASE16 text stream read with the READ-CHAR
            closure into a binary stream written with WRITE-BYTE
            closure.

READ-CHAR:  A function taking no argument and returning a
            character or nil for eof.  It may be called
            several times after eof and should keep returning
            nil.  Only characters whose code is between 0 and
            255 should be returned.

WRITE-BYTE: A function taking one byte (integer 0 255) argument
            used to collect decoded bytes.

IGNORE-INVALID-INPUT:
            When true, any invalid character or padding is ignored
            and processing continues as if it did not occur.
            When nil, such an occurence would raise an error.
(base16-decode-bytes encoded &key ignore-crlf ignore-invalid-input)
function
DO:         Decode the BASE16 encoded string ENCODED.

RETURN:     A decoded vector of (unsigned-byte 8).

ENCODED:    A string.

IGNORE-CRLF:
            When true, ASCII characters LF and CR are not passed to
            the decoding function. When NIL, they're passed, and
            if invalid input is not ignored, an error would be raised.

IGNORE-INVALID-INPUT:
            Passed to the decoding function. See above.
(base16-encode read-byte write-char)
function
DO:         Encode the stream read with the READ-BYTE closure
            in BASE16 text written with WRITE-CHAR closure.

READ-BYTE:  A function taking no argument and returning a
            byte (integer 0 255) or nil for eof.  It may be
            called several times after eof and should keep
            returning nil.

WRITE-CHAR: A function taking one character argument, used to
            collect encoded bytes.

(base16-encode-bytes bytes &key line-width new-line)
function
DO:         Encode the BYTES in BASE16 text.

RETURN:     An encoded string.

BYTES:      A vector of (unsigned-byte 8).

LINE-WIDTH: NIL or an integer indicating the line width.
            the string new-line will be inserted after that
            many characters have been written on a given line.

NEW-LINE:   A string contaiing the new-line character or characters.
            the default +new-line+ is (format nil "~%").
(base32-decode read-char write-byte &key ignore-invalid-input)
function
DO:         Decode the BASE32 text stream read with the READ-CHAR
            closure into a binary stream written with WRITE-BYTE
            closure.

READ-CHAR:  A function taking no argument and returning a
            character or nil for eof.  It may be called
            several times after eof and should keep returning
            nil.  Only characters whose code is between 0 and
            255 should be returned.

WRITE-BYTE: A function taking one byte (integer 0 255) argument
            used to collect decoded bytes.

IGNORE-INVALID-INPUT:
            When true, any invalid character or padding is ignored
            and processing continues as if it did not occur.
            When nil, such an occurence would raise an error.

(base32-decode-bytes encoded &key ignore-crlf ignore-invalid-input)
function
DO:         Decode the BASE32 encoded string ENCODED.

RETURN:     A decoded vector of (unsigned-byte 8).

ENCODED:    A string.

IGNORE-CRLF:
            When true, ASCII characters LF and CR are not passed to
            the decoding function. When NIL, they're passed, and
            if invalid input is not ignored, an error would be raised.

IGNORE-INVALID-INPUT:
            Passed to the decoding function. See above.
(base32-encode read-byte write-char)
function
DO:         Encode the stream read with the READ-BYTE closure
            in BASE32 text written with WRITE-CHAR closure.

READ-BYTE:  A function taking no argument and returning a
            byte (integer 0 255) or nil for eof.  It may be
            called several times after eof and should keep
            returning nil.

WRITE-CHAR: A function taking one character argument, used to
            collect encoded bytes.
(base32-encode-bytes bytes &key line-width new-line)
function
DO:         Encode the BYTES in BASE32 text.

RETURN:     An encoded string.

BYTES:      A vector of (unsigned-byte 8).

LINE-WIDTH: NIL or an integer indicating the line width.
            the string new-line will be inserted after that
            many characters have been written on a given line.

NEW-LINE:   A string contaiing the new-line character or characters.
            the default +new-line+ is (format nil "~%").
(base64-decode read-char write-byte &key ignore-invalid-input)
function
DO:         Decode the BASE64 text stream read with the READ-CHAR
            closure into a binary stream written with WRITE-BYTE
            closure.

READ-CHAR:  A function taking no argument and returning a
            character or nil for eof.  It may be called
            several times after eof and should keep returning
            nil.  Only characters whose code is between 0 and
            255 should be returned.

WRITE-BYTE: A function taking one byte (integer 0 255) argument
            used to collect decoded bytes.

IGNORE-INVALID-INPUT:
            When true, any invalid character or padding is ignored
            and processing continues as if it did not occur.
            When nil, such an occurence would raise an error.
(base64-decode-bytes encoded &key ignore-crlf ignore-invalid-input)
function
DO:         Decode the BASE64 encoded string ENCODED.

RETURN:     A decoded vector of (unsigned-byte 8).

ENCODED:    A string.

IGNORE-CRLF:
            When true, ASCII characters LF and CR are not passed to
            the decoding function. When NIL, they're passed, and
            if invalid input is not ignored, an error would be raised.

IGNORE-INVALID-INPUT:
            Passed to the decoding function. See above.
(base64-encode read-byte write-char)
function
DO:         Encode the stream read with the READ-BYTE closure
            in BASE64 text written with WRITE-CHAR closure.

READ-BYTE:  A function taking no argument and returning a
            byte (integer 0 255) or nil for eof.  It may be
            called several times after eof and should keep
            returning nil.

WRITE-CHAR: A function taking one character argument, used to
            collect encoded bytes.

(base64-encode-bytes bytes &key line-width new-line)
function
DO:         Encode the BYTES in BASE64 text.

RETURN:     An encoded string.

BYTES:      A vector of (unsigned-byte 8).

LINE-WIDTH: NIL or an integer indicating the line width.
            the string new-line will be inserted after that
            many characters have been written on a given line.

NEW-LINE:   A string contaiing the new-line character or characters.
            the default +new-line+ is (format nil "~%").
(filebase64-decode read-char write-byte &key ignore-invalid-input)
function
DO:         Decode the FILEBASE64 text stream read with the READ-CHAR
            closure into a binary stream written with WRITE-BYTE
            closure.


NOTE:       It's the same encoding as BASE64, but the 62nd and 63rd
            characters are - and _ instead of + and /, thus making it
            usable for file names and URLs.

READ-CHAR:  A function taking no argument and returning a
            character or nil for eof.  It may be called
            several times after eof and should keep returning
            nil.  Only characters whose code is between 0 and
            255 should be returned.

WRITE-BYTE: A function taking one byte (integer 0 255) argument
            used to collect decoded bytes.

IGNORE-INVALID-INPUT:
            When true, any invalid character or padding is ignored
            and processing continues as if it did not occur.
            When nil, such an occurence would raise an error.
(filebase64-decode-bytes encoded &key ignore-crlf ignore-invalid-input)
function
DO:         Decode the FILEBASE64 encoded string ENCODED.

RETURN:     A decoded vector of (unsigned-byte 8).

ENCODED:    A string.

IGNORE-CRLF:
            When true, ASCII characters LF and CR are not passed to
            the decoding function. When NIL, they're passed, and
            if invalid input is not ignored, an error would be raised.

IGNORE-INVALID-INPUT:
            Passed to the decoding function. See above.
(filebase64-encode read-byte write-char)
function
DO:         Encode the stream read with the READ-BYTE closure
            in FILEBASE64 text written with WRITE-CHAR closure.

NOTE:       It's the same encoding as BASE64, but the 62nd and 63rd
            characters are - and _ instead of + and /, thus making it
            usable for file names and URLs.

READ-BYTE:  A function taking no argument and returning a
            byte (integer 0 255) or nil for eof.  It may be
            called several times after eof and should keep
            returning nil.

WRITE-CHAR: A function taking one character argument, used to
            collect encoded bytes.
(filebase64-encode-bytes bytes &key line-width new-line)
function
DO:         Encode the BYTES in FILEBASE64 text.

RETURN:     An encoded string.

BYTES:      A vector of (unsigned-byte 8).

LINE-WIDTH: NIL or an integer indicating the line width.
            the string new-line will be inserted after that
            many characters have been written on a given line.

NEW-LINE:   A string contaiing the new-line character or characters.
            the default +new-line+ is (format nil "~%").