hostdepend/X86MAC64/util/X86MAC64/man/man3/Tcl_GetEnsembleFlags.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 '\" RCS: @(#) $Id: Ensemble.3,v 1.5 2007/12/13 15:22:31 dgp Exp $
   8 '\"
   9 '\" This documents the C API introduced in TIP#235
  10 '\"
  11 .\" The -*- nroff -*- definitions below are for supplemental macros used
  12 .\" in Tcl/Tk manual entries.
  13 .\"
  14 .\" .AP type name in/out ?indent?
  15 .\"     Start paragraph describing an argument to a library procedure.
  16 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  17 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  18 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  19 .\"     needed;  use .AS below instead)
  20 .\"
  21 .\" .AS ?type? ?name?
  22 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  23 .\"     name are examples of largest possible arguments that will be passed
  24 .\"     to .AP later.  If args are omitted, default tab stops are used.
  25 .\"
  26 .\" .BS
  27 .\"     Start box enclosure.  From here until next .BE, everything will be
  28 .\"     enclosed in one large box.
  29 .\"
  30 .\" .BE
  31 .\"     End of box enclosure.
  32 .\"
  33 .\" .CS
  34 .\"     Begin code excerpt.
  35 .\"
  36 .\" .CE
  37 .\"     End code excerpt.
  38 .\"
  39 .\" .VS ?version? ?br?
  40 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  41 .\"     of man pages.  The first argument is ignored and used for recording
  42 .\"     the version when the .VS was added, so that the sidebars can be
  43 .\"     found and removed when they reach a certain age.  If another argument
  44 .\"     is present, then a line break is forced before starting the sidebar.
  45 .\"
  46 .\" .VE
  47 .\"     End of vertical sidebar.
  48 .\"
  49 .\" .DS
  50 .\"     Begin an indented unfilled display.
  51 .\"
  52 .\" .DE
  53 .\"     End of indented unfilled display.
  54 .\"
  55 .\" .SO ?manpage?
  56 .\"     Start of list of standard options for a Tk widget. The manpage
  57 .\"     argument defines where to look up the standard options; if
  58 .\"     omitted, defaults to "options". The options follow on successive
  59 .\"     lines, in three columns separated by tabs.
  60 .\"
  61 .\" .SE
  62 .\"     End of list of standard options for a Tk widget.
  63 .\"
  64 .\" .OP cmdName dbName dbClass
  65 .\"     Start of description of a specific option.  cmdName gives the
  66 .\"     option's name as specified in the class command, dbName gives
  67 .\"     the option's name in the option database, and dbClass gives
  68 .\"     the option's class in the option database.
  69 .\"
  70 .\" .UL arg1 arg2
  71 .\"     Print arg1 underlined, then print arg2 normally.
  72 .\"
  73 .\" .QW arg1 ?arg2?
  74 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  75 .\"
  76 .\" .PQ arg1 ?arg2?
  77 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  78 .\"     (for trailing punctuation) and then a closing parenthesis.
  79 .\"
  80 .\" RCS: @(#) $Id: man.macros,v 1.9 2008/01/29 15:32:33 dkf Exp $
  81 .\"
  82 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  83 .if t .wh -1.3i ^B
  84 .nr ^l \n(.l
  85 .ad b
  86 .\"     # Start an argument description
  87 .de AP
  88 .ie !"\\$4"" .TP \\$4
  89 .el \{\
  90 .   ie !"\\$2"" .TP \\n()Cu
  91 .   el          .TP 15
  92 .\}
  93 .ta \\n()Au \\n()Bu
  94 .ie !"\\$3"" \{\
  95 \&\\$1 \\fI\\$2\\fP (\\$3)
  96 .\".b
  97 .\}
  98 .el \{\
  99 .br
 100 .ie !"\\$2"" \{\
 101 \&\\$1  \\fI\\$2\\fP
 102 .\}
 103 .el \{\
 104 \&\\fI\\$1\\fP
 105 .\}
 106 .\}
 107 ..
 108 .\"     # define tabbing values for .AP
 109 .de AS
 110 .nr )A 10n
 111 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 112 .nr )B \\n()Au+15n
 113 .\"
 114 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 115 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 116 ..
 117 .AS Tcl_Interp Tcl_CreateInterp in/out
 118 .\"     # BS - start boxed text
 119 .\"     # ^y = starting y location
 120 .\"     # ^b = 1
 121 .de BS
 122 .br
 123 .mk ^y
 124 .nr ^b 1u
 125 .if n .nf
 126 .if n .ti 0
 127 .if n \l'\\n(.lu\(ul'
 128 .if n .fi
 129 ..
 130 .\"     # BE - end boxed text (draw box now)
 131 .de BE
 132 .nf
 133 .ti 0
 134 .mk ^t
 135 .ie n \l'\\n(^lu\(ul'
 136 .el \{\
 137 .\"     Draw four-sided box normally, but don't draw top of
 138 .\"     box if the box started on an earlier page.
 139 .ie !\\n(^b-1 \{\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .el \}\
 143 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 144 .\}
 145 .\}
 146 .fi
 147 .br
 148 .nr ^b 0
 149 ..
 150 .\"     # VS - start vertical sidebar
 151 .\"     # ^Y = starting y location
 152 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 153 .de VS
 154 .if !"\\$2"" .br
 155 .mk ^Y
 156 .ie n 'mc \s12\(br\s0
 157 .el .nr ^v 1u
 158 ..
 159 .\"     # VE - end of vertical sidebar
 160 .de VE
 161 .ie n 'mc
 162 .el \{\
 163 .ev 2
 164 .nf
 165 .ti 0
 166 .mk ^t
 167 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 168 .sp -1
 169 .fi
 170 .ev
 171 .\}
 172 .nr ^v 0
 173 ..
 174 .\"     # Special macro to handle page bottom:  finish off current
 175 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 176 .\"     # page bottom macro.
 177 .de ^B
 178 .ev 2
 179 'ti 0
 180 'nf
 181 .mk ^t
 182 .if \\n(^b \{\
 183 .\"     Draw three-sided box if this is the box's first page,
 184 .\"     draw two sides but no top otherwise.
 185 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 186 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 187 .\}
 188 .if \\n(^v \{\
 189 .nr ^x \\n(^tu+1v-\\n(^Yu
 190 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 191 .\}
 192 .bp
 193 'fi
 194 .ev
 195 .if \\n(^b \{\
 196 .mk ^y
 197 .nr ^b 2
 198 .\}
 199 .if \\n(^v \{\
 200 .mk ^Y
 201 .\}
 202 ..
 203 .\"     # DS - begin display
 204 .de DS
 205 .RS
 206 .nf
 207 .sp
 208 ..
 209 .\"     # DE - end display
 210 .de DE
 211 .fi
 212 .RE
 213 .sp
 214 ..
 215 .\"     # SO - start of list of standard options
 216 .de SO
 217 'ie '\\$1'' .ds So \\fBoptions\\fR
 218 'el .ds So \\fB\\$1\\fR
 219 .SH "STANDARD OPTIONS"
 220 .LP
 221 .nf
 222 .ta 5.5c 11c
 223 .ft B
 224 ..
 225 .\"     # SE - end of list of standard options
 226 .de SE
 227 .fi
 228 .ft R
 229 .LP
 230 See the \\*(So manual entry for details on the standard options.
 231 ..
 232 .\"     # OP - start of full description for a single option
 233 .de OP
 234 .LP
 235 .nf
 236 .ta 4c
 237 Command-Line Name:      \\fB\\$1\\fR
 238 Database Name:  \\fB\\$2\\fR
 239 Database Class: \\fB\\$3\\fR
 240 .fi
 241 .IP
 242 ..
 243 .\"     # CS - begin code excerpt
 244 .de CS
 245 .RS
 246 .nf
 247 .ta .25i .5i .75i 1i
 248 ..
 249 .\"     # CE - end code excerpt
 250 .de CE
 251 .fi
 252 .RE
 253 ..
 254 .\"     # UL - underline word
 255 .de UL
 256 \\$1\l'|0\(ul'\\$2
 257 ..
 258 .\"     # QW - apply quotation marks to word
 259 .de QW
 260 .ie '\\*(lq'"' ``\\$1''\\$2
 261 .\"" fix emacs highlighting
 262 .el \\*(lq\\$1\\*(rq\\$2
 263 ..
 264 .\"     # PQ - apply parens and quotation marks to word
 265 .de PQ
 266 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 267 .\"" fix emacs highlighting
 268 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 269 ..
 270 .\"     # QR - quoted range
 271 .de QR
 272 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 273 .\"" fix emacs highlighting
 274 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 275 ..
 276 .\"     # MT - "empty" string
 277 .de MT
 278 .QW ""
 279 ..
 280 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
 281 .BS
 282 .SH NAME
 283 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
 284 .SH SYNOPSIS
 285 .nf
 286 \fB#include <tcl.h>\fR
 287 .sp
 288 Tcl_Command
 289 \fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR)
 290 .sp
 291 Tcl_Command
 292 \fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR)
 293 .sp
 294 int
 295 \fBTcl_IsEnsemble\fR(\fItoken\fR)
 296 .sp
 297 int
 298 \fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR)
 299 .sp
 300 int
 301 \fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR)
 302 .sp
 303 int
 304 \fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR)
 305 .sp
 306 int
 307 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 308 .sp
 309 int
 310 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
 311 .sp
 312 int
 313 \fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR)
 314 .sp
 315 int
 316 \fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR)
 317 .sp
 318 int
 319 \fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR)
 320 .sp
 321 int
 322 \fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR)
 323 .SH ARGUMENTS
 324 .AS Tcl_Namespace **namespacePtrPtr in/out
 325 .AP Tcl_Interp *interp in/out
 326 The interpreter in which the ensemble is to be created or found. Also
 327 where error result messages are written. The functions whose names
 328 start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR,
 329 but all other functions must not.
 330 .AP "const char" *name in
 331 The name of the ensemble command to be created.
 332 .AP Tcl_Namespace *namespacePtr in
 333 The namespace to which the ensemble command is to be bound, or NULL
 334 for the current namespace.
 335 .AP int ensFlags in
 336 An ORed set of flag bits describing the basic configuration of the
 337 ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX,
 338 which is present when the ensemble command should also match
 339 unambiguous prefixes of subcommands.
 340 .AP Tcl_Obj *cmdNameObj in
 341 A value holding the name of the ensemble command to look up.
 342 .AP int flags in
 343 An ORed set of flag bits controlling the behavior of
 344 \fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported.
 345 .AP Tcl_Command token in
 346 A normal command token that refers to an ensemble command, or which
 347 you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR.
 348 .AP int *ensFlagsPtr out
 349 Pointer to a variable into which to write the current ensemble flag
 350 bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined.
 351 .AP Tcl_Obj *dictObj in
 352 A dictionary value to use for the subcommand to implementation command
 353 prefix mapping dictionary in the ensemble. May be NULL if the mapping
 354 dictionary is to be removed.
 355 .AP Tcl_Obj **dictObjPtr out
 356 Pointer to a variable into which to write the current ensemble mapping
 357 dictionary.
 358 .AP Tcl_Obj *listObj in
 359 A list value to use for the defined list of subcommands in the
 360 dictionary or the unknown subcommmand handler command prefix. May be
 361 NULL if the subcommand list or unknown handler are to be removed.
 362 .AP Tcl_Obj **listObjPtr out
 363 Pointer to a variable into which to write the current defiend list of
 364 subcommands or the current unknown handler prefix.
 365 .AP Tcl_Namespace **namespacePtrPtr out
 366 Pointer to a variable into which to write the handle of the namespace
 367 to which the ensemble is bound.
 368 .BE
 369
 370 .SH DESCRIPTION
 371 An ensemble is a command, bound to some namespace, which consists of a
 372 collection of subcommands implemented by other Tcl commands. The first
 373 argument to the ensemble command is always interpreted as a selector
 374 that states what subcommand to execute.
 375 .PP
 376 Ensembles are created using \fBTcl_CreateEnsemble\fR, which takes four
 377 arguments: the interpreter to work within, the name of the ensemble to
 378 create, the namespace within the interpreter to bind the ensemble to,
 379 and the default set of ensemble flags. The result of the function is
 380 the command token for the ensemble, which may be used to further
 381 configure the ensemble using the API descibed below in \fBENSEMBLE
 382 PROPERTIES\fR.
 383 .PP
 384 Given the name of an ensemble command, the token for that command may
 385 be retrieved using \fBTcl_FindEnsemble\fR. If the given command name
 386 (in \fIcmdNameObj\fR) does not refer to an ensemble command, the
 387 result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is
 388 set in \fIflags\fR) an error message is left in the interpreter
 389 result.
 390 .PP
 391 A command token may be checked to see if it refers to an ensemble
 392 using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an
 393 ensemble, or 0 otherwise.
 394 .SS "ENSEMBLE PROPERTIES"
 395 Every ensemble has four read-write properties and a read-only
 396 property. The properties are:
 397 .TP
 398 \fBflags\fR (read-write)
 399 The set of flags for the ensemble, expressed as a
 400 bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX
 401 which is set when unambiguous prefixes of subcommands are permitted to
 402 be resolved to implementations as well as exact matches. The flags may
 403 be read and written using \fBTcl_GetEnsembleFlags\fR and
 404 \fBTcl_SetEnsembleFlags\fR respectively. The result of both of those
 405 functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
 406 not refer to an ensemble).
 407 .TP
 408 \fBmapping dictionary\fR (read-write)
 409 A dictionary containing a mapping from subcommand names to lists of
 410 words to use as a command prefix (replacing the first two words of the
 411 command which are the ensemble command itself and the subcommand
 412 name), or NULL if every subcommand is to be mapped to the command with
 413 the same unqualified name in the ensemble's bound namespace. Defaults
 414 to NULL. May be read and written using
 415 \fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR
 416 respectively. The result of both of those functions is a Tcl result
 417 code (TCL_OK, or TCL_ERROR if the token does not refer to an
 418 ensemble) and the dictionary obtained from
 419 \fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable
 420 even if it is unshared.
 421 .TP
 422 \fBsubcommand list\fR (read-write)
 423 A list of all the subcommand names for the ensemble, or NULL if this
 424 is to be derived from either the keys of the mapping dictionary (see
 425 above) or (if that is also NULL) from the set of commands exported by
 426 the bound namespace. May be read and written using
 427 \fBTcl_GetEnsembleSubcommandList\fR and
 428 \fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
 429 of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the
 430 token does not refer to an ensemble) and the list obtained from
 431 \fBTcl_GetEnsembleSubcommandList\fR should alays be treated as
 432 immutable even if it is unshared.
 433 .TP
 434 \fBunknown subcommand handler command prefix\fR (read-write)
 435 A list of words to prepend on the front of any subcommand when the
 436 subcommand is unknown to the ensemble (according to the current prefix
 437 handling rule); see the \fBnamespace ensemble\fR command for more
 438 details. If NULL, the default behavior \- generate a suitable error
 439 message \- will be used when an unknown subcommand is encountered. May
 440 be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and
 441 \fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both
 442 functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
 443 not refer to an ensemble) and the list obtained from
 444 \fBTcl_GetEnsembleUnknownHandler\fR should always be treated as
 445 immutable even if it is unshared.
 446 .TP
 447 \fBbound namespace\fR (read-only)
 448 The namespace to which the ensemble is bound; when the namespace is
 449 deleted, so too will the ensemble, and this namespace is also the
 450 namespace whose list of exported commands is used if both the mapping
 451 dictionary and the subcommand list properties are NULL. May be read
 452 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
 453 (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).
 454
 455 .SH "SEE ALSO"
 456 namespace(n), Tcl_DeleteCommandFromToken(3)