genus

README

中文版

List of Contents:

• Examples

• Generation Plan Specification

• Guideline of Flexible Templates in Go

• Built-in Generators

genus

A general code generation tools in Go.

New to code generation? Refer text/template for basic knowledge.

Why Another Generator?

Code generation has been becoming a popular way of metaprogramming in Go.

For example, when working with a ORM framework, you may want to create models with a given database schema with json tag support. it's trivial and burdensome when it comes with a database with hundreds even thousands of tables.

A code generation tool can help on this kind of issues through retriving database schema and rendering templates to go code.

However, before it turns into reality, you'll have to build a tool to

• reading and organizing templates properly
• formating the generated source code
• fixing imports, especially removing unused imports
• handle relative imports(imports among the generated code)
• naming of generated file names

Today, generators are handling code generation in their own ways, which means that you can not generate models of Beego ORM with generators or gorm. It doesn't make sense to build a new generator becuase those models are generated from the same database schema.

Genus provides a clean way to perform code generation. Go to Examples to see more details.

Installation

Genus has built-in CLI support, you can install it by performing

go get -u github.com/yangyuqian/genus/cmd/genus

Features - V1

• Template Wrapper

  • loading templates from diretories, files and bytes easily
  • grouping templates for Go packages
  • formating, fixing imports after code generation

• Generation Planner

  • planning generation scenarios on template repository
  • planner for regular files(non-Golang)

• Language specified helper funcs

  • Golang helper funcs

• Generation Plan Specification

  • JSON schema and validation support
  • Reference and pointer support for complex specfications

• Command-line Interface

  • accept context in JSON and do generation without writing any code
  • create Generation Plan Specification of Database from given database

Documentation

Index

• Variables
• func BoolWithDefault(v, d bool) bool
• func BuildRepeatableData(framework string, data json.RawMessage) (o []interface{}, err error)
• func BuildSingletonData(framework string, data json.RawMessage) (o []interface{}, err error)
• func StringWithDefault(v, d string) string
• type Imports
• type PackagePlanner
  • func NewPackagePlanner(specPath string) (planner *PackagePlanner, err error)
  • func (pl *PackagePlanner) Perform() (err error)
  • func (pl *PackagePlanner) Plan() (err error)
• type Plan
• type PlanItem
• type PlanType
  • func (i PlanType) String() string
• type Planner
• type RepeatablePlan
  • func (p *RepeatablePlan) Render() (err error)
• type Repo
  • func NewRepo(templateDir, suffix string) *Repo
  • func (r *Repo) BuildGroup(names ...string) (tg *TemplateGroup, err error)
  • func (r *Repo) Load() (err error)
  • func (r *Repo) Lookup(name string) (t *Template, err error)
• type SingletonPlan
  • func (p *SingletonPlan) Render() (err error)
  • func (p *SingletonPlan) Type() types.PlanType
• type Spec
  • func (spec *Spec) Save(baseDir string) (err error)
• type SpecExtension
• type Template
  • func (tmpl *Template) Render(data interface{}) (result []byte, err error)
  • func (tmpl *Template) RenderPartial(data interface{}) (result []byte, err error)
  • func (tmpl *Template) SetRawTemplate(raw []byte) (data []byte)
• type TemplateGroup
  • func (tg *TemplateGroup) Render(data interface{}) (err error)
  • func (tg *TemplateGroup) RenderPartial(data interface{}) (err error)
• type TxtToMany
  • func (t *TxtToMany) Uniq() (err error)
• type TxtToOne
  • func (t *TxtToOne) Uniq() (err error)

Variables

