Modernize the documentation across the entire module
to make use of the newer ability to linkify declarations.
Change-Id: I440f9a3f025ec6fadfd9cba59b1dfb57028bf3f1
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/309430
Reviewed-by: Michael Stapelberg <stapelberg@google.com>
Reviewed-by: Damien Neil <dneil@google.com>
Apply go1.19 gofmt to non-generated files.
Generated .pb.go files are created by generate.bash using Go 1.18,
so leave them unchanged for now.
Change-Id: Ied36c83cf99704988d059bf0412e677f0fbc71b0
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/418676
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Lasse Folger <lassefolger@google.com>
The Unwrap method returns the original concrete message value.
In theory this allows users to mutate the original message when the
cmp documentation says that all options should be mutation free.
If users want to disregard this documented restriction, they can
already do so in a number of different ways.
Updates #1347
Change-Id: I65225681ab5dbce0763a140fd02666a4ab542a04
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/340489
Trust: Joe Tsai <joetsai@digital-static.net>
Reviewed-by: Damien Neil <dneil@google.com>
The protoreflect API does not use the distinction between nil and non-nil
empty []byte to preserve presence. As such, avoid accidentally presenting
such information through the transformation.
Change-Id: Ia46b5e2d3fb534d7cd29f478ad47722bfaa06810
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/247458
Reviewed-by: Damien Neil <dneil@google.com>
We should use TextName instead of Name,
since it is the name that actually appears in the .proto file.
Change-Id: Ie526b200d18b0994d93dbb347c266fa5c50cddfe
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/241658
Reviewed-by: Herbie Ong <herbie@google.com>
Add a new TextName accessor that returns the field name that should
be used for the text format. It is usually just the field name, except:
1) it uses the inlined message name for groups,
2) uses the full name surrounded by brackets for extensions, and
3) strips the "message_set_extension" for well-formed extensions
to the proto1 MessageSet.
We make similar adjustments to the JSONName accessor so that it applies
similar semantics for extensions.
The two changes simplifies all logic that wants the humanly readable
name for a field.
Change-Id: I524b6e017fb955146db81819270fe197f8f97980
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/239838
Reviewed-by: Herbie Ong <herbie@google.com>
The genid package unifies the genname, fieldnum, and detectknown
packages into a single package.
Whenever possible use the generated constants rather than
hard-coded literals. This makes it easier to search the entire
module for special logic that deal with well-known types.
Change-Id: I13beff1f4149444a0c0b9e607ebf759657f000f4
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/235301
Reviewed-by: Herbie Ong <herbie@google.com>
This is dead code as the logic has been moved to internal/msgfmt.
Change-Id: If65f443c9672f5fdfbb91c7cc64fb6f12a93c374
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/224658
Reviewed-by: Damien Neil <dneil@google.com>
Port message formatting logic in testing/protocmp to internal/msgfmt
and improve upon its output.
This formatter is optimized for humanly readable output.
It takes the best parts of both the JSON and proto text formats.
The good of prototext:
* It supports emitting unknown fields (useful for debugging).
* It is relatively concise in the common-case since keys do not
need to be represented as quoted strings (e.g., "key" vs key).
The bad of prototext:
* Requires relatively large dependency on encoding/prototext.
* Our implementation lacks support for serializing packed lists.
* Lacks support for readable maps.
* Lacks support for readable Timestamp and Duration.
The good of protojson:
* First-class support for readable maps.
* First-class support for readable Timestamp and Duration.
The bad of protojson:
* Requires relatively large dependency on encoding/protojson.
* Lacks support for emitting unknown fields.
* More verbose in the common-case as keys are quoted strings.
The msgfmt package has the benefits of both protojson and prototext,
but none of the detriments. It is a relatively simple implementation.
This output is only intended for human consumption with no associated
deserialization implementation.
To avoid any illusion that this is identical to either the proto text
or JSON formats, this always emits surrounding "{}" for
top-level messages and the keys are not quoted strings.
This CL does not use this format for generated Message.String methods
as there is concerns about being inconsistent with the String methods
as implemented in other languages. Having it be a seperate package makes
it trivial to switch over to this if desired.
Change-Id: I8b3581904d1624e84bf1b1954d2f01e5774b7f87
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/223752
Reviewed-by: Damien Neil <dneil@google.com>
SortRepeated is similar to cmpopts.SortSlice where it accepts a
user-provided sort function, but only operates on repeated fields.
It pattern matches based on sort element type.
SortRepeatedFields is similar to SortRepeated, but chooses an
arbitrary sort order for the specified (by name) repeated fields.
It pattern matches based on message field name.
Change-Id: Ib6ef282e5394cf7b22522161d524f22e1b76677a
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/221432
Reviewed-by: Damien Neil <dneil@google.com>
Extensions should be checked based on ContainingMessage,
rather than the Parent. Add tests to ensure this works.
Change-Id: Iaf257f65197fb8d332039bc77a192753f8c4159f
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/221426
Reviewed-by: Damien Neil <dneil@google.com>
For user convenience, automatically transform message values by
shallow copying them if necessary. Storing messages as values is
frowned upon, but is sometimes done by APIs that a user does not own.
Change-Id: I7e927d1a1e050bf4cea1aa889f56d23e99355f26
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/221423
Reviewed-by: Damien Neil <dneil@google.com>
By having the Message type implement proto.Message, it can be passed
to other general-purpose protobuf functions such as proto.Merge.
This provides a convenient way to convert the Message back into a
concrete form that may be easier to work with.
A minor consequence of this change is that invalid messages are
converted to an invalid Message that preserves type information.
Previously, they were simply transformed to a nil Message.
Change-Id: I6fca8a0879408c7f44a99d52734613302fa23f70
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/221422
Reviewed-by: Damien Neil <dneil@google.com>
This CL adds the following helper options:
func FilterEnum(protoreflect.Enum, cmp.Option) cmp.Option
func FilterMessage(proto.Message, cmp.Option) cmp.Option
func FilterField(proto.Message, protoreflect.Name, cmp.Option) cmp.Option
func FilterOneof(proto.Message, protoreflect.Name, cmp.Option) cmp.Option
func FilterDescriptor(protoreflect.Descriptor, cmp.Option) cmp.Option
There is primarily exposing pre-existing functionality that the Ignore options
were already depending on to operate.
Change-Id: I44edf2ffa07de980a9ad3284525bfe3b45428d74
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/207177
Reviewed-by: Damien Neil <dneil@google.com>
The proto package tests often test several variations of messages with a
similar shape. For example, most tests are performed with a proto2
message with a regular field, a proto2 message with an extension field,
and a proto3 message.
Add a protobuild package which can initialize all these variations from
a single template. For example, these three messages:
&testpb.TestAllTypes{OptionalInt32: proto.Int32(1)}
&test3pb.TestAllTypes{OptionalInt32: 1}
m := &testpb.TestAllExtensions{}
proto.SetExtension(m, &testpb.E_OptionalInt32, 1)
can all be constructed from the template:
protobuild.Message{"optional_int32": 1}
This reduces redundancy in tests and will make it more practical to
test alternative code generators.
Change-Id: I3245a4bf74ee1bce957bc772fed513d427720677
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/217457
Reviewed-by: Joe Tsai <thebrokentoaster@gmail.com>
Tweak the test message to allow creating messages with extensions that
contain extensions that contain extensions, etc.
Change-Id: I41844ae699c88ab96bf0d30db3a3fbaf09616161
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/216761
Reviewed-by: Joe Tsai <joetsai@google.com>
The v1 proto.Equal function treats (*Message)(nil) and new(Message)
as being different, while v2 proto.Equal treated them as equal since
a typed nil pointer is functionally an empty message since the
protobuf data model has no concept of presence as a first-class
property of messages.
Unfortunately, a significant amount of code depends on this distinction
that it would be difficult to migrate users from v1 to v2 unless we
preserved similar semantics in the v2 proto.Equal.
Also, double down on these semantics for protocmp.Transform.
Fixes#965
Change-Id: I21e78ba6251401a0ac0ccf495188093973cd7f3f
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/213238
Reviewed-by: Damien Neil <dneil@google.com>
This CL adds the following helper options:
func IgnoreEnums(...protoreflect.Enum) cmp.Option
func IgnoreMessages(...proto.Message) cmp.Option
func IgnoreFields(proto.Message, ...protoreflect.Name) cmp.Option
func IgnoreOneofs(proto.Message, ...protoreflect.Name) cmp.Option
func IgnoreDescriptors(...protoreflect.Descriptor) cmp.Option
func IgnoreDefaultScalars() cmp.Option
func IgnoreEmptyMessages() cmp.Option
func IgnoreUnknown() cmp.Option
It also augments transformMessage to unmarshal and expand Any messages
with the value of the underlying message. At this moment in time
we do not provide an API to provide a custom type resolver.
Change-Id: I51e1d9ff0d56d71161e510f366a7dcc32236d760
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/204577
Reviewed-by: Damien Neil <dneil@google.com>
Accessing Number as a method, rather than a field paves the
way to have Enum potentially implement protoreflect.Enum
in the future.
Change-Id: Iebe9c0ec12e067decf2121d12fe2fb1549477b32
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/207077
Reviewed-by: Damien Neil <dneil@google.com>
High-level API:
func Transform() cmp.Option
type Enum struct{ ... }
type Message map[string]interface{}
The Transform function transform messages into a Message type that
cmp.Equal and cmp.Diff then knows how to traverse and compare.
Change-Id: I445f3b5c69f054b6984f28c205cda69e44af3b89
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/164680
Reviewed-by: Damien Neil <dneil@google.com>
