Deprecate the new(!)/0,1 callbacks (#330)

Author: whatyouhide

README.md

@@ -79,7 +79,7 @@ end
 
       field :name, 1, type: :string
     end
-    
+
     defmodule Helloworld.HelloReply do
       @moduledoc false
       use Protobuf, protoc_gen_elixir_version: "0.10.0", syntax: :proto3
@@ -91,17 +91,13 @@ end
 ### Encode and decode in your code
 
 ```elixir
-struct = Foo.new(a: 3.2, c: Foo.Bar.new())
+struct = %Foo{a: 3.2, c: %Foo.Bar{}}
 encoded = Foo.encode(struct)
 struct = Foo.decode(encoded)
 ```
 
-Note:
-
-- Use `YourModule.new(field: "value")` to ensure default values are set correctly for all fields
-  instead of using the struct directly, as in `%YourModule{field: "value"}`.
-- Validation is done during encoding. An error will be raised if the struct is invalid: when it
-  misses a required field or has a mistyped value.
+Validation is done during encoding. An error will be raised if the struct is invalid: when it
+misses a required field or has a mistyped value.
 
 ### Descriptor support
 

conformance/protobuf/runner.ex

@@ -47,8 +47,10 @@ defmodule Conformance.Protobuf.Runner do
             raise "failed to read #{len} bytes from stdio: #{inspect(reason)}"
 
           encoded_request when byte_size(encoded_request) == len ->
-            mod = Conformance.ConformanceResponse
-            response = mod.new!(result: handle_encoded_request(encoded_request))
+            response =
+              struct!(Conformance.ConformanceResponse,
+                result: handle_encoded_request(encoded_request)
+              )
 
             encoded_response = Protobuf.encode(response)
 

lib/protobuf.ex

@@ -42,16 +42,19 @@ defmodule Protobuf do
 
       @behaviour Protobuf
 
+      @deprecated "Build the struct by hand with %MyMessage{...} or use struct/1"
       @impl unquote(__MODULE__)
       def new() do
         Protobuf.Builder.new(__MODULE__)
       end
 
+      @deprecated "Build the struct by hand with %MyMessage{...} or use struct/2"
       @impl unquote(__MODULE__)
       def new(attrs) do
         Protobuf.Builder.new(__MODULE__, attrs)
       end
 
+      @deprecated "Build the struct by hand with %MyMessage{...} or use struct!/2"
       @impl unquote(__MODULE__)
       def new!(attrs) do
         Protobuf.Builder.new!(__MODULE__, attrs)
@@ -73,10 +76,13 @@ defmodule Protobuf do
   end
 
   @doc """
-  Builds a blank struct with default values. This and other "new" functions are
-  preferred than raw building struct method like `%Foo{}`.
+  Builds a blank struct with default values.
+
+  > #### Deprecated {: .warning}
+  >
+  > This is deprecated in favor of building the struct with `%MyMessage{...}` or using
+  > `struct/1`.
 
-  In proto3, the zero values are the default values.
   """
   @callback new() :: struct()
 
@@ -85,10 +91,14 @@ defmodule Protobuf do
 
   This function will:
 
-  * Recursively call `c:new/1` for embedded fields
-  * Create structs using `struct/2` for keyword lists and maps
-  * Create the correct struct if passed the wrong struct
-  * Call `c:new/1` for each element in the list for repeated fields
+    * Recursively call `c:new/1` for embedded fields
+    * Create structs using `struct/2` for keyword lists and maps
+    * Create the correct struct if passed the wrong struct
+    * Call `c:new/1` for each element in the list for repeated fields
+
+  > #### Deprecated {: .warning}
+  > This is deprecated in favor of building the struct with `%MyMessage{...}` or using
+  > `struct/2`.
 
   ## Examples
 
@@ -105,13 +115,18 @@ defmodule Protobuf do
       #=> %MyMessage{repeated: [%MyRepeated{field1: "foo"}, %MyRepeated{field1: "bar"}]}
 
   """
-  @callback new(Enum.t()) :: struct
+  @callback new(attributes :: Enum.t()) :: struct
 
   @doc """
   Similar to `c:new/1`, but use `struct!/2` to build the struct, so
   errors will be raised if unknown keys are passed.
+
+  > #### Deprecated {: .warning}
+  > This is deprecated in favor of building the struct with `%MyMessage{...}` or using
+  > `struct!/2` directly.
+
   """
-  @callback new!(Enum.t()) :: struct()
+  @callback new!(attributes :: Enum.t()) :: struct()
 
   @doc """
   Encodes the given struct into to a Protobuf binary.
@@ -167,8 +182,7 @@ defmodule Protobuf do
 
   ## Examples
 
-      struct = MyMessage.new()
-      Protobuf.encode(struct)
+      Protobuf.encode(%MyMessage{...})
       #=> <<...>>
 
   """
@@ -180,8 +194,7 @@ defmodule Protobuf do
 
   ## Examples
 
-      struct = MyMessage.new()
-      Protobuf.encode_to_iodata(struct)
+      Protobuf.encode_to_iodata(%MyMessage{...})
       #=> [...]
 
   """

lib/protobuf/any.ex

@@ -12,14 +12,15 @@ defmodule Protobuf.Any do
 
   You can build and decode the `Any` type yourself.
 
-      encoded_any = Google.Protobuf.Any.new!(
-        type_url: "type.googleapis.com/google.protobuf.Duration",
-        value: Google.Protobuf.Duration.encode(%Google.Protobuf.Duration{seconds: 1})
-      )
-
-      # Back to the original message:
-      decoded_any = decoded Google.Protobuf.Any.decode(encoded_any)
-      Google.Protobuf.Duration.decode(decoded_any.value)
+      iex> value = %Google.Protobuf.Duration{seconds: 1}
+      iex> any = %Google.Protobuf.Any{
+      ...>   type_url: "type.googleapis.com/google.protobuf.Duration",
+      ...>   value: Google.Protobuf.Duration.encode(value)
+      ...> }
+      iex> encoded_any = Google.Protobuf.Any.encode(any)
+      iex> decoded_any = Google.Protobuf.Any.decode(encoded_any)
+      iex> Google.Protobuf.Duration.decode(decoded_any.value) == value
+      true
 
   """
 

lib/protobuf/decoder.ex

@@ -14,7 +14,7 @@ defmodule Protobuf.Decoder do
     %MessageProps{repeated_fields: repeated_fields} = props = module.__message_props__()
 
     bin
-    |> build_message(module.new(), props)
+    |> build_message(struct(module), props)
     |> reverse_repeated(repeated_fields)
     |> Map.update!(:__unknown_fields__, &Enum.reverse/1)
     |> transform_module(module)

lib/protobuf/encoder.ex

@@ -144,7 +144,8 @@ defmodule Protobuf.Encoder do
   defp encode_from_type(mod, msg) do
     case msg do
       %{__struct__: ^mod} -> encode_to_iodata(msg)
-      _ -> encode_to_iodata(mod.new(msg))
+      %_{} -> encode_to_iodata(struct(mod, Map.from_struct(msg)))
+      _ -> encode_to_iodata(struct(mod, msg))
     end
   end
 

lib/protobuf/extension.ex

@@ -29,9 +29,10 @@ defmodule Protobuf.Extension do
         extend Foo, :my_custom, 1047, optional: true, type: :string
       end
 
-      foo = Foo.new()
+      foo = %Foo{}
       Foo.put_extension(foo, Ext.PbExtension, :my_custom, "Custom field")
       Foo.get_extension(foo, Ext.PbExtension, :my_custom)
+
   """
 
   @doc "The actual function for `put_extension`"

lib/protobuf/json.ex

@@ -49,7 +49,7 @@ defmodule Protobuf.JSON do
 
   With `encode/1` you can turn any `Protobuf` message struct into a JSON string:
 
-      iex> message = Car.new(color: :RED, top_speed: 125.3)
+      iex> message = %Car{color: :RED, top_speed: 125.3}
       iex> Protobuf.JSON.encode(message)
       {:ok, "{\\"color\\":\\"RED\\",\\"topSpeed\\":125.3}"}
 
@@ -101,7 +101,7 @@ defmodule Protobuf.JSON do
 
   ## Examples
 
-      iex> Car.new(top_speed: 80.0) |> Protobuf.JSON.encode!()
+      iex> Protobuf.JSON.encode!(%Car{top_speed: 80.0})
       ~S|{"topSpeed":80.0}|
 
   """
@@ -143,13 +143,13 @@ defmodule Protobuf.JSON do
 
   Encoding is as simple as:
 
-      iex> Car.new(color: :RED, top_speed: 125.3) |> Protobuf.JSON.encode()
+      iex> Protobuf.JSON.encode(%Car{color: :RED, top_speed: 125.3})
       {:ok, ~S|{"color":"RED","topSpeed":125.3}|}
 
-      iex> Car.new(color: :GREEN) |> Protobuf.JSON.encode()
+      iex> Protobuf.JSON.encode(%Car{color: :GREEN})
       {:ok, "{}"}
 
-      iex> Car.new() |> Protobuf.JSON.encode(emit_unpopulated: true)
+      iex> Protobuf.JSON.encode(%Car{}, emit_unpopulated: true)
       {:ok, ~S|{"color":"GREEN","topSpeed":0.0}|}
 
   """
@@ -174,13 +174,13 @@ defmodule Protobuf.JSON do
 
   ## Examples
 
-      iex> Car.new(color: :RED, top_speed: 125.3) |> Protobuf.JSON.to_encodable()
+      iex> Protobuf.JSON.to_encodable(%Car{color: :RED, top_speed: 125.3})
       {:ok, %{"color" => :RED, "topSpeed" => 125.3}}
 
-      iex> Car.new(color: :GREEN) |> Protobuf.JSON.to_encodable()
+      iex> Protobuf.JSON.to_encodable(%Car{color: :GREEN})
       {:ok, %{}}
 
-      iex> Car.new() |> Protobuf.JSON.to_encodable(emit_unpopulated: true)
+      iex> Protobuf.JSON.to_encodable(%Car{}, emit_unpopulated: true)
       {:ok, %{"color" => :GREEN, "topSpeed" => 0.0}}
 
   """

lib/protobuf/json/decode.ex

@@ -59,11 +59,11 @@ defmodule Protobuf.JSON.Decode do
 
     case Integer.parse(string) do
       {seconds, "s"} when seconds in @duration_seconds_range ->
-        mod.new!(seconds: seconds)
+        struct!(mod, seconds: seconds)
 
       {seconds, "." <> nanos_with_s} when seconds in @duration_seconds_range ->
         case Utils.parse_nanoseconds(nanos_with_s) do
-          {nanos, "s"} -> mod.new!(seconds: seconds, nanos: nanos * sign)
+          {nanos, "s"} -> struct!(mod, seconds: seconds, nanos: nanos * sign)
           :error -> throw({:bad_duration, string, nanos_with_s})
         end
 
@@ -74,80 +74,80 @@ defmodule Protobuf.JSON.Decode do
 
   def from_json_data(string, Google.Protobuf.Timestamp = mod) when is_binary(string) do
     case Protobuf.JSON.RFC3339.decode(string) do
-      {:ok, seconds, nanos} -> mod.new!(seconds: seconds, nanos: nanos)
+      {:ok, seconds, nanos} -> struct!(mod, seconds: seconds, nanos: nanos)
       {:error, reason} -> throw({:bad_timestamp, string, reason})
     end
   end
 
   def from_json_data(map, Google.Protobuf.Empty = mod) when map == %{} do
-    mod.new!([])
+    struct!(mod)
   end
 
   def from_json_data(int, Google.Protobuf.Int32Value = mod),
-    do: mod.new!(value: decode_scalar(:int32, :unknown_name, int))
+    do: struct!(mod, value: decode_scalar(:int32, :unknown_name, int))
 
   def from_json_data(int, Google.Protobuf.UInt32Value = mod),
-    do: mod.new!(value: decode_scalar(:uint32, :unknown_name, int))
+    do: struct!(mod, value: decode_scalar(:uint32, :unknown_name, int))
 
   def from_json_data(int, Google.Protobuf.UInt64Value = mod),
-    do: mod.new!(value: decode_scalar(:uint64, :unknown_name, int))
+    do: struct!(mod, value: decode_scalar(:uint64, :unknown_name, int))
 
   def from_json_data(int, Google.Protobuf.Int64Value = mod),
-    do: mod.new!(value: decode_scalar(:int64, :unknown_name, int))
+    do: struct!(mod, value: decode_scalar(:int64, :unknown_name, int))
 
   def from_json_data(number, mod)
       when mod in [
              Google.Protobuf.FloatValue,
              Google.Protobuf.DoubleValue
            ] and (is_float(number) or is_integer(number)) do
-    mod.new!(value: number * 1.0)
+    struct!(mod, value: number * 1.0)
   end
 
   def from_json_data(bool, Google.Protobuf.BoolValue = mod) when is_boolean(bool) do
-    mod.new!(value: decode_scalar(:bool, :unknown_field, bool))
+    struct!(mod, value: decode_scalar(:bool, :unknown_field, bool))
   end
 
   def from_json_data(string, Google.Protobuf.StringValue = mod) when is_binary(string) do
-    mod.new!(value: decode_scalar(:string, :unknown_field, string))
+    struct!(mod, value: decode_scalar(:string, :unknown_field, string))
   end
 
   def from_json_data(bytes, Google.Protobuf.BytesValue = mod) when is_binary(bytes) do
-    mod.new!(value: decode_scalar(:bytes, :unknown_field, bytes))
+    struct!(mod, value: decode_scalar(:bytes, :unknown_field, bytes))
   end
 
   def from_json_data(list, Google.Protobuf.ListValue = mod) when is_list(list) do
-    mod.new!(values: Enum.map(list, &from_json_data(&1, Google.Protobuf.Value)))
+    struct!(mod, values: Enum.map(list, &from_json_data(&1, Google.Protobuf.Value)))
   end
 
   def from_json_data(struct, Google.Protobuf.Struct = mod) when is_map(struct) do
     fields =
       Map.new(struct, fn {key, val} -> {key, from_json_data(val, Google.Protobuf.Value)} end)
 
-    mod.new!(fields: fields)
+    struct!(mod, fields: fields)
   end
 
   def from_json_data(term, Google.Protobuf.Value = mod) do
     cond do
       is_nil(term) ->
-        mod.new!(kind: {:null_value, :NULL_VALUE})
+        struct!(mod, kind: {:null_value, :NULL_VALUE})
 
       is_binary(term) ->
-        mod.new!(kind: {:string_value, term})
+        struct!(mod, kind: {:string_value, term})
 
       is_integer(term) ->
-        mod.new!(kind: {:number_value, term * 1.0})
+        struct!(mod, kind: {:number_value, term * 1.0})
 
       is_float(term) ->
-        mod.new!(kind: {:number_value, term})
+        struct!(mod, kind: {:number_value, term})
 
       is_boolean(term) ->
-        mod.new!(kind: {:bool_value, term})
+        struct!(mod, kind: {:bool_value, term})
 
       is_list(term) ->
-        mod.new!(kind: {:list_value, from_json_data(term, Google.Protobuf.ListValue)})
+        struct!(mod, kind: {:list_value, from_json_data(term, Google.Protobuf.ListValue)})
 
       is_map(term) ->
-        mod.new!(kind: {:struct_value, from_json_data(term, Google.Protobuf.Struct)})
+        struct!(mod, kind: {:struct_value, from_json_data(term, Google.Protobuf.Struct)})
 
       true ->
         throw({:bad_message, term, mod})
@@ -158,8 +158,8 @@ defmodule Protobuf.JSON.Decode do
     paths = String.split(data, ",")
 
     cond do
-      data == "" -> mod.new!(paths: [])
-      paths = Enum.map(paths, &convert_field_mask_to_underscore/1) -> mod.new!(paths: paths)
+      data == "" -> struct!(mod, paths: [])
+      paths = Enum.map(paths, &convert_field_mask_to_underscore/1) -> struct!(mod, paths: paths)
       true -> throw({:bad_field_mask, data})
     end
   end
@@ -187,7 +187,7 @@ defmodule Protobuf.JSON.Decode do
           |> message_mod.encode()
       end
 
-    mod.new!(type_url: type_url, value: encoded)
+    struct!(mod, type_url: type_url, value: encoded)
   end
 
   def from_json_data(data, module) when is_map(data) and is_atom(module) do

lib/protobuf/protoc/cli.ex

@@ -57,10 +57,10 @@ defmodule Protobuf.Protoc.CLI do
         Protobuf.Protoc.Generator.generate(ctx, desc)
       end)
 
-    Google.Protobuf.Compiler.CodeGeneratorResponse.new(
+    %Google.Protobuf.Compiler.CodeGeneratorResponse{
       file: files,
       supported_features: supported_features()
-    )
+    }
     |> Protobuf.encode_to_iodata()
     |> IO.binwrite()
   end