Replace DebugString with Describe

This change makes tree description completely open to mechanical
analysis and ensures consistency between description formats for each of
the iterator types.

Renamed StatsContainer.(Kind -> Type) for consistency.

graph/bolt/all_iterator.go

@@ -17,7 +17,6 @@ package bolt
 import (
 	"bytes"
 	"fmt"
-	"strings"
 
 	"github.com/barakmich/glog"
 	"github.com/boltdb/bolt"
@@ -179,9 +178,15 @@ func (it *AllIterator) Size() (int64, bool) {
 	return it.qs.size, true
 }
 
-func (it *AllIterator) DebugString(indent int) string {
+func (it *AllIterator) Describe() graph.Description {
 	size, _ := it.Size()
-	return fmt.Sprintf("%s(%s tags: %v bolt size:%d %s %p)", strings.Repeat(" ", indent), it.Type(), it.tags.Tags(), size, it.dir, it)
+	return graph.Description{
+		UID:       it.UID(),
+		Type:      it.Type().String(),
+		Tags:      it.tags.Tags(),
+		Size:      size,
+		Direction: it.dir,
+	}
 }
 
 func (it *AllIterator) Type() graph.Type { return graph.All }

graph/bolt/iterator.go

@@ -19,7 +19,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"strings"
 
 	"github.com/barakmich/glog"
 	"github.com/boltdb/bolt"
@@ -291,16 +290,15 @@ func (it *Iterator) Size() (int64, bool) {
 	return it.size, true
 }
 
-func (it *Iterator) DebugString(indent int) string {
+func (it *Iterator) Describe() graph.Description {
-	return fmt.Sprintf("%s(%s %d tags: %v dir: %s size:%d %s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:       it.UID(),
-		it.Type(),
+		Name:      it.qs.NameOf(&Token{it.bucket, it.checkID}),
-		it.UID(),
+		Type:      it.Type().String(),
-		it.tags.Tags(),
+		Tags:      it.tags.Tags(),
-		it.dir,
+		Size:      it.size,
-		it.size,
+		Direction: it.dir,
-		it.qs.NameOf(&Token{it.bucket, it.checkID}),
+	}
-	)
 }
 
 func (it *Iterator) Type() graph.Type { return boltType }

graph/iterator.go

@@ -17,6 +17,7 @@ package graph
 // Define the general iterator interface.
 
 import (
+	"github.com/google/cayley/quad"
 	"strings"
 	"sync"
 
@@ -130,8 +131,8 @@ type Iterator interface {
 	// Return a slice of the subiterators for this iterator.
 	SubIterators() []Iterator
 
-	// Return a string representation of the iterator, indented by the given amount.
+	// Return a string representation of the iterator.
-	DebugString(int) string
+	Describe() Description
 
 	// Close the iterator and do internal cleanup.
 	Close()
@@ -140,6 +141,17 @@ type Iterator interface {
 	UID() uint64
 }
 
+type Description struct {
+	UID       uint64         `json:",omitempty"`
+	Name      string         `json:",omitempty"`
+	Type      string         `json:",omitempty"`
+	Tags      []string       `json:",omitempty"`
+	Size      int64          `json:",omitempty"`
+	Direction quad.Direction `json:",omitempty"`
+	Iterator  *Description   `json:",omitempty"`
+	Iterators []Description  `json:",omitempty"`
+}
+
 type Nexter interface {
 	// Next advances the iterator to the next value, which will then be available through
 	// the Result method. It returns false if no further advancement is possible.
@@ -256,16 +268,16 @@ func (t Type) String() string {
 }
 
 type StatsContainer struct {
+	UID  uint64
+	Type string
 	IteratorStats
-	Kind   string
-	UID    uint64
 	SubIts []StatsContainer
 }
 
 func DumpStats(it Iterator) StatsContainer {
 	var out StatsContainer
 	out.IteratorStats = it.Stats()
-	out.Kind = it.Type().String()
+	out.Type = it.Type().String()
 	out.UID = it.UID()
 	for _, sub := range it.SubIterators() {
 		out.SubIts = append(out.SubIts, DumpStats(sub))

graph/iterator/all_iterator.go

@@ -23,9 +23,6 @@ package iterator
 // the base iterators, and it helps just to see it here.
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/google/cayley/graph"
 )
 
@@ -81,9 +78,12 @@ func (it *Int64) TagResults(dst map[string]graph.Value) {
 	}
 }
 
-// Prints the All iterator as just an "all".
+func (it *Int64) Describe() graph.Description {
-func (it *Int64) DebugString(indent int) string {
+	return graph.Description{
-	return fmt.Sprintf("%s(%s tags: %v)", strings.Repeat(" ", indent), it.Type(), it.tags.Tags())
+		UID:  it.UID(),
+		Type: it.Type().String(),
+		Tags: it.tags.Tags(),
+	}
 }
 
 // Next() on an Int64 all iterator is a simple incrementing counter.

graph/iterator/and_iterator.go

@@ -16,9 +16,6 @@
 package iterator
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/google/cayley/graph"
 )
 
@@ -111,30 +108,19 @@ func (it *And) ResultTree() *graph.ResultTree {
 	return tree
 }
 
-// Prints information about this iterator.
+func (it *And) Describe() graph.Description {
-func (it *And) DebugString(indent int) string {
+	subIts := make([]graph.Description, len(it.internalIterators))
-	var total string
 	for i, sub := range it.internalIterators {
-		total += strings.Repeat(" ", indent+2)
+		subIts[i] = sub.Describe()
-		total += fmt.Sprintf("%d:\n%s\n", i, sub.DebugString(indent+4))
 	}
-	var tags string
+	primary := it.primaryIt.Describe()
-	for _, k := range it.tags.Tags() {
+	return graph.Description{
-		tags += fmt.Sprintf("%s;", k)
+		UID:       it.UID(),
+		Type:      it.Type().String(),
+		Tags:      it.tags.Tags(),
+		Iterator:  &primary,
+		Iterators: subIts,
 	}
-	spaces := strings.Repeat(" ", indent+2)
-
-	return fmt.Sprintf("%s(%s %d\n%stags:%s\n%sprimary_it:\n%s\n%sother_its:\n%s)",
-		strings.Repeat(" ", indent),
-		it.Type(),
-		it.UID(),
-		spaces,
-		tags,
-		spaces,
-		it.primaryIt.DebugString(indent+4),
-		spaces,
-		total,
-	)
 }
 
 // Add a subiterator to this And iterator.

graph/iterator/fixed_iterator.go

@@ -22,7 +22,7 @@ package iterator
 
 import (
 	"fmt"
-	"strings"
+	"sort"
 
 	"github.com/google/cayley/graph"
 )
@@ -94,20 +94,23 @@ func (it *Fixed) Add(v graph.Value) {
 	it.values = append(it.values, v)
 }
 
-// Print some information about the iterator.
+func (it *Fixed) Describe() graph.Description {
-func (it *Fixed) DebugString(indent int) string {
+	var value string
-	value := ""
 	if len(it.values) > 0 {
 		value = fmt.Sprint(it.values[0])
 	}
-	return fmt.Sprintf("%s(%s %d tags: %s Size: %d id0: %s)",
+	fixed := make([]string, 0, len(it.tags.Fixed()))
-		strings.Repeat(" ", indent),
+	for k := range it.tags.Fixed() {
-		it.Type(),
+		fixed = append(fixed, k)
-		it.UID(),
+	}
-		it.tags.Fixed(),
+	sort.Strings(fixed)
-		len(it.values),
+	return graph.Description{
-		value,
+		UID:  it.UID(),
-	)
+		Name: value,
+		Type: it.Type().String(),
+		Tags: fixed,
+		Size: int64(len(it.values)),
+	}
 }
 
 // Register this iterator as a Fixed iterator.

graph/iterator/hasa_iterator.go

@@ -34,9 +34,6 @@ package iterator
 // Alternatively, can be seen as the dual of the LinksTo iterator.
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/barakmich/glog"
 
 	"github.com/google/cayley/graph"
@@ -130,13 +127,15 @@ func (it *HasA) ResultTree() *graph.ResultTree {
 	return tree
 }
 
-// Print some information about this iterator.
+func (it *HasA) Describe() graph.Description {
-func (it *HasA) DebugString(indent int) string {
+	primary := it.primaryIt.Describe()
-	var tags string
+	return graph.Description{
-	for _, k := range it.tags.Tags() {
+		UID:       it.UID(),
-		tags += fmt.Sprintf("%s;", k)
+		Type:      it.Type().String(),
+		Tags:      it.tags.Tags(),
+		Direction: it.dir,
+		Iterator:  &primary,
 	}
-	return fmt.Sprintf("%s(%s %d tags:%s direction:%s\n%s)", strings.Repeat(" ", indent), it.Type(), it.UID(), tags, it.dir, it.primaryIt.DebugString(indent+4))
 }
 
 // Check a value against our internal iterator. In order to do this, we must first open a new

graph/iterator/iterator.go

@@ -17,7 +17,6 @@ package iterator
 // Define the general iterator interface.
 
 import (
-	"strings"
 	"sync/atomic"
 
 	"github.com/google/cayley/graph"
@@ -78,9 +77,11 @@ func (it *Null) Type() graph.Type { return graph.Null }
 // Null has nothing it needs to do.
 func (it *Null) Optimize() (graph.Iterator, bool) { return it, false }
 
-// Print the null iterator.
+func (it *Null) Describe() graph.Description {
-func (it *Null) DebugString(indent int) string {
+	return graph.Description{
-	return strings.Repeat(" ", indent) + "(null)"
+		UID:  it.UID(),
+		Type: it.Type().String(),
+	}
 }
 
 func (it *Null) Next() bool {

graph/iterator/linksto_iterator.go

@@ -30,9 +30,6 @@ package iterator
 // Can be seen as the dual of the HasA iterator.
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/google/cayley/graph"
 	"github.com/google/cayley/quad"
 )
@@ -108,11 +105,14 @@ func (it *LinksTo) ResultTree() *graph.ResultTree {
 	return tree
 }
 
-// Print the iterator.
+func (it *LinksTo) Describe() graph.Description {
-func (it *LinksTo) DebugString(indent int) string {
+	primary := it.primaryIt.Describe()
-	return fmt.Sprintf("%s(%s %d direction:%s\n%s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:       it.UID(),
-		it.Type(), it.UID(), it.dir, it.primaryIt.DebugString(indent+4))
+		Type:      it.Type().String(),
+		Direction: it.dir,
+		Iterator:  &primary,
+	}
 }
 
 // If it checks in the right direction for the subiterator, it is a valid link

graph/iterator/materialize_iterator.go

@@ -17,9 +17,6 @@ package iterator
 // A simple iterator that, when first called Contains() or Next() upon, materializes the whole subiterator, stores it locally, and responds. Essentially a cache.
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/barakmich/glog"
 
 	"github.com/google/cayley/graph"
@@ -118,15 +115,15 @@ func (it *Materialize) Clone() graph.Iterator {
 	return out
 }
 
-// Print some information about the iterator.
+func (it *Materialize) Describe() graph.Description {
-func (it *Materialize) DebugString(indent int) string {
+	primary := it.subIt.Describe()
-	return fmt.Sprintf("%s(%s tags: %s Size: %d\n%s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:      it.UID(),
-		it.Type(),
+		Type:     it.Type().String(),
-		it.tags.Tags(),
+		Tags:     it.tags.Tags(),
-		len(it.values),
+		Size:     int64(len(it.values)),
-		it.subIt.DebugString(indent+4),
+		Iterator: &primary,
-	)
+	}
 }
 
 // Register this iterator as a Materialize iterator.

graph/iterator/optional_iterator.go

@@ -27,9 +27,6 @@ package iterator
 // -- all things in the graph. It matches everything (as does the regex "(a)?")
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/google/cayley/graph"
 )
 
@@ -120,13 +117,14 @@ func (it *Optional) TagResults(dst map[string]graph.Value) {
 // Registers the optional iterator.
 func (it *Optional) Type() graph.Type { return graph.Optional }
 
-// Prints the optional and it's subiterator.
+func (it *Optional) Describe() graph.Description {
-func (it *Optional) DebugString(indent int) string {
+	primary := it.subIt.Describe()
-	return fmt.Sprintf("%s(%s tags:%s\n%s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:      it.UID(),
-		it.Type(),
+		Type:     it.Type().String(),
-		it.tags.Tags(),
+		Tags:     it.tags.Tags(),
-		it.subIt.DebugString(indent+4))
+		Iterator: &primary,
+	}
 }
 
 // There's nothing to optimize for an optional. Optimize the subiterator and

graph/iterator/or_iterator.go

@@ -22,9 +22,6 @@ package iterator
 // May return the same value twice -- once for each branch.
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/google/cayley/graph"
 )
 
@@ -113,26 +110,17 @@ func (it *Or) ResultTree() *graph.ResultTree {
 	return tree
 }
 
-// Prints information about this graph.iterator.
+func (it *Or) Describe() graph.Description {
-func (it *Or) DebugString(indent int) string {
+	var subIts []graph.Description
-	var total string
 	for i, sub := range it.internalIterators {
-		total += strings.Repeat(" ", indent+2)
+		subIts[i] = sub.Describe()
-		total += fmt.Sprintf("%d:\n%s\n", i, sub.DebugString(indent+4))
 	}
-	var tags string
+	return graph.Description{
-	for _, k := range it.tags.Tags() {
+		UID:       it.UID(),
-		tags += fmt.Sprintf("%s;", k)
+		Type:      it.Type().String(),
+		Tags:      it.tags.Tags(),
+		Iterators: subIts,
 	}
-	spaces := strings.Repeat(" ", indent+2)
-
-	return fmt.Sprintf("%s(%s\n%stags:%s\n%sits:\n%s)",
-		strings.Repeat(" ", indent),
-		it.Type(),
-		spaces,
-		tags,
-		spaces,
-		total)
 }
 
 // Add a subiterator to this Or graph.iterator. Order matters.

graph/iterator/value_comparison_iterator.go

@@ -27,10 +27,8 @@ package iterator
 // In MQL terms, this is the [{"age>=": 21}] concept.
 
 import (
-	"fmt"
 	"log"
 	"strconv"
-	"strings"
 
 	"github.com/google/cayley/graph"
 )
@@ -190,11 +188,13 @@ func (it *Comparison) TagResults(dst map[string]graph.Value) {
 // Registers the value-comparison iterator.
 func (it *Comparison) Type() graph.Type { return graph.Comparison }
 
-// Prints the value-comparison and its subiterator.
+func (it *Comparison) Describe() graph.Description {
-func (it *Comparison) DebugString(indent int) string {
+	primary := it.subIt.Describe()
-	return fmt.Sprintf("%s(%s\n%s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:      it.UID(),
-		it.Type(), it.subIt.DebugString(indent+4))
+		Type:     it.Type().String(),
+		Iterator: &primary,
+	}
 }
 
 // There's nothing to optimize, locally, for a value-comparison iterator.

graph/leveldb/all_iterator.go

@@ -16,8 +16,6 @@ package leveldb
 
 import (
 	"bytes"
-	"fmt"
-	"strings"
 
 	ldbit "github.com/syndtr/goleveldb/leveldb/iterator"
 	"github.com/syndtr/goleveldb/leveldb/opt"
@@ -159,9 +157,15 @@ func (it *AllIterator) Size() (int64, bool) {
 	return int64(^uint64(0) >> 1), false
 }
 
-func (it *AllIterator) DebugString(indent int) string {
+func (it *AllIterator) Describe() graph.Description {
 	size, _ := it.Size()
-	return fmt.Sprintf("%s(%s tags: %v leveldb size:%d %s %p)", strings.Repeat(" ", indent), it.Type(), it.tags.Tags(), size, it.dir, it)
+	return graph.Description{
+		UID:       it.UID(),
+		Type:      it.Type().String(),
+		Tags:      it.tags.Tags(),
+		Size:      size,
+		Direction: it.dir,
+	}
 }
 
 func (it *AllIterator) Type() graph.Type { return graph.All }

graph/leveldb/iterator.go

@@ -17,8 +17,6 @@ package leveldb
 import (
 	"bytes"
 	"encoding/json"
-	"fmt"
-	"strings"
 
 	"github.com/barakmich/glog"
 	ldbit "github.com/syndtr/goleveldb/leveldb/iterator"
@@ -250,17 +248,16 @@ func (it *Iterator) Size() (int64, bool) {
 	return it.qs.SizeOf(Token(it.checkID)), true
 }
 
-func (it *Iterator) DebugString(indent int) string {
+func (it *Iterator) Describe() graph.Description {
 	size, _ := it.Size()
-	return fmt.Sprintf("%s(%s %d tags: %v dir: %s size:%d %s)",
+	return graph.Description{
-		strings.Repeat(" ", indent),
+		UID:       it.UID(),
-		it.Type(),
+		Name:      it.qs.NameOf(Token(it.checkID)),
-		it.UID(),
+		Type:      it.Type().String(),
-		it.tags.Tags(),
+		Tags:      it.tags.Tags(),
-		it.dir,
+		Size:      size,
-		size,
+		Direction: it.dir,
-		it.qs.NameOf(Token(it.checkID)),
+	}
-	)
 }
 
 var levelDBType graph.Type

graph/memstore/iterator.go

@@ -15,9 +15,7 @@
 package memstore
 
 import (
-	"fmt"
 	"math"
-	"strings"
 
 	"github.com/google/cayley/graph"
 	"github.com/google/cayley/graph/iterator"
@@ -159,9 +157,15 @@ func (it *Iterator) Contains(v graph.Value) bool {
 	return graph.ContainsLogOut(it, v, false)
 }
 
-func (it *Iterator) DebugString(indent int) string {
+func (it *Iterator) Describe() graph.Description {
 	size, _ := it.Size()
-	return fmt.Sprintf("%s(%s tags:%s size:%d %s)", strings.Repeat(" ", indent), it.Type(), it.tags.Tags(), size, it.data)
+	return graph.Description{
+		UID:  it.UID(),
+		Name: it.data,
+		Type: it.Type().String(),
+		Tags: it.tags.Tags(),
+		Size: size,
+	}
 }
 
 var memType graph.Type

graph/memstore/quadstore_test.go

@@ -165,8 +165,11 @@ func TestLinksToOptimization(t *testing.T) {
 
 	v := newIt.(*Iterator)
 	vClone := v.Clone()
-	if vClone.DebugString(0) != v.DebugString(0) {
+	origDesc := v.Describe()
-		t.Fatal("Wrong iterator. Got ", vClone.DebugString(0))
+	cloneDesc := vClone.Describe()
+	origDesc.UID, cloneDesc.UID = 0, 0 // We are more strict now, so fake UID equality.
+	if !reflect.DeepEqual(cloneDesc, origDesc) {
+		t.Fatalf("Unexpected iterator description.\ngot: %#v\nexpect: %#v", cloneDesc, origDesc)
 	}
 	vt := vClone.Tagger()
 	if len(vt.Tags()) < 1 || vt.Tags()[0] != "foo" {

graph/mongo/iterator.go

@@ -16,7 +16,6 @@ package mongo
 
 import (
 	"fmt"
-	"strings"
 
 	"github.com/barakmich/glog"
 	"gopkg.in/mgo.v2"
@@ -213,9 +212,14 @@ func (it *Iterator) Type() graph.Type {
 func (it *Iterator) Sorted() bool                     { return true }
 func (it *Iterator) Optimize() (graph.Iterator, bool) { return it, false }
 
-func (it *Iterator) DebugString(indent int) string {
+func (it *Iterator) Describe() graph.Description {
 	size, _ := it.Size()
-	return fmt.Sprintf("%s(%s size:%d %s %s)", strings.Repeat(" ", indent), it.Type(), size, it.hash, it.name)
+	return graph.Description{
+		UID:  it.UID(),
+		Name: fmt.Sprintf("%s/%s", it.name, it.hash),
+		Type: it.Type().String(),
+		Size: size,
+	}
 }
 
 func (it *Iterator) Stats() graph.IteratorStats {

query/gremlin/finals.go

@@ -208,7 +208,14 @@ func (wk *worker) runIteratorToArrayNoTags(it graph.Iterator, limit int) []strin
 func (wk *worker) runIteratorWithCallback(it graph.Iterator, callback otto.Value, this otto.FunctionCall, limit int) {
 	n := 0
 	it, _ = it.Optimize()
-	glog.V(2).Infoln(it.DebugString(0))
+	if glog.V(2) {
+		b, err := json.MarshalIndent(it.Describe(), "", "  ")
+		if err != nil {
+			glog.V(2).Infof("failed to format description: %v", err)
+		} else {
+			glog.V(2).Infof("%s", b)
+		}
+	}
 	for {
 		select {
 		case <-wk.kill:
@@ -271,7 +278,14 @@ func (wk *worker) runIterator(it graph.Iterator) {
 		return
 	}
 	it, _ = it.Optimize()
-	glog.V(2).Infoln(it.DebugString(0))
+	if glog.V(2) {
+		b, err := json.MarshalIndent(it.Describe(), "", "  ")
+		if err != nil {
+			glog.Infof("failed to format description: %v", err)
+		} else {
+			glog.Infof("%s", b)
+		}
+	}
 	for {
 		select {
 		case <-wk.kill:

query/mql/session.go

@@ -85,7 +85,12 @@ func (s *Session) ExecInput(input string, c chan interface{}, _ int) {
 	}
 	it, _ := s.currentQuery.it.Optimize()
 	if glog.V(2) {
-		glog.V(2).Infoln(it.DebugString(0))
+		b, err := json.MarshalIndent(it.Describe(), "", "  ")
+		if err != nil {
+			glog.Infof("failed to format description: %v", err)
+		} else {
+			glog.Infof("%s", b)
+		}
 	}
 	for graph.Next(it) {
 		tags := make(map[string]graph.Value)

query/sexp/parser_test.go

@@ -89,7 +89,7 @@ func TestTreeConstraintParse(t *testing.T) {
 		"($a (:is :good))))"
 	it := BuildIteratorTreeForQuery(qs, query)
 	if it.Type() != graph.And {
-		t.Errorf("Odd iterator tree. Got: %s", it.DebugString(0))
+		t.Errorf("Odd iterator tree. Got: %#v", it.Describe())
 	}
 	if !graph.Next(it) {
 		t.Error("Got no results")
@@ -137,7 +137,7 @@ func TestMultipleConstraintParse(t *testing.T) {
 	)`
 	it := BuildIteratorTreeForQuery(qs, query)
 	if it.Type() != graph.And {
-		t.Errorf("Odd iterator tree. Got: %s", it.DebugString(0))
+		t.Errorf("Odd iterator tree. Got: %#v", it.Describe())
 	}
 	if !graph.Next(it) {
 		t.Error("Got no results")

query/sexp/session.go

@@ -17,6 +17,7 @@ package sexp
 // Defines a running session of the sexp query language.
 
 import (
+	"encoding/json"
 	"errors"
 	"fmt"
 	"sort"
@@ -74,7 +75,12 @@ func (s *Session) ExecInput(input string, out chan interface{}, limit int) {
 	}
 
 	if s.debug {
-		fmt.Println(it.DebugString(0))
+		b, err := json.MarshalIndent(it.Describe(), "", "  ")
+		if err != nil {
+			fmt.Printf("failed to format description: %v", err)
+		} else {
+			fmt.Printf("%s", b)
+		}
 	}
 	nResults := 0
 	for graph.Next(it) {