Skip to content

Commit ae14ce6

Browse files
v0idpwnv0idpwn
authored
Move wire_type() to Protobuf, create Protobuf.unknown_fields() type (#375)
Fixes warnings in generated modules when building documentation; Improves the typespec readability for all protobuf structs.
1 parent 9a97672 commit ae14ce6

File tree

7 files changed

+32
-54
lines changed

7 files changed

+32
-54
lines changed

‎lib/protobuf.ex‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,19 @@ defmodule Protobuf do
3838
3939
"""
4040

41+
@typedoc """
42+
Internal wire type
43+
"""
44+
@type wire_type() :: 0..5
45+
46+
@typedoc """
47+
Represents a field that existed in a decoded message, but didn't exist in the
48+
used protobuf definition.
49+
50+
See `get_unknown_fields/1` for more information.
51+
"""
52+
@type unknown_field() :: {field_number :: integer(), wire_type(), value :: any()}
53+
4154
defmacro __using__(opts) do
4255
quote location: :keep do
4356
import Protobuf.DSL, only: [field: 3, field: 2, oneof: 2, extend: 4, extensions: 1]
@@ -219,7 +232,7 @@ defmodule Protobuf do
219232
a payload, update the resulting message somehow, and re-encode it for future use. In these
220233
cases, you would probably want to re-encode the unknown fields to maintain symmetry.
221234
222-
The returned value of this function is a list of `{field_number, field_value}` tuples where
235+
The returned value of this function is a list of `{field_number, wire_type, field_value}` tuples where
223236
`field_number` is the number of the unknown field in the schema used for its encoding and
224237
`field_value` is its value. The library does not make any assumptions on the value of the
225238
field since it can't know for sure. This means that, for example, it can't properly decode
@@ -239,7 +252,7 @@ defmodule Protobuf do
239252
240253
You encode this:
241254
242-
payload = Protobuf.encode(User.new!(email: "user@example.com))
255+
payload = Protobuf.encode(User.new!(email: "user@example.com"))
243256
#=> <<...>>
244257
245258
Now, you try to decode this payload using this schema instead:
@@ -252,13 +265,12 @@ defmodule Protobuf do
252265
253266
message = User.decode(<<...>>)
254267
Protobuf.get_unknown_fields(message)
255-
#=> [{_field_number = 1, _wire_type = 3, "user@example.com}]
268+
#=> [{_field_number = 1, _wire_type = 3, "user@example.com"}]
256269
257270
"""
258271
@doc since: "0.10.0"
259-
@spec get_unknown_fields(struct()) :: [unknown_field]
260-
when unknown_field:
261-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(), value :: any()}
272+
@spec get_unknown_fields(struct()) :: [unknown_field()]
273+
262274
def get_unknown_fields(message)
263275

264276
def get_unknown_fields(%_{__unknown_fields__: unknown_fields}) do

‎lib/protobuf/dsl/typespecs.ex‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ defmodule Protobuf.DSL.Typespecs do
4040
{:__unknown_fields__,
4141
quote(
4242
do: [
43-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(), value :: term()}
43+
Protobuf.unknown_field()
4444
]
4545
)}
4646
]

‎lib/protobuf/field_props.ex‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,12 @@ defmodule Protobuf.FieldProps do
33

44
# A struct containing information about a field in a Protobuf message.
55

6-
alias Protobuf.Wire.Types
7-
86
@type t :: %__MODULE__{
97
fnum: integer,
108
name: String.t(),
119
name_atom: atom,
1210
json_name: String.t(),
13-
wire_type: Types.wire_type(),
11+
wire_type: Protobuf.wire_type(),
1412
type: atom | {:enum, atom},
1513
default: any,
1614
oneof: non_neg_integer | nil,

‎lib/protobuf/wire.ex‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ defmodule Protobuf.Wire do
3434
@uint32_range 0..0xFFFFFFFF
3535
@uint64_range 0..0xFFFFFFFFFFFFFFFF
3636

37-
@spec wire_type(proto_type() | module()) :: Protobuf.Wire.Types.wire_type()
37+
@spec wire_type(proto_type() | module()) :: Protobuf.wire_type()
3838
def wire_type(:int32), do: wire_varint()
3939
def wire_type(:int64), do: wire_varint()
4040
def wire_type(:uint32), do: wire_varint()
@@ -53,7 +53,7 @@ defmodule Protobuf.Wire do
5353
def wire_type(:float), do: wire_32bits()
5454
def wire_type(mod) when is_atom(mod), do: wire_delimited()
5555

56-
@spec encode_from_wire_type(Protobuf.Wire.Types.wire_type(), term()) :: iodata()
56+
@spec encode_from_wire_type(Protobuf.wire_type(), term()) :: iodata()
5757
def encode_from_wire_type(wire_type, value)
5858

5959
def encode_from_wire_type(wire_varint(), int) when is_integer(int), do: Varint.encode(int)

‎lib/protobuf/wire/types.ex‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
defmodule Protobuf.Wire.Types do
22
@moduledoc false
33

4-
@type wire_type() :: 0..5
5-
64
# From: https://developers.google.com/protocol-buffers/docs/encoding
75
defmacro wire_varint, do: 0
86
defmacro wire_64bits, do: 1

‎test/protobuf/dsl/typespecs_test.exs‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,7 @@ defmodule Protobuf.DSL.TypespecsTest do
77

88
@unknown_fields_spec quote(
99
do: [
10-
__unknown_fields__: [
11-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
12-
value :: term()}
13-
]
10+
__unknown_fields__: [Protobuf.unknown_field()]
1411
]
1512
)
1613

