[ffigen] More config convenience utils (#2775)

Author: liamappelbe

pkgs/ffigen/CHANGELOG.md

@@ -3,6 +3,12 @@
 - Add `xcodeUri`, `iosSdkUri`, and `macSdkUri`, to mirror `xcodePath`,
   `iosSdkPath`, and `macSdkPath`.
 - Export some missing elements from the config API.
+- Provide more convenience utils for building FFIgen configs:
+  `Declarations.excludeAll`, `Declarations.includeAll`,
+  `Declarations.includeSet`, `Declarations.includeAllMembers`,
+  `Declarations.includeMemberSet`, `Declarations.useOriginalName`,
+  `Declarations.renameWithMap`, `Declarations.useMemberOriginalName`, and
+  `Declarations.renameMemberWithMap`.
 
 ## 20.0.0
 

pkgs/ffigen/lib/ffigen.dart

@@ -23,6 +23,7 @@ export 'src/config_provider.dart'
         CommentType,
         CompoundDependencies,
         Declaration,
+        Declarations,
         DynamicLibraryBindings,
         EnumStyle,
         Enums,

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

@@ -158,40 +158,86 @@ final class Declarations {
   /// Checks if a name is allowed by a filter.
   final bool Function(Declaration declaration) include;
 
+  /// A function to pass to [include] that excludes all declarations.
+  static bool excludeAll(Declaration declaration) => false;
+
+  /// A function to pass to [include] that includes all declarations.
+  static bool includeAll(Declaration declaration) => true;
+
+  /// Returns a function to pass to [include] that includes all declarations
+  /// whose `originalName`s are in [names].
+  static bool Function(Declaration) includeSet(Set<String> names) =>
+      (Declaration decl) => names.contains(decl.originalName);
+
   /// Whether a member of a declaration should be included.
   ///
   /// Only used for [Categories], [Interfaces], and [Protocols] methods and
   /// properties.
   final bool Function(Declaration declaration, String member) includeMember;
 
-  static bool _includeAllMembers(Declaration declaration, String member) =>
-      true;
+  /// A function to pass to [includeMember] that includes all members of all
+  /// declarations.
+  static bool includeAllMembers(Declaration declaration, String member) => true;
+
+  /// A function to pass to [includeMember] that includes specific members.
+  ///
+  /// The map key is the declaration's `originalName`, and the value is the set
+  /// of member names to include. If the declaration is not in the map, all its
+  /// members are included.
+  static bool Function(Declaration, String) includeMemberSet(
+    Map<String, Set<String>> members,
+  ) =>
+      (Declaration decl, String member) =>
+          members[decl.originalName]?.contains(member) ?? true;
 
   /// Checks if the symbol address should be included for this name.
   final bool Function(Declaration declaration) includeSymbolAddress;
 
   /// Applies renaming and returns the result.
   final String Function(Declaration declaration) rename;
 
-  static String _useOriginalName(Declaration declaration) =>
+  /// A function to pass to [rename] that doesn't rename the declaration.
+  static String useOriginalName(Declaration declaration) =>
       declaration.originalName;
 
+  /// A function to pass to [rename] that applies a rename map.
+  ///
+  /// The key of the map is the declaration's `originalName`, and the value is
+  /// the new name to use. If the declaration is not in the map, it is not
+  /// renamed.
+  static String Function(Declaration) renameWithMap(
+    Map<String, String> renames,
+  ) =>
+      (Declaration declaration) =>
+          renames[declaration.originalName] ?? declaration.originalName;
+
   /// Applies member renaming and returns the result. Used for struct/union
   /// fields, enum elements, function params, and ObjC
   /// interface/protocol/category methods/properties.
   final String Function(Declaration declaration, String member) renameMember;
 
-  static String _useMemberOriginalName(
-    Declaration declaration,
-    String member,
-  ) => member;
+  /// A function to pass to [renameMember] that doesn't rename the member.
+  static String useMemberOriginalName(Declaration declaration, String member) =>
+      member;
+
+  /// A function to pass to [renameMember] that applies a rename map.
+  ///
+  /// The key of the map is the declaration's `originalName`, and the value is
+  /// a map from member name to renamed member name. If the declaration is not
+  /// in the map, or the member isn't in the declaration's map, the member is
+  /// not renamed.
+  static String Function(Declaration, String) renameMemberWithMap(
+    Map<String, Map<String, String>> renames,
+  ) =>
+      (Declaration declaration, String member) =>
+          renames[declaration.originalName]?[member] ?? member;
 
   const Declarations({
-    this.include = _excludeAll,
-    this.includeMember = _includeAllMembers,
-    this.includeSymbolAddress = _excludeAll,
-    this.rename = _useOriginalName,
-    this.renameMember = _useMemberOriginalName,
+    this.include = excludeAll,
+    this.includeMember = includeAllMembers,
+    this.includeSymbolAddress = excludeAll,
+    this.rename = useOriginalName,
+    this.renameMember = useMemberOriginalName,
   });
 }
 
@@ -221,12 +267,12 @@ final class Enums extends Declarations {
     this.silenceWarning = false,
   });
 
