path

package
v1.12.0 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2024 License: MPL-2.0 Imports: 3 Imported by: 402

Documentation

Overview

Package path implements attribute path functionality, which defines transversals into schema-based data.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Expression

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

Expression represents an attribute path with expression steps, which can represent zero, one, or more actual paths in schema data. This logic is either based on an absolute path starting at the root of the schema data, similar to Path, or a relative path which is intended to be merged with an existing absolute path.

Use the MatchRoot() function to create an Expression for an absolute path with an initial AtName() step. Use the MatchRelative() function to create an Expression for a relative path, which will be merged with an existing absolute path.

Similar to Path, Expression functionality has some overlapping method names and follows a builder pattern, which allows for chaining method calls to construct a full expression. The available traversal steps after Expression creation are:

  • AtAnyListIndex(): Step into a list at any index
  • AtAnyMapKey(): Step into a map at any key
  • AtAnySetValue(): Step into a set at any attr.Value element
  • AtListIndex(): Step into a list at a specific index
  • AtMapKey(): Step into a map at a specific key
  • AtName(): Step into an attribute or block with a specific name
  • AtParent(): Step backwards one step
  • AtSetValue(): Step into a set at a specific attr.Value element

For example, to express any list element with a root list attribute named "some_attribute":

path.MatchRoot("some_attribute").AtAnyListIndex()

An Expression is generally preferable over a Path in schema-defined functionality that is intended to accept paths as parameters, such as attribute validators and attribute plan modifiers, since it allows consumers to support relative paths. Use the Merge() or MergeExpressions() method to combine the current attribute path expression with those expression(s).

To find Paths from an Expression in schema based data structures, such as tfsdk.Config, tfsdk.Plan, and tfsdk.State, use their PathMatches() method.

func MatchRelative

func MatchRelative() Expression

MatchRelative creates an empty attribute path expression that is intended to be combined with an existing attribute path expression. This allows creating a relative expression in nested schemas, using AtParent() to traverse up the path or other At methods to traverse further down.

func MatchRoot

func MatchRoot(rootAttributeName string) Expression

MatchRoot creates an attribute path expression starting with ExpressionStepAttributeNameExact.

func (Expression) AtAnyListIndex

func (e Expression) AtAnyListIndex() Expression

AtAnyListIndex returns a copied expression with a new list index step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtAnyMapKey

func (e Expression) AtAnyMapKey() Expression

AtAnyMapKey returns a copied expression with a new map key step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtAnySetValue

func (e Expression) AtAnySetValue() Expression

AtAnySetValue returns a copied expression with a new set value step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtListIndex

func (e Expression) AtListIndex(index int) Expression

AtListIndex returns a copied expression with a new list index step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtMapKey

func (e Expression) AtMapKey(key string) Expression

AtMapKey returns a copied expression with a new map key step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtName

func (e Expression) AtName(name string) Expression

AtName returns a copied expression with a new attribute or block name step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtParent

func (e Expression) AtParent() Expression

AtParent returns a copied expression with a new parent step at the end. The returned path is safe to modify without affecting the original.

func (Expression) AtSetValue

func (e Expression) AtSetValue(value attr.Value) Expression

AtSetValue returns a copied expression with a new set value step at the end. The returned path is safe to modify without affecting the original.

func (Expression) Copy

func (e Expression) Copy() Expression

Copy returns a duplicate of the expression that is safe to modify without affecting the original.

func (Expression) Equal

func (e Expression) Equal(o Expression) bool

Equal returns true if the given expression is exactly equivalent.

func (Expression) Matches

func (e Expression) Matches(path Path) bool

Matches returns true if the given Path is valid for the Expression. Any relative expression steps, such as ExpressionStepParent, are automatically resolved before matching.

func (Expression) MatchesParent

func (e Expression) MatchesParent(path Path) bool

MatchesParent returns true if the given Path is a valid parent for the Expression. This is helpful for determining if a child Path would potentially match the full Expression during depth-first traversal. Any relative expression steps, such as ExpressionStepParent, are automatically resolved before matching.

func (Expression) Merge

func (e Expression) Merge(other Expression) Expression

Merge returns a copied expression either with the steps of the given expression added to the end of the existing steps, or overwriting the steps if the given expression was a root expression.

