@spec decode(iodata(), module(), [decode_opt()]) ::
  {:ok, struct()} | {:error, Protobuf.JSON.DecodeError.t() | Exception.t()}

Decodes a JSON iodata into a module Protobuf struct.

Options

• :ignore_unknown_fields (boolean): when true, unknown enum string values are treated as if the field was unset (and skipped from repeated fields and map values) instead of raising. Unknown JSON object keys are always ignored regardless of this option. Defaults to false. Available since v0.17.0.

• :recursion_limit (positive integer): the maximum nesting depth allowed when decoding the dynamically-typed Google.Protobuf.Value, Google.Protobuf.ListValue, and Google.Protobuf.Struct wrappers. Exceeding it raises a Protobuf.JSON.DecodeError. Defaults to 100. Available since v0.17.0.

Examples

Given this Protobuf message:

syntax = "proto3";

message Car {
  enum Color {
    GREEN = 0;
    RED = 1;
  }

  Color color = 1;
  float top_speed = 2;
}

You can build its structs from JSON like this:

iex> Protobuf.JSON.decode("{}", Car)
{:ok, %Car{color: :GREEN, top_speed: 0.0}}

iex> ~S|{"color":"RED"}| |> Protobuf.JSON.decode(Car)
{:ok, %Car{color: :RED, top_speed: 0.0}}

iex> ~S|{"color":"GREEN","topSpeed":80.0}| |> Protobuf.JSON.decode(Car)
{:ok, %Car{color: :GREEN, top_speed: 80.0}}

By default, an unknown enum string value is rejected:

iex> {:error, %Protobuf.JSON.DecodeError{}} =
...>   Protobuf.JSON.decode(~S|{"color":"BLUE"}|, Car)

Pass ignore_unknown_fields: true to drop the unknown value and leave the field at its default instead:

iex> Protobuf.JSON.decode(~S|{"color":"BLUE"}|, Car, ignore_unknown_fields: true)
{:ok, %Car{color: :GREEN, top_speed: 0.0}}

@spec decode!(iodata(), module(), [decode_opt()]) :: struct() | no_return()

Decodes a JSON iodata into a module Protobuf struct.

Similar to decode/3 except it will unwrap the error tuple and raise in case of errors. Accepts the exact same options, documented in decode/3.

Examples

iex> Protobuf.JSON.decode!("{}", Car)
%Car{color: :GREEN, top_speed: 0.0}

iex> ~S|{"color":"RED"}| |> Protobuf.JSON.decode!(Car)
%Car{color: :RED, top_speed: 0.0}

iex> ~S|{"color":"GREEN","topSpeed":80.0}| |> Protobuf.JSON.decode!(Car)
%Car{color: :GREEN, top_speed: 80.0}

@spec encode(
  struct(),
  [encode_opt()]
) :: {:ok, String.t()} | {:error, Protobuf.JSON.EncodeError.t() | Exception.t()}

Generates a JSON representation of the given protobuf struct.

Options

• :use_proto_names - use original field name instead of the camelCase json_name for JSON keys. Defaults to false.
• :use_enum_numbers - encode enum field values as numbers instead of their labels. Defaults to false.
• :emit_unpopulated - emit all fields, even when they are blank, empty, or set to their default value. Defaults to false.

Examples

Suppose that this is you Protobuf message:

syntax = "proto3";

message Car {
  enum Color {
    GREEN = 0;
    RED = 1;
  }

  Color color = 1;
  float top_speed = 2;
}

Encoding is as simple as:

iex> Protobuf.JSON.encode(%Car{color: :RED, top_speed: 125.3})
{:ok, ~S|{"color":"RED","topSpeed":125.3}|}

iex> Protobuf.JSON.encode(%Car{color: :GREEN})
{:ok, "{}"}

iex> Protobuf.JSON.encode(%Car{}, emit_unpopulated: true)
{:ok, ~S|{"color":"GREEN","topSpeed":0.0}|}

@spec encode!(
  struct(),
  [encode_opt()]
) :: String.t() | no_return()

Generates a JSON representation of the given protobuf struct.

Similar to encode/2 except it will unwrap the error tuple and raise in case of errors.

Examples

iex> Protobuf.JSON.encode!(%Car{top_speed: 80.0})
~S|{"topSpeed":80.0}|

@spec encode_to_iodata(
  struct(),
  [encode_opt()]
) :: {:ok, iodata()} | {:error, Protobuf.JSON.EncodeError.t() | Exception.t()}

Similar to encode/2, but returns iodata

This function should be preferred to encode/2, if the generated JSON will be handed over to one of the IO functions or sent over the socket. The Erlang runtime is able to leverage vectorised writes and avoid allocating a continuous buffer for the whole resulting string, lowering memory use and increasing performance.

@spec encode_to_iodata!(
  struct(),
  [encode_opt()]
) :: iodata()

Similar to encode!/2, but returns iodata

See encode_to_iodata/2 for more information about when this function should be preferred over encode!/2.

@spec from_decoded(json_data(), module(), [decode_opt()]) ::
  {:ok, struct()} | {:error, Protobuf.JSON.DecodeError.t()}

Decodes a json_data map into a module Protobuf struct.

Similar to decode/2 except it takes a JSON map representation of the data. This is especially useful if you want to use custom JSON encoding or a custom JSON library.

Accepts the same options as decode/3.

Field keys in json_data must be strings (either the proto field name or the JSON name). Data produced by Jason.decode(..., keys: :atoms) is not supported: proto map<...> fields are themselves decoded as maps whose keys come from the wire, so atom-keyed input cannot be reliably distinguished from a map<string, _> value and nested maps would not round-trip. Convert keys to strings before calling from_decoded/2 if you need this.

Examples

iex> Protobuf.JSON.from_decoded(%{}, Car)
{:ok, %Car{color: :GREEN, top_speed: 0.0}}

iex> Protobuf.JSON.from_decoded(%{"color" => "RED"}, Car)
{:ok, %Car{color: :RED, top_speed: 0.0}}

iex> Protobuf.JSON.from_decoded(%{"color" => "GREEN","topSpeed" => 80.0}, Car)
{:ok, %Car{color: :GREEN, top_speed: 80.0}}

By default, an unknown enum string value is rejected:

iex> {:error, %Protobuf.JSON.DecodeError{}} =
...>   Protobuf.JSON.from_decoded(%{"color" => "BLUE"}, Car)

Pass ignore_unknown_fields: true to drop it instead:

iex> Protobuf.JSON.from_decoded(%{"color" => "BLUE"}, Car, ignore_unknown_fields: true)
{:ok, %Car{color: :GREEN, top_speed: 0.0}}

@spec to_encodable(
  struct(),
  [encode_opt()]
) :: {:ok, json_data()} | {:error, Protobuf.JSON.EncodeError.t()}

Generates a JSON-encodable map for the given Protobuf struct.

Similar to encode/2 except it will return an intermediate map representation. This is especially useful if you want to use custom JSON encoding or a custom JSON library.

Supports the same options as encode/2.

Examples

iex> Protobuf.JSON.to_encodable(%Car{color: :RED, top_speed: 125.3})
{:ok, %{"color" => :RED, "topSpeed" => 125.3}}

iex> Protobuf.JSON.to_encodable(%Car{color: :GREEN})
{:ok, %{}}

iex> Protobuf.JSON.to_encodable(%Car{}, emit_unpopulated: true)
{:ok, %{"color" => :GREEN, "topSpeed" => 0.0}}