Protocol Buffers compiler and run-time library for Haxe
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
haxelib-release
test/com/dongxiguo/protobuf/test
.gitattributes
.gitignore
Makefile
README.md
run.hxml
run.hxproj
test.js.hxml
test.js.hxproj
test.n.hxml
test.n.hxproj
test.swf.hxml
test.swf.hxproj
test_cpp.hxml
test_cpp.hxproj
test_cs.hxml
test_cs.hxproj

README.md

Warning: This project is obsolete, and only tested on Haxe 3.0.x branches. Looking for serialization solution in Haxe? Try json-stream!


protoc-gen-haxe

protoc-gen-haxe is a Protocol Buffers implementation in Haxe.

Motive

I am also the author of protoc-gen-as3, which is the best Protocol Buffers implementation in ActionScript 3. I rewritten these code because I want to try the Haxe way to generate code. This table lists main difference between protoc-gen-as (or any other Protocol Buffers implementation) and protoc-gen-haxe:

protoc-gen-as3 protoc-gen-haxe
Cross-platform No. It only runs in Adobe Flash Player or Adobe AIR. Yes. protoc-gen-haxe can run in Flash Players, browsers, servers, and even in Haxe compiler macros.
Run Time Type Information Little, via native Flash API. Yes. By parsing DescriptorProtoSet at runtime, users can access full information from .proto files.
Mutable messages Yes Yes
Readonly messages No Yes
Will unused code be eliminated? No Yes. protoc-gen-haxe separate different features into different classes, unused codes can be easy eliminated by the Haxe compiler.
Can users generate their custom code? No. Users have to create another Protocol Buffers plugin. Yes. Users can use protoc-gen-haxe API in Haxe macros.
Self-hosting No. protoc-gen-as3's compiler is written in Java. Yes. Both compiler and runtime library of protoc-gen-haxe are written in Haxe. Even 20% lines of source code are generated by protoc-gen-haxe itself!
Is it a protoc plugin? Yes. protoc-gen-as3 compiler must be launched by Google's protoc. No. protoc-gen-haxe can directly import binary format DescriptorProtoSet of .proto files.

Installation

  1. Download protoc 2.5.
  2. Download and install Haxe 3.
  3. haxelib install protoc-gen-haxe

Usage

Step 1: Create sample.proto

// sample.proto

package samplePackage;

message SampleMessage {
  optional string sample_field = 1;
}

Step 2: Create SampleMain.hx

// SampleMain.hx

import sys.io.File;
import sys.FileSystem;
import com.dongxiguo.protobuf.binaryFormat.LimitableFileInput;
import samplePackage.SampleMessage_Builder;
using samplePackage.SampleMessage_Merger;
using samplePackage.SampleMessage_Writer;

class SampleMain {

  static function save():Void
  {
    var builder = new SampleMessage_Builder();
    builder.sampleField = "Hello, World!";
    var output = File.write("sample.save");
    builder.writeTo(output);
    output.close();
  }

  static function load():Void
  {
    var builder = new SampleMessage_Builder();
    var input = File.read("sample.save");
    var pbInput = new LimitableFileInput(input, FileSystem.stat("sample.save").size);
    builder.mergeFrom(pbInput);
    trace('builder.sample = ${builder.sampleField}');
    input.close();
  }

  public static function main() {
    save();
    load();
  }

}

Step 3: Convert sample.proto to binary format DescriptorProtoSet.

protoc sample.proto --descriptor_set_out=sample.proto.bin

Step 4: Run it!

haxe -lib protoc-gen-haxe --macro "com.dongxiguo.protobuf.commandLine.Importer.importDescroptorFileSet('sample.proto.bin')" -x SampleMain.hx

Now you see your program created sample.save in Protocol Buffers format, and then loaded this file.

You may want to see which classes are genrated by protoc-gen-haxe. Just add --gen-hx-classes to your haxe command and look at the hxclasses/ folder it generated .

Features

  • All basic types
  • Nested messages
  • Enumerations
  • Packed and non-packed repeated fields
  • Extensions
  • Unknown fields
  • Run-time type information of services, enums, messages, options, custom options...
  • Macro-time type information of services, enums, messages, options, custom options...

Missing features

  • Text format
  • Group (A deprecated feature since Protocol Buffers 2)

I would like to see somebody's contribution for these missing features.

Requirement

  • Haxe 3.x
  • Protocol Buffers 2.x