1Tcl_RegisterConfig(3)       Tcl Library Procedures       Tcl_RegisterConfig(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_RegisterConfig  -  procedures  to  register  embedded configuration
9       information
10

SYNOPSIS

12       #include <tcl.h>
13
14       void
15       Tcl_RegisterConfig(interp, pkgName, configuration, valEncoding)
16
17

ARGUMENTS

19       Tcl_Interp *interp (in)                 Refers to the  interpreter  the
20                                               embedded configuration informa‐
21                                               tion is  registered  for.  Must
22                                               not be NULL.
23
24       const char *pkgName (in)                Contains  the name of the pack‐
25                                               age  registering  the  embedded
26                                               configuration  as ASCII string.
27                                               This means that  this  informa‐
28                                               tion  is in UTF-8 too. Must not
29                                               be NULL.
30
31       const Tcl_Config *configuration (in)    Refers to an array of  Tcl_Con‐
32                                               fig   entries   containing  the
33                                               information  embedded  in   the
34                                               binary  library.  Must  not  be
35                                               NULL. The end of the  array  is
36                                               signaled  by either a key iden‐
37                                               tical to NULL, or a key  refer‐
38                                               ring to the empty string.
39
40       const char *valEncoding (in)            Contains the name of the encod‐
41                                               ing used to store the  configu‐
42                                               ration  values as ASCII string.
43                                               This means that  this  informa‐
44                                               tion  is in UTF-8 too. Must not
45                                               be NULL.
46______________________________________________________________________________
47

DESCRIPTION

49       The function described here has its base in TIP 59 and provides  exten‐
50       sions  with support for the embedding of configuration information into
51       their binary library and the generation of a  Tcl-level  interface  for
52       querying this information.
53
54       To  embed configuration information into their binary library an exten‐
55       sion has to define a non-volatile array of Tcl_Config entries in one if
56       its  source  files  and  then  call Tcl_RegisterConfig to register that
57       information.
58
59       Tcl_RegisterConfig takes four arguments;  first,  a  reference  to  the
60       interpreter  we  are registering the information with, second, the name
61       of the package registering  its  configuration  information,  third,  a
62       pointer  to  an  array of structures, and fourth a string declaring the
63       encoding used by the configuration values.
64
65       The string valEncoding contains the name of an encoding known  to  Tcl.
66       All  these  names  are use only characters in the ASCII subset of UTF-8
67       and are thus implicitly in the UTF-8 encoding. It is expected that keys
68       are legible English text and therefore using the ASCII subset of UTF-8.
69       In other words, they are expected to be in UTF-8 too. The values  asso‐
70       ciated  with the keys can be any string however. For these the contents
71       of valEncoding define which encoding was used to represent the  charac‐
72       ters of the strings.
73
74       Each  element of the configuration array refers to two strings contain‐
75       ing the key and the value associated with that  key.  The  end  of  the
76       array  is  signaled  by either an empty key or a key identical to NULL.
77       The function makes no copy of the configuration array. This means  that
78       the caller has to make sure that the memory holding this array is never
79       released. This is the meaning behind the word  non-volatile  used  ear‐
80       lier.  The  easiest way to accomplish this is to define a global static
81       array of Tcl_Config entries. See the file  “generic/tclPkgConfig.c”  in
82       the sources of the Tcl core for an example.
83
84       When called Tcl_RegisterConfig will
85
86       (1)    create  a  namespace  having  the  provided  pkgName, if not yet
87              existing.
88
89       (2)    create the command pkgconfig in that namespace and  link  it  to
90              the provided information so that the keys from configuration and
91              their associated values can be retrieved through calls  to  pkg‐
92              config.
93
94       The command pkgconfig will provide two subcommands, list and get:
95
96              ::pkgName::pkgconfig list
97                     Returns a list containing the names of all defined keys.
98
99              ::pkgName::pkgconfig get key
100                     Returns the configuration value associated with the spec‐
101                     ified key.
102

TCL_CONFIG

104       The Tcl_Config structure contains the following fields:
105
106              typedef struct Tcl_Config {
107                  const char *key;
108                  const char *value;
109              } Tcl_Config;
110

KEYWORDS

112       embedding, configuration, binary library
113
114
115
116Tcl                                   8.4                Tcl_RegisterConfig(3)
Impressum