TIP: 235
Title: Exposing a C API for Ensembles
Version: $Revision: 1.9 $
Author: Donal K. Fellows <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 10-Dec-2004
Post-History:
Tcl-Version: 8.5
~ Abstract
This TIP exposes a C API for the ensembles of [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: Create an ensemble linked to a particular
namespace and return the command token for the namespace command.
The ''flags'' argument specifies the initial version of the set of
flags controllable through Tcl_SetEnsembleFlags (see below).
> > Tcl_Command '''Tcl_CreateEnsemble'''(Tcl_Interp *''interp'', const char *''name'', Tcl_Namespace *''namespacePtr'', int ''flags'')
Tcl_FindEnsemble: Return a command token for an ensemble, or NULL if
the name does not refer to an ensemble. The ''flags'' argument
controls whether failure to find an ensemble is an error and should
be either 0 or TCL_LEAVE_ERR_MSG.
> > Tcl_Command '''Tcl_FindEnsemble'''(Tcl_Interp *''interp'', Tcl_Obj *''cmdNameObj'', int ''flags'')
Tcl_IsEnsemble: Test whether a command token refers to an ensemble.
> > int '''Tcl_IsEnsemble'''(Tcl_Command ''command'')
Tcl_GetEnsembleSubcommandList, Tcl_SetEnsembleSubcommandList: Read
and write the (fixed) list of subcommands of the ensemble.
Equivalent to manipulating the '''-subcommands''' option.
> > int '''Tcl_GetEnsembleSubcommandList'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj **''subcmdListObjPtr'')
> > int '''Tcl_SetEnsembleSubcommandList'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj *''subcmdListObj'')
Tcl_GetEnsembleMappingDict, Tcl_SetEnsembleMappingDict: Read and
write the dictionary that maps subcommands to prefixes of
implementation commands. Equivalent to manipulating the '''-map'''
option.
> > int '''Tcl_GetEnsembleMappingDict'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj **''mapDictObjPtr'')
> > int '''Tcl_SetEnsembleMappingDict'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj *''mapDictObj'')
Tcl_GetEnsembleUnknownHandler, Tcl_SetEnsembleUnknownHandler: Read
and write the command prefix list that is used to implement the
unknown-subcommand handler. Equivalent to manipulating the
'''-unknown''' option.
> > int '''Tcl_GetEnsembleUnknownHandler'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj **''handlerListObjPtr'')
> > int '''Tcl_SetEnsembleUnknownHandler'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Obj *''handlerListObj'')
Tcl_GetEnsembleFlags, Tcl_SetEnsembleFlags: 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.
> > int '''Tcl_GetEnsembleFlags'''(Tcl_Interp *''interp'', Tcl_Command ''command'', int *''flagsPtr'')
> > int '''Tcl_SetEnsembleFlags'''(Tcl_Interp *''interp'', Tcl_Command ''command'', int ''flags'')
Tcl_GetEnsembleNamespace: Reads the namespace associated with the
ensemble; this value may not be altered.
> > int '''Tcl_GetEnsembleNamespace'''(Tcl_Interp *''interp'', Tcl_Command ''command'', Tcl_Namespace **''namespacePtrPtr'')
~~ Notes
The handle for an ensemble is a normal Tcl_Command handle, and any
operation valid on such a command (e.g. deleting it or finding its name)
is valid. Ensembles are just a special subclass of commands. This allows
the ensemble API to be considerably sparser than it would otherwise have
to be.
~ 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.