\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#317: Extend binary Ensemble with Binary Encodings}
\date{May 03, 2008}
\author{Pat Thoyts}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#317}&\textbf{Extend binary Ensemble with Binary Encodings}\\\hline
Author&

Pat Thoyts \tipmail{patthoyts}{users.sourceforge.net}
\\
Created&Saturday, \(\text{3}^{\text{rd}}\) May 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&base64, uuencode, hex, transfer encoding\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP extends the \textbf{binary} command with implementations in C of commonly used binary encodings. In particular the \textit{base64} encoding is implemented but the Tcl ensemble scheme \cite{tip112} can be used to provide simple extension of the implemented formats.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Specification}

The \textbf{binary} command ensemble will be extended to include two new subcommands, \textbf{encode} and \textbf{decode}. Each subcommand will accept two arguments. The first is the name of an encoding format and the second is the data to be operated upon.

\begin{quote}
\textbf{binary encode} \textit{format ?-option value ...? data}
\end{quote}

\begin{quote}
\textbf{binary decode} \textit{format ?-option value ...? data}
\end{quote}

In keeping with the nature of the \textbf{binary} command, the \textit{data} argument is treated as a byte array. This means that users should ensure their data is already in a suitable character encoding before applying a binary encoding. This is already a requirement for other implementations of this functionality (e.g. the tcllib and Trf packages).

The initial set of binary encodings consists of \textbf{base64}, \textbf{uuencode} and \textbf{hex}. The implementation of the \textbf{encode} and \textbf{decode} subcommands will make use of the Tcl ensemble command mechanism (\cite{tip112}) and will therefore be extensible via the ensemble mechanism.

\section{Reference Implementation}

A patch against the Tcl HEAD (8.6) is located at \url{http://sf.net/tracker/?func=detail&aid=1956530&group_id=10894&atid=310894}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#112]{tip112}
Donal K. Fellows,
\emph{Ensembles are Namespaces are Commands},
on-line at \url{http://purl.org/tcl/tip/112.html}
\end{thebibliography}
\end{document}
