Add T.TODO() to return a child state

The spec [1] suggests "not ok 13 # TODO ...", but if you attempt this
with:

  t.Fail("# TODO foo")

you get an extra hyphen ("not ok 13 - # TODO foo") which is parsed as
a failed test (and not a TODO test).

I'd initially written up an alternative to Ok:

  T.TODO(test bool, description string)

but Michael pointed out that future work may add additional test
methods (e.g. EqOk) and wanted to support those as well with something
like [2]:

  t.TODO = true
  t.Ok(Foo(), "foo")
  t.EqOk(Bar(), Baz(), "bar == baz")
  t.TODO = false  // could be done via defer too

or [2]:

  t.TODO( func () {
    t.Ok(Foo(), "foo")
    t.EqOk(Bar(), Baz(), "bar == baz")
  })

The child-state approach taken in this commit is closer to the latter,
but allows for method chaining in the single-test case:

  t.TODO().Ok(Foo(), "foo")

which I find easier to read.

The root state is the only one which holds nextTestNumber.  It might
make more sense if it was *also* the only the state that held Writer
(so internally t.root().printf(...) instead of t.printf(...)).
However, Writer is public, and we can't keep folks from fiddling with
it.  Respecting local overrides makes as much sense as anything,
although I doubt folks will want to override Writer in their TODO
child state.

[1]: http://testanything.org/tap-version-13-specification.html#todo-tests
[2]: #6 (comment)

Author: wking

Makefile

@@ -1,4 +1,4 @@
-TESTS = auto check diagnostic failing known skip writer
+TESTS = auto check diagnostic failing known skip todo writer
 GOPATH = $(CURDIR)/gopath
 
 .PHONY: $(TESTS)

tap.go

@@ -31,7 +31,9 @@ import "testing/quick"
 // T is a type to encapsulate test state.  Methods on this type generate TAP
 // output.
 type T struct {
-	nextTestNumber int
+	parent         *T
+	nextTestNumber int  // only tracked on the root T instance
+	todo           bool
 
 	// Writer indicates where TAP output should be sent.  The default is os.Stdout.
 	Writer io.Writer
@@ -44,6 +46,13 @@ func New() *T {
 	}
 }
 
+func (t *T) root() *T {
+	if t.parent == nil {
+		return t
+	}
+	return t.parent.root()
+}
+
 func (t *T) w() io.Writer {
 	if t.Writer == nil {
 		return os.Stdout
@@ -74,8 +83,13 @@ func (t *T) Ok(test bool, description string) {
 		ok = "not ok"
 	}
 
-	t.printf("%s %d - %s\n", ok, t.nextTestNumber, description)
-	t.nextTestNumber++
+	root := t.root()
+	if t.todo {
+		t.printf("%s %d # TODO %s\n", ok, root.nextTestNumber, description)
+	} else {
+		t.printf("%s %d - %s\n", ok, root.nextTestNumber, description)
+	}
+	root.nextTestNumber++
 }
 
 // Fail indicates that a test has failed.  This is typically only used when the
@@ -105,7 +119,7 @@ func (t *T) Check(function interface{}, description string) {
 
 // Count returns the number of tests completed so far.
 func (t *T) Count() int {
-	return t.nextTestNumber - 1
+	return t.root().nextTestNumber - 1
 }
 
 // AutoPlan generates a test plan based on the number of tests that were run.
@@ -117,11 +131,22 @@ func escapeNewlines(s string) string {
 	return strings.Replace(strings.TrimRight(s, "\n"), "\n", "\n# ", -1)
 }
 
+// TODO returns a test-state which uses a TODO directive for Ok, Fail,
+// Pass, and similar.
+func (t *T) TODO() *T {
+	return &T{
+		parent: t,
+		todo: true,
+		Writer: t.Writer,
+	}
+}
+
 // Skip indicates that a test has been skipped.
 func (t *T) Skip(count int, description string) {
+	root := t.root()
 	for i := 0; i < count; i++ {
-		t.printf("ok %d # SKIP %s\n", t.nextTestNumber, description)
-		t.nextTestNumber++
+		t.printf("ok %d # SKIP %s\n", root.nextTestNumber, description)
+		root.nextTestNumber++
 	}
 }
 

test/todo/main.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"os"
+
+	tap "github.com/mndrix/tap-go"
+)
+
+func main() {
+	// collect output for comparison later
+	buf := new(bytes.Buffer)
+	t := tap.New()
+	t.Writer = io.MultiWriter(os.Stdout, buf)
+
+	t.Header(5)
+	todo := t.TODO()
+	todo.Ok(false, "bend space and time")
+	todo.Fail("bend space and time further")
+
+	buf2 := new(bytes.Buffer)
+	todo.Writer = io.MultiWriter(os.Stdout, buf2)
+	todo.Fail("use another writer")
+
+	got := buf.String()
+	t.Ok(got == expected, "TODO gave expected output via the root writer")
+
+	got = buf2.String()
+	t.Ok(got == "not ok 3 # TODO use another writer\n", "TODO gave expected output via a child writer")
+}
+
+const expected = `TAP version 13
+1..5
+not ok 1 # TODO bend space and time
+not ok 2 # TODO bend space and time further
+`