spec

README

Spec

Package spec provides a wrapper around reading from and using HCL-based configuration and markup files, such as those used by Contaim. This package is not intended for public consumption yet, we will most likely have breaking API changes.

Documentation

Overview

Package spec provides schema specification parsing for Response's HCL/JSON-based configuration and data files. This package is a convenience wrapper around the hcl/v2 package itself and adds helpers for dealing with our specifications directly. This is likely not useful if you do not need to parse one of our schema files or something similar.

Index

• Constants
• type Diagnostics
  • func (d *Diagnostics) Error() string
  • func (d *Diagnostics) Errs() []error
  • func (d *Diagnostics) HasErrors() bool
  • func (d *Diagnostics) Raw() hcl.Diagnostics
  • func (d *Diagnostics) WriteText(to io.Writer, width uint, color bool) error
• type Spec
  • func New(defs parser.NamedBlockDefinitions) *Spec
  • func NewSubset(defs ...parser.NamedBlockDefinition) *Spec
  • func (s *Spec) Body() hcl.Body
  • func (s *Spec) Build() hcldec.Spec
  • func (s *Spec) Decode(ctx *hcl.EvalContext, val interface{}) *Diagnostics
  • func (s *Spec) FileGlob(pattern string) *Diagnostics
  • func (s *Spec) Files(filenames ...string) *Diagnostics
  • func (s *Spec) Parse(ctx *hcl.EvalContext) *Diagnostics
  • func (s *Spec) ParseHCL(src []byte, filename string) *Diagnostics
  • func (s *Spec) ParseHCLFile(filename string) *Diagnostics
  • func (s *Spec) ParseJSON(src []byte, filename string) *Diagnostics
  • func (s *Spec) ParseJSONFile(filename string) *Diagnostics
  • func (s *Spec) ParsedFiles() []string
  • func (s *Spec) Registrations() []*parser.Registration

Constants

const (
	DiagCannotDetermineFileType       = "Cannot determine file type based on extension, only .json and .hcl files are supported"
	DiagCannotDetermineFileTypeDetail = "You must provide a file with either a .json or .hcl extension, only json and hcl files are supported"

	DiagGlobError       = "There was a problem parsing the file pattern"
	DiagGlobErrorDetail = "The file pattern was not able to be parsed. This might be an implementation problem."
)

diagnostic messages

Types

type Diagnostics

type Diagnostics struct {
	Spec  *Spec
	Diags hcl.Diagnostics
}

Diagnostics is used to represent a number of diagnostics returned from various places in Spec parsing and file reading. Diagnostics is general purpose in nature and is meant to be displayed to the end-user and read by machine.

func (*Diagnostics) Error

func (d *Diagnostics) Error() string

Error returns all of the diagnostics coerced into a string meant to be shown to the end-user. In general this should likely be avoided and you should use WriteText instead.

func (*Diagnostics) Errs

func (d *Diagnostics) Errs() []error

Errs returns all of the native Go error interfaces for the diagnostics returned.

func (*Diagnostics) HasErrors

func (d *Diagnostics) HasErrors() bool

HasErrors simply returns true if there are errors within this Diagnostics instance. If no errors this will return false.

func (*Diagnostics) Raw

func (d *Diagnostics) Raw() hcl.Diagnostics

Raw returns the raw hcl.Diagnostics instance. This is useful if you need to interact with the raw implementation rather than the sugared version we provide. In most cases you won't need this.

func (*Diagnostics) WriteText

func (d *Diagnostics) WriteText(to io.Writer, width uint, color bool) error

WriteText writes the output in a format easily understood by humans to the provided io.Writer. This is useful for showing the output of the diagnostics to end-users in a CLI environment but less useful when the caller is an application.

Setting the width to 0 disables word wrapping. Setting the color to false will disable coloring of key information in the output. The output will contain relevant context such as line numbers and code snippets.

type Spec

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

Spec represents a single type of HCL/JSON schema variant and provides helpers to easily parse raw bytes, files, and more against the schema. The Spec returns a custom Diagnostics rather than the hcl.Diagnostics allowing easy manipulation of our own errors.

func New

func New(defs parser.NamedBlockDefinitions) *Spec

New creates a new Spec instance with the pre-ordered slice of parser.NamedBlockDefiniion instances provided. This is the typical API where you will use the Schema variable from a particular schema.

func NewSubset

func NewSubset(defs ...parser.NamedBlockDefinition) *Spec

NewSubset creates a new Spec instance with one or more parser.NamedBlockDefinition instances provided. This is primarily useful for validating only a specific block or for performing tests.

func (*Spec) Body

func (s *Spec) Body() hcl.Body

Body returns an hcl.Body that merges all processed files into a single body for further processing.

func (*Spec) Build

func (s *Spec) Build() hcldec.Spec

Build builds an hcldec.Spec instance from all registered BlockDefinition's.

func (*Spec) Decode

func (s *Spec) Decode(ctx *hcl.EvalContext, val interface{}) *Diagnostics

Decode extracts the configuration within the given body into the given value. This value must be a non-nil pointer to either a struct or a map, where in the former case the configuration will be decoded using struct tags and in the latter case only attributes are allowed and their values are decoded into the map.

The given hcl.EvalContext is used to resolve any variables or functions in expressions encountered while decoding. This may be nil to require only constant values, for simple applications that do not support variables or functions.

The returned diagnostics should be inspected with its HasErrors method to determine if the populated value is valid and complete. If error diagnostics are returned then the given value may have been partially-populated but may still be accessed by a careful caller for static analysis and editor integration use-cases.

func (*Spec) FileGlob

func (s *Spec) FileGlob(pattern string) *Diagnostics

FileGlob works the same as Files but instead builds a list of filenames to process using the provided glob pattern.

func (*Spec) Files

func (s *Spec) Files(filenames ...string) *Diagnostics

Files accepts many file paths and processes each. All files provided will be processed against the same Spec so all files should be of the same type. If not, the diagnostics will return errors for things not expected by the current Spec.

func (*Spec) Parse

func (s *Spec) Parse(ctx *hcl.EvalContext) *Diagnostics

Parse parses the provided hcl.Body, given the hcl.EvalContext against the generated hcldec.Spec and ordered according to the order that the BlockDefinition's were defined.

func (*Spec) ParseHCL

func (s *Spec) ParseHCL(src []byte, filename string) *Diagnostics

ParseHCL parses the raw src as HCL.

func (*Spec) ParseHCLFile

func (s *Spec) ParseHCLFile(filename string) *Diagnostics

ParseHCLFile parses a single HCL file by reading it from the filesystem.

func (*Spec) ParseJSON

func (s *Spec) ParseJSON(src []byte, filename string) *Diagnostics

ParseJSON parses the raw src as JSON.

func (*Spec) ParseJSONFile

func (s *Spec) ParseJSONFile(filename string) *Diagnostics

ParseJSONFile parses a single JSON file by reading it from the filesystem.

func (*Spec) ParsedFiles

func (s *Spec) ParsedFiles() []string

ParsedFiles returns all of the filenames that we've parsed through various parsing methods.

func (*Spec) Registrations

func (s *Spec) Registrations() []*parser.Registration

Registrations returns all of the parser.Registration instances that are added to the registrar.