1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
[comment {-*- tcl -*- doctools manpage}]
[vset enum_version 1.2]
[manpage_begin critcl::enum 3tcl [vset enum_version]]
[include include/module2.inc]
[keywords singleton {Tcl Interp Association}]
[keywords {string pool} {literal pool}]
[keywords {string to int mapping} conversion]
[keywords {int to string mapping}]
[titledesc {CriTcl - Wrap Support - String/Integer mapping}]
[require Tcl 8.6]
[require critcl [opt 3.2]]
[require critcl::enum [opt [vset enum_version]]]
[description]
[para]
[include include/welcome.inc]
[para]
This document is the reference manpage for the
[package critcl::enum] package. This package provides convenience
commands for advanced functionality built on top of both critcl core
and package [package critcl::literals].
[para] It is an extended form of string pool which not only converts
integer values into Tcl-level strings, but also handles the reverse
direction, converting from strings to the associated integer values.
[para] It essentially provides a bi-directional mapping between a C
enumeration type and a set of strings, one per enumeration value.
[emph Note] that the C enumeration in question is created by the
definition. It is not possible to use the symbols of an existing
enumeration type.
[para] This package was written to make the declaration and management
of such mappings easy. It uses a string pool for one of the directions,
using its ability to return shared literals and conserve memory.
[para] Its intended audience are mainly developers wishing to write
Tcl packages with embedded C code.
[para] This package resides in the Core Package Layer of CriTcl.
[para][image arch_core][para]
[comment {= = == === ===== ======== ============= =====================}]
[section API]
[list_begin definitions]
[call [cmd ::critcl::enum::def] [arg name] [arg definition] [opt [arg mode]]]
This command defines two C functions for the conversion between
C values and Tcl_Obj'ects, with named derived from [arg name].
[para] The [arg definition] dictionary provides the mapping from the
specified C-level symbolic names to the strings themselves.
[para]
The [arg mode]-list configures the output somewhat.
The two allowed modes are [const +list] and [const tcl].
All modes can be used together.
The default mode is [const tcl].
Using mode [const +list] implies [const tcl] as well.
[para] For mode [const tcl] the new function has two arguments, a
[type Tcl_Interp*] pointer refering to the interpreter holding the
string pool, and a code of type "[arg name]_pool_names" (see below),
the symbolic name of the string to return. The result of the function
is a [type Tcl_Obj*] pointer to the requested string constant.
[para] For mode [const +list] all of [const tcl] applies, plus an
additional function is generated which takes three arguments, in
order: a [type Tcl_Interp*] pointer refering to the interpreter
holding the string pool, an [type int] holding the size of the last
argument, and an array of type "[arg name]_pool_names" holding the
codes (see below), the symbolic names of the strings to return. The
result of the function is a [type Tcl_Obj*] pointer to a Tcl list
holding the requested string constants.
[para] The underlying string pool is automatically initialized on
first access, and finalized on interpreter destruction.
[para] The package generates multiple things (declarations and
definitions) with names derived from [arg name], which has to be a
proper C identifier.
[list_begin definitions]
[def [arg name]_pool_names]
The C enumeration type containing the specified symbolic names.
[def [arg name]_ToObj]
The function converting from integer value to Tcl string.
Its signature is
[para][example_begin]
Tcl_Obj* [arg name]_ToObj (Tcl_Interp* interp, [arg name]_names literal);
[example_end]
[def [arg name]_ToObjList]
The mode [const +list] function converting from integer array to Tcl
list of strings.
Its signature is
[para][example_begin]
Tcl_Obj* [arg name]_ToObjList (Tcl_Interp* interp, int c, [arg name]_names* literal);
[example_end]
[def [arg name]_GetFromObj]
The function converting from Tcl string to integer value.
Its signature is
[para][example_begin]
int [arg name]_GetFromObj (Tcl_Interp* interp, Tcl_Obj* obj, int flags, int* literal);
[example_end]
The [arg flags] are like for [fun Tcl_GetIndexFromObj].
[def [arg name].h]
A header file containing the declarations for the converter functions,
for use by other parts of the system, if necessary.
[para] The generated file is stored in a place where it will not
interfere with the overall system outside of the package, yet also be
available for easy inclusion by package files ([cmd csources]).
[def [arg name]]
At the level of critcl itself the command registers a new result-type
for [cmd critcl::cproc], which takes an integer result from the function
and converts it to the equivalent string in the pool for the script.
[def [arg name]]
At the level of critcl itself the command registers a new argument-type
for [cmd critcl::cproc], which takes a Tcl string and converts it to the
equivalent integer for delivery to the function.
[list_end]
[list_end]
[comment {= = == === ===== ======== ============= =====================}]
[section Example]
The example shown below is the specification for a set of actions, methods,
and the like, a function may take as argument.
[example {
package require Tcl 8.6
package require critcl 3.2
critcl::buildrequirement {
package require critcl::enum
}
critcl::enum::def action {
w_create "create"
w_directory "directory"
w_events "events"
w_file "file"
w_handler "handler"
w_remove "remove"
}
# Declarations: action.h
# Type: action_names
# Accessor: Tcl_Obj* action_ToObj (Tcl_Interp* interp, int literal);
# Accessor: int action_GetFromObj (Tcl_Interp* interp, Tcl_Obj* o, int flags, int* literal);
# ResultType: action
# ArgType: action
}]
[comment {= = == === ===== ======== ============= =====================}]
[include include/feedback2.inc]
[manpage_end]
|
