protojs

protojs copied to clipboard

Protojs is a BSD-licensed protocol buffer library written in JavaScript. http://github.com/sirikata/protojs

==== Features:

• Fast compiler using ANTLR
• Packed field + 2.3.0 autodetection
• Full Unicode support (decoding surrogate pairs above 0xffff)
• Getters+setters for error checking (and fallback if not supported)
• Enums and nested messages
• 32-bit and 64-bit floating points
• Serializing/deserializing to base64 or array of int
• PBJ datatypes (uuid, vector, quaternion, normal) defined in pbj.js

==== Bugs or missing features:

• Does not enforce "required", acts the same as "optional"
• Default values are not used
• Setting a field in a sub-message will not cause the sub-message to be serialized, as the python parser worked before 2.3.0
• It is not possible to serialize to binary string in a cross-browser way, because Javascript uses unicode strings. However, the Stream class can be extended for specific applications
• No support for extensions or services
• Not compatible with older versions of protobufs

==== Building protojs:

The build process is tested on Linux, and should work also on mac or cygwin: First, run "./bootstrap.sh" This script downloads antlr-3.2 from antlr.org.

Now, run "make" Builds the "pbj" compiler and a test file from protocol/ into output/

If you want to use the makefile you can put your own .proto files into protocol/. You can also run the pbj file with "pbj input.proto output.proto"

If you want to build a directory full of protocol files, run it with "make INPUTDIR=/path/to/protocol". You can optionally specify OUTPUTDIR if you don't want them to go to output.

==== Using the javascript library:

The javascript library is intended to be as similar as possible to python protocol buffers.

If you have declared the package Example.Test, and made a message called HelloWorld, you can create a message with:

var mymsg = new Example.Test.HelloWorld; mymsg.field1 = "value1"; mymsg.inner_msg.field2 = 5; var newmsg = mymsg.repeated_msg.push(); newmsg.field2 = 6; newmsg.field3.push(1) newmsg.field3.push(2) newmsg.field3.push(3)

To serialize the message, you must create an instance of a class that extends PROTO.Stream.

var serialized = new PROTO.Base64Stream; mymsg.SerializeToStream(serialized); document.write(serialized.getString());

Note that the function names are ParseFromStream and SerializeToStream, not ParseFromString or ParseFromArray as in python or C++. This is because javascript strings are encoded in UTF-16 and cannot handle binary data.

==== Reporting bugs:

Send mail to Patrick Horn [email protected], or find me at irc.freenode.net #sirikata

If you have a cool feature to add, feel free to fork the project.