| 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 |
|