hcl

package
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2024 License: MPL-2.0 Imports: 23 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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.

View Source 
const (
	ErrScriptNoLabels            errors.Kind = "terramate schema error: (script): must provide at least one label"
	ErrScriptRedeclared          errors.Kind = "terramate schema error: (script): multiple script blocks with same labels in the same directory"
	ErrScriptUnrecognizedAttr    errors.Kind = "terramate schema error: (script): unrecognized attribute"
	ErrScriptJobUnrecognizedAttr errors.Kind = "terramate schema error: (script.job): unrecognized attribute"
	ErrScriptUnrecognizedBlock   errors.Kind = "terramate schema error: (script): unrecognized block"
	ErrScriptNoCmds              errors.Kind = "terramate schema error: (script): missing command or commands"
	ErrScriptMissingOrInvalidJob errors.Kind = "terramate schema error: (script): missing or invalid job"
	ErrScriptCmdConflict         errors.Kind = "terramate schema error: (script): conflicting attribute already set"
)

Errors returned during the HCL parsing of script block

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

Variables

This section is empty.

Functions

func IsRootConfig added in v0.4.4 

func IsRootConfig(rootdir string) (bool, error)

IsRootConfig parses rootdir and tells if it contains a root config or not.

func MatchAnyGlob added in v0.4.5 

func MatchAnyGlob(globs []glob.Glob, s string) bool

MatchAnyGlob is a helper function to test if s matches any of the given patterns.

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 CloudConfig added in v0.4.3 

type CloudConfig struct {
	// Organization is the name of the cloud organization
	Organization string
}

CloudConfig represents Terramate cloud configuration.

type Command added in v0.4.4 

type Command ast.Attribute

Command represents an executable command

func NewScriptCommand added in v0.4.4 

func NewScriptCommand(attr ast.Attribute) *Command

NewScriptCommand returns a *Command encapsulating an ast.Attribute

type Commands added in v0.4.4 

type Commands ast.Attribute

Commands represents a list of executable commands

func NewScriptCommands added in v0.4.4 

func NewScriptCommands(attr ast.Attribute) *Commands

NewScriptCommands returns *Commands encapsulating an ast.Attribute

type Config 

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

	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, experiments ...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) Experiments added in v0.4.4 

func (c Config) Experiments() []string

Experiments returns the config enabled experiments, if any.

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 {
	// Dir where the block is declared.
	Dir project.Path

	// 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
	// Represents all stack_filter blocks
	StackFilters []StackFilterConfig
	// Content attribute of the block
	Content *hclsyntax.Attribute
	// Context of the generation (stack by default).
	Context string
	// Asserts represents all assert blocks
	Asserts []AssertConfig

	// Inherit tells if the block is inherited in child directories.
	Inherit *hclsyntax.Attribute
}

GenFileBlock represents a parsed generate_file block

type GenHCLBlock 

type GenHCLBlock struct {
	// Dir where the block is declared.
	Dir project.Path

	// 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
	// Represents all stack_filter blocks
	StackFilters []StackFilterConfig
	// Content block.
	Content *hcl.Block
	// Asserts represents all assert blocks
	Asserts []AssertConfig

	// Inherit tells if the block is inherited in child directories.
	Inherit *hclsyntax.Attribute

	// IsImplicitBlock tells if the block is implicit (does not have a real generate_hcl block).
	// This is the case for the "tmgen" feature.
	IsImplicitBlock bool
}

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 GenerateRootConfig added in v0.5.0 

type GenerateRootConfig struct {
	HCLMagicHeaderCommentStyle *string
}

GenerateRootConfig represents the AST node for the `terramate.config.generate` block.

type GitConfig 

type GitConfig struct {
	// 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 OptionalCheck
}

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 OptionalCheck added in v0.4.4 

type OptionalCheck int

OptionalCheck is a bool that can also have no configured value. 

const (
	// CheckIsUnset means no value was specified.
	CheckIsUnset OptionalCheck = iota
	// CheckIsFalse means the check is disabled.
	CheckIsFalse
	// CheckIsTrue means the check is enabled.
	CheckIsTrue
)

func ToOptionalCheck added in v0.4.4 

func ToOptionalCheck(v bool) OptionalCheck

ToOptionalCheck creates an OptionalCheck value from a bool.

func (OptionalCheck) ValueOr added in v0.4.4 

func (v OptionalCheck) ValueOr(def bool) bool

ValueOr returns if an OptionalCheck is enabled, or the given default if its unset.

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
	Generate          *GenerateRootConfig
	Run               *RunConfig
	Cloud             *CloudConfig
	Experiments       []string
	DisableSafeguards safeguard.Keywords
}

RootConfig represents the root config block of a Terramate configuration.

func (*RootConfig) HasSafeguardDisabled added in v0.4.5 

func (r *RootConfig) HasSafeguardDisabled(keyword safeguard.Keyword) bool

HasSafeguardDisabled checks if the configuration (including the deprecated) has the given keyword disabled.

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.

func NewRunConfig added in v0.4.5 

func NewRunConfig() *RunConfig

NewRunConfig creates a new 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 Script added in v0.4.4 

type Script struct {
	Range       info.Range
	Labels      []string       // Labels of the script block used for grouping scripts
	Name        *ast.Attribute // Name of the script
	Description *ast.Attribute // Description is a human readable description of a script
	Jobs        []*ScriptJob   // Job represents the command(s) part of this script
}

Script represents a parsed script block

func (*Script) AccessorName added in v0.5.0 

func (sc *Script) AccessorName() string

AccessorName returns the name traversal for accessing the script.

type ScriptJob added in v0.4.4 

type ScriptJob struct {
	Name        *ast.Attribute
	Description *ast.Attribute
	Command     *Command  // Command is a single executable command
	Commands    *Commands // Commands is a list of executable commands
}

ScriptJob represent a Job within a Script

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 StackFilterConfig added in v0.4.4 

type StackFilterConfig struct {
	ProjectPaths    []glob.Glob
	RepositoryPaths []glob.Glob
}

StackFilterConfig represents Terramate stack_filter configuration 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
	Experiments []string
	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, experiments ...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, experiments ...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.

Source Files

View all Source files

Directories

Path Synopsis
Package ast provides low level parsing facilities for HCL configuration.
 Package ast provides low level parsing facilities for HCL configuration.
Package eval provides both full and partial evaluation of HCL.
 Package eval provides both full and partial evaluation of HCL.
Package fmt contains functions for formatting hcl config.
 Package fmt contains functions for formatting hcl config.
Package info provides informational types related to hcl.
 Package info provides informational types related to hcl.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.