From aac13526452e2ad19e958055cef8943d05c6a390 Mon Sep 17 00:00:00 2001 From: andreas_kupries Date: Tue, 5 Feb 2002 22:15:22 +0000 Subject: * unix/mkLinks: Regenerated. * doc/RegConfig.3: Added documentation for the new public API function. --- ChangeLog | 4 ++ doc/RegConfig.3 | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ unix/mkLinks | 4 ++ 3 files changed, 131 insertions(+) create mode 100644 doc/RegConfig.3 diff --git a/ChangeLog b/ChangeLog index f4c4fe3..7e1deca 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2002-02-05 Andreas Kupries + * unix/mkLinks: Regenerated. + * doc/RegConfig.3: Added documentation for the new public API + function. + * This commit addresses the following topics from the comments at SF item 507083: diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 new file mode 100644 index 0000000..c3249a2 --- /dev/null +++ b/doc/RegConfig.3 @@ -0,0 +1,123 @@ +'\" +'\" Copyright (c) 2002 Andreas Kupries +'\" +'\" 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.1.2.1 2002/02/05 22:15:23 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 \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 diff --git a/unix/mkLinks b/unix/mkLinks index 6ac5d77..3744e3a 100644 --- a/unix/mkLinks +++ b/unix/mkLinks @@ -869,6 +869,10 @@ if test -r RecordEval.3; then rm -f Tcl_RecordAndEval.3 ln RecordEval.3 Tcl_RecordAndEval.3 fi +if test -r RegConfig.3; then + rm -f Tcl_RegisterConfig.3 + ln RegConfig.3 Tcl_RegisterConfig.3 +fi if test -r RegExp.3; then rm -f Tcl_RegExpMatch.3 rm -f Tcl_RegExpCompile.3 -- cgit v0.12