Protobuf behaviour (protobuf v0.8.0) View Source

protoc should always be used to generate code instead of writing the code by hand.

By use this module, macros defined in Protobuf.DSL will be injected. Most of thee macros are equal to definition in .proto files.

defmodule Foo do
  use Protobuf, syntax: :proto3

  defstruct [:a, :b]

  field :a, 1, type: :int32
  field :b, 2, type: :string
end

Your Protobuf message(module) is just a normal Elixir struct. Some useful functions are also injected, see "Callbacks" for details. Examples:

foo1 = Foo.new!(%{a: 1})
foo1.b == ""
bin = Foo.encode(foo1)
foo1 == Foo.decode(bin)

Except functions in "Callbacks", some other functions may be defined:

Extension functions when your Protobuf message use extensions. See Protobuf.Extension for details.
- put_extension(struct, extension_mod, field, value)
- get_extension(struct, extension_mod, field, default \ nil)

Link to this section Summary

Callbacks

decode(binary)

Decode a protobuf binary to a struct.

encode(struct)

Encode the struct to a protobuf binary.

new()

Build a blank struct with default values. This and other "new" functions are preferred than raw building struct method like %Foo{}.

new(t)

Build and update the struct with passed fields.

new!(t)

Similar to new/1, but use struct!/2 to build the struct, so errors will be raised if unknown keys are passed.

transform_module()

Returns nil or a transformer module that implements the Protobuf.TransformModule behaviour.

Functions

decode(data, mod)

It's preferable to use message's decode function, like

encode(struct)

It's preferable to use message's encode function, like

load_extensions()

Loads extensions modules.

Link to this section Callbacks

decode(binary)

Specs

decode(binary()) :: struct()

Decode a protobuf binary to a struct.

Errors may be raised if there's something wrong in the binary.

encode(struct)

Specs

encode(struct()) :: binary()

Encode the struct to a protobuf binary.

Errors may be raised if there's something wrong in the struct.

new()

Specs

new() :: struct()

Build a blank struct with default values. This and other "new" functions are preferred than raw building struct method like %Foo{}.

In proto3, the zero values are the default values.

new(t)

Specs

new(Enum.t()) :: struct()

Build and update the struct with passed fields.

new!(t)

Specs

new!(Enum.t()) :: struct()

Similar to new/1, but use struct!/2 to build the struct, so errors will be raised if unknown keys are passed.

transform_module()

Specs

transform_module() :: module() | nil

Returns nil or a transformer module that implements the Protobuf.TransformModule behaviour.

This function is overridable in your module.

Link to this section Functions

decode(data, mod)

Specs

decode(binary(), module()) :: struct()

It's preferable to use message's decode function, like:

Foo.decode(bin)

encode(struct)

Specs

encode(struct()) :: binary()

It's preferable to use message's encode function, like:

Foo.encode(foo)

load_extensions()

Specs

load_extensions() :: :ok

Loads extensions modules.

This function should be called in your application's start/2 callback, as seen in the example below, if you wish to use extensions.

Example

def start(_type, _args) do
  Protobuf.load_extensions()
  Supervisor.start_link([], strategy: :one_for_one)
end