gen

Documentation

Overview

Package gen generates Go code based on a compiled Thrift module specification.

NOTE: All APIs in this packages should be considered UNSTABLE and subject to change WITHOUT a major version bump.

Index

• Constants
• func Constant(g Generator, c *compile.Constant) error
• func ConstantValue(g Generator, c compile.ConstantValue, t compile.TypeSpec) (string, error)
• func ConstantValuePtr(g Generator, c compile.ConstantValue, t compile.TypeSpec) (string, error)
• func Generate(m *compile.Module, o *Options) error
• func Service(g Generator, s *compile.ServiceSpec) (map[string]*bytes.Buffer, error)
• func ServiceFunction(g Generator, s *compile.ServiceSpec, f *compile.FunctionSpec) error
• func Services(g Generator, services map[string]*compile.ServiceSpec) error
• func TypeCode(g Generator, spec compile.TypeSpec) string
• func TypeDefinition(g Generator, spec compile.TypeSpec) error
• func Version(g Generator, importPath string) error
• type Generator
  • func NewGenerator(o *GeneratorOptions) Generator
• type GeneratorOptions
• type Namespace
  • func NewNamespace() Namespace
• type Options
• type TemplateOption
  • func TemplateFunc(name string, f interface{}) TemplateOption
• type ThriftPackageImporter
• type WireGenerator
  • func (w *WireGenerator) FromWire(g Generator, spec compile.TypeSpec, value string) (string, error)
  • func (w *WireGenerator) FromWirePtr(g Generator, spec compile.TypeSpec, lhs string, value string) (string, error)
  • func (w *WireGenerator) ToWire(g Generator, spec compile.TypeSpec, varName string) (string, error)
  • func (w *WireGenerator) ToWirePtr(g Generator, spec compile.TypeSpec, varName string) (string, error)

Constants

const NoZapLabel = "go.nolog"

NoZapLabel allows opt out of Zap logging for struct fields. Fields of Thrift structs will use this annotation to opt-out of being logged when that struct is logged. i.e.

struct ZapOptOutStruct {
	1: required string name
	2: required string optout (go.nolog)
}

The above struct will be logged without the optout string.

Functions

func Constant

func Constant(g Generator, c *compile.Constant) error

Constant generates code for `const` expressions in Thrift files.

func ConstantValue

func ConstantValue(g Generator, c compile.ConstantValue, t compile.TypeSpec) (string, error)

ConstantValue generates an expression containing the given constant value of the given type.

The constant must already have been linked to the given type.

func ConstantValuePtr

func ConstantValuePtr(g Generator, c compile.ConstantValue, t compile.TypeSpec) (string, error)

ConstantValuePtr generates an expression which is a pointer to a value of type $t.

func Generate

func Generate(m *compile.Module, o *Options) error

Generate generates code based on the given options.

func Service

func Service(g Generator, s *compile.ServiceSpec) (map[string]*bytes.Buffer, error)

Service generates code for the given service.

Returns a map from file name to contents for that file. The file names are relative to the package directory for the service.

func ServiceFunction

func ServiceFunction(g Generator, s *compile.ServiceSpec, f *compile.FunctionSpec) error

ServiceFunction generates code for the given function of the given service.

func Services

func Services(g Generator, services map[string]*compile.ServiceSpec) error

Services generates code for all services into a single file and stores the code in the generator to be written.

func TypeCode

func TypeCode(g Generator, spec compile.TypeSpec) string

TypeCode gets an expression of type 'wire.Type' that represents the over-the-wire type code for the given TypeSpec.

func TypeDefinition

func TypeDefinition(g Generator, spec compile.TypeSpec) error

TypeDefinition generates code for the given TypeSpec.

func Version

func Version(g Generator, importPath string) error

Version generates an init() function checking the version of the library during generation with the one used at runtime.

Types

type Generator

type Generator interface {
	// MangleType generates a unique name for the given type that may be used
	// in private helper types and functions. This name is unique across all
	// types in the current context including imported types.
	MangleType(spec compile.TypeSpec) string

	// TextTemplate renders the given template with the given template
	// context.
	TextTemplate(s string, data interface{}, opts ...TemplateOption) (string, error)

	// DeclareFromTemplate renders the given template, and includes the
	// declarations from the generated Go code in the package being generated.
	// The next call to Write will write these declarations and any other
	// declarations that have not been written so far.
	DeclareFromTemplate(s string, data interface{}, opts ...TemplateOption) error

	// EnsureDeclared is similar to DeclareFromTemplate except that it simply
	// ignores conflicting definitions.
	EnsureDeclared(s string, data interface{}, opts ...TemplateOption) error

	// LookupTypeName returns the fully qualified name that should be used for
	// the given Thrift type. It imports the corresponding Go package if
	// necessary.
	//
	// This must be called with user-defined types only.
	LookupTypeName(compile.TypeSpec) (string, error)

	// LookupConstantName returns the fully qualified name that should be used
	// for the given Thrift constant. It imports the corresponding Go package if
	// necessary.
	LookupConstantName(*compile.Constant) (string, error)

	// Import ensures that the given package has been imported in the generated
	// code. Returns the name that should be used to reference the imported
	// module.
	Import(path string) string

	// Write the generated code to the given Writer and start a new file for
	// this package. All consecutive calls to DeclareFromTemplate will be
	// accumulated until the next Write call.
	//
	// A single Write must corresponds to a single file in the generated
	// package.
	//
	// The FileSet argument is deprecated and will be ignored.
	Write(w io.Writer, _ *token.FileSet) error
}

