\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#261: Return Imported Commands from [namespace import]}
\date{December 20, 2005}
\author{Martin Lemburg, }
\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 \#261}&\textbf{Return Imported Commands from [namespace import]}\\\hline
Author&

Martin Lemburg \tipmail{martin.lemburg}{gmx.net}
\par
\tipmail{dgp}{users.sf.net}
\\
Created&Tuesday, \(\text{20}^{\text{th}}\) December 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 describes a mechanism for easily finding out the list of commands in the current namespace that have been imported from other namespaces.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

While writing a profiling and introspection module for our C++/Tcl application, I searched for ways to query all the exported and imported commands of a namespace.

Although I found the introspection functionality for discovering all exported commands of a namespace using \textbf{namespace export} in the exporting namespace, I found no way to query all imported commands inside the importing namespace.

The documentation of \textbf{namespace import} said nothing about the behaviour, if no arguments were given, and testing \textbf{namespace import} without arguments resulted in nothing, in a no-op.

Prompted by this, I started a thread in \url{news:comp.lang.tcl} which goes into more detail [\url{http://groups.google.com/group/comp.lang.tcl/browse_frm/thread/9fb246cf65aba54f?tvc=1}].

What seems to be more logical to me would be to change the no-op behaviour of \textbf{namespace import} to be comparable to \textbf{namespace export}, and return all imported commands inside the namespace \textbf{namespace import} is executed in.

As an example...
\begin{itemize}
\item{}
to get all exported commands of a namespace ::exportingNspc:
\begingroup\small\begin{verbatim}
 namespace inscope ::exportingNspc {namespace export}
\end{verbatim}
\endgroup
\item{}
to get all imported commands of the namespace ::importingNspc:
\begingroup\small\begin{verbatim}
 namespace inscope ::importingNspc {namespace import}
\end{verbatim}
\endgroup
\end{itemize}

\section{Consequences}

The only consequence I know is, that old scripts using the no-op \textbf{namespace import} suddenly will return a list, probably filled with names of imported commands. That's all.

Because of the fact, that \textbf{namespace import} never returned values, no script should really break, thus no script should require values from this command.

\section{Proposed Change}

The result of \textbf{namespace import} without arguments shall be a list of all commands that have been imported into the current namespace. Each command in the list will be the simple name by which the command is known in the current namespace. This format for the returned value is most useful because it composes well with \textbf{namespace forget}. To remove all imported commands from a namespace, use the command
\begingroup\small\begin{verbatim}
 namespace forget {*}[namespace import]
\end{verbatim}
\endgroup

\section{Implementation}

A patch implementing an earlier draft is available, [\url{http://sf.net/tracker/?func=detail&aid=1437008&group_id=10894&atid=310894}], and updated patches will be attached to the same Tracker report.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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