1 // Go support for Protocol Buffers - Google's data interchange format
3 // Copyright 2010 The Go Authors. All rights reserved.
4 // https://github.com/golang/protobuf
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are
10 // * Redistributions of source code must retain the above copyright
11 // notice, this list of conditions and the following disclaimer.
12 // * Redistributions in binary form must reproduce the above
13 // copyright notice, this list of conditions and the following disclaimer
14 // in the documentation and/or other materials provided with the
16 // * Neither the name of Google Inc. nor the names of its
17 // contributors may be used to endorse or promote products derived from
18 // this software without specific prior written permission.
20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 // Functions for writing the text protocol buffer format.
51 newline = []byte("\n")
53 endBraceNewline = []byte("}\n")
54 backslashN = []byte{'\\', 'n'}
55 backslashR = []byte{'\\', 'r'}
56 backslashT = []byte{'\\', 't'}
57 backslashDQ = []byte{'\\', '"'}
58 backslashBS = []byte{'\\', '\\'}
59 posInf = []byte("inf")
60 negInf = []byte("-inf")
64 type writer interface {
69 // textWriter is an io.Writer that tracks its indentation level.
70 type textWriter struct {
72 complete bool // if the current position is a complete line
73 compact bool // whether to write out as a one-liner
77 func (w *textWriter) WriteString(s string) (n int, err error) {
78 if !strings.Contains(s, "\n") {
79 if !w.compact && w.complete {
83 return io.WriteString(w.w, s)
85 // WriteString is typically called without newlines, so this
86 // codepath and its copy are rare. We copy to avoid
87 // duplicating all of Write's logic here.
88 return w.Write([]byte(s))
91 func (w *textWriter) Write(p []byte) (n int, err error) {
92 newlines := bytes.Count(p, newline)
94 if !w.compact && w.complete {
102 frags := bytes.SplitN(p, newline, newlines+1)
104 for i, frag := range frags {
106 if err := w.w.WriteByte(' '); err != nil {
111 nn, err := w.w.Write(frag)
120 for i, frag := range frags {
124 nn, err := w.w.Write(frag)
129 if i+1 < len(frags) {
130 if err := w.w.WriteByte('\n'); err != nil {
136 w.complete = len(frags[len(frags)-1]) == 0
140 func (w *textWriter) WriteByte(c byte) error {
141 if w.compact && c == '\n' {
144 if !w.compact && w.complete {
147 err := w.w.WriteByte(c)
148 w.complete = c == '\n'
152 func (w *textWriter) indent() { w.ind++ }
154 func (w *textWriter) unindent() {
156 log.Print("proto: textWriter unindented too far")
162 func writeName(w *textWriter, props *Properties) error {
163 if _, err := w.WriteString(props.OrigName); err != nil {
166 if props.Wire != "group" {
167 return w.WriteByte(':')
172 func requiresQuotes(u string) bool {
173 // When type URL contains any characters except [0-9A-Za-z./\-]*, it must be quoted.
174 for _, ch := range u {
176 case ch == '.' || ch == '/' || ch == '_':
178 case '0' <= ch && ch <= '9':
180 case 'A' <= ch && ch <= 'Z':
182 case 'a' <= ch && ch <= 'z':
191 // isAny reports whether sv is a google.protobuf.Any message
192 func isAny(sv reflect.Value) bool {
194 XXX_WellKnownType() string
196 t, ok := sv.Addr().Interface().(wkt)
197 return ok && t.XXX_WellKnownType() == "Any"
200 // writeProto3Any writes an expanded google.protobuf.Any message.
202 // It returns (false, nil) if sv value can't be unmarshaled (e.g. because
203 // required messages are not linked in).
205 // It returns (true, error) when sv was written in expanded format or an error
207 func (tm *TextMarshaler) writeProto3Any(w *textWriter, sv reflect.Value) (bool, error) {
208 turl := sv.FieldByName("TypeUrl")
209 val := sv.FieldByName("Value")
210 if !turl.IsValid() || !val.IsValid() {
211 return true, errors.New("proto: invalid google.protobuf.Any message")
214 b, ok := val.Interface().([]byte)
216 return true, errors.New("proto: invalid google.protobuf.Any message")
219 parts := strings.Split(turl.String(), "/")
220 mt := MessageType(parts[len(parts)-1])
224 m := reflect.New(mt.Elem())
225 if err := Unmarshal(b, m.Interface().(Message)); err != nil {
230 if requiresQuotes(u) {
236 w.Write([]byte("]:<"))
238 w.Write([]byte("]: <\n"))
241 if err := tm.writeStruct(w, m.Elem()); err != nil {
245 w.Write([]byte("> "))
248 w.Write([]byte(">\n"))
253 func (tm *TextMarshaler) writeStruct(w *textWriter, sv reflect.Value) error {
254 if tm.ExpandAny && isAny(sv) {
255 if canExpand, err := tm.writeProto3Any(w, sv); canExpand {
260 sprops := GetProperties(st)
261 for i := 0; i < sv.NumField(); i++ {
263 props := sprops.Prop[i]
264 name := st.Field(i).Name
266 if name == "XXX_NoUnkeyedLiteral" {
270 if strings.HasPrefix(name, "XXX_") {
271 // There are two XXX_ fields:
272 // XXX_unrecognized []byte
273 // XXX_extensions map[int32]proto.Extension
274 // The first is handled here;
275 // the second is handled at the bottom of this function.
276 if name == "XXX_unrecognized" && !fv.IsNil() {
277 if err := writeUnknownStruct(w, fv.Interface().([]byte)); err != nil {
283 if fv.Kind() == reflect.Ptr && fv.IsNil() {
284 // Field not filled in. This could be an optional field or
285 // a required field that wasn't filled in. Either way, there
286 // isn't anything we can show for it.
289 if fv.Kind() == reflect.Slice && fv.IsNil() {
290 // Repeated field that is empty, or a bytes field that is unused.
294 if props.Repeated && fv.Kind() == reflect.Slice {
296 for j := 0; j < fv.Len(); j++ {
297 if err := writeName(w, props); err != nil {
301 if err := w.WriteByte(' '); err != nil {
306 if v.Kind() == reflect.Ptr && v.IsNil() {
307 // A nil message in a repeated field is not valid,
308 // but we can handle that more gracefully than panicking.
309 if _, err := w.Write([]byte("<nil>\n")); err != nil {
314 if err := tm.writeAny(w, v, props); err != nil {
317 if err := w.WriteByte('\n'); err != nil {
323 if fv.Kind() == reflect.Map {
324 // Map fields are rendered as a repeated struct with key/value fields.
326 sort.Sort(mapKeys(keys))
327 for _, key := range keys {
328 val := fv.MapIndex(key)
329 if err := writeName(w, props); err != nil {
333 if err := w.WriteByte(' '); err != nil {
338 if err := w.WriteByte('<'); err != nil {
342 if err := w.WriteByte('\n'); err != nil {
348 if _, err := w.WriteString("key:"); err != nil {
352 if err := w.WriteByte(' '); err != nil {
356 if err := tm.writeAny(w, key, props.MapKeyProp); err != nil {
359 if err := w.WriteByte('\n'); err != nil {
362 // nil values aren't legal, but we can avoid panicking because of them.
363 if val.Kind() != reflect.Ptr || !val.IsNil() {
365 if _, err := w.WriteString("value:"); err != nil {
369 if err := w.WriteByte(' '); err != nil {
373 if err := tm.writeAny(w, val, props.MapValProp); err != nil {
376 if err := w.WriteByte('\n'); err != nil {
382 if err := w.WriteByte('>'); err != nil {
385 if err := w.WriteByte('\n'); err != nil {
391 if props.proto3 && fv.Kind() == reflect.Slice && fv.Len() == 0 {
395 if fv.Kind() != reflect.Ptr && fv.Kind() != reflect.Slice {
396 // proto3 non-repeated scalar field; skip if zero value
397 if isProto3Zero(fv) {
402 if fv.Kind() == reflect.Interface {
403 // Check if it is a oneof.
404 if st.Field(i).Tag.Get("protobuf_oneof") != "" {
405 // fv is nil, or holds a pointer to generated struct.
406 // That generated struct has exactly one field,
407 // which has a protobuf struct tag.
411 inner := fv.Elem().Elem() // interface -> *T -> T
412 tag := inner.Type().Field(0).Tag.Get("protobuf")
413 props = new(Properties) // Overwrite the outer props var, but not its pointee.
415 // Write the value in the oneof, not the oneof itself.
418 // Special case to cope with malformed messages gracefully:
419 // If the value in the oneof is a nil pointer, don't panic
421 if fv.Kind() == reflect.Ptr && fv.IsNil() {
422 // Use errors.New so writeAny won't render quotes.
423 msg := errors.New("/* nil */")
424 fv = reflect.ValueOf(&msg).Elem()
429 if err := writeName(w, props); err != nil {
433 if err := w.WriteByte(' '); err != nil {
438 // Enums have a String method, so writeAny will work fine.
439 if err := tm.writeAny(w, fv, props); err != nil {
443 if err := w.WriteByte('\n'); err != nil {
448 // Extensions (the XXX_extensions field).
450 if _, err := extendable(pv.Interface()); err == nil {
451 if err := tm.writeExtensions(w, pv); err != nil {
459 // writeAny writes an arbitrary field.
460 func (tm *TextMarshaler) writeAny(w *textWriter, v reflect.Value, props *Properties) error {
461 v = reflect.Indirect(v)
463 // Floats have special cases.
464 if v.Kind() == reflect.Float32 || v.Kind() == reflect.Float64 {
468 case math.IsInf(x, 1):
470 case math.IsInf(x, -1):
479 // Other values are handled below.
482 // We don't attempt to serialise every possible value type; only those
483 // that can occur in protocol buffers.
486 // Should only be a []byte; repeated fields are handled in writeStruct.
487 if err := writeString(w, string(v.Bytes())); err != nil {
491 if err := writeString(w, v.String()); err != nil {
495 // Required/optional group/message.
496 var bra, ket byte = '<', '>'
497 if props != nil && props.Wire == "group" {
500 if err := w.WriteByte(bra); err != nil {
504 if err := w.WriteByte('\n'); err != nil {
510 // Calling v.Interface on a struct causes the reflect package to
511 // copy the entire struct. This is racy with the new Marshaler
512 // since we atomically update the XXX_sizecache.
514 // Thus, we retrieve a pointer to the struct if possible to avoid
515 // a race since v.Interface on the pointer doesn't copy the struct.
517 // If v is not addressable, then we are not worried about a race
518 // since it implies that the binary Marshaler cannot possibly be
519 // mutating this value.
522 if etm, ok := v.Interface().(encoding.TextMarshaler); ok {
523 text, err := etm.MarshalText()
527 if _, err = w.Write(text); err != nil {
531 if v.Kind() == reflect.Ptr {
534 if err := tm.writeStruct(w, v); err != nil {
539 if err := w.WriteByte(ket); err != nil {
543 _, err := fmt.Fprint(w, v.Interface())
549 // equivalent to C's isprint.
550 func isprint(c byte) bool {
551 return c >= 0x20 && c < 0x7f
554 // writeString writes a string in the protocol buffer text format.
555 // It is similar to strconv.Quote except we don't use Go escape sequences,
556 // we treat the string as a byte sequence, and we use octal escapes.
557 // These differences are to maintain interoperability with the other
558 // languages' implementations of the text format.
559 func writeString(w *textWriter, s string) error {
560 // use WriteByte here to get any needed indent
561 if err := w.WriteByte('"'); err != nil {
564 // Loop over the bytes, not the runes.
565 for i := 0; i < len(s); i++ {
567 // Divergence from C++: we don't escape apostrophes.
568 // There's no need to escape them, and the C++ parser
569 // copes with a naked apostrophe.
570 switch c := s[i]; c {
572 _, err = w.w.Write(backslashN)
574 _, err = w.w.Write(backslashR)
576 _, err = w.w.Write(backslashT)
578 _, err = w.w.Write(backslashDQ)
580 _, err = w.w.Write(backslashBS)
583 err = w.w.WriteByte(c)
585 _, err = fmt.Fprintf(w.w, "\\%03o", c)
592 return w.WriteByte('"')
595 func writeUnknownStruct(w *textWriter, data []byte) (err error) {
597 if _, err := fmt.Fprintf(w, "/* %d unknown bytes */\n", len(data)); err != nil {
602 for b.index < len(b.buf) {
603 x, err := b.DecodeVarint()
605 _, err := fmt.Fprintf(w, "/* %v */\n", err)
608 wire, tag := x&7, x>>3
609 if wire == WireEndGroup {
611 if _, err := w.Write(endBraceNewline); err != nil {
616 if _, err := fmt.Fprint(w, tag); err != nil {
619 if wire != WireStartGroup {
620 if err := w.WriteByte(':'); err != nil {
624 if !w.compact || wire == WireStartGroup {
625 if err := w.WriteByte(' '); err != nil {
631 buf, e := b.DecodeRawBytes(false)
633 _, err = fmt.Fprintf(w, "%q", buf)
635 _, err = fmt.Fprintf(w, "/* %v */", e)
638 x, err = b.DecodeFixed32()
639 err = writeUnknownInt(w, x, err)
641 x, err = b.DecodeFixed64()
642 err = writeUnknownInt(w, x, err)
644 err = w.WriteByte('{')
647 x, err = b.DecodeVarint()
648 err = writeUnknownInt(w, x, err)
650 _, err = fmt.Fprintf(w, "/* unknown wire type %d */", wire)
655 if err = w.WriteByte('\n'); err != nil {
662 func writeUnknownInt(w *textWriter, x uint64, err error) error {
664 _, err = fmt.Fprint(w, x)
666 _, err = fmt.Fprintf(w, "/* %v */", err)
671 type int32Slice []int32
673 func (s int32Slice) Len() int { return len(s) }
674 func (s int32Slice) Less(i, j int) bool { return s[i] < s[j] }
675 func (s int32Slice) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
677 // writeExtensions writes all the extensions in pv.
678 // pv is assumed to be a pointer to a protocol message struct that is extendable.
679 func (tm *TextMarshaler) writeExtensions(w *textWriter, pv reflect.Value) error {
680 emap := extensionMaps[pv.Type().Elem()]
681 ep, _ := extendable(pv.Interface())
683 // Order the extensions by ID.
684 // This isn't strictly necessary, but it will give us
685 // canonical output, which will also make testing easier.
686 m, mu := ep.extensionsRead()
691 ids := make([]int32, 0, len(m))
693 ids = append(ids, id)
695 sort.Sort(int32Slice(ids))
698 for _, extNum := range ids {
700 var desc *ExtensionDesc
705 // Unknown extension.
706 if err := writeUnknownStruct(w, ext.enc); err != nil {
712 pb, err := GetExtension(ep, desc)
714 return fmt.Errorf("failed getting extension: %v", err)
717 // Repeated extensions will appear as a slice.
718 if !desc.repeated() {
719 if err := tm.writeExtension(w, desc.Name, pb); err != nil {
723 v := reflect.ValueOf(pb)
724 for i := 0; i < v.Len(); i++ {
725 if err := tm.writeExtension(w, desc.Name, v.Index(i).Interface()); err != nil {
734 func (tm *TextMarshaler) writeExtension(w *textWriter, name string, pb interface{}) error {
735 if _, err := fmt.Fprintf(w, "[%s]:", name); err != nil {
739 if err := w.WriteByte(' '); err != nil {
743 if err := tm.writeAny(w, reflect.ValueOf(pb), nil); err != nil {
746 if err := w.WriteByte('\n'); err != nil {
752 func (w *textWriter) writeIndent() {
762 w.w.Write(spaces[:n])
768 // TextMarshaler is a configurable text format marshaler.
769 type TextMarshaler struct {
770 Compact bool // use compact text format (one line).
771 ExpandAny bool // expand google.protobuf.Any messages of known types
774 // Marshal writes a given protocol buffer in text format.
775 // The only errors returned are from w.
776 func (tm *TextMarshaler) Marshal(w io.Writer, pb Message) error {
777 val := reflect.ValueOf(pb)
778 if pb == nil || val.IsNil() {
779 w.Write([]byte("<nil>"))
785 bw = bufio.NewWriter(w)
794 if etm, ok := pb.(encoding.TextMarshaler); ok {
795 text, err := etm.MarshalText()
799 if _, err = aw.Write(text); err != nil {
807 // Dereference the received pointer so we don't have outer < and >.
808 v := reflect.Indirect(val)
809 if err := tm.writeStruct(aw, v); err != nil {
818 // Text is the same as Marshal, but returns the string directly.
819 func (tm *TextMarshaler) Text(pb Message) string {
826 defaultTextMarshaler = TextMarshaler{}
827 compactTextMarshaler = TextMarshaler{Compact: true}
830 // TODO: consider removing some of the Marshal functions below.
832 // MarshalText writes a given protocol buffer in text format.
833 // The only errors returned are from w.
834 func MarshalText(w io.Writer, pb Message) error { return defaultTextMarshaler.Marshal(w, pb) }
836 // MarshalTextString is the same as MarshalText, but returns the string directly.
837 func MarshalTextString(pb Message) string { return defaultTextMarshaler.Text(pb) }
839 // CompactText writes a given protocol buffer in compact text format (one line).
840 func CompactText(w io.Writer, pb Message) error { return compactTextMarshaler.Marshal(w, pb) }
842 // CompactTextString is the same as CompactText, but returns the string directly.
843 func CompactTextString(pb Message) string { return compactTextMarshaler.Text(pb) }