|
|
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3) _________________________________________________________________
Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags,
Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace,
Tcl_GetEnsembleUnknownHandler,
Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble,
Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict,
Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler
- manipulate ensemble commands
#include <tcl.h>
Tcl_Command
Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)
Tcl_Command
Tcl_FindEnsemble(interp, cmdNameObj, flags)
int
Tcl_IsEnsemble(token)
int
Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)
int
Tcl_SetEnsembleFlags(interp, token, ensFlags)
int
Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)
int
Tcl_SetEnsembleMappingDict(interp, token, dictObj)
int
Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)
int
Tcl_SetEnsembleSubcommandList(interp, token, listObj)
int
Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
int
Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
int
Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)
Tcl_Interp *interp (in/out) The
Tcl Last change: 8.5 1
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
interpreter in
which the
ensemble is to
be created or
found. Also
where error
result mes-
sages are
written. The
functions
whose names
start with
Tcl_GetEnsemble
may have a
NULL for the
interp, but
all other
functions must
not.
const char *name (in) The name of
the ensemble
command to be
created.
Tcl_Namespace *namespacePtr (in) The namespace
to which the
ensemble com-
mand is to be
bound, or NULL
for the
current
namespace.
int ensFlags (in) An ORed set of
flag bits
describing the
basic confi-
guration of
the ensemble.
Currently only
one bit has
meaning,
TCL_ENSEMBLE_PREFIX,
which is
present when
the ensemble
command should
also match
unambiguous
prefixes of
subcommands.
Tcl Last change: 8.5 2
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
Tcl_Obj *cmdNameObj (in) A value hold-
ing the name
of the ensem-
ble command to
look up.
int flags (in) An ORed set of
flag bits con-
trolling the
behavior of
Tcl_FindEnsemble.
Currently only
TCL_LEAVE_ERR_MSG
is supported.
Tcl_Command token (in) A normal com-
mand token
that refers to
an ensemble
command, or
which you wish
to use for
testing as an
ensemble com-
mand in
Tcl_IsEnsemble.
int *ensFlagsPtr (out) Pointer to a
variable into
which to write
the current
ensemble flag
bits;
currently only
the bit
TCL_ENSEMBLE_PREFIX
is defined.
Tcl_Obj *dictObj (in) A dictionary
value to use
for the sub-
command to
implementation
command prefix
mapping dic-
tionary in the
ensemble. May
be NULL if the
mapping dic-
tionary is to
be removed.
Tcl Last change: 8.5 3
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
Tcl_Obj **dictObjPtr (out) Pointer to a
variable into
which to write
the current
ensemble map-
ping diction-
ary.
Tcl_Obj *listObj (in) A list value
to use for the
defined list
of subcommands
in the dic-
tionary or the
unknown sub-
commmand
handler com-
mand prefix.
May be NULL if
the subcommand
list or
unknown
handler are to
be removed.
Tcl_Obj **listObjPtr (out) Pointer to a
variable into
which to write
the current
defiend list
of subcommands
or the current
unknown
handler pre-
fix.
Tcl_Namespace **namespacePtrPtr (out) Pointer to a
variable into
which to write
the handle of
the namespace
to which the
ensemble is
bound.
_________________________________________________________________
An ensemble is a command, bound to some namespace, which
consists of a collection of subcommands implemented by other
Tcl commands. The first argument to the ensemble command is
always interpreted as a selector that states what subcommand
Tcl Last change: 8.5 4
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
to execute.
Ensembles are created using Tcl_CreateEnsemble, which takes
four arguments: the interpreter to work within, the name of
the ensemble to create, the namespace within the interpreter
to bind the ensemble to, and the default set of ensemble
flags. The result of the function is the command token for
the ensemble, which may be used to further configure the
ensemble using the API described below in ENSEMBLE PROPER-
TIES.
Given the name of an ensemble command, the token for that
command may be retrieved using Tcl_FindEnsemble. If the
given command name (in cmdNameObj) does not refer to an
ensemble command, the result of the function is NULL and (if
the TCL_LEAVE_ERR_MSG bit is set in flags) an error message
is left in the interpreter result.
A command token may be checked to see if it refers to an
ensemble using Tcl_IsEnsemble. This returns 1 if the token
refers to an ensemble, or 0 otherwise.
ENSEMBLE PROPERTIES
Every ensemble has four read-write properties and a read-
only property. The properties are:
flags (read-write)
The set of flags for the ensemble, expressed as a bit-
field. Currently, the only public flag is
TCL_ENSEMBLE_PREFIX which is set when unambiguous pre-
fixes of subcommands are permitted to be resolved to
implementations as well as exact matches. The flags may
be read and written using Tcl_GetEnsembleFlags and
Tcl_SetEnsembleFlags respectively. The result of both
of those functions is a Tcl result code (TCL_OK, or
TCL_ERROR if the token does not refer to an ensemble).
mapping dictionary (read-write)
A dictionary containing a mapping from subcommand names
to lists of words to use as a command prefix (replacing
the first two words of the command which are the ensem-
ble command itself and the subcommand name), or NULL if
every subcommand is to be mapped to the command with
the same unqualified name in the ensemble's bound
namespace. Defaults to NULL. May be read and written
using Tcl_GetEnsembleMappingDict and
Tcl_SetEnsembleMappingDict respectively. The result of
both of those functions is a Tcl result code (TCL_OK,
or TCL_ERROR if the token does not refer to an ensem-
ble) and the dictionary obtained from
Tcl_GetEnsembleMappingDict should always be treated as
immutable even if it is unshared. All command names in
Tcl Last change: 8.5 5
Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
prefixes set via Tcl_SetEnsembleMappingDict must be
fully qualified.
subcommand list (read-write)
A list of all the subcommand names for the ensemble, or
NULL if this is to be derived from either the keys of
the mapping dictionary (see above) or (if that is also
NULL) from the set of commands exported by the bound
namespace. May be read and written using
Tcl_GetEnsembleSubcommandList and
Tcl_SetEnsembleSubcommandList respectively. The result
of both of those functions is a Tcl result code
(TCL_OK, or TCL_ERROR if the token does not refer to an
ensemble) and the list obtained from
Tcl_GetEnsembleSubcommandList should always be treated
as immutable even if it is unshared.
unknown subcommand handler command prefix (read-write)
A list of words to prepend on the front of any subcom-
mand when the subcommand is unknown to the ensemble
(according to the current prefix handling rule); see
the namespace ensemble command for more details. If
NULL, the default behavior - generate a suitable error
message - will be used when an unknown subcommand is
encountered. May be read and written using
Tcl_GetEnsembleUnknownHandler and
Tcl_SetEnsembleUnknownHandler respectively. The result
of both functions is a Tcl result code (TCL_OK, or
TCL_ERROR if the token does not refer to an ensemble)
and the list obtained from
Tcl_GetEnsembleUnknownHandler should always be treated
as immutable even if it is unshared.
bound namespace (read-only)
The namespace to which the ensemble is bound; when the
namespace is deleted, so too will the ensemble, and
this namespace is also the namespace whose list of
exported commands is used if both the mapping diction-
ary and the subcommand list properties are NULL. May be
read using Tcl_GetEnsembleNamespace which returns a Tcl
result code (TCL_OK, or TCL_ERROR if the token does not
refer to an ensemble).
namespace(n), Tcl_DeleteCommandFromToken(3)
Tcl Last change: 8.5 6