Added enums -> as-int config option to use integer values (#1344)

Author: LeviLesches-KDAB

pkgs/ffigen/CHANGELOG.md

@@ -16,7 +16,8 @@
   of abstract classes with integer constants. Native enum members with the same
   integer values are handled properly on the Dart side, and native functions
   that use enums in their signatures now accept the generated enums on the Dart
-  side, instead of integer values.
+  side, instead of integer values. To opt out of this, use the `enums->as-int`
+  option as specified in the README.
 - __Breaking change__: Enum integer types are implementation-defined and not
   part of the ABI. Therefore FFIgen does a best-effort approach trying to mimic
   the most common compilers for the various OS and architecture combinations.
@@ -90,7 +91,7 @@ must be passed to change this behaviour.
   generate a typedef for the `Function`.
 - Use Dart wrapper types in args and returns of ObjCBlocks.
 - Use Dart wrapper types in args and returns of static functions.
-- Renamed `asset` to `assetId` for `ffi-native`.  
+- Renamed `asset` to `assetId` for `ffi-native`.
 
 ## 9.0.1
 

pkgs/ffigen/README.md

@@ -111,7 +111,7 @@ or
 ```yaml
 output:
   bindings: 'generated_bindings.dart'
-  ... 
+  ...
 ```
   </td>
   </tr>
@@ -263,6 +263,10 @@ enums:
       # $1 keeps only the 1st
       # group i.e only '(.*)'.
       'CXType(.*)': '$1'
+  as-int:
+    # These enums will be generated as Dart integers instead of Dart enums
+    include:
+      - MyIntegerEnum
 globals:
   exclude:
     - aGlobal
@@ -816,6 +820,31 @@ unnamed-enums:
     'CXType_(.*)': '$1'
 ```
 
+### How can I handle unexpected enum values?
+
+Native enums are, by default, generated into Dart enums with `int get value` and `fromValue(int)`.
+This works well in the case that your enums values are known in advance and not going to change,
+and in return, you get the full benefits of Dart enums like exhaustiveness checking.
+
+However, if a native library adds another possible enum value after you generate your bindings,
+and this new value is passed to your Dart code, this will result in an `ArgumentError` at runtime.
+To fix this, you can regenerate the bindings on the new header file, but if you wish to avoid this
+issue entirely, you can tell ffigen to generate plain Dart integers for your enum instead. To do
+this, simply list your enum's name in the `as-int` section of your ffigen config:
+```yaml
+enums:
+  as-int:
+    include:
+      - MyIntegerEnum
+      - '*IntegerEnum'
+    exclude:
+      - FakeIntegerEnum
+```
+
+Functions that accept or return these enums will now accept or return integers instead, and it will
+be up to your code to map integer values to behavior and handle invalid values. But your code will
+be future-proof against new additions to the enums.
+
 ### Why are some struct/union declarations generated even after excluded them in config?
 
 This happens when an excluded struct/union is a dependency to some included declaration.

pkgs/ffigen/ffigen.schema.json

@@ -250,6 +250,9 @@
         },
         "member-rename": {
           "$ref": "#/$defs/memberRename"
+        },
+        "as-int": {
+          "$ref": "#/$defs/includeExclude"
         }
       }
     },
@@ -265,6 +268,9 @@
         },
         "rename": {
           "$ref": "#/$defs/rename"
+        },
+        "as-int": {
+          "$ref": "#/$defs/includeExclude"
         }
       }
     },

pkgs/ffigen/lib/src/code_generator/enum_class.dart

@@ -52,6 +52,9 @@ class EnumClass extends BindingType {
 
   ObjCBuiltInFunctions? objCBuiltInFunctions;
 
+  /// Whether this enum should be generated as a collection of integers.
+  bool generateAsInt;
+
   EnumClass({
     super.usr,
     super.originalName,
@@ -60,6 +63,7 @@ class EnumClass extends BindingType {
     Type? nativeType,
     List<EnumConstant>? enumConstants,
     this.objCBuiltInFunctions,
+    this.generateAsInt = false,
   })  : nativeType = nativeType ?? intType,
         enumConstants = enumConstants ?? [],
         namer = UniqueNamer({name});
@@ -84,7 +88,7 @@ class EnumClass extends BindingType {
 
   /// Returns a string to declare the enum member and any documentation it may
   /// have had.
-  String formatValue(EnumConstant ec) {
+  String formatValue(EnumConstant ec, {bool asInt = false}) {
     final buffer = StringBuffer();
     final enumValueName = namer.makeUnique(ec.name);
     enumNames[ec] = enumValueName;
@@ -93,7 +97,11 @@ class EnumClass extends BindingType {
       buffer.writeAll(ec.dartDoc!.split('\n'), '\n$depth/// ');
       buffer.write('\n');
     }
-    buffer.write('$depth$enumValueName(${ec.value})');
+    if (asInt) {
+      buffer.write('${depth}static const $enumValueName = ${ec.value};');
+    } else {
+      buffer.write('$depth$enumValueName(${ec.value})');
+    }
     return buffer.toString();
   }
 
@@ -124,6 +132,10 @@ class EnumClass extends BindingType {
     }
   }
 
+  void writeIntegerConstants(StringBuffer s) {
+    s.writeAll(enumConstants.map((c) => formatValue(c, asInt: true)), '\n');
+  }
+
   /// Writes the enum declarations for all unique members.
   ///
   /// Eg, C: `apple = 1`, Dart: `apple(1)`
@@ -232,6 +244,10 @@ class EnumClass extends BindingType {
     writeDartDoc(s);
     if (enumConstants.isEmpty) {
       writeEmptyEnum(s);
+    } else if (generateAsInt) {
+      s.write('abstract class $name {\n');
+      writeIntegerConstants(s);
+      s.write('}\n\n');
     } else {
       s.write('enum $name {\n');
       writeUniqueMembers(s);
@@ -278,7 +294,7 @@ class EnumClass extends BindingType {
   bool get sameFfiDartAndCType => nativeType.sameFfiDartAndCType;
 
   @override
-  bool get sameDartAndFfiDartType => false;
+  bool get sameDartAndFfiDartType => generateAsInt;
 
   @override
   String? getDefaultValue(Writer w) => '0';

pkgs/ffigen/lib/src/config_provider/config.dart

@@ -204,6 +204,12 @@ class Config {
   Includer get leafFunctions => _leafFunctions;
   late Includer _leafFunctions;
 
+  Includer get enumsAsInt => _enumsAsInt;
+  late Includer _enumsAsInt;
+
+  Includer get unnamedEnumsAsInt => _unnamedEnumsAsInt;
+  late Includer _unnamedEnumsAsInt;
+
   FfiNativeConfig get ffiNativeConfig => _ffiNativeConfig;
   late FfiNativeConfig _ffiNativeConfig;
 
@@ -482,10 +488,13 @@ class Config {
                 ..._includeExcludeProperties(),
                 ..._renameProperties(),
                 ..._memberRenameProperties(),
+                ..._enumIntProperties(),
               ],
               result: (node) {
                 _enumClassDecl = declarationConfigExtractor(
                     node.value as Map<dynamic, dynamic>);
+                _enumsAsInt =
+                    (node.value as Map)[strings.enumAsInt] as Includer;
               },
             )),
         HeterogeneousMapEntry(
@@ -494,10 +503,13 @@ class Config {
               entries: [
                 ..._includeExcludeProperties(),
                 ..._renameProperties(),
+                ..._enumIntProperties(),
               ],
               result: (node) {
                 _unnamedEnumConstants = declarationConfigExtractor(
                     node.value as Map<dynamic, dynamic>);
+                _unnamedEnumsAsInt =
+                    (node.value as Map)[strings.enumAsInt] as Includer;
               },
             )),
         HeterogeneousMapEntry(
@@ -946,6 +958,14 @@ class Config {
     ];
   }
 
+  List<HeterogeneousMapEntry> _enumIntProperties() => [
+        HeterogeneousMapEntry(
+          key: strings.enumAsInt,
+          defaultValue: (node) => Includer.excludeByDefault(),
+          valueConfigSpec: _includeExcludeObject(),
+        ),
+      ];
+
   HeterogeneousMapConfigSpec<List<String>, Includer> _includeExcludeObject() {
     return HeterogeneousMapConfigSpec(
       schemaDefName: 'includeExclude',

pkgs/ffigen/lib/src/header_parser/sub_parsers/enumdecl_parser.dart

@@ -55,6 +55,7 @@ final _logger = Logger('ffigen.header_parser.enumdecl_parser');
       originalName: enumName,
       name: config.enumClassDecl.renameUsingConfig(enumName),
       nativeType: nativeType,
+      generateAsInt: config.enumsAsInt.shouldInclude(enumName),
       objCBuiltInFunctions: objCBuiltInFunctions,
     );
     cursor.visitChildren((clang_types.CXCursor child) {

pkgs/ffigen/lib/src/strings.dart

@@ -90,6 +90,9 @@ const exposeFunctionTypedefs = 'expose-typedefs';
 const leafFunctions = 'leaf';
 const varArgFunctions = 'variadic-arguments';
 
+// Nested under `enums`
+const enumAsInt = 'as-int';
+
 // Nested under varArg entries
 const postfix = 'postfix';
 const types = 'types';

pkgs/ffigen/test/code_generator_tests/code_generator_test.dart

@@ -390,6 +390,64 @@ void main() {
       _matchLib(library, 'enumclass_duplicates');
     });
 
+    test('enum_class as integers', () {
+      final enum1 = EnumClass(
+        name: 'MyEnum',
+        enumConstants: [
+          const EnumConstant(
+            name: 'value1',
+            value: 0,
+          ),
+          const EnumConstant(
+            name: 'value2',
+            value: 1,
+          ),
+          const EnumConstant(
+            name: 'value3',
+            value: 2,
+          ),
+        ],
+      );
+      final enum2 = EnumClass(
+        name: 'MyIntegerEnum',
+        generateAsInt: true,
+        enumConstants: [
+          const EnumConstant(
+            name: 'int1',
+            value: 1,
+          ),
+          const EnumConstant(
+            name: 'int2',
+            value: 2,
+          ),
+          const EnumConstant(
+            name: 'int3',
+            value: 10,
+          ),
+        ],
+      );
+      final library = Library(
+        name: 'Bindings',
+        header: '$licenseHeader\n// ignore_for_file: unused_import\n',
+        silenceEnumWarning: true,
+        bindings: [
+          enum1,
+          enum2,
+          Func(
+            name: 'acceptsEnum',
+            returnType: enum1,
+            parameters: [Parameter(name: 'value', type: enum1)],
+          ),
+          Func(
+            name: 'acceptsInt',
+            returnType: enum2,
+            parameters: [Parameter(name: 'value', type: enum2)],
+          ),
+        ],
+      );
+      _matchLib(library, 'enumclass_integers');
+    });
+
     test('Internal conflict resolution', () {
       final library = Library(
         name: 'init_dylib',

pkgs/ffigen/test/code_generator_tests/expected_bindings/_expected_enumclass_integers_bindings.dart

@@ -0,0 +1,72 @@
+// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// ignore_for_file: unused_import
+
+// AUTO GENERATED FILE, DO NOT EDIT.
+//
+// Generated by `package:ffigen`.
+// ignore_for_file: type=lint
+import 'dart:ffi' as ffi;
+
+class Bindings {
+  /// Holds the symbol lookup function.
+  final ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
+      _lookup;
+
+  /// The symbols are looked up in [dynamicLibrary].
+  Bindings(ffi.DynamicLibrary dynamicLibrary) : _lookup = dynamicLibrary.lookup;
+
+  /// The symbols are looked up with [lookup].
+  Bindings.fromLookup(
+      ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
+          lookup)
+      : _lookup = lookup;
+
+  MyEnum acceptsEnum(
+    MyEnum value,
+  ) {
+    return MyEnum.fromValue(_acceptsEnum(
+      value.value,
+    ));
+  }
+
+  late final _acceptsEnumPtr =
+      _lookup<ffi.NativeFunction<ffi.Int Function(ffi.Int)>>('acceptsEnum');
+  late final _acceptsEnum = _acceptsEnumPtr.asFunction<int Function(int)>();
+
+  int acceptsInt(
+    int value,
+  ) {
+    return _acceptsInt(
+      value,
+    );
+  }
+
+  late final _acceptsIntPtr =
+      _lookup<ffi.NativeFunction<ffi.Int Function(ffi.Int)>>('acceptsInt');
+  late final _acceptsInt = _acceptsIntPtr.asFunction<int Function(int)>();
+}
+
+enum MyEnum {
+  value1(0),
+  value2(1),
+  value3(2);
+
+  final int value;
+  const MyEnum(this.value);
+
+  static MyEnum fromValue(int value) => switch (value) {
+        0 => value1,
+        1 => value2,
+        2 => value3,
+        _ => throw ArgumentError("Unknown value for MyEnum: $value"),
+      };
+}
+
+abstract class MyIntegerEnum {
+  static const int1 = 1;
+  static const int2 = 2;
+  static const int3 = 10;
+}