v1_to_v2_migration.md

Migration guide (v1 to v2)

This guide explains how to migrate from version 1 to version 2 of Protox.

Note

You'll find the rationales behind the changes in the changelog.

Encoding

Protox now returns the size of the encoded messages along with the encoded data. If you don't need the size, you can simply ignore it:

iex> msg = %Foo{a: 3, b: %{1 => %Baz{}}}
{:ok, iodata, _iodata_size} = Protox.encode(msg)

JSON support

It's no longer possible to encode or decode JSON data directly using Protox. If it's necessary, you can stick to version 1.7 or switch to protobuf.

Protox macro options

The :path option is removed in favor of the already existing :paths option, thus one just has to provide a list containing a single path.

Also, the :keep_unknown_fields option is no longer available. Thus, unknown fields are always kept. If you don't need them, you can simply ignore them.

Generated code

The following functions generated for messages are replaced by the function schema/0:

• defs/0
• field_def/1
• file_options/0
• required_fields/0
• syntax/0

schema/0 returns a Protox.MessageSchema struct which contains information about the message's fields, syntax, and file options.

Example

iex> defmodule MyModule do
  use Protox, schema: """
  syntax = "proto2";

  message Foo {
    required int32 a = 1;
    map<int32, string> b = 2;
  }
  """
end

iex> Foo.schema().syntax
:proto2

iex> Foo.schema().fields[:a]
%Protox.Field{
  tag: 1,
  label: :required,
  name: :a,
  kind: %Protox.Scalar{default_value: 0},
  type: :int32
}

iex> Foo.schema().file_options
nil