diff options
author | andreas_kupries <andreas_kupries@noemail.net> | 2003-06-09 22:48:32 (GMT) |
---|---|---|
committer | andreas_kupries <andreas_kupries@noemail.net> | 2003-06-09 22:48:32 (GMT) |
commit | dbeab086deb3be8da9853892b4a88e1c1acbc913 (patch) | |
tree | 9f56d3de04d71da41a5b38e81e4714993d4d0af1 /doc | |
parent | 0694f1855b4a6e66f5bcde03b305e777463f9b26 (diff) | |
download | tcl-dbeab086deb3be8da9853892b4a88e1c1acbc913.zip tcl-dbeab086deb3be8da9853892b4a88e1c1acbc913.tar.gz tcl-dbeab086deb3be8da9853892b4a88e1c1acbc913.tar.bz2 |
* generic/tcl.decls: Ported the changes from the
* generic/tcl.h: 'tip-59-implementation' branch into the CVS
* generic/tclBasic.c: head. Regenerated stub table. Regenerated
* generic/tclInt.h: the configure's scripts, with help from Joe
* generic/tclDecls.h English.
* generic/tclStubInit.c:
* generic/tclConfig.c:
* generic/tclPkgConfig.c:
* unix/Makefile.in:
* unix/configure.in: The changes in the windows section are not
* unix/tcl.m4: yet committed, they await feedback from
* unix/mkLinks: David Gravereaux.
* doc/RegConfig.3:
* mac/tclMacPkgConfig.c:
* tests/config.test:
FossilOrigin-Name: 8397302b4de4c8614e57e7e5b8ff31760faa48ef
Diffstat (limited to 'doc')
-rw-r--r-- | doc/RegConfig.3 | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 new file mode 100644 index 0000000..14d17d8 --- /dev/null +++ b/doc/RegConfig.3 @@ -0,0 +1,123 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: RegConfig.3,v 1.2 2003/06/09 22:49:13 andreas_kupries Exp $ +.so man.macros +.TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures" +.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 +.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 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 refering 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 implicity 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 "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 _configuration_ 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 + +The \fBTcl_Config\fR structure contains the following fields: +.PP +.CS + typedef struct Tcl_Config { + CONST char* key; + CONST char* value; + } Tcl_Config; +.CE + +'\" No cross references yet. +'\" .SH "SEE ALSO" + +.SH KEYWORDS +embedding, configuration, bianry library |