-  static const excludeAll = Enums(include: _excludeAll);
+  static const excludeAll = Enums(include: Declarations.excludeAll);
 
-  static const includeAll = Enums(include: _includeAll);
+  static const includeAll = Enums(include: Declarations.includeAll);
 
   static Enums includeSet(Set<String> names) =>
-      Enums(include: (Declaration decl) => names.contains(decl.originalName));
+      Enums(include: Declarations.includeSet(names));
 }
 
 /// Configuration for how to generate enums.
@@ -265,25 +311,24 @@ final class Functions extends Declarations {
     this.varArgs = const <String, List<VarArgFunction>>{},
   });
 
-  static const excludeAll = Functions(include: _excludeAll);
+  static const excludeAll = Functions(include: Declarations.excludeAll);
 
-  static const includeAll = Functions(include: _includeAll);
+  static const includeAll = Functions(include: Declarations.includeAll);
 
-  static Functions includeSet(Set<String> names) => Functions(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static Functions includeSet(Set<String> names) =>
+      Functions(include: Declarations.includeSet(names));
 }
 
 /// Configuration for globals.
 final class Globals extends Declarations {
   const Globals({super.rename, super.include, super.includeSymbolAddress});
 
-  static const excludeAll = Globals(include: _excludeAll);
+  static const excludeAll = Globals(include: Declarations.excludeAll);
 
-  static const includeAll = Globals(include: _includeAll);
+  static const includeAll = Globals(include: Declarations.includeAll);
 
   static Globals includeSet(Set<String> names) =>
-      Globals(include: (Declaration decl) => names.contains(decl.originalName));
+      Globals(include: Declarations.includeSet(names));
 }
 
 /// Configuration for integer types.
@@ -309,12 +354,12 @@ final class Integers {
 final class Macros extends Declarations {
   const Macros({super.rename, super.include});
 
-  static const excludeAll = Macros(include: _excludeAll);
+  static const excludeAll = Macros(include: Declarations.excludeAll);
 
-  static const includeAll = Macros(include: _includeAll);
+  static const includeAll = Macros(include: Declarations.includeAll);
 
   static Macros includeSet(Set<String> names) =>
-      Macros(include: (Declaration decl) => names.contains(decl.originalName));
+      Macros(include: Declarations.includeSet(names));
 }
 
 /// Configuration for struct declarations.
@@ -348,12 +393,12 @@ final class Structs extends Declarations {
     this.packingOverride = _packingOverrideDefault,
   });
 
-  static const excludeAll = Structs(include: _excludeAll);
+  static const excludeAll = Structs(include: Declarations.excludeAll);
 
-  static const includeAll = Structs(include: _includeAll);
+  static const includeAll = Structs(include: Declarations.includeAll);
 
   static Structs includeSet(Set<String> names) =>
-      Structs(include: (Declaration decl) => names.contains(decl.originalName));
+      Structs(include: Declarations.includeSet(names));
 }
 
 /// Configuration for typedefs.
@@ -383,13 +428,12 @@ final class Typedefs extends Declarations {
     this.useSupportedTypedefs = true,
   });
 
-  static const Typedefs excludeAll = Typedefs(include: _excludeAll);
+  static const Typedefs excludeAll = Typedefs(include: Declarations.excludeAll);
 
-  static const Typedefs includeAll = Typedefs(include: _includeAll);
+  static const Typedefs includeAll = Typedefs(include: Declarations.includeAll);
 
-  static Typedefs includeSet(Set<String> names) => Typedefs(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static Typedefs includeSet(Set<String> names) =>
+      Typedefs(include: Declarations.includeSet(names));
 }
 
 /// Configuration for union declarations.
@@ -416,25 +460,24 @@ final class Unions extends Declarations {
     this.imported = const <ImportedType>[],
   });
 
-  static const excludeAll = Unions(include: _excludeAll);
+  static const excludeAll = Unions(include: Declarations.excludeAll);
 
-  static const includeAll = Unions(include: _includeAll);
+  static const includeAll = Unions(include: Declarations.includeAll);
 
   static Unions includeSet(Set<String> names) =>
