Documentation for new RFC 3548 functions.

Doc/lib/libbase64.tex

@@ -1,25 +1,118 @@
 \section{\module{base64} ---
-         Encode and decode MIME base64 data}
+	 RFC 3548: Base16, Base32, Base64 Data Encodings}
 
 \declaremodule{standard}{base64}
-\modulesynopsis{Encode and decode files using the MIME base64 data.}
+\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
 
 
 \indexii{base64}{encoding}
 \index{MIME!base64 encoding}
 
-This module performs base64 encoding and decoding of arbitrary binary
-strings into text strings that can be safely sent by email or included
-as part of an HTTP POST request.  The
-encoding scheme is defined in \rfc{1521} (\emph{MIME
-(Multipurpose Internet Mail Extensions) Part One: Mechanisms for
-Specifying and Describing the Format of Internet Message Bodies},
-section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for
-MIME email and various other Internet-related applications; it is not
-the same as the output produced by the \program{uuencode} program.
-For example, the string \code{'www.python.org'} is encoded as the
-string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}.  
+This module provides data encoding and decoding as specified in
+\rfc{3548}.  This standard defines the Base16, Base32, and Base64
+algorithms for encoding and decoding arbitrary binary strings into
+text strings that can be safely sent by email, used as parts of URLs,
+or included as part of an HTTP POST request.  The encoding algorith is
+not the same as the \program{uuencode} program.
 
+There are two interfaces provided by this module.  The modern
+interface supports encoding and decoding string objects using all
+three alphabets.  The legacy interface provides for encoding and
+decoding to and from file-like objects as well as strings, but only
+using the Base64 standard alphabet.
+
+The modern interface provides:
+
+\begin{funcdesc}{b64encode}{s\optional{, altchars}}
+Encode a string use Base64.
+
+\var{s} is the string to encode.  Optional \var{altchars} must be a
+string of at least length 2 (additional characters are ignored) which
+specifies an alternative alphabet for the \code{+} and \code{/}
+characters.  This allows an application to e.g. generate URL or
+filesystem safe Base64 strings.  The default is \code{None}, for which
+the standard Base64 alphabet is used.
+
+The encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b64decode}{s\optional{, altchars}}
+Decode a Base64 encoded string.
+
+\var{s} is the string to decode.  Optional \var{altchars} must be a
+string of at least length 2 (additional characters are ignored) which
+specifies the alternative alphabet used instead of the \code{+} and
+\code{/} characters.
+
+The decoded string is returned.  A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet
+characters present in the string.
+\end{funcdesc}
+
+\begin{funcdesc}{standard_b64encode}{s}
+Encode string \var{s} using the standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{standard_b64decode}{s}
+Decode string \var{s} using the standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{urlsafe_b64encode}{s}
+Encode string \var{s} using a URL-safe alphabet, which substitutes
+\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{urlsafe_b64decode}{s}
+Decode string \var{s} using a URL-safe alphabet, which substitutes
+\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{b32encode}{s}
+Encode a string using Base32.  \var{s} is the string to encode.  The
+encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
+Decode a Base32 encoded string.
+
+\var{s} is the string to decode.  Optional \var{casefold} is a flag
+specifying whether a lowercase alphabet is acceptable as input.  For
+security purposes, the default is \code{False}.
+
+\rfc{3548} allows for optional mapping of the digit 0 (zero) to the
+letter O (oh), and for optional mapping of the digit 1 (one) to either
+the letter I (eye) or letter L (el).  The optional argument
+\var{map01} when not \code{None}, specifies which letter the digit 1 should
+be mapped to (when map01 is not \var{None}, the digit 0 is always
+mapped to the letter O).  For security purposes the default is
+\code{None}, so that 0 and 1 are not allowed in the input.
+
+The decoded string is returned.  A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet characters
+present in the string.
+\end{funcdesc}
+
+\begin{funcdesc}{b16encode}{s}
+Encode a string using Base16.
+
+\var{s} is the string to encode.  The encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b16decode}{s\optional{, casefold}}
+Decode a Base16 encoded string.
+
+\var{s} is the string to decode.  Optional \var{casefold} is a flag
+specifying whether a lowercase alphabet is acceptable as input.  For
+security purposes, the default is \code{False}.
+
+The decoded string is returned.  A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet
+characters present in the string.
+\end{funcdesc}
+
+The legacy interface:
 
 \begin{funcdesc}{decode}{input, output}
 Decode the contents of the \var{input} file and write the resulting