zclwrite: begin to flesh out public interface

zclwrite/ast.go

@@ -1,6 +1,9 @@
 package zclwrite
 
-import "io"
+import (
+	"bytes"
+	"io"
+)
 
 type Node interface {
 	walkChildNodes(w internalWalkFunc)
@@ -10,18 +13,36 @@ type Node interface {
 type internalWalkFunc func(Node)
 
 type File struct {
-	Name  string
-	Bytes []byte
+	Name     string
+	SrcBytes []byte
 
 	Body *Body
 }
 
+// WriteTo writes the tokens underlying the receiving file to the given writer.
 func (f *File) WriteTo(wr io.Writer) (int, error) {
 	return f.Body.AllTokens.WriteTo(wr)
 }
 
+// Bytes returns a buffer containing the source code resulting from the
+// tokens underlying the receiving file. If any updates have been made via
+// the AST API, these will be reflected in the result.
+func (f *File) Bytes() []byte {
+	buf := &bytes.Buffer{}
+	f.WriteTo(buf)
+	return buf.Bytes()
+}
+
+// Format makes in-place modifications to the tokens underlying the receiving
+// file in order to change the whitespace to be in canonical form.
+func (f *File) Format() {
+	format(f.Body.AllTokens.Tokens())
+}
+
 type Body struct {
 	// Items may contain Attribute, Block and Unstructured instances.
+	// Items and AllTokens should be updated only by methods of this type,
+	// since they must be kept synchronized for correct operation.
 	Items     []Node
 	AllTokens *TokenSeq
 

zclwrite/format.go

@@ -0,0 +1,7 @@
+package zclwrite
+
+// format rewrites tokens within the given sequence, in-place, to adjust the
+// whitespace around their content to achieve canonical formatting.
+func format(tokens Tokens) {
+	// currently does nothing
+}

zclwrite/parser.go

@@ -53,8 +53,8 @@ func parse(src []byte, filename string, start zcl.Pos) (*File, zcl.Diagnostics)
 	_, root, _ := parseBody(file.Body.(*zclsyntax.Body), from)
 
 	return &File{
-		Name:  filename,
-		Bytes: src,
+		Name:     filename,
+		SrcBytes: src,
 
 		Body: root,
 	}, nil

zclwrite/public.go

@@ -0,0 +1,30 @@
+package zclwrite
+
+import (
+	"bytes"
+
+	"github.com/zclconf/go-zcl/zcl"
+)
+
+// Parse interprets the given source bytes into a writer AST. The resulting AST
+// can be used to perform surgical edits on the source code before turning
+// it back into bytes again.
+func Parse(src []byte, filename string, start zcl.Pos) (*File, zcl.Diagnostics) {
+	return parse(src, filename, start)
+}
+
+// Format takes source code and performs simple whitespace changes to transform
+// it to a canonical layout style.
+//
+// Format skips constructing an AST and works directly with tokens, so it
+// is less expensive than formatting via the AST for situations where no other
+// changes will be made. It also ignores syntax errors and can thus be applied
+// to partial source code, although the result in that case may not be
+// desirable.
+func Format(src []byte) []byte {
+	tokens := lexConfig(src)
+	format(tokens)
+	buf := &bytes.Buffer{}
+	(&TokenSeq{tokens}).WriteTo(buf)
+	return buf.Bytes()
+}