var GoHelperFuncs = template.FuncMap{

	"quoteWrap": func(s string) string { return fmt.Sprintf(`"%s"`, s) },
	"id":        strmangle.Identifier,

	"singular": strmangle.Singular,
	"plural":   strmangle.Plural,

	"titleCase": strmangle.TitleCase,
	"camelCase": strmangle.CamelCase,

	"join":               func(sep string, slice []string) string { return strings.Join(slice, sep) },
	"joinSlices":         strmangle.JoinSlices,
	"stringMap":          strmangle.StringMap,
	"prefixStringSlice":  strmangle.PrefixStringSlice,
	"containsAny":        strmangle.ContainsAny,
	"generateTags":       strmangle.GenerateTags,
	"generateIgnoreTags": strmangle.GenerateIgnoreTags,

	"parseEnumName":       strmangle.ParseEnumName,
	"parseEnumVals":       strmangle.ParseEnumVals,
	"isEnumNormal":        strmangle.IsEnumNormal,
	"shouldTitleCaseEnum": strmangle.ShouldTitleCaseEnum,
	"onceNew":             newOnce,
	"oncePut":             once.Put,
	"onceHas":             once.Has,

	"makeStringMap": strmangle.MakeStringMap,

	"setInclude": strmangle.SetInclude,

	"whereClause": strmangle.WhereClause,

	"txtsFromFKey":     txtsFromFKey,
	"txtsFromOneToOne": txtsFromOneToOne,
	"txtsFromToMany":   txtsFromToMany,

	"filterColumnsByDefault": bdb.FilterColumnsByDefault,
	"filterColumnsByEnum":    bdb.FilterColumnsByEnum,
	"sqlColDefinitions":      bdb.SQLColDefinitions,
	"columnNames":            bdb.ColumnNames,
	"columnDBTypes":          bdb.ColumnDBTypes,
	"getTable":               bdb.GetTable,
	"downcase":               strings.ToLower,
}

Functions

func BoolWithDefault

func BoolWithDefault(v, d bool) bool

func BuildRepeatableData

func BuildRepeatableData(framework string, data json.RawMessage) (o []interface{}, err error)

func BuildSingletonData

func BuildSingletonData(framework string, data json.RawMessage) (o []interface{}, err error)

func StringWithDefault

func StringWithDefault(v, d string) string

Types

type Imports

type Imports map[string]string

type PackagePlanner

type PackagePlanner struct {
	RawSpec []byte
	Spec    *Spec
	Plans   []Plan
}

Planner for generations for single Go package Load plan definitions from a json specification

func NewPackagePlanner

func NewPackagePlanner(specPath string) (planner *PackagePlanner, err error)

func (*PackagePlanner) Perform

func (pl *PackagePlanner) Perform() (err error)

func (*PackagePlanner) Plan

func (pl *PackagePlanner) Plan() (err error)

type Plan

type Plan interface {
	Render() error
}

type PlanItem

type PlanItem struct {
	Package         string
	PlanType        string
	Suffix          string
	TemplateDir     string
	BaseDir         string
	BasePackage     string
	RelativePackage string
	Filename        string
	TemplateNames   []string
	SkipExists      bool
	SkipFormat      bool
	SkipFixImports  bool
	Merge           bool
	Imports         Imports
	Data            []interface{}
}

type PlanType

type PlanType int

const (
	SINGLETON PlanType = iota
	REPEATABLE
)

func (PlanType) String

func (i PlanType) String() string

type Planner

type Planner interface{}

type RepeatablePlan

type RepeatablePlan struct {
	Data []interface{}
	SingletonPlan
}

Plan for generations of repeatable files

func (*RepeatablePlan) Render

func (p *RepeatablePlan) Render() (err error)

type Repo

type Repo struct {
	Suffix      string
	TemplateDir string
	Templates   []*Template
	// contains filtered or unexported fields
}

Template repository

func NewRepo

func NewRepo(templateDir, suffix string) *Repo

func (*Repo) BuildGroup

func (r *Repo) BuildGroup(names ...string) (tg *TemplateGroup, err error)

Build template group with given template names

func (*Repo) Load

func (r *Repo) Load() (err error)

Load templates

func (*Repo) Lookup

func (r *Repo) Lookup(name string) (t *Template, err error)

