\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#140: Tracing Namespace Modifications}
\date{June 04, 2003}
\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 \#140}&\textbf{Tracing Namespace Modifications}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Wednesday, \(\text{4}^{\text{th}}\) June 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Deferred\\
Vote&Pending\\
Version&\tipversion$Revision: 1.2 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP allows scripts to register callbacks to monitor alterations to namespaces, such as their deletion, the creation, renaming and deletion of commands within the namespace and modifications to the exports list of the namespace.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

As part of my work on an experimental \cite{tip112} implementation, I have discovered that computing the list of public (i.e. exported) commands from a namespace is a comparatively expensive operation. This means that it is necessary (well, highly desirable) to cache the list of exports from a namespace. But then I thought that it might be nice to expose that interface to use to better enable namespaces to support other interesting uses, and that it should be possible to implement the default behaviour in a Tcl script. It is in support of this that I present this TIP; I also add the ability to trace deletion of the namespace as a fairly obvious extension.

\section{Proposed Change at Tcl Script Level}

I propose that the [trace] command be extended with a new type of thing to trace: a namespace. The operations that would trigger a trace are:
\begin{itemize}
\item{}
Namespace deletion (subject to the same sorts of restrictions in relation to deleted interpreters that are present for traces of command deletion) with the ops value \textit{delete}.
\item{}
Command list modification (being creation, renaming or deletion of any command within that namespace) with the ops value \textit{command}. Modification due to deletion of the namespace will not trigger traces with this operation, but instead the \textit{delete} operation outlined above (subject to the caveats relating to interpreter deletion.)
\item{}
Exports list modification (i.e. updates with [namespace export]) with the ops value \textit{export}. Modification due to the deletion of the namespace will not trigger this traces with this operation, but instead the \textit{delete} operation outlined above (subject to the caveats relating to interpreter deletion.)
\end{itemize}

In each case, the trace callback script will have the fully qualified name of the namespace and the name of the triggering operation appended to it before execution. In the case of command list modification by the \textit{creation} of a command (which might also be through import of commands from another namespace, for example) there will be an extra parameter being the \textit{local} name of the command (without namespace separators.)

These changes will be propagated to each of the [trace add], [trace remove] and [trace info] subcommands, of course.

\section{Proposed Change at C API Level}

Yet to be designed, but will be based as closely as possible on the existing Tcl trace APIs.

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