-      Unions(include: (Declaration decl) => names.contains(decl.originalName));
+      Unions(include: Declarations.includeSet(names));
 }
 
 /// Configuration for unnamed enum constants.
 final class UnnamedEnums extends Declarations {
   const UnnamedEnums({super.include, super.rename, super.renameMember});
 
-  static const excludeAll = UnnamedEnums(include: _excludeAll);
+  static const excludeAll = UnnamedEnums(include: Declarations.excludeAll);
 
-  static const includeAll = UnnamedEnums(include: _includeAll);
+  static const includeAll = UnnamedEnums(include: Declarations.includeAll);
 
-  static UnnamedEnums includeSet(Set<String> names) => UnnamedEnums(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static UnnamedEnums includeSet(Set<String> names) =>
+      UnnamedEnums(include: Declarations.includeSet(names));
 }
 
 /// Configuration for Objective-C.
@@ -487,13 +530,12 @@ final class Categories extends Declarations {
     this.includeTransitive = true,
   });
 
-  static const excludeAll = Categories(include: _excludeAll);
+  static const excludeAll = Categories(include: Declarations.excludeAll);
 
-  static const includeAll = Categories(include: _includeAll);
+  static const includeAll = Categories(include: Declarations.includeAll);
 
-  static Categories includeSet(Set<String> names) => Categories(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static Categories includeSet(Set<String> names) =>
+      Categories(include: Declarations.includeSet(names));
 }
 
 /// Configuration for Objective-C interfaces.
@@ -517,13 +559,12 @@ final class Interfaces extends Declarations {
     this.module = noModule,
   });
 
-  static const excludeAll = Interfaces(include: _excludeAll);
+  static const excludeAll = Interfaces(include: Declarations.excludeAll);
 
-  static const includeAll = Interfaces(include: _includeAll);
+  static const includeAll = Interfaces(include: Declarations.includeAll);
 
-  static Interfaces includeSet(Set<String> names) => Interfaces(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static Interfaces includeSet(Set<String> names) =>
+      Interfaces(include: Declarations.includeSet(names));
 
   static String? noModule(Declaration declaration) => null;
 }
@@ -549,13 +590,12 @@ final class Protocols extends Declarations {
     this.module = noModule,
   });
 
-  static const excludeAll = Protocols(include: _excludeAll);
+  static const excludeAll = Protocols(include: Declarations.excludeAll);
 
-  static const includeAll = Protocols(include: _includeAll);
+  static const includeAll = Protocols(include: Declarations.includeAll);
 
-  static Protocols includeSet(Set<String> names) => Protocols(
-    include: (Declaration decl) => names.contains(decl.originalName),
-  );
+  static Protocols includeSet(Set<String> names) =>
+      Protocols(include: Declarations.includeSet(names));
 
   static String? noModule(Declaration declaration) => null;
 }
@@ -758,7 +798,3 @@ extension type Config(FfiGenerator ffiGen) implements FfiGenerator {
 
   Language get language => objectiveC != null ? Language.objc : Language.c;
 }
-
-bool _excludeAll(Declaration declaration) => false;
-
-bool _includeAll(Declaration d) => true;

pkgs/ffigen/test/unit_tests/config_util_test.dart

@@ -0,0 +1,48 @@
+// Copyright (c) 2025, 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.
+
+import 'package:ffigen/ffigen.dart';
+import 'package:test/test.dart';
+
+Declaration decl(String name) => Declaration(usr: '', originalName: name);
+
+void main() {
+  group('Declarations utils', () {
+    test('includeSet', () {
+      final includer = Declarations.includeSet({'foo', 'bar'});
+      expect(includer(decl('foo')), isTrue);
+      expect(includer(decl('bar')), isTrue);
+      expect(includer(decl('baz')), isFalse);
+    });
+
+    test('includeMemberSet', () {
+      final includer = Declarations.includeMemberSet({
+        'foo': {'bar'},
+      });
+      expect(includer(decl('foo'), 'bar'), isTrue);
+      expect(includer(decl('foo'), 'baz'), isFalse);
+      expect(includer(decl('goo'), 'bar'), isTrue);
+      expect(includer(decl('goo'), 'baz'), isTrue);
+    });
+
+    test('renameWithMap', () {
+      final renamer = Declarations.renameWithMap({'foo': 'bar'});
+      expect(renamer(decl('foo')), 'bar');
+      expect(renamer(decl('bar')), 'bar');
+      expect(renamer(decl('baz')), 'baz');
+    });
+
+    test('renameMemberWithMap', () {
+      final renamer = Declarations.renameMemberWithMap({
+        'foo': {'bar': 'baz'},
+      });
+      expect(renamer(decl('foo'), 'bar'), 'baz');
+      expect(renamer(decl('foo'), 'baz'), 'baz');
+      expect(renamer(decl('foo'), 'bop'), 'bop');
+      expect(renamer(decl('goo'), 'bar'), 'bar');
+      expect(renamer(decl('goo'), 'baz'), 'baz');
+      expect(renamer(decl('goo'), 'bop'), 'bop');
+    });
+  });
+}