'\"
'\" Generated from file 'namespacex\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 200? Neil Madden (http://wiki\&.tcl\&.tk/12790)
'\" Copyright (c) 200? Various (http://wiki\&.tcl\&.tk/1489)
'\" Copyright (c) 2010 Documentation, Andreas Kupries
'\"
.TH "namespacex" 3tcl 0\&.3 tcllib "Namespace utility commands"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp
-1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
namespacex \- Namespace utility commands
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBnamespacex  ?0\&.3?\fR
.sp
\fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR
.sp
\fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR
.sp
\fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR
.sp
\fB::namespacex hook next\fR \fIarg\fR\&.\&.\&.
.sp
\fB::namespacex import fromns\fR \fIcmdname ?\fInewname\fR \&.\&.\&.?\fR
.sp
\fB::namespacex info allchildren\fR \fInamespace\fR
.sp
\fB::namespacex info allvars\fR \fInamespace\fR
.sp
\fB::namespacex normalize\fR \fInamespace\fR
.sp
\fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR?
.sp
\fB::namespacex state get\fR \fInamespace\fR
.sp
\fB::namespacex state set\fR \fInamespace\fR \fIdict\fR
.sp
\fB::namespacex state drop\fR \fInamespace\fR
.sp
\fB::namespacex strip\fR \fIprefix\fR \fInamespaces\fR
.sp
.BE
.SH DESCRIPTION
This package provides a number of utility commands for working with
namespaces\&.
The commands fall into four categories:
.IP [1]
Hook commands provide and manipulate a chain of commands which
replaces the single regular \fBnamespace unknown\fR handler\&.
.IP [2]
An import command provides the ability to import any command
from another namespace\&.
.IP [3]
Information commands allow querying of variables and child
namespaces\&.
.IP [4]
State commands provide a means to serialize variable values in
a namespace\&.
.PP
.SH COMMANDS
.TP
\fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR
Adds the \fIcmdprefix\fR to the chain of unknown command handlers that
are invoked when the \fInamespace\fR would otherwise invoke its
unknown handler\&.
If \fInamespace\fR is not specified, then \fIcmdprefix\fR is added to
the chain of handlers for the namespace of the caller\&.
.sp
The chain of \fIcmdprefix\fR are executed in reverse order of
addition, \fIi\&.e\&.\fR the most recently added \fIcmdprefix\fR is
executed first\&.
When executed, \fIcmdprefix\fR has additional arguments appended to it
as would any namespace unknown handler\&.
.TP
\fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR
Adds an anonymous procedure to the chain of namespace unknown handlers
for the \fInamespace\fR\&.
.sp
If \fInamespace\fR is not specified, then the handler is added
to the chain of handlers for the namespace of the caller\&.
.sp
The \fIarguments\fR and \fIbody\fR are specified as for the
core \fBproc\fR command\&.
.TP
\fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR
Adds a guarded action to the chain of namespace unknown handlers for
the \fInamespace\fR\&.
.sp
If \fInamespace\fR is not specified, then the handler is added
to the chain of handlers for the namespace of the caller\&.
.sp
The \fIguardcmdprefix\fR is executed first\&. If it returns a
value that can be interpreted as false, then the next unknown hander
in the chain is executed\&. Otherwise, \fIactioncmdprefix\fR is executed
and the return value of the handler is the value returned by
\fIactioncmdprefix\fR\&.
.sp
When executed, both \fIguardcmdprefix\fR and
\fIactioncmdprefix\fR have the same additional arguments appended as
for any namespace unknown handler\&.
.TP
\fB::namespacex hook next\fR \fIarg\fR\&.\&.\&.
This command is available to namespace hooks to execute the next hook
in the chain of handlers for the namespace\&.
.TP
\fB::namespacex import fromns\fR \fIcmdname ?\fInewname\fR \&.\&.\&.?\fR
Imports the command \fIcmdname\fR from the \fIfromns\fR namespace into
the namespace of the caller\&.
The \fIcmdname\fR command is imported even if the \fIfromns\fR did not
originally export the command\&.
.sp
If \fInewname\fR is specified, then the imported command will
be known by that name\&. Otherwise, the command retains is original name
as given by \fIcmdname\fR\&.
.sp
Additional pairs of \fIcmdname\fR / \fInewname\fR arguments may
also be specified\&.
.TP
\fB::namespacex info allchildren\fR \fInamespace\fR
Returns a list containing the names of all child namespaces in the
specified \fInamespace\fR and its children\&. The names are all fully
qualified\&.
.TP
\fB::namespacex info allvars\fR \fInamespace\fR
Returns a list containing the names of all variables in the specified
\fInamespace\fR and its children\&. The names are all given relative to
\fInamespace\fR, and \fInot\fR fully qualified\&.
.TP
\fB::namespacex normalize\fR \fInamespace\fR
Returns the absolute name of \fInamespace\fR, which is resolved
relative to the namespace of the caller, with all unneeded colon
characters removed\&.
.TP
\fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR?
Returns a list containing the names of all variables in
the specified \fInamespace\fR\&.
If the \fIpattern\fR argument is specified, then only variables
matching \fIpattern\fR are returned\&. Matching is determined using the
same rules as for \fBstring match\fR\&.
.TP
\fB::namespacex state get\fR \fInamespace\fR
Returns a dictionary holding the names and values of all variables in
the specified \fInamespace\fR and its child namespaces\&.
.sp
Note that the names are all relative to \fInamespace\fR, and
\fInot\fR fully qualified\&.
.TP
\fB::namespacex state set\fR \fInamespace\fR \fIdict\fR
Takes a dictionary holding the names and values for a set of variables
and replaces the current state of the specified \fInamespace\fR and
its child namespaces with this state\&.
The result of the command is the empty string\&.
.TP
\fB::namespacex state drop\fR \fInamespace\fR
Unsets all variables in the specified \fInamespace\fR and its child
namespaces\&.
The result of the command is the empty string\&.
.TP
\fB::namespacex strip\fR \fIprefix\fR \fInamespaces\fR
Each item in \fInamespaces\fR must be the absolute normalized name of
a child namespace of namespace \fIprefix\fR\&.
Returns the corresponding list of relative names of child namespaces\&.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fInamespacex\fR of the
\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.PP
When proposing code changes, please provide \fIunified diffs\fR,
i\&.e the output of \fBdiff -u\fR\&.
.PP
Note further that \fIattachments\fR are strongly preferred over
inlined patches\&. Attachments can be made by going to the \fBEdit\fR
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar\&.
.SH KEYWORDS
extended namespace, info, namespace unknown, namespace utilities, state (de)serialization, unknown hooking, utilities
.SH COPYRIGHT
.nf
Copyright (c) 200? Neil Madden (http://wiki\&.tcl\&.tk/12790)
Copyright (c) 200? Various (http://wiki\&.tcl\&.tk/1489)
Copyright (c) 2010 Documentation, Andreas Kupries

.fi