ggen

Documentation

Index

• Constants
• func Errorf(err error, format string, args ...interface{}) error
• func Errors(msg string, errs []error) error
• func Start(cfg Config, patterns ...string) error
• type CommandFilter
  • func FilterByCommand(command string) CommandFilter
  • func (cmd CommandFilter) Filter(ng FilterEngine) error
  • func (cmd CommandFilter) FilterAll(ng FilterEngine) error
  • func (cmd CommandFilter) Include(ds Directives) bool
• type Comment
  • func (c Comment) Text() string
• type Config
  • func (c *Config) EnablePlugin(names ...string)
  • func (c *Config) RegisterPlugin(plugins ...Plugin)
• type DefaultQualifier
  • func (q DefaultQualifier) Qualify(pkg *types.Package) string
• type Directive
  • func ParseDirective(line string) (result Directive, _ error)
  • func ParseDirectiveFromBody(body []byte) (directives, inlineDirective []Directive, err error)
  • func ParseDirectiveFromFile(filename string) (directives, inlineDirective []Directive, err error)
  • func (d Directive) GetArgs() ([]string, error)
  • func (d Directive) IsPackageLevel() bool
  • func (d Directive) String() string
• type Directives
  • func (ds Directives) FilterBy(prefix string) Directives
  • func (ds Directives) Get(cmd string) (Directive, bool)
  • func (ds Directives) GetArg(cmd string) string
• type Engine
• type FilterEngine
• type Filterer
• type FilteringPackage
  • func (p *FilteringPackage) Include()
• type GenerateFileNameInput
• type GeneratingPackage
  • func (g *GeneratingPackage) GetDirectives() []Directive
  • func (g *GeneratingPackage) GetObjects() []types.Object
  • func (g *GeneratingPackage) GetPrinter() Printer
• type LogAttr
• type LogHandler
• type LogLevel
• type Logger
• type Plugin
• type Positioner
• type Printer
• type Qualifier

Constants

const (
	DebugLevel = logging.DebugLevel
	InfoLevel  = logging.InfoLevel
	WarnLevel  = logging.WarnLevel
	ErrorLevel = logging.ErrorLevel
)

Functions

func Errorf

func Errorf(err error, format string, args ...interface{}) error

func Errors

func Errors(msg string, errs []error) error

func Start

func Start(cfg Config, patterns ...string) error

Types

type CommandFilter

type CommandFilter string

func FilterByCommand

func FilterByCommand(command string) CommandFilter

func (CommandFilter) Filter

func (cmd CommandFilter) Filter(ng FilterEngine) error

func (CommandFilter) FilterAll

func (cmd CommandFilter) FilterAll(ng FilterEngine) error

func (CommandFilter) Include

func (cmd CommandFilter) Include(ds Directives) bool

type Comment

type Comment struct {
	Doc *ast.CommentGroup

	Comment *ast.CommentGroup

	Directives []Directive
}

func (Comment) Text

func (c Comment) Text() string

type Config

type Config struct {
	Plugins []Plugin

	// Map of enabled plugins. Leave this nil to enable all plugins.
	EnabledPlugins map[string]bool

	// default to "zz_generated.{{.Name}}.go"
	GenerateFileName func(GenerateFileNameInput) string

	CleanOnly bool

	Namespace string

	GoimportsArgs []string

	BuildTags []string

	LogLevel   LogLevel
	LogHandler LogHandler
}

func (*Config) EnablePlugin

func (c *Config) EnablePlugin(names ...string)

func (*Config) RegisterPlugin

func (c *Config) RegisterPlugin(plugins ...Plugin)

type DefaultQualifier

type DefaultQualifier struct{}

func (DefaultQualifier) Qualify

func (q DefaultQualifier) Qualify(pkg *types.Package) string

type Directive

type Directive struct {
	Raw string // +foo:pkg:foo this is a string
	Cmd string // foo:pkg
	Arg string // sample,baz

	Item Positioner // the item that the directive is attached to
}

Directive comment has one of following formats

// +foo:valid=required,optional
// +foo:valid=null +gen=foo
// +foo:pkg=sample,baz
// +foo:valid: 0 < $ && $ <= 10

For example "// +foo:pkg=sample,baz" will be parsed as

Command: "foo:pkg"
Arg:     "sample,baz"

Directives must start at the begin of a line, after "//" and a space (the same as "// +build"). Multiple directives can appear in one line.

Directive ending with "=" can not have space in argument and can have multiple directives. Directive ending with ":" can have space in argument, therefore it will be parsed as a single directive.

func ParseDirective

func ParseDirective(line string) (result Directive, _ error)

ParseDirective parses directives from a single line.

func ParseDirectiveFromBody

func ParseDirectiveFromBody(body []byte) (directives, inlineDirective []Directive, err error)

ParseDirectiveFromBody reads directives from body and returns the parsed directives.

func ParseDirectiveFromFile

func ParseDirectiveFromFile(filename string) (directives, inlineDirective []Directive, err error)

ParseDirectiveFromFile reads from file and returns the parsed directives.

func (Directive) GetArgs

func (d Directive) GetArgs() ([]string, error)

ParseArgs parse directive argument using the standard "flag" package format. Example:

+ggen:sample -name=Alice DoSomething

func (Directive) IsPackageLevel

func (d Directive) IsPackageLevel() bool

func (Directive) String

func (d Directive) String() string

type Directives

type Directives []Directive

func (Directives) FilterBy

func (ds Directives) FilterBy(prefix string) Directives

FilterBy returns list of directives that have the given command. Examples of accepted directives with input "+ggen:sample" or "ggen:sample"