Loakup template by name

type SingletonPlan

type SingletonPlan struct {
	// Set manually
	Suffix          string
	Package         string // leave empty will use the base directory name
	TemplateDir     string
	BaseDir         string
	BasePackage     string
	RelativePackage string
	Filename        string
	TemplateNames   []string
	Imports         Imports
	Data            interface{}
	SkipExists      bool
	SkipFormat      bool
	SkipFixImports  bool
	Merge           bool

	// Calculated
	Repo          *Repo
	TemplateGroup *TemplateGroup
}

Plan for generations of singleton files

func (*SingletonPlan) Render

func (p *SingletonPlan) Render() (err error)

func (*SingletonPlan) Type

func (p *SingletonPlan) Type() types.PlanType

PlanType of SingletonPlan

type Spec

type Spec struct {
	Suffix         string
	TemplateDir    string
	BaseDir        string
	BasePackage    string
	SkipExists     bool
	SkipFormat     bool
	SkipFixImports bool
	Merge          bool
	PlanItems      []*PlanItem
	Extension      *SpecExtension
	Data           []interface{}
}

func (*Spec) Save

func (spec *Spec) Save(baseDir string) (err error)

type SpecExtension

type SpecExtension struct {
	Framework string
	Data      json.RawMessage
}

type Template

type Template struct {
	Name           string // template name
	Source         string // source path
	TargetDir      string // target directory
	Filename       string // filename of generated code
	SkipExists     bool   // skip generation if exist
	SkipFormat     bool   // skip go format
	SkipFixImports bool   // skip generation if exist
	// contains filtered or unexported fields
}

Represents single Go file

func (*Template) Render

func (tmpl *Template) Render(data interface{}) (result []byte, err error)

Render template by given data

func (*Template) RenderPartial

func (tmpl *Template) RenderPartial(data interface{}) (result []byte, err error)

func (*Template) SetRawTemplate

func (tmpl *Template) SetRawTemplate(raw []byte) (data []byte)

Set raw template data

type TemplateGroup

type TemplateGroup struct {
	Package         string // package name
	BaseDir         string // absolute directory for template group
	BasePackage     string // base package
	RelativePackage string
	AbsolutePackage string // absolute package combined with Package and BasePackage
	Filename        string
	Imports         Imports
	Templates       []*Template
	SkipFixImports  bool // skip fixing imports
	SkipExists      bool // skip generation if exist
	SkipFormat      bool // skip go format
	Merge           bool
}

Represents single Go package

func (*TemplateGroup) Render

func (tg *TemplateGroup) Render(data interface{}) (err error)

func (*TemplateGroup) RenderPartial

func (tg *TemplateGroup) RenderPartial(data interface{}) (err error)

type TxtToMany

type TxtToMany struct {
	LocalTable struct {
		NameGo       string
		ColumnNameGo string
	}

	ForeignTable struct {
		NameGo            string
		NamePluralGo      string
		NameHumanReadable string
		ColumnNameGo      string
		Slice             string
	}

	Function struct {
		Name        string
		ForeignName string

		UsesBytes bool

		LocalAssignment   string
		ForeignAssignment string
	}
}

TxtToMany contains text that will be used by many-to-one relationships.

func (*TxtToMany) Uniq

func (t *TxtToMany) Uniq() (err error)

type TxtToOne

type TxtToOne struct {
	ForeignKey bdb.ForeignKey

	LocalTable struct {
		NameGo       string
		ColumnNameGo string
	}

	ForeignTable struct {
		NameGo       string
		NamePluralGo string
		ColumnNameGo string
		ColumnName   string
	}

	Function struct {
		Name        string
		ForeignName string

		UsesBytes bool

		LocalAssignment   string
		ForeignAssignment string
	}
}

TxtToOne contains text that will be used by templates for a one-to-many or a one-to-one relationship.

func (*TxtToOne) Uniq

func (t *TxtToOne) Uniq() (err error)