commit | 0c27646382120244200ab198f068907812bd33af | [log] [tgz] |
---|---|---|
author | Brian Slesinsky <skybrian@google.com> | Wed Jun 10 14:53:31 2015 -0700 |
committer | Brian Slesinsky <skybrian@google.com> | Wed Jun 10 15:42:53 2015 -0700 |
tree | e88ba9162a610014e213a17d7b09de92f002fee1 | |
parent | bf7f818b687c0bba7668ef32bfdeb598911c6c61 [diff] |
Add an option to extend Map in GeneratedMessage subclasses When enabled, the GeneratedMessage acts as a map with a fixed number of (key, value) pairs, one for each field. The key is the field name (string), using same name as the Dart getter, not the original field name in the .proto file. The value of each pair starts out with the field's default value. Extensions and unknown fields aren't included in the map. Unlike regular maps, pairs can't be added or removed. Values can be changed using map operations only for non-repeated fields, where the new value has a matching type. The following operations don't behave like a regular map: - clear() sets fields back to their default values, rather than removing all pairs in the map. - operator == only returns true if the other map is also a GeneratedMessage with the same type. It does a deep equality check that compares all fields in the message, including extensions and unknown fields. As a result, comparisons using == aren't commutative between a GeneratedMessage and other kinds of maps. - hashCode is consistent with operator ==. A GeneratedMessage won't have the same hashCode as a regular map containing the same pairs. This option is experimental and may change without notice. But if you really want to try it out, see map_api.proto and dart_options.proto for how to turn it on. BUG=https://github.com/dart-lang/dart-protoc-plugin/issues/44
This application provides a plugin for protoc compiler which generates pure Dart library to deal with protobufs.
Please, do not forget that generated libraries depend on runtime support library which can be found here.
Note: currently the workflow is POSIX-oriented.
To build standalone protoc
plugin:
pub install
to install all dependeciesmake build-plugin
. That will create a file out/protoc-gen-dart
which is a pluginPATH
or passing directly with protoc
's --plugin
option.Please, remember that the plugin is pure Dart script and requires the presence of dart
executable in your PATH
.
When both the dart
executable and out/protoc-gen-dart
are in the PATH
the protocol buffer compiler can be invoked to generate like this:
$ protoc --dart_out=. test.proto
The protocol buffer compiler accepts options for each plugin. For the Dart plugin, these options are passed together with the --dart_out
option. The individial options are separated using comma, and the final output directive is separated from the options using colon. Pass options <option 1>
and <option 2>
like this:
--dart_out="<option 1>,<option 2>:."
The following message definition has the field name has_field
.
message MyMessage { optional string has_field = 1; }
This poses the problem, that the Dart class will have a getter and a setter called hasField
. This conflicts with the method hasField
which is already defined on the superclass GeneratedMessage
.
To work around this problem the option field_name
can be used. Option field_name
takes two values separated by the vertical bar. The first value is the full name of the field and the second value is the name of the field in the generated Dart code. Passing the following option:
--dart_out="field_name=MyMessage.has_field|HasFld:."
Will generate the following message field accessors:
String get hasFld => getField(1); void set hasFld(String v) { setField(1, v); } bool hasHasFld() => hasField(1); void clearHasFld() => clearField(1);
The protocol buffer compiler produces one library for each .proto
file it compiles. In some cases this is not exactly what is needed, e.g one would like to create new libraries which exposes the objects in these libraries or create new librares combining object definitions from several .proto
libraries into one.
The best way to aproach this is to create the new libraries needed and re-export the relevant protocol buffer classes.
Say we have the file m1.proto
with the following content
message M1 { optional string a; }
and m2.proto
containing
message M2 { optional string b; }
Compiling these to Dart will produce two libraries in m1.pb.dart
and m2.pb.dart
. The following code shows a library M which combines these two protocol buffer libraries, exposes the classes M1
and M2
and adds som additional methods.
library M; import "m1.pb.dart"; import "m2.pb.dart"; export "m1.pb.dart" show M1; export "m2.pb.dart" show M2; M1 createM1() => new M1(); M2 createM2() => new M2();
You need to have protoc
installed.
apt-get install protobuf-compiler
brew install protobuf
Remember to run the tests. That is as easy as make run-tests
.
The default way of running the Dart protoc plugin is through the generated out/protoc-gen-dart
script. However when run this way the Dart code is assembled into one large Dart file using dart2dart. To run with the actual source in the repository create an executable script called protoc-gen-dart
with the following content:
#! /bin/bash dart bin/protoc_plugin.dart
When running protoc just ensure that this script is first when PATH is searched. If the script is in the current directory run protoc
like this:
$ PATH=.:$PATH protoc --dart_out=. test.proto
It is also possible to call the script something else than protoc-gen-dart
and then refer directly to it using the --plugin
option. If the script is called dart-plugin
run protoc
like this:
$ protoc --plugin=protoc-gen-dart=./plugin --dart_out=. test.proto