Any merged expressions will preserve all expressions steps, such as ExpressionStepParent, for troubleshooting. Methods such as Matches() will automatically resolve the expression when using it. Call the Resolve() method explicitly if a resolved expression without any ExpressionStepParent is desired.

func (Expression) MergeExpressions

func (e Expression) MergeExpressions(others ...Expression) Expressions

MergeExpressions returns collection of expressions that calls Merge() on the current expression with each of the others.

If no Expression are given, then it will return a collection of expressions containing only the current expression.

func (Expression) Resolve

func (e Expression) Resolve() Expression

Resolve returns a copied expression with any relative steps, such as ExpressionStepParent, resolved. This is not necessary before calling methods such as Matches(), however it can be useful before returning the String() method so the path information is simplified.

Returns an empty expression if any ExpressionStepParent attempt to go beyond the first element.

func (Expression) Steps

func (e Expression) Steps() ExpressionSteps

Steps returns a copy of the underlying expression steps. Returns an empty collection of steps if expression is nil.

func (Expression) String

func (e Expression) String() string

String returns the human-readable representation of the path. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStep

type ExpressionStep interface {
	// Equal should return true if the given Step is exactly equivalent.
	Equal(ExpressionStep) bool

	// Matches should return true if the given PathStep can be fulfilled by the
	// ExpressionStep.
	Matches(PathStep) bool

	// String should return a human-readable representation of the step
	// intended for logging and error messages. There should not be usage
	// that needs to be protected by compatibility guarantees.
	String() string
	// contains filtered or unexported methods
}

ExpressionStep represents an expression of an attribute path step, which may match zero, one, or more actual paths.

type ExpressionStepAttributeNameExact

type ExpressionStepAttributeNameExact string

ExpressionStepAttributeNameExact is an attribute path expression for an exact attribute name match within an object.

func (ExpressionStepAttributeNameExact) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepAttributeNameExact and the attribute name is equivalent.

func (ExpressionStepAttributeNameExact) Matches

func (s ExpressionStepAttributeNameExact) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepAttributeNameExact condition.

func (ExpressionStepAttributeNameExact) String

String returns the human-readable representation of the attribute name expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyIntAny

type ExpressionStepElementKeyIntAny struct{}

ExpressionStepElementKeyIntAny is an attribute path expression for a matching any integer element key within a list.

func (ExpressionStepElementKeyIntAny) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyIntAny.

func (ExpressionStepElementKeyIntAny) Matches

func (s ExpressionStepElementKeyIntAny) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyIntAny condition.

func (ExpressionStepElementKeyIntAny) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyIntExact

type ExpressionStepElementKeyIntExact int64

ExpressionStepElementKeyIntExact is an attribute path expression for an exact integer element key match within a list. List indexing starts at 0.

func (ExpressionStepElementKeyIntExact) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyIntExact and the integer element key is equivalent.

func (ExpressionStepElementKeyIntExact) Matches

func (s ExpressionStepElementKeyIntExact) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyIntExact condition.

func (ExpressionStepElementKeyIntExact) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyStringAny

type ExpressionStepElementKeyStringAny struct{}

ExpressionStepElementKeyStringAny is an attribute path expression for a matching any string key within a map.

func (ExpressionStepElementKeyStringAny) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyStringAny.

func (ExpressionStepElementKeyStringAny) Matches

func (s ExpressionStepElementKeyStringAny) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyStringAny condition.

func (ExpressionStepElementKeyStringAny) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyStringExact

type ExpressionStepElementKeyStringExact string

ExpressionStepElementKeyStringExact is an attribute path expression for an exact string key within a map. Map keys are always strings.

func (ExpressionStepElementKeyStringExact) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyStringExact and the string element key is equivalent.

func (ExpressionStepElementKeyStringExact) Matches

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyStringExact condition.

func (ExpressionStepElementKeyStringExact) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyValueAny

type ExpressionStepElementKeyValueAny struct{}

ExpressionStepElementKeyValueAny is an attribute path expression for a matching any Value element within a set.

func (ExpressionStepElementKeyValueAny) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyValueAny.

func (ExpressionStepElementKeyValueAny) Matches

func (s ExpressionStepElementKeyValueAny) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyValueAny condition.

func (ExpressionStepElementKeyValueAny) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepElementKeyValueExact

type ExpressionStepElementKeyValueExact struct {
	// Value is an interface, so it cannot be type aliased with methods.
	attr.Value
}

