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
|
[comment {-*- tcl -*- doctools manpage}]
[vset enum_version 1.0.1]
[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 Utilities: String/Integer mapping}]
[require Tcl 8.4]
[require critcl [opt 3.1.11]]
[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]]
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 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]_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.5
package require critcl 3.1.11
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]
|