‎test/protobuf/protoc/generator/message_test.exs‎

Lines changed: 9 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
2020
quote(
2121
do:
2222
t() :: %Foo{
23-
__unknown_fields__: [
24-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
25-
value :: term()}
26-
]
23+
__unknown_fields__: [Protobuf.unknown_field()]
2724
}
2825
)
2926
)
@@ -48,10 +45,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
4845
quote(
4946
do:
5047
t() :: %Foo{
51-
__unknown_fields__: [
52-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
53-
value :: term()}
54-
]
48+
__unknown_fields__: [Protobuf.unknown_field()]
5549
}
5650
)
5751
)
@@ -177,10 +171,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
177171
quote(
178172
do:
179173
t() :: %Foo{
180-
__unknown_fields__: [
181-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
182-
value :: term()}
183-
],
174+
__unknown_fields__: [Protobuf.unknown_field()],
184175
a: integer(),
185176
b: String.t(),
186177
c: [integer()]
@@ -371,10 +362,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
371362
quote(
372363
do:
373364
t() :: %Foo{
374-
__unknown_fields__: [
375-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
376-
value :: term()}
377-
],
365+
__unknown_fields__: [Protobuf.unknown_field()],
378366
bar: Bar.t() | nil,
379367
baz: [Baz.t()]
380368
}
@@ -443,10 +431,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
443431
quote(
444432
do:
445433
t() :: %FooBar.AbCd.Foo{
446-
__unknown_fields__: [
447-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
448-
value :: term()}
449-
],
434+
__unknown_fields__: [Protobuf.unknown_field()],
450435
a: %{optional(integer()) => FooBar.AbCd.Bar.t() | nil}
451436
}
452437
)
@@ -535,10 +520,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
535520
quote(
536521
do:
537522
t() :: %FooBar.AbCd.Foo{
538-
__unknown_fields__: [
539-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
540-
value :: term()}
541-
],
523+
__unknown_fields__: [Protobuf.unknown_field()],
542524
a: OtherPkg.MsgFoo.t() | nil
543525
}
544526
)
@@ -598,10 +580,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
598580
quote(
599581
do:
600582
t() :: %MyPkg.Foo{
601-
__unknown_fields__: [
602-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
603-
value :: term()}
604-
],
583+
__unknown_fields__: [Protobuf.unknown_field()],
605584
a: MyPkg.Foo.Nested.t() | nil
606585
}
607586
)
@@ -702,10 +681,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
702681
quote(
703682
do:
704683
t() :: %Foo{
705-
__unknown_fields__: [
706-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
707-
value :: term()}
708-
],
684+
__unknown_fields__: [Protobuf.unknown_field()],
709685
first: {:a, integer()} | {:b, integer()} | nil,
710686
other: integer() | nil,
711687
second: {:c, integer()} | {:d, integer()} | nil
@@ -809,10 +785,7 @@ defmodule Protobuf.Protoc.Generator.MessageTest do
809785
quote(
810786
do:
811787
t() :: %FooBar.AbCd.Foo{
812-
__unknown_fields__: [
813-
{field_number :: integer(), Protobuf.Wire.Types.wire_type(),
814-
value :: term()}
815-
],
788+
__unknown_fields__: [Protobuf.unknown_field()],
816789
a: [FooBar.AbCd.EnumFoo.t()]
817790
}
818791
)

0 commit comments

Comments
 (0)