typewriter

README

##What’s this?

Typewriter is a new package to enable pluggable, type-based codegen for Go. The envisioned use case is for generics-like functionality. This package forms the underpinning of (the next version of) gen.

Usage is analogous to how codecs work with Go’s image package, or database drivers in the sql package.

import (
    // main package
	“github.com/clipperhouse/gen/typewriter”
	
	// any number of typewriters 
	_ “github.com/clipperhouse/gen/typewriters/container”
	_ “github.com/clipperhouse/gen/typewriters/genwriter”
)

func main() {
	app, err := typewriter.NewApp(”+gen”)
	if err != nil {
		panic(err)
	}

	app.WriteAll()
}

Individual typewriters register themselves to the “parent” package via their init() functions.

This is new and in-progress. Feedback is welcome.

Documentation

Index

• func NewApp(directive string) (*app, error)
• func NewAppFiltered(directive string, filter func(os.FileInfo) bool) (*app, error)
• func Register(tw TypeWriter) error
• type Package
  • func NewPackage(path, name string) *Package
  • func (p *Package) Eval(name string) (result Type, err error)
• type Pointer
  • func (p Pointer) String() string
• type Tag
  • func (t Tag) String() string
• type Tags
  • func (ts Tags) ByName(name string) (result Tag, found bool, err error)
  • func (rcv Tags) Where(fn func(Tag) bool) (result Tags)
• type Template
  • func (tmpl Template) ApplicableTo(t Type) bool
• type TemplateSet
  • func (ts TemplateSet) Contains(name string) bool
  • func (ts TemplateSet) Get(name string) (t *template.Template, err error)
  • func (ts TemplateSet) GetAllKeys() (result []string)
• type Type
  • func (t *Type) Comparable() bool
  • func (t *Type) LocalName() (result string)
  • func (t *Type) Numeric() bool
  • func (t *Type) Ordered() bool
  • func (t *Type) String() (result string)
• type TypeWriter

Functions

func NewApp

func NewApp(directive string) (*app, error)

NewApp parses the current directory, collecting Types and their related information.

func NewAppFiltered

func NewAppFiltered(directive string, filter func(os.FileInfo) bool) (*app, error)

NewAppNewAppFiltered parses the current directory, collecting Types and their related information. Pass a filter to limit which files are operated on.

func Register

func Register(tw TypeWriter) error

Register allows template packages to make themselves known to a 'parent' package, usually in the init() func. Comparable to the approach taken by builtin image package for registration of image types (eg image/png). Your program will do something like:

import (
	"github.com/clipperhouse/gen/typewriter"
	_ "github.com/clipperhouse/gen/typewriters/container"
)

Types

type Package

type Package struct {
	*types.Package
}

func NewPackage

func NewPackage(path, name string) *Package

func (*Package) Eval

func (p *Package) Eval(name string) (result Type, err error)

type Pointer

type Pointer bool

Pointer exists as a type to allow simple use as bool or as String, which returns *

func (Pointer) String

func (p Pointer) String() string

type Tag

type Tag struct {
	Name    string
	Items   []string
	Negated bool
	// contains filtered or unexported fields
}

+gen methods:"Where"

func (Tag) String

func (t Tag) String() string

type Tags

type Tags []Tag

Tags is a slice of type Tag, for use with gen methods below. Use this type where you would use []Tag. (This is required because slices cannot be method receivers.)

func (Tags) ByName

func (ts Tags) ByName(name string) (result Tag, found bool, err error)

func (Tags) Where

func (rcv Tags) Where(fn func(Tag) bool) (result Tags)

Where returns a new Tags slice whose elements return true for func. See: http://clipperhouse.github.io/gen/#Where

type Template

type Template struct {
	Text            string
	RequiresNumeric bool
	// A comparable type is one that supports the == operator. Map keys must be comparable, for example.
	RequiresComparable bool
	// An ordered type is one where greater-than and less-than are supported
	RequiresOrdered bool
}

Template includes the text of a template as well as requirements for the types to which it can be applied.

func (Template) ApplicableTo

func (tmpl Template) ApplicableTo(t Type) bool

type TemplateSet

type TemplateSet map[string]*Template

TemplateSet is a map of string names to Template.

func (TemplateSet) Contains

func (ts TemplateSet) Contains(name string) bool

Contains returns true if the TemplateSet includes a template of a given name.

func (TemplateSet) Get

func (ts TemplateSet) Get(name string) (t *template.Template, err error)

Get attempts to 1) locate a tempalte of that name and 2) parse the template Returns an error if the template is not found, and panics if the template can not be parsed (per text/template.Must)

func (TemplateSet) GetAllKeys

func (ts TemplateSet) GetAllKeys() (result []string)

GetAllKeys returns a slice of all 'exported' key names of templates in the TemplateSet

type Type

type Type struct {
	Package *Package
	Pointer Pointer
	Name    string
	Tags    Tags

	types.Type
	// contains filtered or unexported fields
}

func (*Type) Comparable

func (t *Type) Comparable() bool

func (*Type) LocalName

func (t *Type) LocalName() (result string)

func (*Type) Numeric

func (t *Type) Numeric() bool

func (*Type) Ordered

func (t *Type) Ordered() bool

func (*Type) String

func (t *Type) String() (result string)

type TypeWriter

type TypeWriter interface {
	Name() string
	// Validate is called for every Type to a) indicate that it will write for this Type and b) ensure that the TypeWriter considers it valid
	Validate(t Type) (bool, error)
	// WriteHeader writer to the top of the generated code, befoe the package declaration; intended for licenses.
	WriteHeader(w io.Writer, t Type)
	// Imports is a slice of import paths required for the type.
	Imports(t Type) []string
	// Write writes to the body of the generated code. This is the meat.
	Write(w io.Writer, t Type)
}