diff options
Diffstat (limited to 'doc/Ensemble.3')
| -rw-r--r-- | doc/Ensemble.3 | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 new file mode 100644 index 0000000..dca164d --- /dev/null +++ b/doc/Ensemble.3 @@ -0,0 +1,188 @@ +'\" +'\" Copyright (c) 2005 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: Ensemble.3,v 1.5.2.1 2009/11/27 14:53:54 dkf Exp $ +'\" +'\" This documents the C API introduced in TIP#235 +'\" +.so man.macros +.TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +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 +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +Tcl_Command +\fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR) +.sp +Tcl_Command +\fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR) +.sp +int +\fBTcl_IsEnsemble\fR(\fItoken\fR) +.sp +int +\fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR) +.sp +int +\fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR) +.sp +int +\fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR) +.sp +int +\fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR) +.sp +int +\fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR) +.sp +int +\fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR) +.sp +int +\fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR) +.sp +int +\fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR) +.sp +int +\fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR) +.SH ARGUMENTS +.AS Tcl_Namespace **namespacePtrPtr in/out +.AP Tcl_Interp *interp in/out +The interpreter in which the ensemble is to be created or found. Also +where error result messages are written. The functions whose names +start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR, +but all other functions must not. +.AP "const char" *name in +The name of the ensemble command to be created. +.AP Tcl_Namespace *namespacePtr in +The namespace to which the ensemble command is to be bound, or NULL +for the current namespace. +.AP int ensFlags in +An ORed set of flag bits describing the basic configuration 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. +.AP Tcl_Obj *cmdNameObj in +A value holding the name of the ensemble command to look up. +.AP int flags in +An ORed set of flag bits controlling the behavior of +\fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported. +.AP Tcl_Command token in +A normal command token that refers to an ensemble command, or which +you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR. +.AP 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. +.AP Tcl_Obj *dictObj in +A dictionary value to use for the subcommand to implementation command +prefix mapping dictionary in the ensemble. May be NULL if the mapping +dictionary is to be removed. +.AP Tcl_Obj **dictObjPtr out +Pointer to a variable into which to write the current ensemble mapping +dictionary. +.AP Tcl_Obj *listObj in +A list value to use for the defined list of subcommands in the +dictionary or the unknown subcommmand handler command prefix. May be +NULL if the subcommand list or unknown handler are to be removed. +.AP Tcl_Obj **listObjPtr out +Pointer to a variable into which to write the current defiend list of +subcommands or the current unknown handler prefix. +.AP Tcl_Namespace **namespacePtrPtr out +Pointer to a variable into which to write the handle of the namespace +to which the ensemble is bound. +.BE + +.SH DESCRIPTION +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 to execute. +.PP +Ensembles are created using \fBTcl_CreateEnsemble\fR, 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 \fBENSEMBLE +PROPERTIES\fR. +.PP +Given the name of an ensemble command, the token for that command may +be retrieved using \fBTcl_FindEnsemble\fR. If the given command name +(in \fIcmdNameObj\fR) 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 \fIflags\fR) an error message is left in the interpreter +result. +.PP +A command token may be checked to see if it refers to an ensemble +using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an +ensemble, or 0 otherwise. +.SS "ENSEMBLE PROPERTIES" +Every ensemble has four read-write properties and a read-only +property. The properties are: +.TP +\fBflags\fR (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 prefixes of subcommands are permitted to +be resolved to implementations as well as exact matches. The flags may +be read and written using \fBTcl_GetEnsembleFlags\fR and +\fBTcl_SetEnsembleFlags\fR 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). +.TP +\fBmapping dictionary\fR (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 ensemble 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 +\fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR +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 dictionary obtained from +\fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable +even if it is unshared. +.TP +\fBsubcommand list\fR (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 +\fBTcl_GetEnsembleSubcommandList\fR and +\fBTcl_SetEnsembleSubcommandList\fR 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 +\fBTcl_GetEnsembleSubcommandList\fR should always be treated as +immutable even if it is unshared. +.TP +\fBunknown subcommand handler command prefix\fR (read-write) +A list of words to prepend on the front of any subcommand when the +subcommand is unknown to the ensemble (according to the current prefix +handling rule); see the \fBnamespace ensemble\fR 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 \fBTcl_GetEnsembleUnknownHandler\fR and +\fBTcl_SetEnsembleUnknownHandler\fR 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 +\fBTcl_GetEnsembleUnknownHandler\fR should always be treated as +immutable even if it is unshared. +.TP +\fBbound namespace\fR (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 +dictionary and the subcommand list properties are NULL. May be read +using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code +(TCL_OK, or TCL_ERROR if the token does not refer to an ensemble). + +.SH "SEE ALSO" +namespace(n), Tcl_DeleteCommandFromToken(3) |