hcl

Documentation

Overview

Package hcl provides parsing functionality for Terramate HCL configuration. It also provides printing and formatting for Terramate configuration.

Index

• Constants
• func PrintConfig(w io.Writer, cfg Config) error
• func PrintImports(w io.Writer, imports []string) error
• func ValueAsStringList(val cty.Value) ([]string, error)
• type AssertConfig
• type Config
  • func NewConfig(dir string) (Config, error)
  • func ParseDir(root string, dir string) (Config, error)
  • func (c Config) AbsDir() string
  • func (c Config) HasGlobals() bool
  • func (c Config) HasRunEnv() bool
  • func (c Config) IsEmpty() bool
  • func (c Config) Save(filename string) (err error)
• type Evaluator
• type GenFileBlock
• type GenHCLBlock
• type GenerateConfig
• type GitConfig
  • func NewGitConfig() *GitConfig
• type ManifestConfig
• type ManifestDesc
• type RawConfig
  • func NewCustomRawConfig(handlers map[string]mergeHandler) RawConfig
  • func NewTopLevelRawConfig() RawConfig
  • func (cfg RawConfig) Copy() RawConfig
  • func (cfg *RawConfig) Merge(other RawConfig) error
• type RootConfig
• type RunConfig
• type RunEnv
• type Stack
• type Terramate
• type TerramateParser
  • func NewStrictTerramateParser(rootdir string, dir string) (*TerramateParser, error)
  • func NewTerramateParser(rootdir string, dir string) (*TerramateParser, error)
  • func (p *TerramateParser) AddDir(dir string) error
  • func (p *TerramateParser) AddFile(path string) error
  • func (p *TerramateParser) AddFileContent(name string, data []byte) error
  • func (p *TerramateParser) Imports() (ast.Blocks, error)
  • func (p *TerramateParser) Parse() error
  • func (p *TerramateParser) ParseConfig() (Config, error)
  • func (p *TerramateParser) ParsedBodies() map[string]*hclsyntax.Body
• type VendorConfig

Constants

const (
	ErrHCLSyntax           errors.Kind = "HCL syntax error"
	ErrTerramateSchema     errors.Kind = "terramate schema error"
	ErrImport              errors.Kind = "import error"
	ErrUnexpectedTerramate errors.Kind = "`terramate` block is only allowed at the project root directory"
)

Errors returned during the HCL parsing.

const (
	// StackBlockType name of the stack block type
	StackBlockType = "stack"
)

Functions

func PrintConfig

func PrintConfig(w io.Writer, cfg Config) error

PrintConfig will print the given config as HCL on the given writer.

func PrintImports

func PrintImports(w io.Writer, imports []string) error

PrintImports will print the given imports list as import blocks.

func ValueAsStringList

func ValueAsStringList(val cty.Value) ([]string, error)

ValueAsStringList will convert the given cty.Value to a string list.

Types

type AssertConfig

type AssertConfig struct {
	Range     info.Range
	Warning   hcl.Expression
	Assertion hcl.Expression
	Message   hcl.Expression
}

AssertConfig represents Terramate assert configuration block.

type Config

type Config struct {
	Terramate *Terramate
	Stack     *Stack
	Globals   ast.MergedLabelBlocks
	Vendor    *VendorConfig
	Asserts   []AssertConfig
	Generate  GenerateConfig

	Imported RawConfig
	// contains filtered or unexported fields
}

Config represents a Terramate configuration.

func NewConfig

func NewConfig(dir string) (Config, error)

NewConfig creates a new HCL config with dir as config directory path.

func ParseDir

func ParseDir(root string, dir string) (Config, error)

ParseDir will parse Terramate configuration from a given directory, using root as project workspace, parsing all files with the suffixes .tm and .tm.hcl. It parses in non-strict mode for compatibility with older versions. Note: it does not recurse into child directories.

func (Config) AbsDir

func (c Config) AbsDir() string

AbsDir returns the absolute path of the configuration directory.

func (Config) HasGlobals

func (c Config) HasGlobals() bool

HasGlobals tells if the configuration has any globals defined.

func (Config) HasRunEnv

func (c Config) HasRunEnv() bool

HasRunEnv returns true if the config has a terramate.config.run.env block defined

func (Config) IsEmpty

func (c Config) IsEmpty() bool

IsEmpty returns true if the config is empty, false otherwise.