Generator allows generating declarations and other templated text for a single Go package which may be spread across multiple files.

Multiple files may be written by calling Write multiple times between calls to DeclareFromTemplate.

func NewGenerator

func NewGenerator(o *GeneratorOptions) Generator

NewGenerator sets up a new generator for Go code.

type GeneratorOptions

type GeneratorOptions struct {
	Importer    ThriftPackageImporter
	ImportPath  string
	PackageName string

	NoZap bool
}

GeneratorOptions controls a generator's behavior

type Namespace

type Namespace interface {
	// Generates a new name based on the given name. Prefers the provided name
	// but the name may be altered if it conflicts with another name in the
	// current scope.
	//
	// The returned name is also reserved so that future names cannot conflict
	// with it.
	NewName(name string) string

	// Reserve the given name in this namespace. Fails with an error if the name
	// is already taken.
	Reserve(name string) error

	// Forget the given name. Nothing happens if this name wasn't already
	// taken in this namespace. The name will NOT be removed from parent
	// namespaces.
	Forget(name string)

	// Create a new Child namespace. The child namespace cannot use any names
	// defined in this namespace or any of its parent namespaces.
	Child() Namespace

	// Rotate returns the oldest known name that was used for the given
	// requested name, and moves it to the end of the list of names used for
	// that requested name.
	//
	// This may be used to access the names used in a template dynamically in a
	// deterministic order if recording them in local variables is not possible.
	Rotate(name string) (string, error)
}

Namespace allows finding names that don't conflict with other names in certain scopes.

func NewNamespace

func NewNamespace() Namespace

NewNamespace creates a new namespace.

type Options

type Options struct {
	// OutputDir is the directory into which all generated code is written.
	//
	// This must be an absolute path.
	OutputDir string

	// PackagePrefix controls the import path prefix for all generated
	// packages.
	PackagePrefix string

	// ThriftRoot is the directory within whose tree all Thrift files consumed
	// are contained. The locations of the Thrift files relative to the
	// ThriftFile determines the module structure in OutputDir.
	//
	// This must be an absolute path.
	ThriftRoot string

	// NoRecurse determines whether code should be generated for included Thrift
	// files as well. If true, code gets generated only for the first module.
	NoRecurse bool

	// If true, we will not generate versioncheck.go files.
	NoVersionCheck bool

	// Code generation plugin
	Plugin plugin.Handle

	// Do not generate types.go
	NoTypes bool

	// Do not generate constants.go
	NoConstants bool

	// Do not generate service helpers
	NoServiceHelpers bool

	// Do not embed IDLs in generated code
	NoEmbedIDL bool

	// Do not generate Zap logging code
	NoZap bool

	// Name of the file to be generated by ThriftRW.
	OutputFile string
}

Options controls how code gets generated.

type TemplateOption

type TemplateOption func(Generator, *template.Template) *template.Template

TemplateOption customizes templates.

func TemplateFunc

func TemplateFunc(name string, f interface{}) TemplateOption

TemplateFunc adds a function to the template.

The function may be anything accepted by text/template. If the function accepts a Generator as its first argument, it will be provided automatically.

type ThriftPackageImporter

type ThriftPackageImporter interface {
	// RelativePackage returns the import path for the top-level package of the
	// given Thrift file relative to the ImportPrefix.
	RelativePackage(file string) (importPath string, err error)

	// RelativePackage returns the relative path of the given Thrift file
	// relative to the ThriftRoot.
	RelativeThriftFilePath(file string) (relPath string, err error)

	// Package returns the import path for the top-level package of the given Thrift
	// file.
	Package(file string) (importPath string, err error)
}

ThriftPackageImporter determines import paths from a Thrift root.

type WireGenerator

type WireGenerator struct {
	// contains filtered or unexported fields
}

WireGenerator is responsible for generating code that knows how to convert between Thrift types and their Value representations.

func (*WireGenerator) FromWire

func (w *WireGenerator) FromWire(g Generator, spec compile.TypeSpec, value string) (string, error)

FromWire generates an expression of type ($spec, error) which reads the Value at $value into a $spec.

func (*WireGenerator) FromWirePtr

func (w *WireGenerator) FromWirePtr(g Generator, spec compile.TypeSpec, lhs string, value string) (string, error)

FromWirePtr generates a string assigning the given Value to the given lhs, which is a pointer to a value of the given type.

A variable err of type error MUST be in scope and will be assigned the parse error, if any.

func (*WireGenerator) ToWire

func (w *WireGenerator) ToWire(g Generator, spec compile.TypeSpec, varName string) (string, error)

ToWire generates an expression of type (Value, error) object containing the wire representation of the variable $varName of type $spec or an error.

func (*WireGenerator) ToWirePtr

func (w *WireGenerator) ToWirePtr(g Generator, spec compile.TypeSpec, varName string) (string, error)

ToWirePtr is the same as ToWire expect `varName` is expected to be a reference to a value of the given type.