Merge pull request #72 from clipperhouse/v4

v4

Author: clipperhouse

.gitignore

@@ -5,3 +5,5 @@ coverage.out
 *_bar_test.go
 *_foo.go
 *_foo_test.go
+
+_site/*

CHANGELOG.md

@@ -1,4 +1,87 @@
-###28 Jun 2014
+###30 Nov 2014 (v4)
+
+To get the latest: `go get -u github.com/clipperhouse/gen`. Type `gen help` to see commands.
+
+This release has several substantial changes.
+
+####Type parameters
+
+Tags now have support for type parameters, for example:
+
+	// +gen foo:"Bar[qux], Qaz[thing, stuff]"
+	// type MyType struct{}
+	
+Those type paramters (qux, thing, stuff) are properly evaluated as types. Which not only increases safety, but gives more information to typewriters.
+
+####Type constraints
+
+Speaking of above, types are evaluated for Numeric, Ordered and Comparable. Templates, in turn, can have type constraints.
+
+So, you can declare your Sum template only to be applicable to Numeric types, and your Set to Comparable types.
+
+####gen add
+
+Third-party typewriters are added to your package using a new command, `add`. It looks like this:
+
+	gen add github.com/clipperhouse/setwriter
+	
+That’s a plain old Go import path.
+
+After adding, you can mark up a type like:
+
+	// +gen set slice:"GroupBy[string], Select[Foo]"
+	// type MyType struct{}
+
+As always, it’s up to the third-party typewriter to determine behavior. In this case, a “naked” `set` tag is enough.
+
+We deprecated the unintuitive `gen custom` command, `add` replaces it.
+
+####Explcitness
+
+Previous versions of gen would generate a dozen or so LINQ-style slice methods simply by marking up:
+
+	// +gen
+	// type MyType struct{}
+	
+We’ve opted for explicitness moving forward – in the case of slices, you’ll write this instead:
+
+	// +gen slice:"Where, SortBy, Any"
+	// type MyType struct{}
+
+In other words, only the methods you want.
+
+####Projections
+
+Certain methods, such as Select and GroupBy require an additional type parameter. I won’t bore you with the convoluted old way. Now it’s:
+
+	// +gen slice:"GroupBy[string], Select[Foo]"
+	// type MyType struct{}
+
+Those type parameters are properly evaluated, and typewriters get full type information on them.
+
+####slice
+
+The main built-in typewriter used to be called `genwriter`, it is now called `slice`. Instead of the generated slice type being called Things, it’s now called ThingSlice.
+
+[slice](https://github.com/clipperhouse/slice) is now the only built-in typewriter.
+
+We’ve deprecated the built-in container typewriter, instead splitting it into optional [Set](https://github.com/clipperhouse/set), [List](https://github.com/clipperhouse/linkedlist) and [Ring](https://github.com/clipperhouse/ring) typewriters. How to add optional typewriters, you ask?
+
+####Smaller interface
+
+For those developing their own typewriters: the [`TypeWriter` interface](https://github.com/clipperhouse/typewriter/blob/master/typewriter.go) got smaller. It’s now:
+
+	type TypeWriter interface {
+		Name() string
+		Imports(t Type) []ImportSpec
+		Write(w io.Writer, t Type) error
+	}
+
+`Validate` is gone, it was awkward. The easy fix there was to allow Write to return an error. `WriteHeader` is gone, there was little use for it in practice. `WriteBody` is now simply `Write`.
+
+Let me (@clipperhouse) know if any questions.
+
+###28 Jun 2014 (v3)
 
 To get the latest: `go get -u github.com/clipperhouse/gen`. Type `gen help` to see commands.
 
@@ -12,8 +95,8 @@ Prior to this release, typewriters were simply part of the `gen` binary. Now, by
 package main
 
 import (
-	_ "github.com/clipperhouse/gen/typewriters/container"
-	_ "github.com/clipperhouse/gen/typewriters/genwriter"
+	_ "github.com/clipperhouse/containerwriter"
+	_ "github.com/clipperhouse/typewriters/genwriter"
 )
 ```
 

README.md

@@ -1,31 +1,29 @@
 ## What’s this?
 
-`gen` is a code-generation tool for Go. It’s intended to offer generics-like functionality on your types.
+`gen` is a code-generation tool for Go. It’s intended to offer generics-like functionality on your types. Out of the box, it offers offers LINQ/underscore-inspired methods.
 
-Out of the box, it offers LINQ/underscore/js-inspired methods as well as some handy containers.
-
-It also offers third-party, runtime extensibility via [typewriters](http://godoc.org/github.com/clipperhouse/gen/typewriter).
+It also offers third-party, runtime extensibility via [typewriters](https://github.com/clipperhouse/typewriter).
 
 ####[Introduction and docs…](http://clipperhouse.github.io/gen/)
 
 [Changelog](https://github.com/clipperhouse/gen/blob/master/CHANGELOG.md)
 
-[Unstable branch](https://github.com/clipperhouse/gen/tree/v4)
+###Contributing
 
-## Contributing
+There are three big parts of `gen`.
 
-It’s early days and the API is likely volatile, ideas and contributions are welcome. Have a look at the design principles below. Feel free to [open an issue](//github.com/clipperhouse/gen/issues), send a pull request, or ping Matt Sherman [@clipperhouse](http://twitter.com/clipperhouse).
+####gen
 
-## Design principles for contributors
+This repository. The gen package is primarily the command-line interface. Most of the work is done by the typewriter package, and individual typewriters.
 
-This library exists to provide readability and reduce boilerplate in users’ code. It’s intended to reduce the number of explicit loops, by instead passing func’s as you would with C#’s Linq, JavaScript’s Array methods, or the underscore library. If it feels like piping, that’s good.
+####typewriter
 
-It’s intended to fit well with idiomatic Go. Explicitness and compile-time safety are preferred. For this reason, we are not using interfaces or run-time reflection. (Though if a good case can be made, we’ll listen.)
+The [typewriter package](https://github.com/clipperhouse/typewriter) is where most of the parsing, type evaluation and code generation architecture lives.
 
-The goal is to keep the API small. We aim to implement the **least number of orthogonal methods** which allow the desired range of function.
+####typewriters
 
-It’s about types. If something would be expressed <T> in another language, perhaps it’s a good candidate for gen. If it would not be expressed that way, perhaps it’s not a good candidate.
+Typewriters are where templates and logic live for generating code. Here’s [set](https://github.com/clipperhouse/set), which will make a lovely Set container for your type. Here’s [slice](https://github.com/clipperhouse/slice), which provides the built-in LINQ-like functionality.
 
-We avoid methods that feel like wrappers or aliases to existing methods, even if they are convenient. A good proxy is to imagine a user asking the question ‘which method should I use?’. If that’s a reasonable question, the library should be doing less.
+Third-party typewriters are added easily by the end user. You publish them as Go packages for import. [Learn more].
 
-These guidelines are not entirely deterministic! There’s lots of room for judgment and taste, and we look forward to seeing how it evolves.
+We’d love to see typewriter packages for things like strongly-typed JSON serialization, `Queue`s, `Pool`s or other containers. Anything “of T” is a candidate for a typewriter.

_gen.go

@@ -0,0 +1,6 @@
+package main
+
+import (
+	_ "github.com/clipperhouse/slice"
+	_ "github.com/clipperhouse/set"
+)

add.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+
+	"github.com/clipperhouse/typewriter"
+)
+
+// add adds a new typewriter import to the current package, by creating (or appending) a _gen.go file.
+func add(c config, args ...string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("please specify the import path of the typewriter you wish to add")
+	}
+
+	imports, err := getTypewriterImports(c)
+
+	if err != nil {
+		return err
+	}
+
+	for _, arg := range args {
+		imp := typewriter.ImportSpec{Name: "_", Path: arg}
+
+		// try to go get it
+		cmd := exec.Command("go", "get", imp.Path)
+		cmd.Stdout = c.out
+		cmd.Stderr = c.out
+
+		if err := cmd.Run(); err != nil {
+			return err
+		}
+
+		imports.Add(imp)
+	}
+
+	if createCustomFile(c, imports); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func createCustomFile(c config, imports typewriter.ImportSpecSet) error {
+	w, err := os.Create(c.customName)
+
+	if err != nil {
+		return err
+	}
+
+	defer w.Close()
+
+	p := pkg{
+		Name:    "main",
+		Imports: imports,
+	}
+
+	if err := tmpl.Execute(w, p); err != nil {
+		return err
+	}
+
+	return nil
+}

add_test.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"os"
+	"testing"
+
+	"github.com/clipperhouse/typewriter"
+)
+
+func TestAdd(t *testing.T) {
+	// use custom name so test won't interfere with a real _gen.go
+	c := defaultConfig
+	c.customName = "_gen_add_test.go"
+	defer os.Remove(c.customName)
+
+	if err := add(c); err == nil {
+		t.Error("add with no arguments should be an error")
+	}
+
+	foo := typewriter.ImportSpec{Name: "_", Path: "github.com/clipperhouse/foowriter"}
+	before, err := getTypewriterImports(c)
+
+	if err != nil {
+		t.Error(err)
+	}
+
+	// ensure that the custom import is not in the default set
+	if before.Contains(foo) {
+		t.Errorf("default imports should not include %s", foo.Path)
+	}
+
+	// adding import which exists should succeed
+	if err := add(c, foo.Path); err != nil {
+		t.Error(err)
+	}
+
+	after, err := getTypewriterImports(c)
+
+	// the new import should be reflected in imports
+	if !after.Contains(foo) {
+		t.Errorf("imports should include %s", foo.Path)
+	}
+}

config.go

@@ -3,40 +3,21 @@ package main
 import (
 	"io"
 	"os"
-	"sync"
-)
-
-// lock for changing configs below
-var mu = &sync.Mutex{}
 
-// global state for output; useful with testing
-var (
-	defaultOut io.Writer = os.Stdout
-	out        io.Writer = defaultOut
+	"github.com/clipperhouse/typewriter"
 )
 
-// with inspiration from http://golang.org/src/pkg/log/log.go?s=7258:7285#L229
-func setOutput(w io.Writer) {
-	mu.Lock()
-	defer mu.Unlock()
-	out = w
-}
-
-func revertOutput() {
-	setOutput(defaultOut)
+type config struct {
+	out        io.Writer
+	customName string
 }
 
-// global state for custom imports file name; useful with testing
-const defaultCustomName string = "_gen.go"
-
-var customName string = defaultCustomName
-
-func setCustomName(s string) {
-	mu.Lock()
-	defer mu.Unlock()
-	customName = s
+var defaultConfig = config{
+	out:        os.Stdout,
+	customName: "_gen.go",
 }
 
-func revertCustomName() {
-	setCustomName(defaultCustomName)
-}
+// keep in sync with imports.go
+var stdImports = typewriter.NewImportSpecSet(
+	typewriter.ImportSpec{Name: "_", Path: "github.com/clipperhouse/slice"},
+)