README.md

rebar3 proto plugin
=====

The purpose of this plugin is to provide an auto-incrementing id for each protocol name, for using the protocol definition that uses protocol numbers instead of protocol names.

This plugin would generat a module `proto_info.erl`, which provides frequently-used functions defined by users.

Cooperates with [rebar3_gpb_plugin](https://github.com/lrascao/rebar3_gpb_plugin), so [configure](https://github.com/lrascao/rebar3_gpb_plugin#usage-with-umbrella-projects) it first.

rebar.config's options specification
-----

- `o_meta_file`: The output file record the protocol name, auto-incrementing id, pb module generated by gpb.
- `o_proto_info`: The ouput file genterated functions defined by `custom_info`.
- `custom_info`: The file defines functions for `o_proto_info`'s file.

Use
---

Add the plugin to your rebar config:

```erlang
    {project_plugins, [
        {rebar3_gpb_plugin, "2.22.1"},
        {rebar3_proto_plugin, "0.1.9"}
    ]}.
```

Config the `proto_opts` and `provider_hooks`:

```erlang
    {proto_opts, [
                  {o_meta_file, "proto_info.meta"},
                  {o_proto_info, "src/proto_info.erl"},
                  {custom_info, ["src/proto_info_custom.erl"]},


                  {proto_hrl, true},
                  {proto_hrl_uppercase, true},
                  {o_proto_hrl, "include/pt_define.hrl"}
                 ]}.


    {provider_hooks, [
        {pre, [
               {compile, {protobuf, compile}},
               {compile, {proto, generate}},

               {clean, {protobuf, clean}}
              ]},
        {post, [
               ]
        }
    ]}.
```

Define custom functions in the file `custom_info` above, each function in `fun_list` would be applied with the argument `MetaList`, and expected to return a map like: `#{fun_name => ?, clauses => [ #{args => ?, return => ?} ]}`).

`MetaList` is a list, each element is a map that contains keys `msg_code`, `msg_name`, `pb_module`.

```
-module(proto_info_custom).

-export([
          fun_list/0
        ]).

fun_list() ->
    [fun get_msg_handle/1].

get_msg_handle(MetaList) ->
    Fun = fun(PbModule) ->
                  case atom_to_list(PbModule) of
                      "pb_" ++ Proto ->
                          list_to_atom("handle_"++Proto);
                      _ ->
                          undefined
                  end
          end,
    ClausesMapsList = [ #{args => [MsgCode], return => Fun(PbModule)}
                        || #{msg_code := MsgCode, pb_module := PbModule} <- MetaList],
    #{fun_name => ?FUNCTION_NAME,
      clauses => ClausesMapsList}.
```

Example
-------------

A simple example locate in [doc/example_app](/doc/example_app).

`proto_info.meta` and `src/pb/proto_info.erl` are generated by current plugin.