# TIP 15: Functions to List and Detail Math Functions
Author: Donal K. Fellows <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 22-Nov-2000
Post-History:
Keywords: Tcl,expr,function,introspection
Tcl-Version: 8.4.0
-----
# Abstract
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.
# 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
<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ôle;
_Tcl\_GetMathFuncInfo_ and _Tcl\_ListMathFuncs_. These functions
will be documented on the same manual page as _Tcl\_CreateMathFunc_
and implemented in the same file.
Furthermore, I also propose that the _info_ command in the Tcl
interpreter be extended to include a new subcommand, _functions_,
which will allow Tcl scripts to discover the list of installed
functions \(by acting as a thin veneer over _Tcl\_ListMathFuncs_.\)
Note that this is an extension of the _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: _expr_,
_for_, _if_ and _while_.
# 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 _Tcl\_CreateMathFunc_, and will return a standard
Tcl result \(either _TCL\_OK_ or _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
_TCL\_ERROR_ case.\) The array of argument types whose reference is
placed into the variable pointed to by _argTypesPtr_ will be
allocated by Tcl, and should be freed with _Tcl\_Free_.
int Tcl_GetMathFuncInfo(Tcl_Interp *interp, CONST char *name,
int *numArgsPtr, Tcl_ValueType **argTypesPtr,
Tcl_MathProc **procPtr,
ClientData *clientDataPtr);
The parameter names are chosen by analogy with _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
_procPtr_ argument will be NULL.
# 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
_NULL_ indicating that no filtering is desired.\) The function will
return a pointer to a newly-allocated _Tcl\_Obj_ list of the names of
all the math functions defined within that interpreter, or _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.
Tcl_Obj *Tcl_ListMathFuncs(Tcl_Interp *interp, CONST char *pattern);
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 _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.
# info functions
This new subcommand will provide access from Tcl scripts to the
functionality of _Tcl\_ListMathFuncs_. It will take a single optional
argument consisting of a pattern to pass on as the _pattern_ argument
\(with the absence of the argument indicating that NULL is to be passed
instead.\)
# Copyright
This document is placed in the public domain.