\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#52: Hierarchical Namespace Lookup of Commands and Variables}
\date{August 09, 2001}
\author{David Cuthbert, Andreas Kupries}
\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 \#52}&\textbf{Hierarchical Namespace Lookup of Commands and Variables}\\\hline
Author&

David Cuthbert \tipmail{dacut}{kanga.org}
\par
Andreas Kupries \tipmail{andreas_kupries}{users.sourceforge.net}
\\
Created&Thursday, \(\text{9}^{\text{th}}\) August 2001\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&namespace, lookup, hierarchy\\
Post History&\\
Discussions To&news:comp.lang.tcl\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to change the command and variable namespace lookup system so that the full hierarchy of namespaces is parsed, rather than just the current namespace followed by the global namespace. This is primarily intended to rectify problems often encountered with the use of [incr Tcl] (ITcl) and namespaces. In addition, package encapsulation can be enhanced with judicious application of this feature.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Currently, the following code is invalid in Tcl/ITcl:
\begingroup\small\begin{verbatim}
package require Itcl

namespace eval SampleNS {
    proc Hello {} { puts "Hello world!" }

    ::itcl::class X {
        public constructor {} {} { Hello }
    }
}

SampleNS::X x1  ;# Error: invalid command name "Hello"
\end{verbatim}
\endgroup

This is due to the fact that ITcl classes double as namespaces. Therefore, the lookup of \textit{Hello} takes place first in \textit{::SampleNS::X}, followed by \textit{::} (the global namespace).

The current workaround --- to reopen the class' namespace and issue a \textit{namespace import} directive --- is of limited value since \textit{namespace import} is not capable of bringing in names defined later on. The following code illustrates this point:
\begingroup\small\begin{verbatim}
package require Itcl

namespace eval SampleNS {
    ::itcl::class X1 {
        public method GetSibling {} { return [X2 \#auto] }
    }
    namespace eval X1 { namespace import ::SampleNS }

    # Further down, or perhaps in a separate file source later:

    ::itcl::class X2 { }
}

set x [SampleNS::X1 \#auto]
$x GetSibling ;# Error: invalid command name "X2"
\end{verbatim}
\endgroup

Non-ITcl code can also make use of hierarchical namespaces to better encapsulate support procedures. In this example, the child namespace \textit{private} illustrates that the \textit{GetUniqueId} procedure should not be used outside of the package; however, \textit{GetUniqueId} still has access to the procedures and variables in the package's main namespace:
\begingroup\small\begin{verbatim}
# MyPackage

namespace eval MyPackage {
    variable nextId 0

    namespace eval private {
        proc GetUniqueId {} {
            variable nextId
            return "MyPackage.[incr nextId]"
        }
    }

    proc CreateObject {} {
        set name ::[private::GetUniqueId]
        proc $name args { body }
        return $name
    }
}
\end{verbatim}
\endgroup

\section{Specification}

Currently, the \textit{NAME RESOLUTION} section of the \textit{namespace} documentation states:

\begin{quote}
If the name does not start with a :: (i.e., is \textit{relative}), Tcl follows a fixed rule for looking it up: Command and variable names are always resolved by looking first in the current namespace, and then in the global namespace. Namespace names, on the other hand, are always resolved by looking in only the current namespace.
\end{quote}

The proposed change to this is as follows:

\begin{quote}
If the name does not start with a :: (i.e., is \textit{relative}), Tcl follows a fixed rule for looking it up: Command and variable names are always resolved by traversing the namespace hierarchy --- that is, the current namespace is examined first, followed by the parent, the parent's parent, and so on, until (finally) the global namespace is examined. Namespace names, on the other hand, are always resolved by looking in only the current namespace.
\end{quote}

By keeping the current behaviour for namespace names, this TIP affects only completely unqualified commands and variables (i.e. those that do not contain ::). Changing the behaviour of partially qualified names (those that are relative \textit{and} contain ::) is often unintuitive and can lead to unexpected errors.

\section{Consequences}
\begin{enumerate}
\item{}
ITcl classes and child namespaces can refer to command and variable names in their parent hierarchy without requiring the names to be fully qualified. This improves the intuitiveness and readability of Tcl code. In addition, it can reduce the brittleness of the code should parent namespace names undergo a change (e.g., \textit{namespace eval scriptics.com} to \textit{namespace eval ajubasolutions.com}).
\setcounter{enumi}{1}
\item{}
Currently well-defined behaviour is modified. This can break existing code if the following conditions are met:
\begin{itemize}
\item{}
The code employs the use of namespaces with a depth greater than one below the global namespace.
\item{}
The code creates a variable or procedure in a parent namespace with the same name as a variable or procedure in the global namespace.
\item{}
The code in the child namespace uses unscoped names to refer to commands and/or variables in the global namespace.
\end{itemize}

A cursory examination of existing Tcl code available on the Internet revealed no code which used deeply nested namespaces.
\setcounter{enumi}{2}
\item{}
Existing well-defined behaviour of the internal Tcl function \textit{TclGetNamespaceForQualName} is modified. Under the sample implementation, the \textit{altNsPtrPtr} parameter (which currently returns a pointer to the global namespace if a name was found there) always returns NULL. It is up to the calling functions (e.g., Tcl\_FindCommand and Tcl\_FindNamespaceVar) to traverse the hierarchy. Although the Tcl and Tk code-base can be modified to accommodate this, extensions which depend on this internal function may be broken.
\end{enumerate}

\section{Namespace History}

Namespaces were originally developed by Michael McLennan for ITcl, and apparently had this hierarchical resolution feature. When they were adopted into Tcl, an optimisation was made which led to the current behaviour.

This TIP argues for the reversal of this decision based on experiences with the new behaviour.

\section{See Also}
\begin{itemize}
\item{}
Tcl manual page \textit{namespace}.
\item{}
Tcl source code file \textit{tcl8.4a3/generic/tclNamesp.c}.
\item{}
Sample implementation at \url{http://www.kanga.org/tclnamespace/}
\end{itemize}

\section{Comments}
\begin{itemize}
\item{}
Andreas Kupries:
\begin{description}
\item[Related information]
SF entry [ \#218101 ] ``no man page for library procedures Tcl\_AddInterpResolver Tcl'' [\url{http://sourceforge.net/tracker/?func=detail&aid=218101&group_id=10894&atid=110894}]
\item[Not addressed in this TIP]
Impact on speed of the interpreter. (Seeking out mail on Tcl core where author of talks about this)
\end{description}
\end{itemize}

\section{Notice of Withdrawal}

This TIP was Withdrawn by the TIP Editor following discussion on the tcl-core mailing list. The following is a summary of reasons for withdrawal:

\begin{quote}
Insufficiently subtle. 52 will break any code that assumes the current behaviour (and you can bet someone will have that assumption) and 142 doesn't let two namespaces have different search paths (unless the variable is always interpreted locally, which just creates bizarre variable name magic.)
\end{quote}

\section{Copyright}

Copyright (c) 2001 by David Cuthbert. Distribution in whole or part, with or without annotations, is unlimited.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