func (Config) Save

func (c Config) Save(filename string) (err error)

Save the configuration file using filename inside config directory.

type Evaluator

type Evaluator interface {
	// Eval evaluates the given expression returning a value.
	Eval(hcl.Expression) (cty.Value, error)

	// PartialEval partially evaluates the given expression returning the
	// tokens that form the result of the partial evaluation. Any unknown
	// namespace access are ignored and left as is, while known namespaces
	// are substituted by its value.
	PartialEval(hcl.Expression) (hcl.Expression, error)

	// SetNamespace adds a new namespace, replacing any with the same name.
	SetNamespace(name string, values map[string]cty.Value)

	// DeleteNamespace deletes a namespace.
	DeleteNamespace(name string)
}

Evaluator represents a Terramate evaluator

type GenFileBlock

type GenFileBlock struct {
	// Range is the range of the entire block definition.
	Range info.Range
	// Label of the block
	Label string
	// Lets is a block of local variables.
	Lets *ast.MergedBlock
	// Condition attribute of the block, if any.
	Condition *hclsyntax.Attribute
	// Content attribute of the block
	Content *hclsyntax.Attribute
	// Context of the generation (stack by default).
	Context string
	// Asserts represents all assert blocks
	Asserts []AssertConfig
}

GenFileBlock represents a parsed generate_file block

type GenHCLBlock

type GenHCLBlock struct {
	// Range is the range of the entire block definition.
	Range info.Range
	// Label of the block.
	Label string
	// Lets is a block of local variables.
	Lets *ast.MergedBlock
	// Condition attribute of the block, if any.
	Condition *hclsyntax.Attribute
	// Content block.
	Content *hclsyntax.Block
	// Asserts represents all assert blocks
	Asserts []AssertConfig
}

GenHCLBlock represents a parsed generate_hcl block.

type GenerateConfig

type GenerateConfig struct {
	Files []GenFileBlock
	HCLs  []GenHCLBlock
}

GenerateConfig includes code generation related configurations, like generate_file and generate_hcl.

type GitConfig

type GitConfig struct {
	// DefaultBranchBaseRef is the baseRef when in default branch.
	DefaultBranchBaseRef string

	// DefaultBranch is the default branch.
	DefaultBranch string

	// DefaultRemote is the default remote.
	DefaultRemote string

	// CheckUntracked enables untracked files checking.
	CheckUntracked bool

	// CheckUncommitted enables uncommitted files checking.
	CheckUncommitted bool

	// CheckRemote enables checking if local default branch is updated with remote.
	CheckRemote bool
}

GitConfig represents Terramate Git configuration.

func NewGitConfig

func NewGitConfig() *GitConfig

NewGitConfig creates a git configuration with proper default values.

type ManifestConfig

type ManifestConfig struct {
	Default *ManifestDesc
}

ManifestConfig represents the manifest config block of a Terramate configuration.

type ManifestDesc

type ManifestDesc struct {
	// Files is a list of patterns that specify which files the manifest wants to include.
	Files []string

	// Excludes is a list of patterns that specify which files the manifest wants to exclude.
	Excludes []string
}

ManifestDesc represents a parsed manifest description.

type RawConfig

type RawConfig struct {
	// MergedAttributes are the top-level attributes of all files.
	// This will be available after calling Parse or ParseConfig
	MergedAttributes ast.Attributes

	// MergedBlocks are the merged blocks from all files.
	// This will be available after calling Parse or ParseConfig
	MergedBlocks ast.MergedBlocks

	// MergedLabelBlocks are the labelled merged blocks.
	// This will be available after calling Parse or ParseConfig
	MergedLabelBlocks ast.MergedLabelBlocks

	// UnmergedBlocks are the unmerged blocks from all files.
	// This will be available after calling Parse or ParseConfig
	UnmergedBlocks ast.Blocks
	// contains filtered or unexported fields
}

RawConfig is the configuration (attributes and blocks) without schema validations.

func NewCustomRawConfig

func NewCustomRawConfig(handlers map[string]mergeHandler) RawConfig

NewCustomRawConfig returns a new customized RawConfig.

func NewTopLevelRawConfig

func NewTopLevelRawConfig() RawConfig

NewTopLevelRawConfig returns a new RawConfig object tailored for the Terramate top-level attributes and blocks.

func (RawConfig) Copy

