Documentation
¶
Overview ¶
Package text implements the text format for protocol buffers. This package has no semantic understanding for protocol buffers and is only a parser and composer for the format.
There is no formal specification for the protobuf text format, as such the C++ implementation (see google::protobuf::TextFormat) is the reference implementation of the text format.
This package is neither a superset nor a subset of the C++ implementation. This implementation permits a more liberal grammar in some cases to be backwards compatible with the historical Go implementation. Future parsings unique to Go should not be added. Some grammars allowed by the C++ implementation are deliberately not implemented here because they are considered a bug by the protobuf team and should not be replicated.
The Go implementation should implement a sufficient amount of the C++ grammar such that the default text serialization by C++ can be parsed by Go. However, just because the C++ parser accepts some input does not mean that the Go implementation should as well.
The text format is almost a superset of JSON except:
- message keys are not quoted strings, but identifiers
- the top-level value must be a message without the delimiters
Index ¶
- func Marshal(v Value, indent string, delims [2]byte, outputASCII bool) ([]byte, error)
- type Type
- type Value
- func (v Value) Bool() (x bool, ok bool)
- func (v Value) Float(b64 bool) (x float64, ok bool)
- func (v Value) Int(b64 bool) (x int64, ok bool)
- func (v Value) List() []Value
- func (v Value) Message() [][2]Value
- func (v Value) Name() (protoreflect.Name, bool)
- func (v Value) Raw() []byte
- func (v Value) String() string
- func (v Value) Type() Type
- func (v Value) Uint(b64 bool) (x uint64, ok bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal serializes v as the proto text format, where v must be a Message. In the proto text format, the top-level value is always a message where the delimiters are elided.
If indent is a non-empty string, it causes every entry in a List or Message to be preceded by the indent and trailed by a newline.
If delims is not the zero value, it controls the delimiter characters used for messages (e.g., "{}" vs "<>").
If outputASCII is true, strings will be serialized in such a way that multi-byte UTF-8 sequences are escaped. This property ensures that the overall output is ASCII (as opposed to UTF-8).
Types ¶
type Type ¶
type Type uint8
Type represents a type expressible in the text format.
const ( // Bool is a boolean (e.g., "true" or "false"). Bool Type // Int is a signed integer (e.g., "-1423"). Int // Uint is an unsigned integer (e.g., "0xdeadbeef"). Uint // Float32 is a 32-bit floating-point number (e.g., "1.234" or "1e38"). // This allows encoding to differentiate the bitsize used for formatting. Float32 // Float64 is a 64-bit floating-point number. Float64 // String is a quoted string (e.g., `"the quick brown fox"`). String // Name is a protocol buffer identifier (e.g., `field_name`). Name // List is an ordered list of values (e.g., `[0, "one", true]`). List // Message is an ordered map of values (e.g., `{"key": null}`). Message )
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value contains a value of a given Type.
func Unmarshal ¶
Unmarshal parses b as the proto text format. It returns a Value, which is always of the Message type.
func ValueOf ¶
func ValueOf(v interface{}) Value
ValueOf returns a Value for a given Go value:
bool => Bool int32, int64 => Int uint32, uint64 => Uint float32 => Float32 float64 => Float64 string, []byte => String protoreflect.Name => Name []Value => List [][2]Value => Message
ValueOf panics if the Go type is not one of the above.
func (Value) Float ¶
Float returns v as a float64 of the specified precision and reports whether the conversion succeeded.
func (Value) Int ¶
Int returns v as an int64 of the specified precision and reports whether the conversion succeeded.
func (Value) List ¶
List returns the elements of v and panics if the Type is not List. Mutations on the return value may not be observable from the Raw method.
func (Value) Message ¶
Message returns the items of v and panics if the Type is not Message. The [2]Value represents a key and value pair, where the key is either a Name (representing a field name), a String (representing extension field names or the Any type URL), or an Uint for unknown fields.
Mutations on the return value may not be observable from the Raw method.
func (Value) Name ¶
func (v Value) Name() (protoreflect.Name, bool)
Name returns the field name or enum value name and reports whether the value can be treated as an identifier.
func (Value) Raw ¶
Raw returns the raw representation of the value. The returned value may alias the input given to Unmarshal.
func (Value) String ¶
String returns v as a string if the Type is String. Otherwise, this returns a formatted string of v for debugging purposes.
Since String is used to represent both text and binary, it is not validated to contain valid UTF-8. When using this value with the string type in proto, it is the user's responsibility perform additional UTF-8 validation.
func (Value) Type ¶
Type is the type of the value. When parsing, this is a best-effort guess at the resulting type. However, there are ambiguities as to the exact type of the value (e.g., "false" is either a bool or a name). Thus, some of the types are convertible with each other. The Bool, Int, Uint, Float32, Float64, and Name methods return a boolean to report whether the conversion was successful.
Source Files