hostdepend/X86MAC64/util/X86MAC64/man/man3/Tcl_GetCurrentNamespace.3

   1 '\"
   2 '\" Copyright (c) 2003 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: Namespace.3,v 1.8.10.1 2008/04/18 14:30:51 dkf Exp $
   8 '\"
   9 '\" Note that some of these functions do not seem to belong, but they
  10 '\" were all introduced with the same TIP (#139)
  11 '\"
  12 .\" The -*- nroff -*- definitions below are for supplemental macros used
  13 .\" in Tcl/Tk manual entries.
  14 .\"
  15 .\" .AP type name in/out ?indent?
  16 .\"     Start paragraph describing an argument to a library procedure.
  17 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  18 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  19 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  20 .\"     needed;  use .AS below instead)
  21 .\"
  22 .\" .AS ?type? ?name?
  23 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  24 .\"     name are examples of largest possible arguments that will be passed
  25 .\"     to .AP later.  If args are omitted, default tab stops are used.
  26 .\"
  27 .\" .BS
  28 .\"     Start box enclosure.  From here until next .BE, everything will be
  29 .\"     enclosed in one large box.
  30 .\"
  31 .\" .BE
  32 .\"     End of box enclosure.
  33 .\"
  34 .\" .CS
  35 .\"     Begin code excerpt.
  36 .\"
  37 .\" .CE
  38 .\"     End code excerpt.
  39 .\"
  40 .\" .VS ?version? ?br?
  41 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  42 .\"     of man pages.  The first argument is ignored and used for recording
  43 .\"     the version when the .VS was added, so that the sidebars can be
  44 .\"     found and removed when they reach a certain age.  If another argument
  45 .\"     is present, then a line break is forced before starting the sidebar.
  46 .\"
  47 .\" .VE
  48 .\"     End of vertical sidebar.
  49 .\"
  50 .\" .DS
  51 .\"     Begin an indented unfilled display.
  52 .\"
  53 .\" .DE
  54 .\"     End of indented unfilled display.
  55 .\"
  56 .\" .SO ?manpage?
  57 .\"     Start of list of standard options for a Tk widget. The manpage
  58 .\"     argument defines where to look up the standard options; if
  59 .\"     omitted, defaults to "options". The options follow on successive
  60 .\"     lines, in three columns separated by tabs.
  61 .\"
  62 .\" .SE
  63 .\"     End of list of standard options for a Tk widget.
  64 .\"
  65 .\" .OP cmdName dbName dbClass
  66 .\"     Start of description of a specific option.  cmdName gives the
  67 .\"     option's name as specified in the class command, dbName gives
  68 .\"     the option's name in the option database, and dbClass gives
  69 .\"     the option's class in the option database.
  70 .\"
  71 .\" .UL arg1 arg2
  72 .\"     Print arg1 underlined, then print arg2 normally.
  73 .\"
  74 .\" .QW arg1 ?arg2?
  75 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  76 .\"
  77 .\" .PQ arg1 ?arg2?
  78 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  79 .\"     (for trailing punctuation) and then a closing parenthesis.
  80 .\"
  81 .\" RCS: @(#) $Id: man.macros,v 1.9 2008/01/29 15:32:33 dkf Exp $
  82 .\"
  83 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  84 .if t .wh -1.3i ^B
  85 .nr ^l \n(.l
  86 .ad b
  87 .\"     # Start an argument description
  88 .de AP
  89 .ie !"\\$4"" .TP \\$4
  90 .el \{\
  91 .   ie !"\\$2"" .TP \\n()Cu
  92 .   el          .TP 15
  93 .\}
  94 .ta \\n()Au \\n()Bu
  95 .ie !"\\$3"" \{\
  96 \&\\$1 \\fI\\$2\\fP (\\$3)
  97 .\".b
  98 .\}
  99 .el \{\
 100 .br
 101 .ie !"\\$2"" \{\
 102 \&\\$1  \\fI\\$2\\fP
 103 .\}
 104 .el \{\
 105 \&\\fI\\$1\\fP
 106 .\}
 107 .\}
 108 ..
 109 .\"     # define tabbing values for .AP
 110 .de AS
 111 .nr )A 10n
 112 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 113 .nr )B \\n()Au+15n
 114 .\"
 115 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 116 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 117 ..
 118 .AS Tcl_Interp Tcl_CreateInterp in/out
 119 .\"     # BS - start boxed text
 120 .\"     # ^y = starting y location
 121 .\"     # ^b = 1
 122 .de BS
 123 .br
 124 .mk ^y
 125 .nr ^b 1u
 126 .if n .nf
 127 .if n .ti 0
 128 .if n \l'\\n(.lu\(ul'
 129 .if n .fi
 130 ..
 131 .\"     # BE - end boxed text (draw box now)
 132 .de BE
 133 .nf
 134 .ti 0
 135 .mk ^t
 136 .ie n \l'\\n(^lu\(ul'
 137 .el \{\
 138 .\"     Draw four-sided box normally, but don't draw top of
 139 .\"     box if the box started on an earlier page.
 140 .ie !\\n(^b-1 \{\
 141 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 142 .\}
 143 .el \}\
 144 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 145 .\}
 146 .\}
 147 .fi
 148 .br
 149 .nr ^b 0
 150 ..
 151 .\"     # VS - start vertical sidebar
 152 .\"     # ^Y = starting y location
 153 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 154 .de VS
 155 .if !"\\$2"" .br
 156 .mk ^Y
 157 .ie n 'mc \s12\(br\s0
 158 .el .nr ^v 1u
 159 ..
 160 .\"     # VE - end of vertical sidebar
 161 .de VE
 162 .ie n 'mc
 163 .el \{\
 164 .ev 2
 165 .nf
 166 .ti 0
 167 .mk ^t
 168 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 169 .sp -1
 170 .fi
 171 .ev
 172 .\}
 173 .nr ^v 0
 174 ..
 175 .\"     # Special macro to handle page bottom:  finish off current
 176 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 177 .\"     # page bottom macro.
 178 .de ^B
 179 .ev 2
 180 'ti 0
 181 'nf
 182 .mk ^t
 183 .if \\n(^b \{\
 184 .\"     Draw three-sided box if this is the box's first page,
 185 .\"     draw two sides but no top otherwise.
 186 .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
 187 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 188 .\}
 189 .if \\n(^v \{\
 190 .nr ^x \\n(^tu+1v-\\n(^Yu
 191 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 192 .\}
 193 .bp
 194 'fi
 195 .ev
 196 .if \\n(^b \{\
 197 .mk ^y
 198 .nr ^b 2
 199 .\}
 200 .if \\n(^v \{\
 201 .mk ^Y
 202 .\}
 203 ..
 204 .\"     # DS - begin display
 205 .de DS
 206 .RS
 207 .nf
 208 .sp
 209 ..
 210 .\"     # DE - end display
 211 .de DE
 212 .fi
 213 .RE
 214 .sp
 215 ..
 216 .\"     # SO - start of list of standard options
 217 .de SO
 218 'ie '\\$1'' .ds So \\fBoptions\\fR
 219 'el .ds So \\fB\\$1\\fR
 220 .SH "STANDARD OPTIONS"
 221 .LP
 222 .nf
 223 .ta 5.5c 11c
 224 .ft B
 225 ..
 226 .\"     # SE - end of list of standard options
 227 .de SE
 228 .fi
 229 .ft R
 230 .LP
 231 See the \\*(So manual entry for details on the standard options.
 232 ..
 233 .\"     # OP - start of full description for a single option
 234 .de OP
 235 .LP
 236 .nf
 237 .ta 4c
 238 Command-Line Name:      \\fB\\$1\\fR
 239 Database Name:  \\fB\\$2\\fR
 240 Database Class: \\fB\\$3\\fR
 241 .fi
 242 .IP
 243 ..
 244 .\"     # CS - begin code excerpt
 245 .de CS
 246 .RS
 247 .nf
 248 .ta .25i .5i .75i 1i
 249 ..
 250 .\"     # CE - end code excerpt
 251 .de CE
 252 .fi
 253 .RE
 254 ..
 255 .\"     # UL - underline word
 256 .de UL
 257 \\$1\l'|0\(ul'\\$2
 258 ..
 259 .\"     # QW - apply quotation marks to word
 260 .de QW
 261 .ie '\\*(lq'"' ``\\$1''\\$2
 262 .\"" fix emacs highlighting
 263 .el \\*(lq\\$1\\*(rq\\$2
 264 ..
 265 .\"     # PQ - apply parens and quotation marks to word
 266 .de PQ
 267 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 268 .\"" fix emacs highlighting
 269 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 270 ..
 271 .\"     # QR - quoted range
 272 .de QR
 273 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 274 .\"" fix emacs highlighting
 275 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 276 ..
 277 .\"     # MT - "empty" string
 278 .de MT
 279 .QW ""
 280 ..
 281 .TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
 282 .BS
 283 .SH NAME
 284 Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
 285 .SH SYNOPSIS
 286 .nf
 287 \fB#include <tcl.h>\fR
 288 .sp
 289 Tcl_Namespace *
 290 \fBTcl_CreateNamespace\fR(\fIinterp, name, clientData, deleteProc\fR)
 291 .sp
 292 \fBTcl_DeleteNamespace\fR(\fInsPtr\fR)
 293 .sp
 294 int
 295 \fBTcl_AppendExportList\fR(\fIinterp, nsPtr, objPtr\fR)
 296 .sp
 297 int
 298 \fBTcl_Export\fR(\fIinterp, nsPtr, pattern, resetListFirst\fR)
 299 .sp
 300 int
 301 \fBTcl_Import\fR(\fIinterp, nsPtr, pattern, allowOverwrite\fR)
 302 .sp
 303 int
 304 \fBTcl_ForgetImport\fR(\fIinterp, nsPtr, pattern\fR)
 305 .sp
 306 Tcl_Namespace *
 307 \fBTcl_GetCurrentNamespace\fR(\fIinterp\fR)
 308 .sp
 309 Tcl_Namespace *
 310 \fBTcl_GetGlobalNamespace\fR(\fIinterp\fR)
 311 .sp
 312 Tcl_Namespace *
 313 \fBTcl_FindNamespace\fR(\fIinterp, name, contextNsPtr, flags\fR)
 314 .sp
 315 Tcl_Command
 316 \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
 317 .sp
 318 Tcl_Obj *
 319 \fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
 320 .sp
 321 int
 322 \fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
 323 .SH ARGUMENTS
 324 .AS Tcl_NamespaceDeleteProc allowOverwrite in/out
 325 .AP Tcl_Interp *interp in/out
 326 The interpreter in which the namespace exists and where name lookups
 327 are performed. Also where error result messages are written.
 328 .AP "const char" *name in
 329 The name of the namespace or command to be created or accessed.
 330 .AP ClientData clientData in
 331 A context pointer by the creator of the namespace.  Not interpreted by
 332 Tcl at all.
 333 .AP Tcl_NamespaceDeleteProc *deleteProc in
 334 A pointer to function to call when the namespace is deleted, or NULL
 335 if no such callback is to be performed.
 336 .AP Tcl_Namespace *nsPtr in
 337 The namespace to be manipulated, or NULL (for other than
 338 \fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
 339 .AP Tcl_Obj *objPtr out
 340 A reference to an unshared object to which the function output will be
 341 written.
 342 .AP "const char" *pattern in
 343 The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
 344 commands to be imported or exported.
 345 .AP int resetListFirst in
 346 Whether the list of export patterns should be reset before adding the
 347 current pattern to it.
 348 .AP int allowOverwrite in
 349 Whether new commands created by this import action can overwrite
 350 existing commands.
 351 .AP Tcl_Namespace *contextNsPtr in
 352 The location in the namespace hierarchy where the search for a
 353 namespace or command should be conducted relative to when the search
 354 term is not rooted at the global namespace.  NULL indicates the
 355 current namespace.
 356 .AP int flags in
 357 OR-ed combination of bits controlling how the search is to be
 358 performed.  The following flags are supported: \fBTCL_GLOBAL_ONLY\fR
 359 (indicates that the search is always to be conducted relative to the
 360 global namespace), \fBTCL_NAMESPACE_ONLY\fR (just for \fBTcl_FindCommand\fR;
 361 indicates that the search is always to be conducted relative to the
 362 context namespace), and \fBTCL_LEAVE_ERR_MSG\fR (indicates that an error
 363 message should be left in the interpreter if the search fails.)
 364 .AP Tcl_Obj *handlerPtr in
 365 A script fragment to be installed as the unknown command handler for the
 366 namespace, or NULL to reset the handler to its default.
 367 .BE
 368
 369 .SH DESCRIPTION
 370 .PP
 371 Namespaces are hierarchic naming contexts that can contain commands
 372 and variables.  They also maintain a list of patterns that describes
 373 what commands are exported, and can import commands that have been
 374 exported by other namespaces.  Namespaces can also be manipulated
 375 through the Tcl command \fBnamespace\fR.
 376 .PP
 377 The \fITcl_Namespace\fR structure encapsulates a namespace, and is
 378 guaranteed to have the following fields in it: \fIname\fR (the local
 379 name of the namespace, with no namespace separator characters in it,
 380 with empty denoting the global namespace), \fIfullName\fR (the fully
 381 specified name of the namespace), \fIclientData\fR, \fIdeleteProc\fR
 382 (the values specified in the call to \fBTcl_CreateNamespace\fR), and
 383 \fIparentPtr\fR (a pointer to the containing namespace, or NULL for
 384 the global namespace.)
 385 .PP
 386 \fBTcl_CreateNamespace\fR creates a new namespace.  The
 387 \fIdeleteProc\fR will have the following type signature:
 388 .CS
 389 typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData);
 390 .CE
 391 .PP
 392 \fBTcl_DeleteNamespace\fR deletes a namespace.
 393 .PP
 394 \fBTcl_AppendExportList\fR retrieves the export patterns for a
 395 namespace given namespace and appends them (as list items) to
 396 \fIobjPtr\fR.
 397 .PP
 398 \fBTcl_Export\fR sets and appends to the export patterns for a
 399 namespace.  Patterns are appended unless the \fIresetListFirst\fR flag
 400 is true.
 401 .PP
 402 \fBTcl_Import\fR imports commands matching a pattern into a
 403 namespace.  Note that the pattern must include the name of the
 404 namespace to import from.  This function returns an error if
 405 an attempt to import a command over an existing command is made,
 406 unless the \fIallowOverwrite\fR flag has been set.
 407 .PP
 408 \fBTcl_ForgetImport\fR removes imports matching a pattern.
 409 .PP
 410 \fBTcl_GetCurrentNamespace\fR returns the current namespace for an
 411 interpreter.
 412 .PP
 413 \fBTcl_GetGlobalNamespace\fR returns the global namespace for an
 414 interpreter.
 415 .PP
 416 \fBTcl_FindNamespace\fR searches for a namespace named \fIname\fR
 417 within the context of the namespace \fIcontextNsPtr\fR.  If the
 418 namespace cannot be found, NULL is returned.
 419 .PP
 420 \fBTcl_FindCommand\fR searches for a command named \fIname\fR within
 421 the context of the namespace \fIcontextNsPtr\fR.  If the command
 422 cannot be found, NULL is returned.
 423 .PP
 424 \fBTcl_GetNamespaceUnknownHandler\fR returns the unknown command handler
 425 for the namespace, or NULL if none is set.
 426 .PP
 427 \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
 428 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 429 its default.
 430
 431 .SH "SEE ALSO"
 432 Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar
 433
 434 .SH KEYWORDS
 435 namespace, command