TIP #235 Version 1.3: Exposing a C API for Ensembles

This is not necessarily the current version of this TIP.

Abstract

This TIP exposes a C API for the ensembles of TIP #112.

Rationale

As the Tcl core moves to make more use of ensembles, it becomes more necessary for there to be an API available to allow control over those ensembles from the C level so that it is not necessary for such manipulation to be done through the evaluation of Tcl scripts (e.g. because this interferes with the interpreter's command count and that may be limited in that particular interpreter). Given such an API, it should be exposed to code outside the Tcl core if at all possible.

Proposed Change

This TIP proposes exposing the following functions:

Tcl_CreateEnsemble(interp, name, namespacePtr, flags)

Create an ensemble linked to a particular namespace and return the command token for the namespace command.

Tcl_FindEnsemble(interp, objPtr, flags)

Locate a command token for an ensemble. Has an argument that controls whether failure to find an ensemble is an error.

Tcl_IsEnsemble(token)

Test whether a command token refers to an ensemble.

Tcl_GetEnsembleSubcommandList(interp,token,objPtrPtr), Tcl_SetEnsembleSubcommandList(interp,token,objPtr)

Read and write the (fixed) list of subcommands of the ensemble. Equivalent to manipulating the -subcommands option.

Tcl_GetEnsembleMappingDict(interp,token,objPtrPtr), Tcl_SetEnsembleMappingDict(interp,token,objPtr)

Read and write the dictionary that maps subcommands to prefixes of implementation commands. Equivalent to manipulating the -map option.

Tcl_GetEnsembleUnknownHandler(interp,token,objPtrPtr), Tcl_SetEnsembleUnknownHandler(interp,token,objPtr)

Read and write the command prefix list that is used to implement the unknown-subcommand handler. Equivalent to manipulating the -unknown option.

Tcl_GetEnsembleFlags(interp,token,flagsPtr), Tcl_SetEnsembleFlags(interp,token,flags)

Read and write the flags for the ensemble. Currently there is only one settable flag bit, TCL_ENSEMBLE_PREFIX, which is present exactly when -prefix option is true.

Tcl_GetEnsembleNamespace(interp,token,namespacePtrPtr)

Reads the namespace associated with the ensemble; this value may not be altered.

Reference Implementation

The API is already in the core, but with internal naming and not exposed to anyone. Exposure is just renaming a few functions and putting them in the stubs table. No new types are exposed. All this means that a reference implementation is truly trivial.

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.