code review 5574053: encoding/xml: bring API closer to other packages

src/pkg/encoding/xml/marshal.go

 // Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 package xml
 
 import (
         "bufio"
         "bytes"
         "fmt"
         "io"
         "reflect"
         "strconv"
         "strings"
 )
 
 const (
         // A generic XML header suitable for use with the output of Marshal.
         // This is not automatically added to any output of this package,
         // it is provided as a convenience.
         Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n"
 )
 
 // A Marshaler can produce well-formatted XML representing its internal state.
 type Marshaler interface {
         MarshalXML() ([]byte, error)
 }
 
-type printer struct {
-        *bufio.Writer
-}
-
-// Marshal writes an XML-formatted representation of v to w.
+// Marshal returns the XML encoding of v.
 //
 // If v implements Marshaler, then Marshal calls its MarshalXML method.
 // Otherwise, Marshal uses the following procedure to create the XML.
 //
 // Marshal handles an array or slice by marshalling each of the elements.
 // Marshal handles a pointer by marshalling the value it points at or, if the
 // pointer is nil, by writing nothing.  Marshal handles an interface value by
 // marshalling the value it contains or, if the interface value is nil, by
 // writing nothing.  Marshal handles all other data by writing one or more XML
 // elements containing the data.
@@ skipping 25 matching lines @@
 // the same parent will be enclosed in one XML element.  For example:
 //
 //      type Result struct {
 //              XMLName   xml.Name `xml:"result"`
 //              Id        int      `xml:"id,attr"`
 //              FirstName string   `xml:"person>name>first"`
 //              LastName  string   `xml:"person>name>last"`
 //              Age       int      `xml:"person>age"`
 //      }
 //
-//      xml.Marshal(w, &Result{Id: 13, FirstName: "John", LastName: "Doe", Age: 42})
+//      xml.Marshal(&Result{Id: 13, FirstName: "John", LastName: "Doe", Age: 42})
 //
 // would be marshalled as:
 //
 //      <result>
 //              <person id="13">
 //                      <name>
 //                              <first>John</first>
 //                              <last>Doe</last>
 //                      </name>
 //                      <age>42</age>
 //              </person>
 //      </result>
 //
 // Marshal will return an error if asked to marshal a channel, function, or map.
-func Marshal(w io.Writer, v interface{}) (err error) {
-        p := &printer{bufio.NewWriter(w)}
-        err = p.marshalValue(reflect.ValueOf(v), nil)
-        p.Flush()
+func Marshal(v interface{}) ([]byte, error) {
+        var b bytes.Buffer
+        if err := NewEncoder(&b).Encode(v); err != nil {
+                return nil, err
+        }
+        return b.Bytes(), nil
+}
+
+// An Encoder writes XML data to an output stream.
+type Encoder struct {
+        printer
+}
+
+// NewEncoder returns a new encoder that writes to w.
+func NewEncoder(w io.Writer) *Encoder {
+        return &Encoder{printer{bufio.NewWriter(w)}}
+}
+
+// Encode writes the XML encoding of v to the stream.
+//
+// See the documentation for Marshal for details about the conversion
+// of Go values to XML.
+func (enc *Encoder) Encode(v interface{}) error {
+        err := enc.marshalValue(reflect.ValueOf(v), nil)
+        enc.Flush()
         return err
 }
 
+type printer struct {
+        *bufio.Writer
+}
+
 func (p *printer) marshalValue(val reflect.Value, finfo *fieldInfo) error {
         if !val.IsValid() {
                 return nil
         }
 
         kind := val.Kind()
         typ := val.Type()
 
         // Try Marshaler
         if typ.NumMethod() > 0 {
@@ skipping 258 matching lines @@
 
 // A MarshalXMLError is returned when Marshal encounters a type
 // that cannot be converted into XML.
 type UnsupportedTypeError struct {
         Type reflect.Type
 }
 
 func (e *UnsupportedTypeError) Error() string {
         return "xml: unsupported type: " + e.Type.String()
 }