\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#15: Functions to List and Detail Math Functions}
\date{November 22, 2000}
\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 \#15}&\textbf{Functions to List and Detail Math Functions}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\\
Created&Wednesday, \(\text{22}^{\text{nd}}\) November 2000\\
Type&Project\\
Tcl Version&\(8.4.0\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Keywords&Tcl, expr, function, introspection\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Provides a way for the list of all math functions defined in the current interpreter to be discovered, and for discovering what arguments might be passed to an existing math function. This may be useful in tests as well as more general use.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Although it is quite easy to define a new function for use in expressions, there is no public way of performing introspection on this information. Having a way to extract the arguments from an existing math function was requested by \url{http://sourceforge.net/bugs/?func=detailbug&bug_id=119304&group_id=10894} and once you have one, it becomes trivial to also ask for a second function to list what functions are defined.

I propose the creation of two functions that fulfil this r\^{o}le; \textit{Tcl\_GetMathFuncInfo} and \textit{Tcl\_ListMathFuncs}. These functions will be documented on the same manual page as \textit{Tcl\_CreateMathFunc} and implemented in the same file.

Furthermore, I also propose that the \textit{info} command in the Tcl interpreter be extended to include a new subcommand, \textit{functions}, which will allow Tcl scripts to discover the list of installed functions (by acting as a thin veneer over \textit{Tcl\_ListMathFuncs}.) Note that this is an extension of the \textit{info} command because it allows for introspection of a system that affects the behaviour of several commands that form the core part of the command-set: \textit{expr}, \textit{for}, \textit{if} and \textit{while}.

\section{Tcl\_GetMathFuncInfo}

This function will take an interpreter reference, a function name (as a string) and pointers to variables capable of taking each of the last four arguments to \textit{Tcl\_CreateMathFunc}, and will return a standard Tcl result (either \textit{TCL\_OK} or \textit{TCL\_ERROR}, depending on whether a function with the given name exists within the given interpreter, with an error message being left in the interpreter's result in the \textit{TCL\_ERROR} case.) The array of argument types whose reference is placed into the variable pointed to by \textit{argTypesPtr} will be allocated by Tcl, and should be freed with \textit{Tcl\_Free}.
\begingroup\small\begin{verbatim}
int Tcl_GetMathFuncInfo(Tcl_Interp *interp, CONST char *name,
                        int *numArgsPtr, Tcl_ValueType **argTypesPtr,
                        Tcl_MathProc **procPtr,
                        ClientData *clientDataPtr);
\end{verbatim}
\endgroup

The parameter names are chosen by analogy with \textit{Tcl\_CreateMathFunc}.

In the case where a math function is defined internally by the bytecode engine and has no standard implementation (all the builtin functions in 8.4a2 are like this) the value placed in the variable indicated by the \textit{procPtr} argument will be NULL.

\section{Tcl\_ListMathFuncs}

This function will take an interpreter reference and an optional string that describes a glob-like pattern that restricts the set of math functions that the caller is interested in receiving (with a \textit{NULL} indicating that no filtering is desired.) The function will return a pointer to a newly-allocated \textit{Tcl\_Obj} list of the names of all the math functions defined within that interpreter, or \textit{NULL} in the case of an error (in which case a suitable message will be left in the interpreter.) The list will not be required to be sorted.
\begingroup\small\begin{verbatim}
Tcl_Obj *Tcl_ListMathFuncs(Tcl_Interp *interp, CONST char *pattern);
\end{verbatim}
\endgroup

The alternative is to pass in the addresses of variables that will be updated to contain the number of functions and an array of function names. But I prefer the \textit{Tcl\_Obj} approach as it is expressing the fact that the list of function names is really a single thing being returned (albeit one that is not a simple value.) It is not anticipated that the performance of this function will need to be crucial to too many applications.

\section{info functions}

This new subcommand will provide access from Tcl scripts to the functionality of \textit{Tcl\_ListMathFuncs}. It will take a single optional argument consisting of a pattern to pass on as the \textit{pattern} argument (with the absence of the argument indicating that NULL is to be passed instead.)

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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