\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#250: Efficient Access to Namespace Variables}
\date{June 19, 2005}
\author{Will Duquette, miguel sofer}
\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 \#250}&\textbf{Efficient Access to Namespace Variables}\\\hline
Author&

Will Duquette \tipmail{will}{wjduquette.com}
\par
miguel sofer \tipmail{msofer}{users.sf.net}
\\
Created&Sunday, \(\text{19}^{\text{th}}\) June 2005\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.7 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new \textbf{namespace} subcommand, \textbf{namespace upvar}, to efficiently alias namespace variables into the current scope.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

A pure-Tcl object system which defines a namespace to contain the variables for each object instance must either duplicate the object's method code in each instance namespace, or define the method code such that it exists in one namespace but accesses data from another. The Snit package [\url{http://www.wjduquette.com/snit}] does the latter. Instance variables are declared automatically within each method body using code like this, where ``selfns'' is a variable containing the name of the instance namespace:
\begingroup\small\begin{verbatim}
 upvar ${selfns}::myvar myvar
\end{verbatim}
\endgroup

The fully-qualified variable name ``\$\{selfns\}::myvar'' must be recomputed each time the method is called, which is a significant source of method-call overhead. This TIP proposes a mechanism for avoiding many of these costs while also allowing people to write clearer code.

With \textbf{namespace upvar}, the code would look like this:
\begingroup\small\begin{verbatim}
 namespace upvar $selfns myvar myvar
\end{verbatim}
\endgroup

The speed gains come from:
\begin{itemize}
\item{}
it avoids building and then destroying a Tcl\_Obj for the fully qualified name
\item{}
it avoids parsing the fully qualified name into its namespace/tail components, creating and then destroying the corresponding Tcl\_Objs
\item{}
it may reuse a cached namespace in the internal representation of \$\{selfns\}
\end{itemize}

In addition, the programmer's intention is easier to see in a command
\begingroup\small\begin{verbatim}
 namespace upvar $selfns var1 var1 var2 var2 var3 var3
\end{verbatim}
\endgroup

than in the currently necessary
\begingroup\small\begin{verbatim}
 upvar 0 ${selfns}::var1 var1 ${selfns}::var2 var2 ${selfns}::var3 var3
\end{verbatim}
\endgroup

where the fact that all variables come from the same namespace is not so obvious.

\section{Specification}

The syntax of the new subcommand is as follows:

\begin{quote}
\textbf{namespace upvar} \textit{ns otherVar myVar} ?\textit{otherVar myVar} ...?
\end{quote}

The semantics are identical to the following \textbf{upvar} call:

\begin{quote}
\textbf{upvar 0} \textit{ns}::\textit{otherVar} \textit{myVar} ?\textit{ns}::\textit{otherVar} \textit{myVar}...?
\end{quote}

That is, the variable \textit{otherVar} in namespace \textit{ns} (as resolved from the local scope) is aliased to variable \textit{myVar} in the local scope.

\section{Reference Implementation}

A reference implementation of \textbf{namespace upvar} is being developed at SF patch \#1275435 [\url{https://sourceforge.net/tracker/index.php?func=detail&aid=1275435&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}
\end{document}