// +ggen:sample
// +ggen:sample:foo
// +ggen:sample:foo argument

func (Directives) Get

func (ds Directives) Get(cmd string) (Directive, bool)

func (Directives) GetArg

func (ds Directives) GetArg(cmd string) string

type Engine

type Engine interface {

	// Plugin should use the embedded logger to log messages.
	Logger

	// GenerateEachPackage loops through the list of GeneratingPackages and call the given function.
	GenerateEachPackage(func(Engine, *packages.Package, Printer) error) error

	// GeneratingPackages returns a list of packages available for generating.
	GeneratingPackages() []*GeneratingPackage

	// GeneratePackage generates file at given package path with the given file name. The file name must not include any slash character (/). If fileName is empty, use default file name.
	GeneratePackage(pkg *packages.Package, fileName string) (Printer, error)

	// GenerateFile generates file at given path. It should be an absolute path, can include slash character (/). If the path ends with /, use default file name.
	GenerateFile(pkgName, filePath string) (Printer, error)

	GetComment(Positioner) Comment
	GetDirectives(Positioner) Directives
	GetDirectivesByPackage(*packages.Package) Directives
	GetIdent(Positioner) *ast.Ident
	GetObject(Positioner) types.Object
	GetObjectByName(pkgPath, name string) types.Object
	GetBuiltinType(name string) types.Type
	GetObjectsByPackage(*packages.Package) []types.Object
	GetObjectsByScope(*types.Scope) []types.Object
	GetPackage(Positioner) *packages.Package
	GetPackageByPath(string) *packages.Package

	LogDebugNode(node ast.Node) error
}

type FilterEngine

type FilterEngine interface {

	// Plugin should use the embedded logger to log messages.
	Logger

	// IncludePackage indicates that the given package will be included for generating. It will be returned later in
	// Engine.GeneratingPackages(). If it does not exist, an error with be returned later.
	IncludePackage(pkgPath string)

	// ParsePackage indicates that the given package should be parsed. If it does not exist, an error with be returned
	// later.
	//
	// Sometimes, the plugin depends on some specific package that are not transitive imported by IncludePackage. In
	// this case, the plugin can call ParsePackage to parse these packages. This should happen sparsely and not all
	// plugins need to call this function.
	ParsePackage(pkgPath string)

	// ParsePackages takes a pattern and add the matched packages to ParsingPackages. Pattern is the go package pattern:
	//
	//     example.com/...
	//     github.com/path/...
	//
	// ParsePackages indicates that the given package pattern should be parsed. If the pattern does not match any
	// package, an error with be returned later.
	//
	// Sometimes, the plugin depends on some specific package that are not transitive imported by IncludePackage. In
	// this case, the plugin can call ParsePackage to parse these packages. This should happen sparsely and not all
	// plugins need to call this function.
	//
	// A program may require many packages. So it's best to only include packages related to your work. For example if
	// all your packages are put under github.com/yourcompany, it's recommended to call
	// ParsePackages("github.com/yourcompany/...") to avoid parsing unnecessary packages. Or if your plugin only care
	// about protobuf files, you can call ParsePackages("github.com/yourcompany/models/protobuf/...") to include only
	// protobuf generated packages.
	ParsePackages(patterns ...string)

	// ParsingPackages returns a list of packages that are processing. The plugin can can use
	// FilteringPackage.Directives or FilteringPackage.Imports to determine which packages should be available to
	// Generate, then calls IncludePackage on those packages.
	ParsingPackages() []*FilteringPackage
}

type Filterer

type Filterer interface {
	Filter(FilterEngine) error
}

type FilteringPackage

type FilteringPackage struct {
	PkgPath          string
	Imports          map[string]*packages.Package
	Directives       Directives
	InlineDirectives Directives
	// contains filtered or unexported fields
}

func (*FilteringPackage) Include

func (p *FilteringPackage) Include()

type GenerateFileNameInput

type GenerateFileNameInput struct {
	PluginName string
}

type GeneratingPackage

type GeneratingPackage struct {
	*packages.Package
	// contains filtered or unexported fields
}

func (*GeneratingPackage) GetDirectives

func (g *GeneratingPackage) GetDirectives() []Directive

func (*GeneratingPackage) GetObjects

func (g *GeneratingPackage) GetObjects() []types.Object

func (*GeneratingPackage) GetPrinter

func (g *GeneratingPackage) GetPrinter() Printer

type LogAttr

type LogAttr = logging.Attr

type LogHandler

type LogHandler = logging.Handler

type LogLevel

type LogLevel = logging.Level

type Logger

type Logger = logging.Logger

type Plugin

type Plugin interface {

	// Name returns name of the plugin. Each plugin must have a different name.
	Name() string

	// Filter is called to determine which packages will be parsed and which will be skipped. It will be called before
	// Generate. It received a FilterEngine and need to call the following methods:
	//
	//     ParsingPackages: Get a list of all packages available for IncludePackage.
	//                      The plugin can only include packages in this list.
	//     IncludePackage:  Make the package available for Generate.
	Filter(FilterEngine) error

	// Generate is called to actually generate code for the given packages. Only packages passed to
	// FilterEngine.IncludePackage are available for Generate.
	Generate(Engine) error
}

type Positioner

type Positioner interface {
	Pos() token.Pos
}

type Printer

type Printer interface {
	FilePath() string
	Import(name, path string)
	Qualifier(pkg *types.Package) string
	TypeString(types.Type) string
	Bytes() []byte

	io.WriteCloser
}

type Qualifier

type Qualifier interface {
	Qualify(*types.Package) string
}