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 ImportSpec
• 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 SyntaxError
  • func (e *SyntaxError) Error() string
• type Tag
• type Tags
  • func (ts Tags) ByName(name string) (result Tag, found bool, err error)
  • func (tags Tags) Equal(other Tags) bool
  • 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)

NewAppFiltered 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 ImportSpec

type ImportSpec struct {
	Name, Path string
}

ImportSpec describes the name and path of an import The name is often omitted

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 SyntaxError

type SyntaxError struct {
	Pos token.Pos
	// contains filtered or unexported fields
}

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Tag

type Tag struct {
	Name    string
	Items   []string
	Negated bool
}

+gen methods:"Where"

type Tags

type Tags []Tag

Tags is a slice of type Tag. Use it where you would use []Tag.

func (Tags) ByName

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

func (Tags) Equal

func (tags Tags) Equal(other Tags) bool

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, prior to further action, to answer two questions:
	// a) that your TypeWriter will write for this Type; return false if your TypeWriter intends not to write a file for this Type at all.
	// b) that your TypeWriter considers the declaration (i.e., Tags) valid; return err if not.
	Validate(t Type) (bool, error)
	// WriteHeader writer to the top of the generated code, before the package declaration; intended for licenses or general documentation.
	WriteHeader(w io.Writer, t Type)
	// Imports is a slice of imports required for the type; each will be written into the imports declaration.
	Imports(t Type) []ImportSpec
	// WriteBody writes to the body of the generated code, following package declaration, headers and imports. This is the meat.
	WriteBody(w io.Writer, t Type)
}