Documentation
¶
Overview ¶
Package textcodec implements protobuf text format marshaling and unmarshaling for protobuf messages. It operates through the protoreflect.Message reflection API so that both generated types and dynamic messages are supported uniformly.
The top-level Marshal and Unmarshal functions use default options. For customization, use MarshalOptions and UnmarshalOptions directly.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMaxDepthExceeded = errors.New("textcodec: maximum recursion depth exceeded")
ErrMaxDepthExceeded is returned when the text format input exceeds the configured recursion depth limit during unmarshaling.
Functions ¶
Types ¶
type MarshalError ¶
type MarshalError struct {
// Field is the full name of the field being marshaled, if known.
Field string
// Detail is a human-readable description of the failure.
Detail string
// Cause is the underlying error, if any.
Cause error
}
MarshalError is a typed error returned when text-format marshaling fails. It includes the field context where available and wraps an optional cause.
func (*MarshalError) Error ¶
func (e *MarshalError) Error() string
Error returns a human-readable message describing the marshal failure.
func (*MarshalError) Unwrap ¶
func (e *MarshalError) Unwrap() error
Unwrap returns the underlying cause so that errors.Is and errors.As work.
type MarshalOptions ¶
type MarshalOptions struct {
// Multiline is a convenience flag that enables multiline indented output.
// When true and Indent is empty, Indent defaults to two spaces (" ").
// When Indent is already set, Multiline has no additional effect.
Multiline bool
// Indent specifies the indentation string for multiline output.
// When non-empty, produce multiline indented output using this string
// as the indent unit. When empty, produce compact single-line output
// with spaces separating tokens.
Indent string
// EmitFieldNumbers uses numeric field tags as keys instead of field names.
// When true, keys are emitted as "1: value" instead of "field_name: value".
// When false (the default), field names are used as keys.
EmitFieldNumbers bool
// EmitDefaultValues emits fields even when they hold the proto3 zero value.
// When false (the default), fields with zero values are omitted from the
// text format output.
EmitDefaultValues bool
// Deterministic causes map fields to be serialized with keys in sorted
// order: bool false before true, integers numerically, strings
// lexicographically. When false (the default), map iteration order is
// undefined.
Deterministic bool
// AllowPartial allows marshaling a message that has missing required fields.
// When false (the default), Marshal returns ErrRequiredNotSet if any proto2
// required field is not set. When true, required field validation is skipped.
AllowPartial bool
// Resolver is an optional resolver used for resolving Any type URLs
// during marshaling. Any implementation of registry.MessageResolver is
// accepted, enabling dependency inversion: callers can supply a
// *registry.TypeRegistry or any custom resolver. When nil,
// registry.GlobalTypes is used.
Resolver registry.MessageResolver
}
MarshalOptions configures text format marshaling behavior.
fieldalignment: fields ordered for semantic clarity, not padding
func (MarshalOptions) Marshal ¶
func (o MarshalOptions) Marshal(msg proto.Message) ([]byte, error)
Marshal serializes a protobuf message to text format using the configured options. When Multiline is true and Indent is empty, Indent defaults to two spaces. When AllowPartial is false, required fields are validated before encoding. It panics if msg is nil.
type UnmarshalError ¶
type UnmarshalError struct {
// Line is the 1-based line number where the error occurred, if known.
Line int
// Column is the 1-based column number where the error occurred, if known.
Column int
// Detail is a human-readable description of the failure.
Detail string
// Cause is the underlying error, if any.
Cause error
}
UnmarshalError is a typed error returned when text-format unmarshaling fails. It includes position context (line, column) where available and wraps an optional cause.
func (*UnmarshalError) Error ¶
func (e *UnmarshalError) Error() string
Error returns a human-readable message describing the unmarshal failure.
func (*UnmarshalError) Unwrap ¶
func (e *UnmarshalError) Unwrap() error
Unwrap returns the underlying cause so that errors.Is and errors.As work.
type UnmarshalOptions ¶
type UnmarshalOptions struct {
// DiscardUnknown silently discards text fields that do not map to any
// known field when true. When false, unknown field names cause an error.
DiscardUnknown bool
// AllowPartial allows unmarshaling a message that has missing required
// fields. When false (the default), Unmarshal returns ErrRequiredNotSet
// if any proto2 required field is not present after decoding. When true,
// required field validation is skipped.
AllowPartial bool
// RecursionLimit sets the maximum nesting depth allowed during unmarshal.
// A value of 0 means use the default limit of 10,000.
RecursionLimit int
// Resolver is an optional resolver used for resolving Any type URLs
// during unmarshaling. Any implementation of registry.MessageResolver is
// accepted, enabling dependency inversion: callers can supply a
// *registry.TypeRegistry or any custom resolver. When nil,
// registry.GlobalTypes is used.
Resolver registry.MessageResolver
}
UnmarshalOptions configures text format unmarshaling behavior.
fieldalignment: fields ordered for semantic clarity, not padding
func (UnmarshalOptions) Unmarshal ¶
func (o UnmarshalOptions) Unmarshal(data []byte, msg proto.Message) error
Unmarshal deserializes text format data into a protobuf message using the configured options. When AllowPartial is false, required fields are validated after decoding. It panics if msg is nil.
Source Files