protobuf

module
v0.0.0-...-7cc19b7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 25, 2016 License: BSD-3-Clause

README

Go support for Protocol Buffers

Google's data interchange format. Copyright 2010 The Go Authors. https://github.com/golang/protobuf

This package and the code it generates requires at least Go 1.4.

This software implements Go bindings for protocol buffers. For information about protocol buffers themselves, see https://developers.google.com/protocol-buffers/

Installation

To use this software, you must:

This software has two parts: a 'protocol compiler plugin' that generates Go source files that, once compiled, can access and manage protocol buffers; and a library that implements run-time support for encoding (marshaling), decoding (unmarshaling), and accessing protocol buffers.

There is support for gRPC in Go using protocol buffers. See the note at the bottom of this file for details.

There are no insertion points in the plugin.

Using protocol buffers with Go

Once the software is installed, there are two steps to using it. First you must compile the protocol buffer definitions and then import them, with the support library, into your program.

To compile the protocol buffer definition, run protoc with the --go_out parameter set to the directory you want to output the Go code to.

protoc --go_out=. *.proto

The generated files will be suffixed .pb.go. See the Test code below for an example using such a file.

The package comment for the proto library contains text describing the interface provided in Go for protocol buffers. Here is an edited version.

==========

The proto package converts data structures to and from the wire format of protocol buffers. It works in concert with the Go source code generated for .proto files by the protocol compiler.

A summary of the properties of the protocol buffer interface for a protocol buffer variable v:

  • Names are turned from camel_case to CamelCase for export.
  • There are no methods on v to set fields; just treat them as structure fields.
  • There are getters that return a field's value if set, and return the field's default value if unset. The getters work even if the receiver is a nil message.
  • The zero value for a struct is its correct initialization state. All desired fields must be set before marshaling.
  • A Reset() method will restore a protobuf struct to its zero state.
  • Non-repeated fields are pointers to the values; nil means unset. That is, optional or required field int32 f becomes F *int32.
  • Repeated fields are slices.
  • Helper functions are available to aid the setting of fields. Helpers for getting values are superseded by the GetFoo methods and their use is deprecated. msg.Foo = proto.String("hello") // set field
  • Constants are defined to hold the default values of all fields that have them. They have the form Default_StructName_FieldName. Because the getter methods handle defaulted values, direct use of these constants should be rare.
  • Enums are given type names and maps from names to values. Enum values are prefixed with the enum's type name. Enum types have a String method, and a Enum method to assist in message construction.
  • Nested groups and enums have type names prefixed with the name of the surrounding message type.
  • Extensions are given descriptor names that start with E_, followed by an underscore-delimited list of the nested messages that contain it (if any) followed by the CamelCased name of the extension field itself. HasExtension, ClearExtension, GetExtension and SetExtension are functions for manipulating extensions.
  • Oneof field sets are given a single field in their message, with distinguished wrapper types for each possible field value.
  • Marshal and Unmarshal are functions to encode and decode the wire format.

When the .proto file specifies syntax="proto3", there are some differences:

  • Non-repeated fields of non-message type are values instead of pointers.
  • Getters are only generated for message and oneof fields.
  • Enum types do not get an Enum method.

Consider file test.proto, containing

	package example;
	
	enum FOO { X = 17; };
	
	message Test {
	  required string label = 1;
	  optional int32 type = 2 [default=77];
	  repeated int64 reps = 3;
	  optional group OptionalGroup = 4 {
	    required string RequiredField = 5;
	  }
	}

To create and play with a Test object from the example package,

	package main

	import (
		"log"

		"github.com/golang/protobuf/proto"
		"path/to/example"
	)

	func main() {
		test := &example.Test {
			Label: proto.String("hello"),
			Type:  proto.Int32(17),
			Reps:  []int64{1, 2, 3},
			Optionalgroup: &example.Test_OptionalGroup {
				RequiredField: proto.String("good bye"),
			},
		}
		data, err := proto.Marshal(test)
		if err != nil {
			log.Fatal("marshaling error: ", err)
		}
		newTest := &example.Test{}
		err = proto.Unmarshal(data, newTest)
		if err != nil {
			log.Fatal("unmarshaling error: ", err)
		}
		// Now test and newTest contain the same data.
		if test.GetLabel() != newTest.GetLabel() {
			log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel())
		}
		// etc.
	}

Parameters

To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon:

protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
  • import_prefix=xxx - a prefix that is added onto the beginning of all imports. Useful for things like generating protos in a subdirectory, or regenerating vendored protobufs in-place.
  • import_path=foo/bar - used as the package if no input files declare go_package. If it contains slashes, everything up to the rightmost slash is ignored.
  • plugins=plugin1+plugin2 - specifies the list of sub-plugins to load. The only plugin in this repo is grpc.
  • Mfoo/bar.proto=quux/shme - declares that foo/bar.proto is associated with Go package quux/shme. This is subject to the import_prefix parameter.

gRPC Support

If a proto file specifies RPC services, protoc-gen-go can be instructed to generate code compatible with gRPC (http://www.grpc.io/). To do this, pass the plugins parameter to protoc-gen-go; the usual way is to insert it into the --go_out argument to protoc:

protoc --go_out=plugins=grpc:. *.proto

Plugins

The protoc-gen-go/generator package exposes a plugin interface, which is used by the gRPC code generation. This interface is not supported and is subject to incompatible changes without notice.

Directories

Path Synopsis
Package jsonpb provides marshaling and unmarshaling between protocol buffers and JSON.
Package jsonpb provides marshaling and unmarshaling between protocol buffers and JSON.
jsonpb_test_proto
Package jsonpb is a generated protocol buffer package.
Package jsonpb is a generated protocol buffer package.
Package proto converts data structures to and from the wire format of protocol buffers.
Package proto converts data structures to and from the wire format of protocol buffers.
proto3_proto
Package proto3_proto is a generated protocol buffer package.
Package proto3_proto is a generated protocol buffer package.
protoc-gen-go
descriptor
Package descriptor is a generated protocol buffer package.
Package descriptor is a generated protocol buffer package.
generator
The code generator for the plugin for the Google protocol buffer compiler.
The code generator for the plugin for the Google protocol buffer compiler.
grpc
Package grpc outputs gRPC service descriptions in Go code.
Package grpc outputs gRPC service descriptions in Go code.
plugin
Package plugin_go is a generated protocol buffer package.
Package plugin_go is a generated protocol buffer package.
Package ptypes contains code for interacting with well-known types.
Package ptypes contains code for interacting with well-known types.
any
Package any is a generated protocol buffer package.
Package any is a generated protocol buffer package.
duration
Package duration is a generated protocol buffer package.
Package duration is a generated protocol buffer package.
empty
Package empty is a generated protocol buffer package.
Package empty is a generated protocol buffer package.
struct
Package structpb is a generated protocol buffer package.
Package structpb is a generated protocol buffer package.
timestamp
Package timestamp is a generated protocol buffer package.
Package timestamp is a generated protocol buffer package.
wrappers
Package wrappers is a generated protocol buffer package.
Package wrappers is a generated protocol buffer package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL