generate

Documentation

Overview

Package generate implements code generation. It includes all available code generation strategies on Terramate and it also handles outdated code detection and deletion.

Index

• Constants
• func ListStackGenFiles(root *config.Root, dir string) ([]string, error)
• func NewAPI() di.Factory[API]
• type API
• type GenFile
• type LoadResult
  • func Load(root *config.Root, vendorDir project.Path) ([]LoadResult, error)

Constants

const (
	// ErrLoadingGlobals indicates failure loading globals during code generation.
	ErrLoadingGlobals errors.Kind = "loading globals"

	// ErrManualCodeExists indicates code generation would replace code that
	// was not previously generated by Terramate.
	ErrManualCodeExists errors.Kind = "manually defined code found"

	// ErrConflictingConfig indicates that two code generation configurations
	// are conflicting, like both generates a file with the same name
	// and would overwrite each other.
	ErrConflictingConfig errors.Kind = "conflicting config detected"

	// ErrInvalidGenBlockLabel indicates that a generate block
	// has an invalid label as the target to save the generated code.
	ErrInvalidGenBlockLabel errors.Kind = "invalid generate block label"

	// ErrAssertion indicates that code generation configuration
	// has a failed assertion.
	ErrAssertion errors.Kind = "assertion failed"
)

Functions

func ListStackGenFiles

func ListStackGenFiles(root *config.Root, dir string) ([]string, error)

ListStackGenFiles will list the path of all generated code inside the given dir and all its subdirs that are not stacks. The returned paths are relative to the given dir, like:

• filename.hcl
• dir/filename.hcl

The filenames are ordered lexicographically. They always use slash (/) as a dir separator (independent on the OS).

dir must be an absolute path and must be inside the given rootdir.

When called with a dir that is not a stack this function will provide a list of all orphaned generated files inside this dir, since it won't search inside any stacks. So calling with dir == rootdir will provide all orphaned files inside a project if the root of the project is not a stack.

When called with a dir that is a stack this function will list all generated files that are owned by the stack, since it won't search inside any child stacks.

func NewAPI

func NewAPI() di.Factory[API]

NewAPI returns a factory for generate.API.

Types

type API

type API interface {
	// Do runs the code generation.
	Do(
		root *config.Root,
		targetDir project.Path,
		parallel int,
		vendorDir project.Path,
		vendorRequests chan<- event.VendorRequest,
	) *genreport.Report

	// DetectOutdated checks for outdated files that would be changed by Do, but without making any changes.
	DetectOutdated(
		root *config.Root,
		target *config.Tree,
		vendorDir project.Path,
	) ([]string, error)
}

API for code generation.

type GenFile

type GenFile interface {
	// Builtin tells if the generated file is builtin.
	Builtin() bool
	// Header is the header of the generated file, if any.
	Header() string
	// Body is the body of the generated file, if any.
	Body() string
	// Label is the label of the origin generate block that generated this file.
	Label() string
	// Context is the context of the generate block.
	Context() string
	// Range is the range of the origin generate block that generated this file.
	Range() info.Range
	// Condition is true if the origin generate block had a true condition, false otherwise.
	Condition() bool
	// Asserts is the origin generate block assert blocks.
	Asserts() []config.Assert
}

GenFile represents a generated file loaded from a Terramate configuration.

type LoadResult

type LoadResult struct {
	// Dir is from where the generated files were loaded, or where a failure occurred
	// if Err is not nil.
	Dir project.Path
	// Files is the generated files for this directory.
	Files []GenFile
	// Err will be non-nil if loading generated files for a specific dir failed
	Err error
}

LoadResult represents all generated files of a specific directory.

func Load

func Load(root *config.Root, vendorDir project.Path) ([]LoadResult, error)

Load will load all the generated files inside the given tree. Each directory will be represented by a single LoadResult inside the returned slice. Errors generating code for specific dirs will be found inside each LoadResult.

The given vendorDir is used when calculating the vendor path using tm_vendor on the generate blocks.

If a critical error that fails the loading of all results happens it returns a non-nil error. In this case the error is not specific to generating code for a specific dir.