Debian Codegraph @

README

raw
1 NAME
2
3 FFI::Platypus::Type::Enum - Custom platypus type for dealing with C
4 enumerated types
5
6 VERSION
7
8 version 0.06
9
10 SYNOPSIS
11
12 C:
13
14 enum {
15 DEFAULT,
16 BETTER,
17 BEST = 12
18 } foo_t;
19
20 foo_t
21 f(foo_t arg)
22 {
23 return foo_t;
24 }
25
26 Perl with strings:
27
28 use FFI::Platypus 1.00;
29 my $ffi = FFI::Platypus->new( api => 1 );
30
31 $ffi->load_custom_type('::Enum', 'foo_t',
32 'default',
33 'better',
34 ['best' => 12],
35 );
36
37 $ffi->attach( f => ['foo_t'] => 'foo_t' );
38
39 f("default") eq 'default'; # true
40 f("default") eq 'better'; # false
41
42 print f("default"), "\n"; # default
43 print f("better"), "\n"; # better
44 print f("best"), "\n"; # best
45
46 Perl with constants:
47
48 use FFI::Platypus 1.00;
49 my $ffi = FFI::Platypus->new( api => 1 );
50
51 $ffi->load_custom_type('::Enum', 'foo_t',
52 { rev => 'int', package => 'Foo', prefix => 'FOO_' },
53 'default',
54 'better',
55 ['best' => 12],
56 );
57
58 $ffi->attach( f => ['foo_t'] => 'foo_t' );
59
60 f(Foo::FOO_DEFAULT) == Foo::FOO_DEFAULT; # true
61 f(Foo::FOO_DEFAULT) == Foo::FOO_BETTER; # false
62
63 DESCRIPTION
64
65 This type plugin is a helper for making enumerated types. It makes the
66 most sense to use this when you have an enumerated type with a small
67 number of possible values. For a large set of enumerated values or
68 constants, see FFI::Platypus::Constant.
69
70 This type plugin has two modes:
71
72 string
73
74 In string mode, string representations of the enum values are
75 converted into the integer enum values when passed into C, and the
76 enums are converted back into strings when coming from C back into
77 Perl. You can also pass in the integer values.
78
79 constant
80
81 In constant mode, constants are defined in the specified package, and
82 with the optional prefix. The string representation or integer
83 constants can be passed into C, but the integer constants are
84 returned from C back into Perl.
85
86 In both modes, if you attempt to pass in a value that isn't one of the
87 possible enum values, an exception will be thrown.
88
89 OPTIONS
90
91 The general form of the custom type load is:
92
93 $ffi->load_custom_type('::Enum', $name, \%options, @values);
94 $ffi->load_custom_type('::Enum', $name, @values);
95
96 The enumerated values are specified as a list of strings and array
97 references.
98
99 string
100
101 $ffi->load_custom_type('::Enum', $name, $string1, $string2, ... );
102
103 For strings the constant value starts at zero (0) and increases by
104 one for each possible value.
105
106 array reference
107
108 $ffi->load_custom_type('::Enum', $name, [ $value_name, $value, %options ]);
109 $ffi->load_custom_type('::Enum', $name, [ $value_name, %options ]);
110
111 You can use an array reference to include an explicit integer value,
112 rather than using the implicit incremented value. You can also use
113 the array reference for value options. If the value isn't included
114 (that is if there are an odd number of values in the array
115 reference), then the implicit incremented value will be used.
116
117 Value options:
118
119 alias
120
121 $ffi->load_custom_type('::Enum, $name, [ $value_name, $value, alias => \@aliases ]);
122 $ffi->load_custom_type('::Enum, $name, [ $value_name, alias => \@aliases ]);
123
124 The alias option lets you specify value aliases. For example,
125 suppose you have an enum definition like:
126
127 enum {
128 FOO,
129 BAR,
130 BAZ=BAR,
131 ABC,
132 XYZ
133 } foo_t;
134
135 The Perl definition would be:
136
137 $ffi->load_custom_type('::Enum', 'foo_t',
138 'foo',
139 ['bar', alias => ['baz']],
140 'abc',
141 'xyz',
142 );
143
144 Type options may be passed in as a hash reference after the type name.
145
146 Type options:
147
148 maps
149
150 my @maps;
151 $ffi->load_custom_type('::Enum', $name, { maps => \@maps }, ... );
152 my($str,$int,$type) = @maps;
153
154 If set to an empty array reference, this will be filled with the
155 string, integer and native type for the enum.
156
157 package
158
159 $ffi->load_custom_type('::Enum', $name, { package => $package }, ... );
160 $ffi->load_custom_type('::Enum', $name, { package => \@package }, ... ); # version 0.05
161
162 This option specifies the Perl package where constants will be
163 defined. If not specified, then no constants will be generated.
164 Unless otherwise specified (see 'casing' below), the constants will
165 be the upper case of the value names as per the usual convention.
166
167 [version 0.05]
168
169 As of version 0.05, you can specify multiple packages to create the
170 constants via an array reference.
171
172 prefix
173
174 $ffi->load_custom_type('::Enum', $name, { prefix => $prefix }, ... );
175
176 This specifies an optional prefix to give each constant. If not
177 specified, then no prefix will be used.
178
179 rev
180
181 $ffi->load_custom_type('::Enum', $name, { rev => 'int' }, ... );
182 $ffi->load_custom_type('::Enum', $name, { rev => 'str' }, ... );
183 $ffi->load_custom_type('::Enum', $name, { rev => 'dualvar' }, ... ); # version 0.05
184
185 This specifies what should be returned for C functions that return
186 the enumerated type. For strings, use str, and for integer constants
187 use int.
188
189 (rev is short for "reverse")
190
191 [version 0.05]
192
193 As of version 0.05, dualvar can be specified to return a
194 string/integer dualvar.
195
196 type
197
198 $ffi->load_custom_type('::Enum', $name, { type => $type }, ... );
199
200 This specifies the integer type that should be used for the
201 enumerated type. The default is to use enum for types that only have
202 positive possible values and senum for types that have possible
203 negative values. (Note that on some platforms these two types may
204 actually be the same).
205
206 You can also use other integer types, which is useful if the enum is
207 only used to define constants, and the values are stored in a type
208 smaller than the default for enum or senum. For example:
209
210 C:
211
212 enum {
213 DEFAULT,
214 BETTER,
215 BEST = 12
216 } foo_enum;
217 typedef uint8_t foo_t;
218
219 /*
220 * you are expected to use the constants from foo_enum,
221 * but the signature actually uses a uint8_t
222 */
223 void f(foo_t);
224
225 Perl:
226
227 $ffi->load_custom_type('::Enum', 'foo_t',
228 { type => 'uint8' },
229 'default',
230 'better',
231 [best => 12],
232 );
233
234 $ffi->attach( f => [ 'foo_t' ] => 'void' );
235
236 casing
237
238 [version 0.06]
239
240 $ffi->load_custom_type('::Enum', $name, { casing => 'upper' }, ... );
241 $ffi->load_custom_type('::Enum', $name, { casing => 'keep' }, ... );
242
243 When in constant mode, all constant names are by default generated in
244 uppercase as is conventional. However, some libraries will on
245 occasion define constant names in mixed case. For these cases, the
246 casing option, added in version 0.06, can be set to keep to prevent
247 the names from being modified. The only other allowed value is upper,
248 which is the default.
249
250 SEE ALSO
251
252 FFI::Platypus
253
254 FFI::C
255
256 AUTHOR
257
258 Author: Graham Ollis <[email protected]>
259
260 Contributors:
261
262 José Joaquín Atria (JJATRIA)
263
264 COPYRIGHT AND LICENSE
265
266 This software is copyright (c) 2020 by Graham Ollis.
267
268 This is free software; you can redistribute it and/or modify it under
269 the same terms as the Perl 5 programming language system itself.
270