README
¶
ProtoYAML
Marshal and unmarshal Protocol Buffers as YAML. Provides fine-grained error details with file, line, column and snippet information.
Fully compatible with protojson.
Usage
package main
import (
"log"
"buf.build/go/protoyaml"
)
func main() {
// Marshal a proto message to YAML.
yamlBytes, err := protoyaml.Marshal(
&pb.MyMessage{
MyField: "hello world",
},
)
if err != nil {
log.Fatal(err)
}
// Unmarshal a proto message from YAML.
options := protoyaml.UnmarshalOptions{
Path: "testdata/basic.proto3test.yaml",
}
var myMessage pb.MyMessage
if err := options.Unmarshal(yamlBytes, &myMessage); err != nil {
log.Fatal(err)
}
}
ProtoYAML returns either nil or an error with a detailed message. For every error found in the file, the error
message includes the file name (if Path is set on UnmarshalOptions), line number, column number, and snippet
of the YAML that caused the error. For example, when unmarshalling the following YAML file:
values:
- single_bool: true
- single_bool: false
- single_bool: 1
- single_bool: 0
- single_bool: "true"
- single_bool: "false"
- single_bool: True
- single_bool: False
- single_bool: TRUE
- single_bool: FALSE
- single_bool: yes
- single_bool: no
The following errors are returned:
testdata/basic.proto3test.yaml:5:18: expected bool, got "1"
5 | - single_bool: 1
| .................^
testdata/basic.proto3test.yaml:6:18: expected bool, got "0"
6 | - single_bool: 0
| .................^
testdata/basic.proto3test.yaml:7:18: expected tag !!bool, got !!str
7 | - single_bool: "true"
| .................^
testdata/basic.proto3test.yaml:8:18: expected tag !!bool, got !!str
8 | - single_bool: "false"
| .................^
testdata/basic.proto3test.yaml:9:18: expected bool, got "True"
9 | - single_bool: True
| .................^
testdata/basic.proto3test.yaml:10:18: expected bool, got "False"
10 | - single_bool: False
| .................^
testdata/basic.proto3test.yaml:11:18: expected bool, got "TRUE"
11 | - single_bool: TRUE
| .................^
testdata/basic.proto3test.yaml:12:18: expected bool, got "FALSE"
12 | - single_bool: FALSE
| .................^
testdata/basic.proto3test.yaml:13:18: expected bool, got "yes"
13 | - single_bool: yes
| .................^
testdata/basic.proto3test.yaml:14:18: expected bool, got "no"
14 | - single_bool: no
| .................^
Only true and false are valid values for the single_bool field.
For more examples, see the internal/testdata directory.
Validation
ProtoYAML can integrate with external validation libraries such as
Protovalidate to provide additional rich error
information. Simply provide a Validator to the UnmarshalOptions:
package main
import (
"log"
"buf.build/go/protoyaml"
"buf.build/go/protovalidate"
)
func main() {
validator, err := protovalidate.NewValidator()
if err != nil {
log.Fatal(err)
}
var myMessage pb.MyMessage
options := protoyaml.UnmarshalOptions{
Path: "testdata/basic.proto3test.yaml",
Validator: validator,
}
if err := options.Unmarshal(yamlBytes, &myMessage); err != nil {
log.Fatal(err)
}
}
The errors produced by the Validator will show up along side the ProtoYAML errors. For example:
testdata/validate.validate.yaml:4:18 cases[2].float_gt_lt: value must be greater than 0 and less than 10 (float.gt_lt)
4 | - float_gt_lt: 10.5
| .................^
Status: Beta
ProtoYAML is not yet stable. However, the final shape is unlikely to change drastically—future edits will be somewhat minor.
Legal
Offered under the Apache 2 license
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseDuration ¶
func ParseDuration(str string) (*durationpb.Duration, error)
ParseDuration parses a duration string into a durationpb.Duration.
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
This function supports the full range of durationpb.Duration values, including those outside the range of time.Duration.
Types ¶
type CustomUnmarshaler ¶ added in v0.4.0
type CustomUnmarshaler interface {
// Unmarshal the given node into the given message.
//
// Returns an error if the node is invalid for the message.
// Returns (true, nil) if the node was handled by the custom unmarshaler.
// Otherwise, returns (false, nil), to indicate that the node should be
// unmarshaled by the default unmarshaler.
//
// When unmarshaling a google.protobuf.Any message, the `@type` field is
// included in the node.
//
// The 'message' argument maybe [dynamicpb.Message] or a concrete message type
// depending on the [UnmarshalOptions].Resolver used.
Unmarshal(node *yaml.Node, message proto.Message) (bool, error)
}
CustomUnmarshaler is an interface for custom unmarshaling of Protobuf messages.
type MarshalOptions ¶
type MarshalOptions struct {
// The number of spaces to indent. Passed to yaml.Encoder.SetIndent.
// If 0, uses the default indent of yaml.v3.
Indent int
// AllowPartial allows messages that have missing required fields to marshal
// without returning an error.
AllowPartial bool
// UseProtoNames uses proto field name instead of lowerCamelCase name in YAML
// field names.
UseProtoNames bool
// UseEnumNumbers emits enum values as numbers.
UseEnumNumbers bool
// EmitUnpopulated specifies whether to emit unpopulated fields.
EmitUnpopulated bool
// Resolver is used for looking up types when expanding google.protobuf.Any
// messages. If nil, this defaults to using protoregistry.GlobalTypes.
Resolver interface {
protoregistry.ExtensionTypeResolver
protoregistry.MessageTypeResolver
}
}
MarshalOptions is a configurable YAML format marshaller.
It uses similar options to protojson.MarshalOptions.
type UnmarshalOptions ¶
type UnmarshalOptions struct {
// The path for the data being unmarshaled.
//
// If set, this will be used when producing error messages.
Path string
// Validator is a validator to run after unmarshaling a message.
Validator Validator
// CustomUnmarshaler is a custom unmarshaler to use for specific message types.
CustomUnmarshaler CustomUnmarshaler
// Resolver is the Protobuf type resolver to use.
Resolver interface {
protoregistry.MessageTypeResolver
protoregistry.ExtensionTypeResolver
}
// If AllowPartial is set, input for messages that will result in missing
// required fields will not return an error.
AllowPartial bool
// DiscardUnknown specifies whether to discard unknown fields instead of
// returning an error.
DiscardUnknown bool
}
UnmarshalOptions is a configurable YAML format parser for Protobuf messages.
Source Files
Directories