FFI::Platypus::Type::Enum - Custom platypus type for dealing with C enumerated types

       Author: Graham Ollis <plicease@cpan.org>

       Contributors:

       José Joaquín Atria (JJATRIA)

       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.

perl v5.36.0                                       2023-02-05                     FFI::Platypus::Type::Enum(3pm)

       This type plugin is a helper for making enumerated types.  It makes the most sense to use this when you
       have an enumerated type with a small number of possible values.  For a large set of enumerated values or
       constants, see FFI::Platypus::Constant.

       This type plugin has two modes:

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

       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
           returned from C back into Perl.

       In both modes, if you attempt to pass in a value that isn't one of the possible enum values, an exception
       will be thrown.

       FFI::Platypus::Type::Enum - Custom platypus type for dealing with C enumerated types

       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.

       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.   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 may be passed in as a hash reference after the type name.

       Type options:

       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.

       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.

       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.

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

           [version 0.05]

           As of version 0.05, dualvar can be specified to return a string/integer dualvar.

       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.

       FFI::Platypus
       FFI::C

       C:

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

        foo_t
        f(foo_t arg)
        {
          return foo_t;
        }

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

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

       version 0.06