[pigeon] Adds SwiftFunction annotation

packages/pigeon/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 7.1.0
+
+* Adds `@SwiftFunction` annotation for specifying custom swift function signature.
+
 ## 7.0.4
 
 * [c++] Fixes minor output formatting issues.

packages/pigeon/lib/ast.dart

@@ -32,6 +32,7 @@ class Method extends Node {
     this.isAsynchronous = false,
     this.offset,
     this.objcSelector = '',
+    this.swiftFunction = '',
     this.taskQueueType = TaskQueueType.serial,
     this.documentationComments = const <String>[],
   });
@@ -54,6 +55,9 @@ class Method extends Node {
   /// An override for the generated objc selector (ex. "divideNumber:by:").
   String objcSelector;
 
+  /// An override for the generated swift function signature (ex. "divideNumber(_:by:)").
+  String swiftFunction;
+
   /// Specifies how handlers are dispatched with respect to threading.
   TaskQueueType taskQueueType;
 
@@ -68,7 +72,9 @@ class Method extends Node {
   String toString() {
     final String objcSelectorStr =
         objcSelector.isEmpty ? '' : ' objcSelector:$objcSelector';
-    return '(Method name:$name returnType:$returnType arguments:$arguments isAsynchronous:$isAsynchronous$objcSelectorStr documentationComments:$documentationComments)';
+    final String swiftFunctionStr =
+        swiftFunction.isEmpty ? '' : ' swiftFunction:$swiftFunction';
+    return '(Method name:$name returnType:$returnType arguments:$arguments isAsynchronous:$isAsynchronous$objcSelectorStr$swiftFunctionStr documentationComments:$documentationComments)';
   }
 }
 

packages/pigeon/lib/generator_tools.dart

@@ -11,7 +11,7 @@ import 'ast.dart';
 /// The current version of pigeon.
 ///
 /// This must match the version in pubspec.yaml.
-const String pigeonVersion = '7.0.4';
+const String pigeonVersion = '7.1.0';
 
 /// Read all the content from [stdin] to a String.
 String readStdin() {

packages/pigeon/lib/pigeon_lib.dart

@@ -100,6 +100,20 @@ class ObjCSelector {
   final String value;
 }
 
+/// Metadata to annotate methods to control the signature used for Swift output.
+///
+/// The number of components in the provided signature must match the number of
+/// arguments in the annotated method.
+/// For example:
+///   @SwiftFunction('setValue(_:for:)') double divide(int value, String key);
+class SwiftFunction {
+  /// Constructor.
+  const SwiftFunction(this.value);
+
+  /// The string representation of the function signature.
+  final String value;
+}
+
 /// Type of TaskQueue which determines how handlers are dispatched for
 /// HostApi's.
 enum TaskQueueType {
@@ -724,6 +738,17 @@ List<Error> _validateAst(Root root, String source) {
           ));
         }
       }
