\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#235: Exposing a C API for Ensembles}
\date{December 10, 2004}
\author{Donal K. Fellows}
\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 \#235}&\textbf{Exposing a C API for Ensembles}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Friday, \(\text{10}^{\text{th}}\) December 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.9 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP exposes a C API for the ensembles of \cite{tip112}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

As the Tcl core moves to make more use of ensembles, it becomes more necessary for there to be an API available to allow control over those ensembles from the C level so that it is not necessary for such manipulation to be done through the evaluation of Tcl scripts (e.g. because this interferes with the interpreter's command count and that may be limited in that particular interpreter). Given such an API, it should be exposed to code outside the Tcl core if at all possible.

\section{Proposed Change}

This TIP proposes exposing the following functions:
\begin{description}
\item[Tcl\_CreateEnsemble]
Create an ensemble linked to a particular namespace and return the command token for the namespace command. The \textit{flags} argument specifies the initial version of the set of flags controllable through Tcl\_SetEnsembleFlags (see below).

Tcl\_Command \textbf{Tcl\_CreateEnsemble}(Tcl\_Interp *\textit{interp}, const char *\textit{name}, Tcl\_Namespace *\textit{namespacePtr}, int \textit{flags})
\item[Tcl\_FindEnsemble]
Return a command token for an ensemble, or NULL if the name does not refer to an ensemble. The \textit{flags} argument controls whether failure to find an ensemble is an error and should be either 0 or TCL\_LEAVE\_ERR\_MSG.

Tcl\_Command \textbf{Tcl\_FindEnsemble}(Tcl\_Interp *\textit{interp}, Tcl\_Obj *\textit{cmdNameObj}, int \textit{flags})
\item[Tcl\_IsEnsemble]
Test whether a command token refers to an ensemble.

int \textbf{Tcl\_IsEnsemble}(Tcl\_Command \textit{command})
\item[Tcl\_GetEnsembleSubcommandList, Tcl\_SetEnsembleSubcommandList]
Read and write the (fixed) list of subcommands of the ensemble. Equivalent to manipulating the \textbf{-subcommands} option.

int \textbf{Tcl\_GetEnsembleSubcommandList}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj **\textit{subcmdListObjPtr})

int \textbf{Tcl\_SetEnsembleSubcommandList}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj *\textit{subcmdListObj})
\item[Tcl\_GetEnsembleMappingDict, Tcl\_SetEnsembleMappingDict]
Read and write the dictionary that maps subcommands to prefixes of implementation commands. Equivalent to manipulating the \textbf{-map} option.

int \textbf{Tcl\_GetEnsembleMappingDict}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj **\textit{mapDictObjPtr})

int \textbf{Tcl\_SetEnsembleMappingDict}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj *\textit{mapDictObj})
\item[Tcl\_GetEnsembleUnknownHandler, Tcl\_SetEnsembleUnknownHandler]
Read and write the command prefix list that is used to implement the unknown-subcommand handler. Equivalent to manipulating the \textbf{-unknown} option.

int \textbf{Tcl\_GetEnsembleUnknownHandler}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj **\textit{handlerListObjPtr})

int \textbf{Tcl\_SetEnsembleUnknownHandler}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Obj *\textit{handlerListObj})
\item[Tcl\_GetEnsembleFlags, Tcl\_SetEnsembleFlags]
Read and write the flags for the ensemble. Currently there is only one settable flag bit, TCL\_ENSEMBLE\_PREFIX, which is present exactly when \textbf{-prefix} option is true.

int \textbf{Tcl\_GetEnsembleFlags}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, int *\textit{flagsPtr})

int \textbf{Tcl\_SetEnsembleFlags}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, int \textit{flags})
\item[Tcl\_GetEnsembleNamespace]
Reads the namespace associated with the ensemble; this value may not be altered.

int \textbf{Tcl\_GetEnsembleNamespace}(Tcl\_Interp *\textit{interp}, Tcl\_Command \textit{command}, Tcl\_Namespace **\textit{namespacePtrPtr})
\end{description}

\subsection{Notes}

The handle for an ensemble is a normal Tcl\_Command handle, and any operation valid on such a command (e.g. deleting it or finding its name) is valid. Ensembles are just a special subclass of commands. This allows the ensemble API to be considerably sparser than it would otherwise have to be.

\section{Reference Implementation}

The API is already in the core, but with internal naming and not exposed to anyone. Exposure is just renaming a few functions and putting them in the stubs table. No new types are exposed. All this means that a reference implementation is truly trivial.

\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}
