Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
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