TIP: 15
Title: Functions to List and Detail Math Functions
Version: $Revision: 1.8 $
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.