\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#426: Determining the "Type" of Commands}
\date{July 31, 2013}
\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 \#426}&\textbf{Determining the "Type" of Commands}\\\hline
Author&

Donal K. Fellows \tipmail{dkf}{users.sf.net}
\\
Created&Wednesday, \(\text{31}^{\text{st}}\) July 2013\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.2 $\\
Keywords&introspection, commands, Tcl, Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP describes a mechanism for determining what ``type'' of command a particular command is. This can be used as a prelude to performing other kinds of introspection, such as using \textbf{info body}, \textbf{namespace origin} or \textbf{interp alias}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Currently, in order to find out information about an arbitrary command you have to apply a suitable introspection command and deal with any errors arising in order to tell that you had a command of some other type. It was made clear to me at EuroTcl 2013 that this was inelegant, especially since we in principle had the information available to do something neater.

The information in question is the pointer to the implementation function, that's stored in the C record describing the command. All that is needed is a way to surface that information to Tcl as a new introspection command.

\section{Proposed Change}

This new introspection interface shall consist of one new subcommand of \textbf{info} and a pair of new public C functions.

\begin{quote}
\textbf{info cmdtype} \textit{commandName}
\end{quote}

The new \textbf{info} subcommand is to be called \textbf{cmdtype} (the name is chosen so as to not conflict with abbreviations \textbf{info commands} even though it does conflict with \textbf{info cmdcount}) and it takes a single argument, \textit{commandName}, which must be the name of an existing Tcl command. The result of this subcommand shall be a string describing what sort of command \textit{commandName} is; if no other information is available, the result shall be \textbf{native}.

NB: The Tcl implementation will not make any guarantees of the command type for any particular command supplied by default in any interpreter. User code should never assume that just because a command is implemented one way in one particular version that it will continue to be implemented that way in any future version.

\subsection{Supporting C API}

The supporting public C functions shall be:

\begin{quote}
void \textbf{Tcl\_RegisterCommandTypeName}(Tcl\_ObjCmdProc *\textit{implementationProc}, const char *\textit{nameStr})
\end{quote}

\begin{quote}
const char * \textbf{Tcl\_GetCommandTypeName}(Tcl\_Command \textit{command})
\end{quote}

\textbf{Tcl\_RegisterCommandTypeName} will associate a particular implementation function, \textit{implementationProc}, with an (assumed literal constant) string, \textit{nameStr}; if \textit{nameStr} is supplied as NULL, the mapping for \textit{implementationProc} will be removed. The \textit{implementationProc} argument must not be NULL. The use of a package prefix within the name is \textit{recommended}.

\textbf{Tcl\_GetCommandTypeName} shall take a command handle, \textit{command}, and return the registered type name string (as previously passed to Tcl\_RegisterCommandTypeName) for the command implementation function that the \textit{command} is using. If there is no type name registered for the command's implementation function, the literal string \textbf{native} will be returned instead. The result will never be NULL.

\subsection{Predefined Command Types}

The following command types are guaranteed to be among the set defined by default, but others may be done as well.
\begin{description}
\item[proc]
Procedures defined by the \textbf{proc} command.
\item[alias]
Aliases defined by the \textbf{interp alias} command.
\item[ensemble]
Ensembles defined by the \textbf{namespace ensemble} command.
\item[import]
Commands imported by the \textbf{namespace import} command.
\item[object]
Object (or class) defined by instantiating any TclOO class.
\end{description}

\subsection{Impact on Tk}

It is anticipated that Tk widget instances will report themselves through this mechanism as well, with a prefix to their names of \textbf{tk::}; that prefix \textit{should not} be used by any other package. Note however that not all widget types will be distinguishable; this is part of the way that Tk is implemented.

The built-in widget creation functions \textit{may} declare themselves to be of type \textbf{tk::widgetFactory}.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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