summaryrefslogtreecommitdiffstats
path: root/tcl8.6/doc/RegConfig.3
diff options
context:
space:
mode:
Diffstat (limited to 'tcl8.6/doc/RegConfig.3')
-rw-r--r--tcl8.6/doc/RegConfig.3111
1 files changed, 0 insertions, 111 deletions
diff --git a/tcl8.6/doc/RegConfig.3 b/tcl8.6/doc/RegConfig.3
deleted file mode 100644
index d73e3d7..0000000
--- a/tcl8.6/doc/RegConfig.3
+++ /dev/null
@@ -1,111 +0,0 @@
-'\"
-'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-'\" Note: do not modify the .SH NAME line immediately below!
-.SH NAME
-Tcl_RegisterConfig \- procedures to register embedded configuration information
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-void
-\fBTcl_RegisterConfig\fR(\fIinterp, pkgName, configuration, valEncoding\fR)
-.sp
-.SH ARGUMENTS
-.AS Tcl_Interp *configuration
-.AP Tcl_Interp *interp in
-Refers to the interpreter the embedded configuration information is
-registered for. Must not be NULL.
-.AP "const char" *pkgName in
-Contains the name of the package registering the embedded
-configuration as ASCII string. This means that this information is in
-UTF-8 too. Must not be NULL.
-.AP "const Tcl_Config" *configuration in
-Refers to an array of Tcl_Config entries containing the information
-embedded in the binary library. Must not be NULL. The end of the array
-is signaled by either a key identical to NULL, or a key referring to
-the empty string.
-.AP "const char" *valEncoding in
-Contains the name of the encoding used to store the configuration
-values as ASCII string. This means that this information is in UTF-8
-too. Must not be NULL.
-.BE
-.SH DESCRIPTION
-.PP
-The function described here has its base in TIP 59 and provides
-extensions with support for the embedding of configuration
-information into their binary library and the generation of a
-Tcl-level interface for querying this information.
-.PP
-To embed configuration information into their binary library an
-extension has to define a non-volatile array of Tcl_Config entries in
-one if its source files and then call \fBTcl_RegisterConfig\fR to
-register that information.
-.PP
-\fBTcl_RegisterConfig\fR takes four arguments; first, a reference to
-the interpreter we are registering the information with, second, the
-name of the package registering its configuration information, third,
-a pointer to an array of structures, and fourth a string declaring the
-encoding used by the configuration values.
-.PP
-The string \fIvalEncoding\fR contains the name of an encoding known to
-Tcl. All these names are use only characters in the ASCII subset of
-UTF-8 and are thus implicitly in the UTF-8 encoding. It is expected
-that keys are legible English text and therefore using the ASCII
-subset of UTF-8. In other words, they are expected to be in UTF-8
-too. The values associated with the keys can be any string
-however. For these the contents of \fIvalEncoding\fR define which
-encoding was used to represent the characters of the strings.
-.PP
-Each element of the \fIconfiguration\fR array refers to two strings
-containing the key and the value associated with that key. The end of
-the array is signaled by either an empty key or a key identical to
-NULL. The function makes \fBno\fR copy of the \fIconfiguration\fR
-array. This means that the caller has to make sure that the memory
-holding this array is never released. This is the meaning behind the
-word \fBnon-volatile\fR used earlier. The easiest way to accomplish
-this is to define a global static array of Tcl_Config entries. See the file
-.QW generic/tclPkgConfig.c
-in the sources of the Tcl core for an example.
-.PP
-When called \fBTcl_RegisterConfig\fR will
-.IP (1)
-create a namespace having the provided \fIpkgName\fR, if not yet
-existing.
-.IP (2)
-create the command \fBpkgconfig\fR in that namespace and link it to
-the provided information so that the keys from \fIconfiguration\fR and
-their associated values can be retrieved through calls to
-\fBpkgconfig\fR.
-.PP
-The command \fBpkgconfig\fR will provide two subcommands, \fBlist\fR
-and \fBget\fR:
-.RS
-.TP
-::\fIpkgName\fR::\fBpkgconfig\fR list
-Returns a list containing the names of all defined keys.
-.TP
-::\fIpkgName\fR::\fBpkgconfig\fR get \fIkey\fR
-Returns the configuration value associated with the specified
-\fIkey\fR.
-.RE
-.SH TCL_CONFIG
-.PP
-The \fBTcl_Config\fR structure contains the following fields:
-.PP
-.CS
-typedef struct Tcl_Config {
- const char *\fIkey\fR;
- const char *\fIvalue\fR;
-} \fBTcl_Config\fR;
-.CE
-.\" No cross references yet.
-.\" .SH "SEE ALSO"
-.SH KEYWORDS
-embedding, configuration, binary library