func (cfg RawConfig) Copy() RawConfig

Copy cfg into a new RawConfig

func (*RawConfig) Merge

func (cfg *RawConfig) Merge(other RawConfig) error

Merge the config with the provided other config.

type RootConfig

type RootConfig struct {
	Git *GitConfig
	Run *RunConfig
}

RootConfig represents the root config block of a Terramate configuration.

type RunConfig

type RunConfig struct {
	// CheckGenCode enables generated code is up-to-date check on run.
	CheckGenCode bool

	// Env contains environment definitions for run.
	Env *RunEnv
}

RunConfig represents Terramate run configuration.

type RunEnv

type RunEnv struct {
	// Attributes is the collection of attribute definitions within the env block.
	Attributes ast.Attributes
}

RunEnv represents Terramate run environment.

type Stack

type Stack struct {
	// ID of the stack. If the ID is empty it indicates this stack has no ID.
	ID string

	// Name of the stack
	Name string

	// Description of the stack
	Description string

	// Tags is a list of non-duplicated list of tags
	Tags []string

	// After is a list of non-duplicated stack entries that must run before the
	// current stack runs.
	After []string

	// Before is a list of non-duplicated stack entries that must run after the
	// current stack runs.
	Before []string

	// Wants is a list of non-duplicated stack entries that must be selected
	// whenever the current stack is selected.
	Wants []string

	// WantedBy is a list of non-duplicated stack entries that must select
	// this stack whenever they are selected.
	WantedBy []string

	// Watch is a list of files to be watched for changes.
	Watch []string
}

Stack is the parsed "stack" HCL block.

type Terramate

type Terramate struct {
	// RequiredVersion contains the terramate version required by the stack.
	RequiredVersion string

	// RequiredVersionAllowPreReleases allows pre-release to be matched if true.
	RequiredVersionAllowPreReleases bool

	// Config is the parsed config blocks.
	Config *RootConfig
}

Terramate is the parsed "terramate" HCL block.

type TerramateParser

type TerramateParser struct {
	Config   RawConfig
	Imported RawConfig
	// contains filtered or unexported fields
}

TerramateParser is an HCL parser tailored for Terramate configuration schema. As the Terramate configuration can span multiple files in the same directory, this API allows you to define the exact set of files (and contents) that are going to be included in the final configuration.

func NewStrictTerramateParser

func NewStrictTerramateParser(rootdir string, dir string) (*TerramateParser, error)

NewStrictTerramateParser is like NewTerramateParser but will fail instead of warn for harmless configuration mistakes.

func NewTerramateParser

func NewTerramateParser(rootdir string, dir string) (*TerramateParser, error)

NewTerramateParser creates a Terramate parser for the directory dir inside the root directory. The parser creates sub-parsers for parsing imports but keeps a list of all parsed files of all sub-parsers for detecting cycles and import duplications. Calling Parse() or MinimalParse() multiple times is an error.

func (*TerramateParser) AddDir

func (p *TerramateParser) AddDir(dir string) error

AddDir walks over all the files in the directory dir and add all .tm and .tm.hcl files to the parser.

func (*TerramateParser) AddFile

func (p *TerramateParser) AddFile(path string) error

AddFile adds a file path to be parsed.

func (*TerramateParser) AddFileContent

func (p *TerramateParser) AddFileContent(name string, data []byte) error

AddFileContent adds a file to the set of files to be parsed.

func (*TerramateParser) Imports

func (p *TerramateParser) Imports() (ast.Blocks, error)

Imports returns all import blocks.

func (*TerramateParser) Parse

func (p *TerramateParser) Parse() error

Parse does the syntax parsing and merging of configurations but do not validate if the HCL schema is a valid Terramate configuration.

func (*TerramateParser) ParseConfig

func (p *TerramateParser) ParseConfig() (Config, error)

ParseConfig parses and checks the schema of previously added files and return either a Config or an error.

func (*TerramateParser) ParsedBodies

func (p *TerramateParser) ParsedBodies() map[string]*hclsyntax.Body

ParsedBodies returns a map of filename to the parsed hclsyntax.Body.

type VendorConfig

type VendorConfig struct {
	// Manifest is the parsed manifest block, if any.
	Manifest *ManifestConfig

	// Dir is the path where vendored projects will be stored.
	Dir string
}

VendorConfig is the parsed "vendor" HCL block.