diff options
Diffstat (limited to 'doc/namespace.n')
| -rw-r--r-- | doc/namespace.n | 325 |
1 files changed, 286 insertions, 39 deletions
diff --git a/doc/namespace.n b/doc/namespace.n index f3df73d..ee4f908 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -2,28 +2,28 @@ '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies '\" Copyright (c) 1997 Sun Microsystems, Inc. '\" Copyright (c) 2000 Scriptics Corporation. +'\" Copyright (c) 2004-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. '\" .so man.macros -.TH namespace n 8.0 Tcl "Tcl Built-In Commands" +.TH namespace n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME namespace \- create and manipulate contexts for commands and variables .SH SYNOPSIS -\fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR? +\fBnamespace \fR?\fIsubcommand\fR? ?\fIarg ...\fR? .BE - .SH DESCRIPTION .PP The \fBnamespace\fR command lets you create, access, and destroy separate contexts for commands and variables. See the section \fBWHAT IS A NAMESPACE?\fR below for a brief overview of namespaces. -The legal values of \fIoption\fR are listed below. -Note that you can abbreviate the \fIoption\fRs. +The legal values of \fIsubcommand\fR are listed below. +Note that you can abbreviate the \fIsubcommand\fRs. .TP \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? Returns a list of all child namespaces that belong to the @@ -54,7 +54,7 @@ and they will be passed to \fIscript\fR as additional arguments. For example, suppose the command \fBset script [namespace code {foo bar}]\fR is invoked in namespace \fB::a::b\fR. -Then \fBeval "$script x y"\fR +Then \fBeval $script [list x y]\fR can be executed in any namespace (assuming the value of \fBscript\fR has been passed in properly) and will have the same effect as the command @@ -69,7 +69,8 @@ of how this is used to create callback scripts. .TP \fBnamespace current\fR Returns the fully-qualified name for the current namespace. -The actual name of the global namespace is ``'' +The actual name of the global namespace is +.MT (i.e., an empty string), but this command returns \fB::\fR for the global namespace as a convenience to programmers. @@ -82,9 +83,16 @@ If a procedure is currently executing inside the namespace, the namespace will be kept alive until the procedure returns; however, the namespace is marked to prevent other code from looking it up by name. -If a namespace doesn't exist, this command returns an error. +If a namespace does not exist, this command returns an error. If no namespace names are given, this command does nothing. .TP +\fBnamespace ensemble\fR \fIsubcommand\fR ?\fIarg ...\fR? +.VS 8.5 +Creates and manipulates a command that is formed out of an ensemble of +subcommands. See the section \fBENSEMBLES\fR below for further +details. +.VE 8.5 +.TP \fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR? Activates a namespace called \fInamespace\fR and evaluates some code in that context. @@ -93,11 +101,12 @@ If more than one \fIarg\fR argument is specified, the arguments are concatenated together with a space between each one in the same fashion as the \fBeval\fR command, and the result is evaluated. -.br -.sp +.RS +.PP If \fInamespace\fR has leading namespace qualifiers and any leading namespaces do not exist, they are automatically created. +.RE .TP \fBnamespace exists\fR \fInamespace\fR Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current @@ -117,10 +126,10 @@ but it may not include any namespace qualifiers. That is, the pattern can only specify commands in the current (exporting) namespace. Each \fIpattern\fR is appended onto the namespace's list of export patterns. -If the \-\fBclear\fR flag is given, +If the \fB\-clear\fR flag is given, the namespace's export pattern list is reset to empty before any \fIpattern\fR arguments are appended. -If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given, +If no \fIpattern\fRs are given and the \fB\-clear\fR flag is not given, this command returns the namespace's current export list. .TP \fBnamespace forget \fR?\fIpattern pattern ...\fR? @@ -129,24 +138,37 @@ Each \fIpattern\fR is a simple or qualified name such as \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR. Qualified names contain double colons (\fB::\fR) and qualify a name with the name of one or more namespaces. -Each \fIqualified pattern\fR is qualified with the name of an -exporting namespace +Each +.QW "qualified pattern" +is qualified with the name of an exporting namespace and may have glob-style special characters in the command name at the end of the qualified name. Glob characters may not appear in a namespace name. -For each \fIsimple pattern\fR this command deletes the matching -commands of the +For each +.QW "simple pattern" +this command deletes the matching commands of the current namespace that were imported from a different namespace. -For \fIqualified patterns\fR, this command first finds the matching -exported commands. +For +.QW "qualified patterns" , +this command first finds the matching exported commands. It then checks whether any of those commands were previously imported by the current namespace. -If so, this command deletes the corresponding imported commands. +If so, this command deletes the corresponding imported commands. In effect, this un-does the action of a \fBnamespace import\fR command. .TP \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR? -Imports commands into a namespace. -Each \fIpattern\fR is a qualified name like +.VS 8.5 +Imports commands into a namespace, or queries the set of imported +commands in a namespace. When no arguments are present, +\fBnamespace import\fR returns the list of commands in +the current namespace that have been imported from other +namespaces. The commands in the returned list are in +the format of simple names, with no namespace qualifiers at all. +This format is suitable for composition with \fBnamespace forget\fR +(see \fBEXAMPLES\fR below). +.VE 8.5 +When \fIpattern\fR arguments are present, +each \fIpattern\fR is a qualified name like \fBfoo::x\fR or \fBa::p*\fR. That is, it includes the name of an exporting namespace and may have glob-style special characters in the command name @@ -180,12 +202,18 @@ The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR command except that the \fInamespace\fR must already exist, and \fBnamespace inscope\fR appends additional \fIarg\fRs as proper list elements. -.br +.RS +.PP +.CS \fBnamespace inscope ::foo $script $x $y $z\fR +.CE is equivalent to +.CS \fBnamespace eval ::foo [concat $script [list $x $y $z]]\fR +.CE thus additional arguments will not undergo a second round of substitution, as is the case with \fBnamespace eval\fR. +.RE .TP \fBnamespace origin \fIcommand\fR Returns the fully-qualified name of the original command @@ -207,6 +235,17 @@ for namespace \fInamespace\fR. If \fInamespace\fR is not specified, the fully-qualified name of the current namespace's parent is returned. .TP +\fBnamespace path\fR ?\fInamespaceList\fR? +.\" Should really have the .TP inside the .VS, but that triggers a groff bug +.VS 8.5 +Returns the command resolution path of the current namespace. If +\fInamespaceList\fR is specified as a list of named namespaces, the +current namespace's command resolution path is set to those namespaces +and returns the empty list. The default command resolution path is +always empty. See the section \fBNAME RESOLUTION\fR below for an +explanation of the rules regarding name resolution. +.VE 8.5 +.TP \fBnamespace qualifiers\fR \fIstring\fR Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -228,6 +267,27 @@ This command is the complement of the \fBnamespace qualifiers\fR command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. .TP +\fBnamespace upvar\fR \fInamespace\fR \fIotherVar myVar \fR?\fIotherVar myVar \fR... +This command arranges for one or more local variables in the current +procedure to refer to variables in \fInamespace\fR. The namespace name is +resolved as described in section \fBNAME RESOLUTION\fR. +The command +\fBnamespace upvar $ns a b\fR has the same behaviour as +\fBupvar 0 ${ns}::a b\fR, with the sole exception of the resolution rules +used for qualified namespace or variable names. +\fBnamespace upvar\fR returns an empty string. +.TP +\fBnamespace unknown\fR ?\fIscript\fR? +Sets or returns the unknown command handler for the current namespace. +The handler is invoked when a command called from within the namespace +cannot be found (in either the current namespace or the global namespace). +The \fIscript\fR argument, if given, should be a well +formed list representing a command name and optional arguments. When +the handler is invoked, the full invocation line will be appended to the +script and the result evaluated in the context of the namespace. The +default handler for all namespaces is \fB::unknown\fR. If no argument +is given, it returns the handler for the current namespace. +.TP \fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR Looks up \fIname\fR as either a command or variable and returns its fully-qualified name. @@ -237,7 +297,7 @@ this command returns a fully-qualified name in the global namespace. If the command or variable does not exist, this command returns an empty string. If the variable has been created but not defined, such as with the \fBvariable\fR command -or through a \fBtrace\fR on the variable, this command will return the +or through a \fBtrace\fR on the variable, this command will return the fully-qualified name of the variable. If no flag is given, \fIname\fR is treated as a command name. See the section \fBNAME RESOLUTION\fR below for an explanation of @@ -246,7 +306,7 @@ the rules regarding name resolution. .PP A namespace is a collection of commands and variables. It encapsulates the commands and variables to ensure that they -won't interfere with the commands and variables of other namespaces. +will not interfere with the commands and variables of other namespaces. Tcl has always had one such collection, which we refer to as the \fIglobal namespace\fR. The global namespace holds all global variables and commands. @@ -317,8 +377,9 @@ Qualified names are similar to the hierarchical path names for Unix files or Tk widgets, except that \fB::\fR is used as the separator instead of \fB/\fR or \fB.\fR. -The topmost or global namespace has the name ``'' (i.e., an empty string), -although \fB::\fR is a synonym. +The topmost or global namespace has the name +.MT +(i.e., an empty string), although \fB::\fR is a synonym. As an example, the name \fB::safe::interp::create\fR refers to the command \fBcreate\fR in the namespace \fBinterp\fR that is a child of namespace \fB::safe\fR, @@ -377,11 +438,19 @@ If you provide a fully-qualified name that starts with a \fB::\fR, there is no question about what command, variable, or namespace you mean. However, if the name does not start with a \fB::\fR -(i.e., is \fIrelative\fR), -Tcl follows a fixed rule for looking it up: -Command and variable names are always resolved +(i.e., is \fIrelative\fR), +Tcl follows basic rules for looking it up: +Variable names are always resolved by looking first in the current namespace, and then in the global namespace. +.VS 8.5 +Command names are also always resolved by looking in the current +namespace first. If not found there, they are searched for in every +namespace on the current namespace's command path (which is empty by +default). If not found there, command names are looked up in the +global namespace (or, failing that, are processed by the \fBunknown\fR +command.) +.VE 8.5 Namespace names, on the other hand, are always resolved by looking in only the current namespace. .PP @@ -409,7 +478,7 @@ set traceLevel 0 } .CE Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. -Since it is not found there, Tcl then looks for it +Since it is not found there, Tcl then looks for it in the global namespace. The variable \fBFoo::traceLevel\fR is completely ignored during the name resolution process. @@ -484,7 +553,7 @@ from a namespace that that namespace exported with a \fBnamespace export\fR command. .PP Importing \fIevery\fR command from a namespace is generally -a bad idea since you don't know what you will get. +a bad idea since you do not know what you will get. It is better to import just the specific commands you need. For example, the command .CS @@ -561,12 +630,14 @@ may be imported by other namespaces. If a \fBnamespace import\fR command specifies a command that is not exported, the command is not imported. .SH "SCOPED SCRIPTS" +.PP The \fBnamespace code\fR command is the means by which a script may be packaged for evaluation in a namespace other than the one in which it was created. It is used most often to create event handlers, Tk bindings, and traces for evaluation in the global context. For instance, the following -code indicates how to direct a variable trace callback into the current +code indicates how to direct a variable \fBtrace\fR callback into the current namespace: +.PP .CS \fBnamespace eval\fR a { variable b @@ -575,14 +646,172 @@ namespace: puts "the value of $n1 has changed to $var" return } - trace variable b w [\fBnamespace code\fR theTraceCallback] + trace add variable b write [\fBnamespace code\fR theTraceCallback] } set a::b c .CE +.PP When executed, it prints the message: +.PP .CS the value of a::b has changed to c .CE +.SH ENSEMBLES +.PP +.VS 8.5 +The \fBnamespace ensemble\fR is used to create and manipulate ensemble +commands, which are commands formed by grouping subcommands together. +The commands typically come from the current namespace when the +ensemble was created, though this is configurable. Note that there +may be any number of ensembles associated with any namespace +(including none, which is true of all namespaces by default), though +all the ensembles associated with a namespace are deleted when that +namespace is deleted. The link between an ensemble command and its +namespace is maintained however the ensemble is renamed. +.PP +Three subcommands of the \fBnamespace ensemble\fR command are defined: +.TP +\fBnamespace ensemble create\fR ?\fIoption value ...\fR? +Creates a new ensemble command linked to the current namespace, +returning the fully qualified name of the command created. The +arguments to \fBnamespace ensemble create\fR allow the configuration +of the command as if with the \fBnamespace ensemble configure\fR +command. If not overridden with the \fB\-command\fR option, this +command creates an ensemble with exactly the same name as the linked +namespace. See the section \fBENSEMBLE OPTIONS\fR below for a full +list of options supported and their effects. +.TP +\fBnamespace ensemble configure \fIcommand\fR ?\fIoption\fR? ?\fIvalue ...\fR? +Retrieves the value of an option associated with the ensemble command +named \fIcommand\fR, or updates some options associated with that +ensemble command. See the section \fBENSEMBLE OPTIONS\fR below for a +full list of options supported and their effects. +.TP +\fBnamespace ensemble exists\fR \fIcommand\fR +Returns a boolean value that describes whether the command +\fIcommand\fR exists and is an ensemble command. This command only +ever returns an error if the number of arguments to the command is +wrong. +.PP +When called, an ensemble command takes its first argument and looks it +up (according to the rules described below) to discover a list of +words to replace the ensemble command and subcommand with. The +resulting list of words is then evaluated (with no further +substitutions) as if that was what was typed originally (i.e. by +passing the list of words through \fBTcl_EvalObjv\fR) and returning +the result of the command. Note that it is legal to make the target +of an ensemble rewrite be another (or even the same) ensemble +command. The ensemble command will not be visible through the use of +the \fBuplevel\fR or \fBinfo level\fR commands. +.SS "ENSEMBLE OPTIONS" +.PP +The following options, supported by the \fBnamespace ensemble +create\fR and \fBnamespace ensemble configure\fR commands, control how +an ensemble command behaves: +.TP +\fB\-map\fR +When non-empty, this option supplies a dictionary that provides a +mapping from subcommand names to a list of prefix words to substitute +in place of the ensemble command and subcommand words (in a manner +similar to an alias created with \fBinterp alias\fR; the words are not +reparsed after substitution). When this option is empty, the mapping +will be from the local name of the subcommand to its fully-qualified +name. Note that when this option is non-empty and the +\fB\-subcommands\fR option is empty, the ensemble subcommand names +will be exactly those words that have mappings in the dictionary. +.TP +\fB\-prefixes\fR +This option (which is enabled by default) controls whether the +ensemble command recognizes unambiguous prefixes of its subcommands. +When turned off, the ensemble command requires exact matching of +subcommand names. +.TP +\fB\-subcommands\fR +When non-empty, this option lists exactly what subcommands are in the +ensemble. The mapping for each of those commands will be either whatever +is defined in the \fB\-map\fR option, or to the command with the same +name in the namespace linked to the ensemble. If this option is +empty, the subcommands of the namespace will either be the keys of the +dictionary listed in the \fB\-map\fR option or the exported commands +of the linked namespace at the time of the invocation of the ensemble +command. +.TP +\fB\-unknown\fR +When non-empty, this option provides a partial command (to which all +the words that are arguments to the ensemble command, including the +fully-qualified name of the ensemble, are appended) to handle the case +where an ensemble subcommand is not recognized and would otherwise +generate an error. When empty (the default) an error (in the style of +\fBTcl_GetIndexFromObj\fR) is generated whenever the ensemble is +unable to determine how to implement a particular subcommand. See +\fBUNKNOWN HANDLER BEHAVIOUR\fR for more details. +.PP +The following extra option is allowed by \fBnamespace ensemble +create\fR: +.TP +\fB\-command\fR +This write-only option allows the name of the ensemble created by +\fBnamespace ensemble create\fR to be anything in any existing +namespace. The default value for this option is the fully-qualified +name of the namespace in which the \fBnamespace ensemble create\fR +command is invoked. +.PP +The following extra option is allowed by \fBnamespace ensemble +configure\fR: +.TP +\fB\-namespace\fR +This read-only option allows the retrieval of the fully-qualified name +of the namespace which the ensemble was created within. +.SS "UNKNOWN HANDLER BEHAVIOUR" +.PP +If an unknown handler is specified for an ensemble, that handler is +called when the ensemble command would otherwise return an error due +to it being unable to decide which subcommand to invoke. The exact +conditions under which that occurs are controlled by the +\fB\-subcommands\fR, \fB\-map\fR and \fB\-prefixes\fR options as +described above. +.PP +To execute the unknown handler, the ensemble mechanism takes the +specified \fB\-unknown\fR option and appends each argument of the +attempted ensemble command invocation (including the ensemble command +itself, expressed as a fully qualified name). It invokes the resulting +command in the scope of the attempted call. If the execution of the +unknown handler terminates normally, the ensemble engine reparses the +subcommand (as described below) and tries to dispatch it again, which +is ideal for when the ensemble's configuration has been updated by the +unknown subcommand handler. Any other kind of termination of the +unknown handler is treated as an error. +.PP +The result of the unknown handler is expected to be a list (it is an +error if it is not). If the list is an empty list, the ensemble +command attempts to look up the original subcommand again and, if it +is not found this time, an error will be generated just as if the +\fB\-unknown\fR handler was not there (i.e. for any particular +invocation of an ensemble, its unknown handler will be called at most +once.) This makes it easy for the unknown handler to update the +ensemble or its backing namespace so as to provide an implementation +of the desired subcommand and reparse. +.PP +When the result is a non-empty list, the words of that list are used +to replace the ensemble command and subcommand, just as if they had +been looked up in the \fB\-map\fR. It is up to the unknown handler to +supply all namespace qualifiers if the implementing subcommand is not +in the namespace of the caller of the ensemble command. Also note that +when ensemble commands are chained (e.g. if you make one of the +commands that implement an ensemble subcommand into an ensemble, in a +manner similar to the \fBtext\fR widget's tag and mark subcommands) then the +rewrite happens in the context of the caller of the outermost +ensemble. That is to say that ensembles do not in themselves place any +namespace contexts on the Tcl call stack. +.PP +Where an empty \fB\-unknown\fR handler is given (the default), the +ensemble command will generate an error message based on the list of +commands that the ensemble has defined (formatted similarly to the +error message from \fBTcl_GetIndexFromObj\fR). This is the error that +will be thrown when the subcommand is still not recognized during +reparsing. It is also an error for an \fB\-unknown\fR handler to +delete its namespace. +.VE 8.5 .SH EXAMPLES Create a namespace containing a variable and an exported command: .CS @@ -599,20 +828,38 @@ Create a namespace containing a variable and an exported command: Call the command defined in the previous example in various ways. .CS # Direct call -foo::grill +::foo::grill + +# Use the command resolution path to find the name +\fBnamespace eval\fR boo { + \fBnamespace path\fR ::foo + grill +} # Import into current namespace, then call local alias -namespace import foo::grill +\fBnamespace import\fR foo::grill grill + +# Create two ensembles, one with the default name and one with a +# specified name. Then call through the ensembles. +\fBnamespace eval\fR foo { + \fBnamespace ensemble\fR create + \fBnamespace ensemble\fR create -command ::foobar +} +foo grill +foobar grill .CE .PP Look up where the command imported in the previous example came from: .CS puts "grill came from [\fBnamespace origin\fR grill]" .CE - +.PP +Remove all imported commands from the current namespace: +.CS +namespace forget {*}[namespace import] +.CE .SH "SEE ALSO" -variable(n) - +interp(n), upvar(n), variable(n) .SH KEYWORDS -exported, internal, variable +command, ensemble, exported, internal, variable |