FFI::P...e::Enum(3pm)

✨ NAME ✨

FFI::Platypus::Type::Enum — a custom platypus type for dealing with C enumerated types 💖

(It lives in the User Contributed Perl Documentation corner of the manual world, section 3pm, iykyk.)

---

🌸 VERSION 🌸

version 0.06

---

🦋 SYNOPSIS 🦋

okay so FIRST, the C side, because we gotta set the scene:

enum {
  DEFAULT,
  BETTER,
  BEST = 12
} foo_t;

foo_t
f(foo_t arg)
{
  return foo_t;
}

Then Perl, but make it strings:

use FFI::Platypus 1.00;
my $ffi = FFI::Platypus->new( api => 1 );

$ffi->load_custom_type('::Enum', 'foo_t',
  'default',
  'better',
  ['best' => 12],
);

$ffi->attach( f => ['foo_t'] => 'foo_t' );

f("default") eq 'default';  # true
f("default") eq 'better';   # false

print f("default"), "\n";   # default
print f("better"),  "\n";   # better
print f("best"),    "\n";   # best

And now Perl, but make it constants:

use FFI::Platypus 1.00;
my $ffi = FFI::Platypus->new( api => 1 );

$ffi->load_custom_type('::Enum', 'foo_t',
  { rev => 'int', package => 'Foo', prefix => 'FOO_' },
  'default',
  'better',
  ['best' => 12],
);

$ffi->attach( f => ['foo_t'] => 'foo_t' );

f(Foo::FOO_DEFAULT) == Foo::FOO_DEFAULT;   # true
f(Foo::FOO_DEFAULT) == Foo::FOO_BETTER;    # false

---

💅 DESCRIPTION 💅

This type plugin is basically your lil helper for making enumerated types. It makes the most sense to use this when you've got an enumerated type with a small number of possible values. Got a large set of enumerated values or constants instead? Then bestie, go see FFI::Platypus::Constant — different vibe, different tool 💅

This type plugin has two modes:

string

In string mode, the string representations of the enum values get converted into the integer enum values when passed into C, and the enums get converted back into strings when coming from C back into Perl. You can also pass in the integer values. Versatile queen ✨

constant

In constant mode, constants are defined in the specified package, and with the optional prefix. The string representation or integer constants can be passed into C, but the integer constants are what get returned from C back into Perl.

And in BOTH modes, no cap: if you attempt to pass in a value that isn't one of the possible enum values, an exception will be thrown. 💀

---

🎀 OPTIONS 🎀

The general form of the custom type load is:

$ffi->load_custom_type('::Enum', $name, \%options, @values);
$ffi->load_custom_type('::Enum', $name, @values);

The enumerated values are specified as a list of strings and array references.

string

$ffi->load_custom_type('::Enum', $name, $string1, $string2, ... );

For strings, the constant value starts at zero (0) and increases by one for each possible value. cute, predictable, iconic.

array reference

$ffi->load_custom_type('::Enum', $name, [ $value_name, $value, %options ]);
$ffi->load_custom_type('::Enum', $name, [ $value_name, %options ]);

You can use an array reference to include an explicit integer value, rather than using the implicit incremented value. You can also use the array reference for value options. And if the value isn't included (that is, if there are an odd number of values in the array reference), then the implicit incremented value will be used. 💫

Value options

alias

$ffi->load_custom_type('::Enum, $name, [ $value_name, $value, alias => \@aliases ]);
$ffi->load_custom_type('::Enum, $name, [ $value_name, alias => \@aliases ]);

The alias option lets you specify value aliases. For example, suppose you have an enum definition like:

enum {
  FOO,
  BAR,
  BAZ=BAR,
  ABC,
  XYZ
} foo_t;

The Perl definition would be:

$ffi->load_custom_type('::Enum', 'foo_t',
  'foo',
  ['bar', alias => ['baz']],
  'abc',
  'xyz',
);

Type options

Type options may be passed in as a hash reference after the type name. Slay.

maps

my @maps;
$ffi->load_custom_type('::Enum', $name, { maps => \@maps }, ... );
my($str,$int,$type) = @maps;

If set to an empty array reference, this will be filled with the string, integer and native type for the enum. Free info, we love that 🫶

package

$ffi->load_custom_type('::Enum', $name, { package => $package  }, ... );
$ffi->load_custom_type('::Enum', $name, { package => \@package }, ... );  # version 0.05

This option specifies the Perl package where constants will be defined. If not specified, then no constants will be generated. Unless otherwise specified (see casing below), the constants will be the upper case of the value names as per the usual convention.

[version 0.05]

As of version 0.05, you can specify multiple packages to create the constants via an array reference. glow up ✨

prefix

$ffi->load_custom_type('::Enum', $name, { prefix => $prefix }, ... );

This specifies an optional prefix to give each constant. If not specified, then no prefix will be used. simple as that.

rev

$ffi->load_custom_type('::Enum', $name, { rev => 'int'     }, ... );
$ffi->load_custom_type('::Enum', $name, { rev => 'str'     }, ... );
$ffi->load_custom_type('::Enum', $name, { rev => 'dualvar' }, ... );  # version 0.05

This specifies what should be returned for C functions that return the enumerated type. For strings, use "str", and for integer constants use "int".

("rev" is short for "reverse" — cute lil abbreviation, we stan)

[version 0.05]

As of version 0.05, dualvar can be specified to return a string/integer dualvar. two-for-one deal 💅

type

$ffi->load_custom_type('::Enum', $name, { type => $type }, ... );

This specifies the integer type that should be used for the enumerated type. The default is to use "enum" for types that only have positive possible values and "senum" for types that have possible negative values. (Note that on some platforms these two types may actually be the same.)

You can also use other integer types, which is useful if the enum is only used to define constants, and the values are stored in a type smaller than the default for "enum" or "senum". For example:

C:

enum {
  DEFAULT,
  BETTER,
  BEST = 12
} foo_enum;
typedef uint8_t foo_t;

/*
 * you are expected to use the constants from foo_enum,
 * but the signature actually uses a uint8_t
 */
void f(foo_t);

Perl:

$ffi->load_custom_type('::Enum', 'foo_t',
  { type => 'uint8' },
  'default',
  'better',
  [best => 12],
);

$ffi->attach( f => [ 'foo_t' ] => 'void' );

casing

[version 0.06]

$ffi->load_custom_type('::Enum', $name, { casing => 'upper' }, ... );
$ffi->load_custom_type('::Enum', $name, { casing => 'keep'  }, ... );

When in constant mode, all constant names are by default generated in uppercase as is conventional. However, some libraries will on occasion define constant names in mixed case. For these cases, the "casing" option, added in version 0.06, can be set to "keep" to prevent the names from being modified. The only other allowed value is "upper", which is the default. no in-between, we don't do that here 🎀

---

🌈 SEE ALSO 🌈

• FFI::Platypus
• FFI::C

---

👑 AUTHOR 👑

Author: Graham Ollis <plicease@cpan.org>

Contributors:

• José Joaquín Atria (JJATRIA)

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2020 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page bestie, tysm for reading 🫶 this one's from perl v5.36.0, dated 2023-02-05, and it ate, no notes 💖✨