ExpressionStepElementKeyValueExact is an attribute path expression for an exact Value element within a set. Sets do not use integer-based indexing.

func (ExpressionStepElementKeyValueExact) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepElementKeyValueExact and the Value element key is equivalent.

func (ExpressionStepElementKeyValueExact) Matches

func (s ExpressionStepElementKeyValueExact) Matches(pathStep PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepElementKeyValueExact condition.

func (ExpressionStepElementKeyValueExact) String

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionStepParent

type ExpressionStepParent struct{}

StepParent is an attribute path expression for a traversing to the parent attribute path relative to the current one. This is intended only for the start of attribute-level expressions which will be combined with the current attribute path being called.

func (ExpressionStepParent) Equal

Equal returns true if the given ExpressionStep is a ExpressionStepParent.

func (ExpressionStepParent) Matches

func (s ExpressionStepParent) Matches(_ PathStep) bool

Matches returns true if the given PathStep is fulfilled by the ExpressionStepParent condition.

func (ExpressionStepParent) String

func (s ExpressionStepParent) String() string

String returns the human-readable representation of the element key expression. It is intended for logging and error messages and is not protected by compatibility guarantees.

type ExpressionSteps

type ExpressionSteps []ExpressionStep

ExpressionSteps represents an ordered collection of attribute path expressions.

func (*ExpressionSteps) Append

func (s *ExpressionSteps) Append(steps ...ExpressionStep) ExpressionSteps

Append adds the given ExpressionSteps to the end of the previous ExpressionSteps and returns the combined result.

func (ExpressionSteps) Copy

Copy returns a duplicate of the steps that is safe to modify without affecting the original. Returns nil if the original steps is nil.

func (ExpressionSteps) Equal

Equal returns true if the given ExpressionSteps are equivalent.

func (ExpressionSteps) LastStep

LastStep returns the final ExpressionStep and the remaining ExpressionSteps.

func (ExpressionSteps) Matches

func (s ExpressionSteps) Matches(pathSteps PathSteps) bool

Matches returns true if the given PathSteps match each ExpressionStep.

Any ExpressionStepParent will automatically be resolved.

func (ExpressionSteps) MatchesParent

func (s ExpressionSteps) MatchesParent(pathSteps PathSteps) bool

MatchesParent returns true if the given PathSteps match each ExpressionStep until there are no more PathSteps. This is helpful for determining if the PathSteps would potentially match the full ExpressionSteps during depth-first traversal.

Any ExpressionStepParent will automatically be resolved.

func (ExpressionSteps) NextStep

NextStep returns the first ExpressionStep and the remaining ExpressionSteps.

func (ExpressionSteps) Resolve

func (s ExpressionSteps) Resolve() ExpressionSteps

Resolve returns a copy of ExpressionSteps without any ExpressionStepParent.

Returns empty ExpressionSteps if any ExpressionStepParent attempt to go beyond the first element. Returns nil if the original steps is nil.

func (ExpressionSteps) String

func (s ExpressionSteps) String() string

String returns the human-readable representation of the ExpressionSteps. It is intended for logging and error messages and is not protected by compatibility guarantees.

type Expressions

type Expressions []Expression

Expressions is a collection of attribute path expressions.

Refer to the Expression documentation for more details about intended usage.

func (*Expressions) Append

func (e *Expressions) Append(expressions ...Expression) Expressions

Append adds the given Expressions to the collection without duplication and returns the combined result.

func (Expressions) Contains

func (e Expressions) Contains(checkExpression Expression) bool

Contains returns true if the collection of expressions includes the given expression.

func (Expressions) Matches added in v1.1.0

func (e Expressions) Matches(checkPath Path) bool

Matches returns true if one of the expressions in the collection matches the given path.

func (Expressions) String

func (p Expressions) String() string

String returns the human-readable representation of the expression collection. It is intended for logging and error messages and is not protected by compatibility guarantees.

Empty expressions are skipped.

type Path

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

Path represents exact traversal steps into a schema or schema-based data. These steps always start from the root of the schema, which is an object with zero or more attributes and blocks.

Use the Root() function to create a Path with an initial AtName() step. Path functionality follows a builder pattern, which allows for chaining method calls to construct a full path. The available traversal steps after Path creation are:

  • AtListIndex(): Step into a list at a specific 0-based index
  • AtMapKey(): Step into a map at a specific key
  • AtName(): Step into an attribute or block with a specific name
  • AtSetValue(): Step into a set at a specific attr.Value element

For example, to represent the first list element with a root list attribute named "some_attribute":

path.MatchRoot("some_attribute").AtListIndex(0)

Path is used for functionality which must exactly match the underlying schema structure and types, such as diagnostics that are intended for a specific attribute or working with specific attribute values in a schema based data structure such as tfsdk.Config, tfsdk.Plan, or tfsdk.State.

Refer to Expression for situations where relative or wildcard step logic is desirable for schema defined functionality, such as attribute validators or attribute plan modifiers.

func Empty

func Empty() Path

Empty creates an empty attribute path. Provider code should use Root.

func Root

func Root(rootAttributeName string) Path

Root creates an attribute path starting with a PathStepAttributeName.

func (Path) AtListIndex

func (p Path) AtListIndex(index int) Path

AtListIndex returns a copied path with a new list index step at the end. The returned path is safe to modify without affecting the original.

List indices are 0-based. The first element of a list is 0.

func (Path) AtMapKey

func (p Path) AtMapKey(key string) Path

AtMapKey returns a copied path with a new map key step at the end. The returned path is safe to modify without affecting the original.

func (Path) AtName

func (p Path) AtName(name string) Path

AtName returns a copied path with a new attribute or block name step at the end. The returned path is safe to modify without affecting the original.

func (Path) AtSetValue

func (p Path) AtSetValue(value attr.Value) Path

AtSetValue returns a copied path with a new set value step at the end. The returned path is safe to modify without affecting the original.

func (Path) AtTupleIndex added in v1.6.0

func (p Path) AtTupleIndex(index int) Path

AtTupleIndex returns a copied path with a new tuple index step at the end. The returned path is safe to modify without affecting the original.

Tuple indices are 0-based. The first element of a tuple is 0.

func (Path) Copy

func (p Path) Copy() Path

Copy returns a duplicate of the path that is safe to modify without affecting the original.

func (Path) Equal

func (p Path) Equal(o Path) bool

Equal returns true if the given path is exactly equivalent.

func (Path) Expression

func (p Path) Expression() Expression

Expression returns an Expression which exactly matches the Path.

func (Path) ParentPath

func (p Path) ParentPath() Path

ParentPath returns a copy of the path with the last step removed.

If the current path is empty, an empty path is returned.

func (Path) Steps

func (p Path) Steps() PathSteps

Steps returns a copy of the underlying path steps. Returns an empty collection of steps if path is nil.

func (Path) String

func (p Path) String() string

String returns the human-readable representation of the path. It is intended for logging and error messages and is not protected by compatibility guarantees.

type PathStep

type PathStep interface {
	// Equal should return true if the given PathStep is exactly equivalent.
	Equal(PathStep) bool

	// ExpressionStep should return an ExpressionStep which exactly
	// matches the PathStep.
	ExpressionStep() ExpressionStep

	// String should return a human-readable representation of the step
	// intended for logging and error messages. There should not be usage
	// that needs to be protected by compatibility guarantees.
	String() string
	// contains filtered or unexported methods
}

PathStep represents a transversal for an attribute path. Only exact path transversals are supported as implementations of this interface must remain compatible with all protocol implementations.

type PathStepAttributeName

type PathStepAttributeName string

PathStepAttributeName is an attribute path tranversal for an attribute name within an object.

List elements must be transversed by PathStepElementKeyInt. Map elements must be transversed by PathStepElementKeyString. Set elements must be transversed by PathStepElementKeyValue.

func (PathStepAttributeName) Equal

func (s PathStepAttributeName) Equal(o PathStep) bool

Equal returns true if the given PathStep is a PathStepAttributeName and the attribute name is equivalent.

func (PathStepAttributeName) ExpressionStep

func (s PathStepAttributeName) ExpressionStep() ExpressionStep

ExpressionStep returns the ExpressionStep for the PathStep.

func (PathStepAttributeName) String

func (s PathStepAttributeName) String() string

String returns the human-readable representation of the attribute name. It is intended for logging and error messages and is not protected by compatibility guarantees.

type PathStepElementKeyInt

type PathStepElementKeyInt int64

PathStepElementKeyInt is an attribute path transversal for an integer element of a list. List indexing starts a 0.

Map elements must be transversed by PathStepElementKeyString. Object attributes must be transversed by PathStepAttributeName. Set elements must be transversed by PathStepElementKeyValue.

func (PathStepElementKeyInt) Equal

func (s PathStepElementKeyInt) Equal(o PathStep) bool

Equal returns true if the given PathStep is a PathStepAttributeName and the attribute name is equivalent.

func (PathStepElementKeyInt) ExpressionStep

func (s PathStepElementKeyInt) ExpressionStep() ExpressionStep

ExpressionStep returns the ExpressionStep for the PathStep.

func (PathStepElementKeyInt) String

func (s PathStepElementKeyInt) String() string

String returns the human-readable representation of the element key. It is intended for logging and error messages and is not protected by compatibility guarantees.

type PathStepElementKeyString

type PathStepElementKeyString string

PathStepElementKeyString is an attribute path transversal for a string key of a map. Map keys are always strings.

List elements must be transversed by PathStepElementKeyInt. Object attributes must be transversed by PathStepAttributeName. Set elements must be transversed by PathStepElementKeyValue.

func (PathStepElementKeyString) Equal

Equal returns true if the given PathStep is a PathStepAttributeName and the attribute name is equivalent.

func (PathStepElementKeyString) ExpressionStep

func (s PathStepElementKeyString) ExpressionStep() ExpressionStep

ExpressionStep returns the ExpressionStep for the PathStep.

func (PathStepElementKeyString) String

func (s PathStepElementKeyString) String() string

String returns the human-readable representation of the element key. It is intended for logging and error messages and is not protected by compatibility guarantees.

type PathStepElementKeyValue

type PathStepElementKeyValue struct {
	// Value is an interface, so it cannot be type aliased with methods.
	attr.Value
}

PathStepElementKeyValue is an attribute path transversal for a Value element of a set. Sets do not use integer-based indexing.

List elements must be transversed by PathStepElementKeyInt. Map elements must be transversed by PathStepElementKeyString. Object attributes must be transversed by PathStepAttributeName.

func (PathStepElementKeyValue) Equal

Equal returns true if the given PathStep is a PathStepAttributeName and the attribute name is equivalent.

func (PathStepElementKeyValue) ExpressionStep

func (s PathStepElementKeyValue) ExpressionStep() ExpressionStep

ExpressionStep returns the ExpressionStep for the PathStep.

func (PathStepElementKeyValue) String

func (s PathStepElementKeyValue) String() string

String returns the human-readable representation of the element key. It is intended for logging and error messages and is not protected by compatibility guarantees.

type PathSteps

type PathSteps []PathStep

PathSteps represents an ordered collection of attribute path transversals.

func (*PathSteps) Append

func (s *PathSteps) Append(steps ...PathStep) PathSteps

Append adds the given PathSteps to the end of the previous PathSteps and returns the combined result.

func (PathSteps) Copy

func (s PathSteps) Copy() PathSteps

Copy returns a duplicate of the steps that is safe to modify without affecting the original. Returns nil if the original steps is nil.

func (PathSteps) Equal

func (s PathSteps) Equal(o PathSteps) bool

Equal returns true if the given PathSteps are equivalent.

func (PathSteps) ExpressionSteps

func (s PathSteps) ExpressionSteps() ExpressionSteps

ExpressionSteps returns the ordered collection of expression steps which exactly matches the PathSteps.

func (PathSteps) LastStep

func (s PathSteps) LastStep() (PathStep, PathSteps)

LastStep returns the final PathStep and the remaining PathSteps.

func (PathSteps) NextStep

func (s PathSteps) NextStep() (PathStep, PathSteps)

NextStep returns the first PathStep and the remaining PathSteps.

func (PathSteps) String

func (s PathSteps) String() string

String returns the human-readable representation of the PathSteps. It is intended for logging and error messages and is not protected by compatibility guarantees.

type Paths

type Paths []Path

Paths is a collection of exact attribute paths.

Refer to the Path documentation for more details about intended usage.

func (*Paths) Append

func (p *Paths) Append(paths ...Path) Paths

Append adds the given Paths to the collection without duplication and returns the combined result.

func (Paths) Contains

func (p Paths) Contains(checkPath Path) bool

Contains returns true if the collection of paths includes the given path.

func (Paths) String

func (p Paths) String() string

String returns the human-readable representation of the path collection. It is intended for logging and error messages and is not protected by compatibility guarantees.

Empty paths are skipped.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL