util/src/TclTk/tcl8.6.12/doc/Ensemble.3

   1 '\"
   2 '\" Copyright (c) 2005 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" This documents the C API introduced in TIP#235
   8 '\"
   9 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
  10 .so man.macros
  11 .BS
  12 .SH NAME
  13 Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tcl.h>\fR
  17 .sp
  18 Tcl_Command
  19 \fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR)
  20 .sp
  21 Tcl_Command
  22 \fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR)
  23 .sp
  24 int
  25 \fBTcl_IsEnsemble\fR(\fItoken\fR)
  26 .sp
  27 int
  28 \fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR)
  29 .sp
  30 int
  31 \fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR)
  32 .sp
  33 int
  34 \fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR)
  35 .sp
  36 int
  37 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
  38 .sp
  39 .VS 8.6
  40 int
  41 \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
  42 .sp
  43 int
  44 \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
  45 .VE 8.6
  46 .sp
  47 int
  48 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
  49 .sp
  50 int
  51 \fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR)
  52 .sp
  53 int
  54 \fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR)
  55 .sp
  56 int
  57 \fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR)
  58 .sp
  59 int
  60 \fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR)
  61 .SH ARGUMENTS
  62 .AS Tcl_Namespace **namespacePtrPtr in/out
  63 .AP Tcl_Interp *interp in/out
  64 The interpreter in which the ensemble is to be created or found. Also
  65 where error result messages are written. The functions whose names
  66 start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR,
  67 but all other functions must not.
  68 .AP "const char" *name in
  69 The name of the ensemble command to be created.
  70 .AP Tcl_Namespace *namespacePtr in
  71 The namespace to which the ensemble command is to be bound, or NULL
  72 for the current namespace.
  73 .AP int ensFlags in
  74 An ORed set of flag bits describing the basic configuration of the
  75 ensemble. Currently only one bit has meaning, \fBTCL_ENSEMBLE_PREFIX\fR,
  76 which is present when the ensemble command should also match
  77 unambiguous prefixes of subcommands.
  78 .AP Tcl_Obj *cmdNameObj in
  79 A value holding the name of the ensemble command to look up.
  80 .AP int flags in
  81 An ORed set of flag bits controlling the behavior of
  82 \fBTcl_FindEnsemble\fR. Currently only \fBTCL_LEAVE_ERR_MSG\fR is supported.
  83 .AP Tcl_Command token in
  84 A normal command token that refers to an ensemble command, or which
  85 you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR.
  86 .AP int *ensFlagsPtr out
  87 Pointer to a variable into which to write the current ensemble flag
  88 bits; currently only the bit \fBTCL_ENSEMBLE_PREFIX\fR is defined.
  89 .AP Tcl_Obj *dictObj in
  90 A dictionary value to use for the subcommand to implementation command
  91 prefix mapping dictionary in the ensemble. May be NULL if the mapping
  92 dictionary is to be removed.
  93 .AP Tcl_Obj **dictObjPtr out
  94 Pointer to a variable into which to write the current ensemble mapping
  95 dictionary.
  96 .AP Tcl_Obj *listObj in
  97 A list value to use for the list of formal pre-subcommand parameters, the
  98 defined list of subcommands in the dictionary or the unknown subcommand
  99 handler command prefix. May be NULL if the subcommand list or unknown handler
 100 are to be removed.
 101 .AP Tcl_Obj **listObjPtr out
 102 Pointer to a variable into which to write the current list of formal
 103 pre-subcommand parameters, the defined list of subcommands or the current
 104 unknown handler prefix.
 105 .AP Tcl_Namespace **namespacePtrPtr out
 106 Pointer to a variable into which to write the handle of the namespace
 107 to which the ensemble is bound.
 108 .BE
 109 .SH DESCRIPTION
 110 An ensemble is a command, bound to some namespace, which consists of a
 111 collection of subcommands implemented by other Tcl commands. The first
 112 argument to the ensemble command is always interpreted as a selector
 113 that states what subcommand to execute.
 114 .PP
 115 Ensembles are created using \fBTcl_CreateEnsemble\fR, which takes four
 116 arguments: the interpreter to work within, the name of the ensemble to
 117 create, the namespace within the interpreter to bind the ensemble to,
 118 and the default set of ensemble flags. The result of the function is
 119 the command token for the ensemble, which may be used to further
 120 configure the ensemble using the API described below in
 121 \fBENSEMBLE PROPERTIES\fR.
 122 .PP
 123 Given the name of an ensemble command, the token for that command may
 124 be retrieved using \fBTcl_FindEnsemble\fR. If the given command name
 125 (in \fIcmdNameObj\fR) does not refer to an ensemble command, the
 126 result of the function is NULL and (if the \fBTCL_LEAVE_ERR_MSG\fR bit is
 127 set in \fIflags\fR) an error message is left in the interpreter
 128 result.
 129 .PP
 130 A command token may be checked to see if it refers to an ensemble
 131 using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an
 132 ensemble, or 0 otherwise.
 133 .SS "ENSEMBLE PROPERTIES"
 134 Every ensemble has four read-write properties and a read-only
 135 property. The properties are:
 136 .TP
 137 \fBflags\fR (read-write)
 138 .
 139 The set of flags for the ensemble, expressed as a
 140 bit-field. Currently, the only public flag is \fBTCL_ENSEMBLE_PREFIX\fR
 141 which is set when unambiguous prefixes of subcommands are permitted to
 142 be resolved to implementations as well as exact matches. The flags may
 143 be read and written using \fBTcl_GetEnsembleFlags\fR and
 144 \fBTcl_SetEnsembleFlags\fR respectively. The result of both of those
 145 functions is a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if
 146 the token does not refer to an ensemble).
 147 .TP
 148 \fBmapping dictionary\fR (read-write)
 149 .
 150 A dictionary containing a mapping from subcommand names to lists of
 151 words to use as a command prefix (replacing the first two words of the
 152 command which are the ensemble command itself and the subcommand
 153 name), or NULL if every subcommand is to be mapped to the command with
 154 the same unqualified name in the ensemble's bound namespace. Defaults
 155 to NULL. May be read and written using
 156 \fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR
 157 respectively. The result of both of those functions is a Tcl result
 158 code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an
 159 ensemble) and the dictionary obtained from
 160 \fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable
 161 even if it is unshared.
 162 All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
 163 must be fully qualified.
 164 .TP
 165 \fBformal pre-subcommand parameter list\fR (read-write)
 166 .VS 8.6
 167 A list of formal parameter names (the names only being used when generating
 168 error messages) that come at invocation of the ensemble between the name of
 169 the ensemble and the subcommand argument. NULL (the default) is equivalent to
 170 the empty list. May be read and written using
 171 \fBTcl_GetEnsembleParameterList\fR and \fBTcl_SetEnsembleParameterList\fR
 172 respectively. The result of both of those functions is a Tcl result code
 173 (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an
 174 ensemble) and the
 175 dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
 176 treated as immutable even if it is unshared.
 177 .VE 8.6
 178 .TP
 179 \fBsubcommand list\fR (read-write)
 180 .
 181 A list of all the subcommand names for the ensemble, or NULL if this
 182 is to be derived from either the keys of the mapping dictionary (see
 183 above) or (if that is also NULL) from the set of commands exported by
 184 the bound namespace. May be read and written using
 185 \fBTcl_GetEnsembleSubcommandList\fR and
 186 \fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
 187 of those functions is a Tcl result code (\fBTCL_OK\fR, or
 188 \fBTCL_ERROR\fR if the
 189 token does not refer to an ensemble) and the list obtained from
 190 \fBTcl_GetEnsembleSubcommandList\fR should always be treated as
 191 immutable even if it is unshared.
 192 .TP
 193 \fBunknown subcommand handler command prefix\fR (read-write)
 194 .
 195 A list of words to prepend on the front of any subcommand when the
 196 subcommand is unknown to the ensemble (according to the current prefix
 197 handling rule); see the \fBnamespace ensemble\fR command for more
 198 details. If NULL, the default behavior \- generate a suitable error
 199 message \- will be used when an unknown subcommand is encountered. May
 200 be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and
 201 \fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both
 202 functions is a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if
 203 the token does
 204 not refer to an ensemble) and the list obtained from
 205 \fBTcl_GetEnsembleUnknownHandler\fR should always be treated as
 206 immutable even if it is unshared.
 207 .TP
 208 \fBbound namespace\fR (read-only)
 209 .
 210 The namespace to which the ensemble is bound; when the namespace is
 211 deleted, so too will the ensemble, and this namespace is also the
 212 namespace whose list of exported commands is used if both the mapping
 213 dictionary and the subcommand list properties are NULL. May be read
 214 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
 215 (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble).
 216 .SH "SEE ALSO"
 217 namespace(n), Tcl_DeleteCommandFromToken(3)
 218 .SH KEYWORDS
 219 command, ensemble