util/X86LINUX64/man/man3/Tcl_AppendExportList.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 '\" Note that some of these functions do not seem to belong, but they
   8 '\" were all introduced with the same TIP (#139)
   9 '\"
  10 .TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
  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 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  81 .if t .wh -1.3i ^B
  82 .nr ^l \n(.l
  83 .ad b
  84 .\"     # Start an argument description
  85 .de AP
  86 .ie !"\\$4"" .TP \\$4
  87 .el \{\
  88 .   ie !"\\$2"" .TP \\n()Cu
  89 .   el          .TP 15
  90 .\}
  91 .ta \\n()Au \\n()Bu
  92 .ie !"\\$3"" \{\
  93 \&\\$1 \\fI\\$2\\fP (\\$3)
  94 .\".b
  95 .\}
  96 .el \{\
  97 .br
  98 .ie !"\\$2"" \{\
  99 \&\\$1  \\fI\\$2\\fP
 100 .\}
 101 .el \{\
 102 \&\\fI\\$1\\fP
 103 .\}
 104 .\}
 105 ..
 106 .\"     # define tabbing values for .AP
 107 .de AS
 108 .nr )A 10n
 109 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 110 .nr )B \\n()Au+15n
 111 .\"
 112 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 113 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 114 ..
 115 .AS Tcl_Interp Tcl_CreateInterp in/out
 116 .\"     # BS - start boxed text
 117 .\"     # ^y = starting y location
 118 .\"     # ^b = 1
 119 .de BS
 120 .br
 121 .mk ^y
 122 .nr ^b 1u
 123 .if n .nf
 124 .if n .ti 0
 125 .if n \l'\\n(.lu\(ul'
 126 .if n .fi
 127 ..
 128 .\"     # BE - end boxed text (draw box now)
 129 .de BE
 130 .nf
 131 .ti 0
 132 .mk ^t
 133 .ie n \l'\\n(^lu\(ul'
 134 .el \{\
 135 .\"     Draw four-sided box normally, but don't draw top of
 136 .\"     box if the box started on an earlier page.
 137 .ie !\\n(^b-1 \{\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .el \}\
 141 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 142 .\}
 143 .\}
 144 .fi
 145 .br
 146 .nr ^b 0
 147 ..
 148 .\"     # VS - start vertical sidebar
 149 .\"     # ^Y = starting y location
 150 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 151 .de VS
 152 .if !"\\$2"" .br
 153 .mk ^Y
 154 .ie n 'mc \s12\(br\s0
 155 .el .nr ^v 1u
 156 ..
 157 .\"     # VE - end of vertical sidebar
 158 .de VE
 159 .ie n 'mc
 160 .el \{\
 161 .ev 2
 162 .nf
 163 .ti 0
 164 .mk ^t
 165 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 166 .sp -1
 167 .fi
 168 .ev
 169 .\}
 170 .nr ^v 0
 171 ..
 172 .\"     # Special macro to handle page bottom:  finish off current
 173 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 174 .\"     # page bottom macro.
 175 .de ^B
 176 .ev 2
 177 'ti 0
 178 'nf
 179 .mk ^t
 180 .if \\n(^b \{\
 181 .\"     Draw three-sided box if this is the box's first page,
 182 .\"     draw two sides but no top otherwise.
 183 .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
 184 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 185 .\}
 186 .if \\n(^v \{\
 187 .nr ^x \\n(^tu+1v-\\n(^Yu
 188 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 189 .\}
 190 .bp
 191 'fi
 192 .ev
 193 .if \\n(^b \{\
 194 .mk ^y
 195 .nr ^b 2
 196 .\}
 197 .if \\n(^v \{\
 198 .mk ^Y
 199 .\}
 200 ..
 201 .\"     # DS - begin display
 202 .de DS
 203 .RS
 204 .nf
 205 .sp
 206 ..
 207 .\"     # DE - end display
 208 .de DE
 209 .fi
 210 .RE
 211 .sp
 212 ..
 213 .\"     # SO - start of list of standard options
 214 .de SO
 215 'ie '\\$1'' .ds So \\fBoptions\\fR
 216 'el .ds So \\fB\\$1\\fR
 217 .SH "STANDARD OPTIONS"
 218 .LP
 219 .nf
 220 .ta 5.5c 11c
 221 .ft B
 222 ..
 223 .\"     # SE - end of list of standard options
 224 .de SE
 225 .fi
 226 .ft R
 227 .LP
 228 See the \\*(So manual entry for details on the standard options.
 229 ..
 230 .\"     # OP - start of full description for a single option
 231 .de OP
 232 .LP
 233 .nf
 234 .ta 4c
 235 Command-Line Name:      \\fB\\$1\\fR
 236 Database Name:  \\fB\\$2\\fR
 237 Database Class: \\fB\\$3\\fR
 238 .fi
 239 .IP
 240 ..
 241 .\"     # CS - begin code excerpt
 242 .de CS
 243 .RS
 244 .nf
 245 .ta .25i .5i .75i 1i
 246 ..
 247 .\"     # CE - end code excerpt
 248 .de CE
 249 .fi
 250 .RE
 251 ..
 252 .\"     # UL - underline word
 253 .de UL
 254 \\$1\l'|0\(ul'\\$2
 255 ..
 256 .\"     # QW - apply quotation marks to word
 257 .de QW
 258 .ie '\\*(lq'"' ``\\$1''\\$2
 259 .\"" fix emacs highlighting
 260 .el \\*(lq\\$1\\*(rq\\$2
 261 ..
 262 .\"     # PQ - apply parens and quotation marks to word
 263 .de PQ
 264 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 265 .\"" fix emacs highlighting
 266 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 267 ..
 268 .\"     # QR - quoted range
 269 .de QR
 270 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 271 .\"" fix emacs highlighting
 272 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 273 ..
 274 .\"     # MT - "empty" string
 275 .de MT
 276 .QW ""
 277 ..
 278 .BS
 279 .SH NAME
 280 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
 281 .SH SYNOPSIS
 282 .nf
 283 \fB#include <tcl.h>\fR
 284 .sp
 285 Tcl_Namespace *
 286 \fBTcl_CreateNamespace\fR(\fIinterp, name, clientData, deleteProc\fR)
 287 .sp
 288 \fBTcl_DeleteNamespace\fR(\fInsPtr\fR)
 289 .sp
 290 int
 291 \fBTcl_AppendExportList\fR(\fIinterp, nsPtr, objPtr\fR)
 292 .sp
 293 int
 294 \fBTcl_Export\fR(\fIinterp, nsPtr, pattern, resetListFirst\fR)
 295 .sp
 296 int
 297 \fBTcl_Import\fR(\fIinterp, nsPtr, pattern, allowOverwrite\fR)
 298 .sp
 299 int
 300 \fBTcl_ForgetImport\fR(\fIinterp, nsPtr, pattern\fR)
 301 .sp
 302 Tcl_Namespace *
 303 \fBTcl_GetCurrentNamespace\fR(\fIinterp\fR)
 304 .sp
 305 Tcl_Namespace *
 306 \fBTcl_GetGlobalNamespace\fR(\fIinterp\fR)
 307 .sp
 308 Tcl_Namespace *
 309 \fBTcl_FindNamespace\fR(\fIinterp, name, contextNsPtr, flags\fR)
 310 .sp
 311 Tcl_Command
 312 \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR)
 313 .sp
 314 Tcl_Obj *
 315 \fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR)
 316 .sp
 317 int
 318 \fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR)
 319 .SH ARGUMENTS
 320 .AS Tcl_NamespaceDeleteProc allowOverwrite in/out
 321 .AP Tcl_Interp *interp in/out
 322 The interpreter in which the namespace exists and where name lookups
 323 are performed. Also where error result messages are written.
 324 .AP "const char" *name in
 325 The name of the namespace or command to be created or accessed.
 326 .AP ClientData clientData in
 327 A context pointer by the creator of the namespace.  Not interpreted by
 328 Tcl at all.
 329 .AP Tcl_NamespaceDeleteProc *deleteProc in
 330 A pointer to function to call when the namespace is deleted, or NULL
 331 if no such callback is to be performed.
 332 .AP Tcl_Namespace *nsPtr in
 333 The namespace to be manipulated, or NULL (for other than
 334 \fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
 335 .AP Tcl_Obj *objPtr out
 336 A reference to an unshared value to which the function output will be
 337 written.
 338 .AP "const char" *pattern in
 339 The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
 340 commands to be imported or exported.
 341 .AP int resetListFirst in
 342 Whether the list of export patterns should be reset before adding the
 343 current pattern to it.
 344 .AP int allowOverwrite in
 345 Whether new commands created by this import action can overwrite
 346 existing commands.
 347 .AP Tcl_Namespace *contextNsPtr in
 348 The location in the namespace hierarchy where the search for a
 349 namespace or command should be conducted relative to when the search
 350 term is not rooted at the global namespace.  NULL indicates the
 351 current namespace.
 352 .AP int flags in
 353 OR-ed combination of bits controlling how the search is to be
 354 performed.  The following flags are supported: \fBTCL_GLOBAL_ONLY\fR
 355 (indicates that the search is always to be conducted relative to the
 356 global namespace), \fBTCL_NAMESPACE_ONLY\fR (just for \fBTcl_FindCommand\fR;
 357 indicates that the search is always to be conducted relative to the
 358 context namespace), and \fBTCL_LEAVE_ERR_MSG\fR (indicates that an error
 359 message should be left in the interpreter if the search fails.)
 360 .AP Tcl_Obj *handlerPtr in
 361 A script fragment to be installed as the unknown command handler for the
 362 namespace, or NULL to reset the handler to its default.
 363 .BE
 364 .SH DESCRIPTION
 365 .PP
 366 Namespaces are hierarchic naming contexts that can contain commands
 367 and variables.  They also maintain a list of patterns that describes
 368 what commands are exported, and can import commands that have been
 369 exported by other namespaces.  Namespaces can also be manipulated
 370 through the Tcl command \fBnamespace\fR.
 371 .PP
 372 The \fITcl_Namespace\fR structure encapsulates a namespace, and is
 373 guaranteed to have the following fields in it: \fIname\fR (the local
 374 name of the namespace, with no namespace separator characters in it,
 375 with empty denoting the global namespace), \fIfullName\fR (the fully
 376 specified name of the namespace), \fIclientData\fR, \fIdeleteProc\fR
 377 (the values specified in the call to \fBTcl_CreateNamespace\fR), and
 378 \fIparentPtr\fR (a pointer to the containing namespace, or NULL for
 379 the global namespace.)
 380 .PP
 381 \fBTcl_CreateNamespace\fR creates a new namespace.  The
 382 \fIdeleteProc\fR will have the following type signature:
 383 .PP
 384 .CS
 385 typedef void \fBTcl_NamespaceDeleteProc\fR(
 386         ClientData \fIclientData\fR);
 387 .CE
 388 .PP
 389 \fBTcl_DeleteNamespace\fR deletes a namespace, calling the
 390 \fIdeleteProc\fR defined for the namespace (if any).
 391 .PP
 392 \fBTcl_AppendExportList\fR retrieves the export patterns for a
 393 namespace given namespace and appends them (as list items) to
 394 \fIobjPtr\fR.
 395 .PP
 396 \fBTcl_Export\fR sets and appends to the export patterns for a
 397 namespace.  Patterns are appended unless the \fIresetListFirst\fR flag
 398 is true.
 399 .PP
 400 \fBTcl_Import\fR imports commands matching a pattern into a
 401 namespace.  Note that the pattern must include the name of the
 402 namespace to import from.  This function returns an error if
 403 an attempt to import a command over an existing command is made,
 404 unless the \fIallowOverwrite\fR flag has been set.
 405 .PP
 406 \fBTcl_ForgetImport\fR removes imports matching a pattern.
 407 .PP
 408 \fBTcl_GetCurrentNamespace\fR returns the current namespace for an
 409 interpreter.
 410 .PP
 411 \fBTcl_GetGlobalNamespace\fR returns the global namespace for an
 412 interpreter.
 413 .PP
 414 \fBTcl_FindNamespace\fR searches for a namespace named \fIname\fR
 415 within the context of the namespace \fIcontextNsPtr\fR.  If the
 416 namespace cannot be found, NULL is returned.
 417 .PP
 418 \fBTcl_FindCommand\fR searches for a command named \fIname\fR within
 419 the context of the namespace \fIcontextNsPtr\fR.  If the command
 420 cannot be found, NULL is returned.
 421 .PP
 422 \fBTcl_GetNamespaceUnknownHandler\fR returns the unknown command handler
 423 for the namespace, or NULL if none is set.
 424 .PP
 425 \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
 426 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 427 its default.
 428 .SH "SEE ALSO"
 429 Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
 430 .SH KEYWORDS
 431 namespace, command