+      if (method.swiftFunction.isNotEmpty) {
+        final RegExp signatureRegex =
+            RegExp('\\w+ *\\((\\w+:){${method.arguments.length}}\\)');
+        if (!signatureRegex.hasMatch(method.swiftFunction)) {
+          result.add(Error(
+            message:
+                'Invalid function signature, expected ${method.arguments.length} arguments.',
+            lineNumber: _calculateLineNumberNullable(source, method.offset),
+          ));
+        }
+      }
       if (method.taskQueueType != TaskQueueType.serial &&
           api.location != ApiLocation.host) {
         result.add(Error(
@@ -1026,6 +1051,13 @@ class _RootBuilder extends dart_ast_visitor.RecursiveAstVisitor<Object?> {
             .asNullable<dart_ast.SimpleStringLiteral>()
             ?.value ??
         '';
+    final String swiftFunction = _findMetadata(node.metadata, 'SwiftFunction')
+            ?.arguments
+            ?.arguments
+            .first
+            .asNullable<dart_ast.SimpleStringLiteral>()
+            ?.value ??
+        '';
     final dart_ast.ArgumentList? taskQueueArguments =
         _findMetadata(node.metadata, 'TaskQueue')?.arguments;
     final String? taskQueueTypeName = taskQueueArguments == null
@@ -1054,6 +1086,7 @@ class _RootBuilder extends dart_ast_visitor.RecursiveAstVisitor<Object?> {
           arguments: arguments,
           isAsynchronous: isAsynchronous,
           objcSelector: objcSelector,
+          swiftFunction: swiftFunction,
           offset: node.offset,
           taskQueueType: taskQueueType,
           documentationComments:

packages/pigeon/lib/swift_generator.dart

@@ -294,6 +294,9 @@ import FlutterMacOS
         });
       }
       for (final Method func in api.methods) {
+        final _SwiftFunctionComponents components =
+            _SwiftFunctionComponents.fromMethod(func);
+
         final String channelName = makeChannelName(api, func);
         final String returnType = func.returnType.isVoid
             ? ''
@@ -309,8 +312,11 @@ import FlutterMacOS
         } else {
           final Iterable<String> argTypes = func.arguments
               .map((NamedType e) => _nullsafeSwiftTypeForDartType(e.type));
-          final Iterable<String> argLabels =
-              indexMap(func.arguments, _getArgumentName);
+          final Iterable<String> argLabels = indexMap(components.arguments,
+              (int index, _SwiftFunctionArgument argument) {
+            return argument.label ??
+                _getArgumentName(index, argument.namedType);
+          });
           final Iterable<String> argNames =
               indexMap(func.arguments, _getSafeArgumentName);
           sendArgument = '[${argNames.join(', ')}] as [Any?]';
@@ -322,10 +328,10 @@ import FlutterMacOS
                   '$label $name: $type').join(', ');
           if (func.returnType.isVoid) {
             indent.write(
-                'func ${func.name}($argsSignature, completion: @escaping () -> Void) ');
+                'func ${components.name}($argsSignature, completion: @escaping () -> Void) ');
           } else {
             indent.write(
-                'func ${func.name}($argsSignature, completion: @escaping ($returnType) -> Void) ');
+                'func ${components.name}($argsSignature, completion: @escaping ($returnType) -> Void) ');
           }
         }
         indent.addScoped('{', '}', () {
@@ -369,7 +375,6 @@ import FlutterMacOS
     if (isCustomCodec) {
       _writeCodec(indent, api, root);
     }
-
     const List<String> generatedComments = <String>[
       ' Generated protocol from Pigeon that represents a handler of messages from Flutter.'
     ];
@@ -379,17 +384,15 @@ import FlutterMacOS
     indent.write('protocol $apiName ');
     indent.addScoped('{', '}', () {
       for (final Method method in api.methods) {
-        final List<String> argSignature = <String>[];
-        if (method.arguments.isNotEmpty) {
-          final Iterable<String> argTypes = method.arguments
-              .map((NamedType e) => _nullsafeSwiftTypeForDartType(e.type));
-          final Iterable<String> argNames =
-              method.arguments.map((NamedType e) => e.name);
-          argSignature.addAll(
-              map2(argTypes, argNames, (String argType, String argName) {
-            return '$argName: $argType';
-          }));
-        }
+        final _SwiftFunctionComponents components =
+            _SwiftFunctionComponents.fromMethod(method);
+        final List<String> argSignature =
+            components.arguments.map((_SwiftFunctionArgument argument) {
+          final String? label = argument.label;
+          final String name = argument.name;
+          final String type = _nullsafeSwiftTypeForDartType(argument.type);
+          return '${label == null ? '' : '$label '}$name: $type';
+        }).toList();
 
         final String returnType = method.returnType.isVoid
             ? ''
@@ -399,12 +402,12 @@ import FlutterMacOS
 
         if (method.isAsynchronous) {
           argSignature.add('completion: @escaping ($returnType) -> Void');
-          indent.writeln('func ${method.name}(${argSignature.join(', ')})');
+          indent.writeln('func ${components.name}(${argSignature.join(', ')})');
         } else if (method.returnType.isVoid) {
-          indent.writeln('func ${method.name}(${argSignature.join(', ')})');
+          indent.writeln('func ${components.name}(${argSignature.join(', ')})');
         } else {
           indent.writeln(
-              'func ${method.name}(${argSignature.join(', ')}) -> $returnType');
+              'func ${components.name}(${argSignature.join(', ')}) -> $returnType');
         }
       }
     });
@@ -428,6 +431,9 @@ import FlutterMacOS
           'static func setUp(binaryMessenger: FlutterBinaryMessenger, api: $apiName?) ');
       indent.addScoped('{', '}', () {
         for (final Method method in api.methods) {
+          final _SwiftFunctionComponents components =
+              _SwiftFunctionComponents.fromMethod(method);
+
           final String channelName = makeChannelName(api, method);
           final String varChannelName = '${method.name}Channel';
           addDocumentationComments(
@@ -442,18 +448,25 @@ import FlutterMacOS
                 method.arguments.isNotEmpty ? 'message' : '_';
             indent.addScoped('{ $messageVarName, reply in', '}', () {
               final List<String> methodArgument = <String>[];
-              if (method.arguments.isNotEmpty) {
+              if (components.arguments.isNotEmpty) {
                 indent.writeln('let args = message as! [Any?]');
-                enumerate(method.arguments, (int index, NamedType arg) {
-                  final String argName = _getSafeArgumentName(index, arg);
+                enumerate(components.arguments,
+                    (int index, _SwiftFunctionArgument arg) {
+                  final String argName =
+                      _getSafeArgumentName(index, arg.namedType);
                   final String argIndex = 'args[$index]';
                   indent.writeln(
                       'let $argName = ${_castForceUnwrap(argIndex, arg.type, root)}');
-                  methodArgument.add('${arg.name}: $argName');
+
+                  if (arg.label == '_') {
+                    methodArgument.add(argName);
+                  } else {
+                    methodArgument.add('${arg.label ?? arg.name}: $argName');
+                  }
                 });
               }
               final String call =
-                  'api.${method.name}(${methodArgument.join(', ')})';
+                  'api.${components.name}(${methodArgument.join(', ')})';
               if (method.isAsynchronous) {
                 indent.write('$call ');
                 if (method.returnType.isVoid) {
@@ -695,3 +708,87 @@ String _nullsafeSwiftTypeForDartType(TypeDeclaration type) {
   final String nullSafe = type.isNullable ? '?' : '';
   return '${_swiftTypeForDartType(type)}$nullSafe';
 }
+
+/// A class that represents a Swift function argument.
+///
+/// The [name] is the name of the argument.
+/// The [type] is the type of the argument.
+/// The [namedType] is the [NamedType] that this argument is generated from.
+/// The [label] is the label of the argument.
+class _SwiftFunctionArgument {
+  _SwiftFunctionArgument({
+    required this.name,
+    required this.type,
+    required this.namedType,
+    this.label,
+  });
+
+  final String name;
+  final TypeDeclaration type;
+  final NamedType namedType;
+  final String? label;
+}
+
+/// A class that represents a Swift function signature.
+///
+/// The [name] is the name of the function.
+/// The [arguments] are the arguments of the function.
+/// The [returnType] is the return type of the function.
+/// The [method] is the method that this function signature is generated from.
+class _SwiftFunctionComponents {
+  _SwiftFunctionComponents._({
+    required this.name,
+    required this.arguments,
+    required this.returnType,
+    required this.method,
+  });
+
+  /// Constructor that generates a [_SwiftFunctionComponents] from a [Method].
+  factory _SwiftFunctionComponents.fromMethod(Method method) {
+    if (method.swiftFunction.isEmpty) {
+      return _SwiftFunctionComponents._(
+        name: method.name,
+        returnType: method.returnType,
+        arguments: method.arguments
+            .map((NamedType field) => _SwiftFunctionArgument(
+                  name: field.name,
+                  type: field.type,
+                  namedType: field,
+                ))
+            .toList(),
+        method: method,
+      );
+    }
+
+    final String argsExtractor =
+        repeat(r'(\w+):', method.arguments.length).join();
+    final RegExp signatureRegex = RegExp(r'(\w+) *\(' + argsExtractor + r'\)');
+    final RegExpMatch match = signatureRegex.firstMatch(method.swiftFunction)!;
+
+    final Iterable<String> labels = match
+        .groups(List<int>.generate(
+            method.arguments.length, (int index) => index + 2))
+        .whereType();
+
+    return _SwiftFunctionComponents._(
+      name: match.group(1)!,
+      returnType: method.returnType,
+      arguments: map2(
+        method.arguments,
+        labels,
+        (NamedType field, String label) => _SwiftFunctionArgument(
+          name: field.name,
+          label: label == field.name ? null : label,
+          type: field.type,
+          namedType: field,
+        ),
+      ).toList(),
+      method: method,
+    );
+  }
+
+  final String name;
+  final List<_SwiftFunctionArgument> arguments;
+  final TypeDeclaration returnType;
+  final Method method;
+}