pigeon 0.1.0-experimental.0

  • Readme
  • Changelog
  • Installing
  • 82

Pigeon #

Pigeon is a code generator tool to make communication between Flutter and the host platform type-safe and easier.

Supported Platforms #

Currently Pigeon only supports generating Objective-C code for usage on iOS and calling host functions from Flutter.

Runtime Requirements #

Pigeon generates all the code that is needed to communicate between Flutter and the host platform, there is no extra runtime requirement. A plugin author doesn't need to worry about conflicting versions of Pigeon.

Usage #

Steps #

  1. Add Pigeon as a dev_dependency.
  2. Make a ".dart" file outside of your "lib" directory for defining the communication interface.
  3. Run pigeon on your ".dart" file to generate the required Dart and Objective-C code.
  4. Add the generated code to your ios/Runner.xcworkspace XCode project for compilation.
  5. Implement the generated iOS protocol for handling the calls on iOS, set it up as the handler for the messages.
  6. Call the generated Dart methods.

Rules for defining your communication interface #

  1. The file should contain no methods or function definitions.
  2. Datatypes are defined as classes with fields of the supported datatypes (see the supported Datatypes section).
  3. Api's should be defined as an abstract class with either HostApi() or FlutterApi() as metadata. The former being for procedures that are defined on the host platform and the latter for procedures that are defined in Dart.
  4. Method declarations on the Api classes should have one argument and a return value whose types are defined in the file.

Example #

message.dart

import 'package:pigeon/pigeon_lib.dart';

class SearchRequest {
  String query;
}

class SearchReply {
  String result;
}

@HostApi()
abstract class Api {
  SearchReply search(SearchRequest request);
}

invocation

pub run pigeon \
  --input pigeons/message.dart \
  --dart_out lib/pigeon.dart \
  --objc_header_out ios/Runner/pigeon.h \
  --objc_source_out ios/Runner/pigeon.m

AppDelegate.m

#import "AppDelegate.h"
#import <Flutter/Flutter.h>
#import "pigeon.h"

@interface MyApi : NSObject <Api>
@end

@implementation MyApi
-(SearchReply*)search:(SearchRequest*)request {
  SearchReply *reply = [[SearchReply alloc] init];
  reply.result =
      [NSString stringWithFormat:@"Hi %@!", request.query];
  return reply;
}
@end

- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
  MyApi *api = [[MyApi alloc] init];
  ApiSetup(getFlutterEngine().binaryMessenger, api);
  return YES;
}

test.dart

import 'pigeon.dart';

void main() {
  testWidgets("test pigeon", (WidgetTester tester) async {
    SearchRequest request = SearchRequest()..query = "Aaron";
    Api api = Api();
    SearchReply reply = await api.search(request);
    expect(reply.result, equals("Hi Aaron!"));
  });
}

Supported Datatypes #

Pigeon uses the StandardMessageCodec so it supports any data-type platform channels supports [documentation]. Nested data-types are supported, too.

Note: Generics for List and Map aren't supported yet.

Feedback #

File an issue in flutter/flutter with the word 'pigeon' clearly in the title and cc @gaaclarke.

0.1.0-experimental.0 #

  • Initial release.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  pigeon: ^0.1.0-experimental.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:pigeon/ast.dart';
import 'package:pigeon/dart_generator.dart';
import 'package:pigeon/generator_tools.dart';
import 'package:pigeon/objc_generator.dart';
import 'package:pigeon/pigeon_lib.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
70
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
85
Overall:
Weighted score of the above. [more]
82
Learn more about scoring.

We analyzed this package on Jul 5, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package not compatible with SDK flutter

Because it is not compatible with any of the supported runtimes: flutter-native, flutter-web

Package not compatible with runtime flutter-native on android

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on ios

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on linux

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on macos

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on windows

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-web on web

Because of the import of dart:io via the import chain package:pigeon/dart_generator.dartpackage:pigeon/generator_tools.dartdart:io

Package not compatible with runtime native-aot

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime web

Because of the import of dart:io via the import chain package:pigeon/dart_generator.dartpackage:pigeon/generator_tools.dartdart:io

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and pigeon.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
args ^1.5.2 1.6.0
path ^1.6.4 1.7.0
Dev dependencies
test ^1.11.1