TIP 426: Determining the "Type" of Commands

Login
Home Timeline Branches Tags Help 
State:		Final
Type:		Project
Tcl-Version:	8.7
Vote:		Done
Post-History:	
Author:		Donal K. Fellows <[email protected]>
Created:	31-Jul-2013
Keywords:	introspection, commands, Tcl, Tk
Vote-Results:   4/2/3 accepted
Votes-For:      DKF, BG, JN, JD
Votes-Against:  DGP, AK
Votes-Present:  KBK, FV, SL
Tcl-Branch:     dkf-command-type

Abstract

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 info body, namespace origin or interp alias.

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.

Proposed Change

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

info cmdtype commandName

The new info subcommand is to be called cmdtype (the name is chosen so as to not conflict with abbreviations info commands even though it does conflict with info cmdcount) and it takes a single argument, 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 commandName is; if no other information is available, the result shall be 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.

Supporting C API

The supporting public C functions shall be:

void Tcl_RegisterCommandTypeName(Tcl_ObjCmdProc *implementationProc, const char *nameStr)

const char * Tcl_GetCommandTypeName(Tcl_Command command)

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

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

Predefined Command Types

The following command types are guaranteed to be among the set defined by default, but others may be done as well.

proc: Procedures defined by the proc command. Introspection commands like info body may be used (without error due to the command not being a procedure).

alias: Aliases defined by the interp alias command, which will be able to perform introspection on it. Inter-interpreter aliases are not required to report themselves this way to the slave interpreter.

ensemble: Ensembles defined by the namespace ensemble command.

import: Commands imported by the namespace import command.

object: Object (or class) defined by instantiating any TclOO class. The introspection command info object may be used (without error due to the command not being an object).

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 tk::; that prefix 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 may declare themselves to be of type tk::widgetFactory.

Copyright

This document has been placed in the public domain.