path: Initial Path Expression Support

[bflad]

Reference: #81
Reference: hashicorp/terraform-plugin-framework-validators#14
Reference: hashicorp/terraform-plugin-framework-validators#15
Reference: hashicorp/terraform-plugin-framework-validators#16
Reference: hashicorp/terraform-plugin-framework-validators#17
Reference: hashicorp/terraform-plugin-framework-validators#20

This introduces the concept of root and relative attribute path expressions, abstractions on top of an attribute path, which enables provider developers to declare logic which might match zero, one, or more paths.

Paths are directly convertible into path expressions as exact expression steps. The builder-like syntax for exact expression steps matches the syntax for regular path steps, such as AtName() in both cases always represents an exact transversal into the attribute name of an object. Additional expression steps enable matching any list, map, or set element, such as AtAnyListIndex(). It also supports relative attribute path expressions, by supporting a parent expression step AtParent() and starting an expression with MatchRelative() so it can be combined with a prior path expression.

The framework will automatically expose path expressions to attribute plan modifiers and validators, so they can more intuitively support relative paths as inputs to their logic. For example, the terraform-plugin-framework-validators Go module will implement support for terraform-plugin-sdk multiple attribute schema behaviors such as ConflictsWith. It is expected that the downstream implementation can allow provider developers to declare the validator with expressions such as:

tfsdk.Attribute{
	// ... other fields ...

	Validators: []AttributeValidators{
		schemavalidator.ConflictsWith(
			// Example absolute path from root
			path.MatchRoot("root_attribute"),

			// Example relative path from current attribute
			// e.g. another attribute at the same list index of ListNestedAttributes
			path.MatchRelative().AtParent().AtName("another_same_level_attribute"),
		),
	},
}

Then the logic within the validator can take the ValidateAttributeRequest.AttributePathExpression and use the (path.Expression).Merge() method to combine the current attribute expression with any incoming expressions.

To find matching attribute paths based on a path expression within tfsdk.Config, tfsdk.Plan, and tfsdk.State, a PathMatches(path.Expression) method has been added to each type. The resulting paths can then be used to fetch data via existing functionality, such as the GetAttribute() method of each type.

[detro]

Code wise is 👨‍🍳 💋

But I do have a "how do I use this?" question.

[detro]

Given the description, I was expecting an .Append() method here.

I see there is one on the ExpressionSteps, but not on the expression itself.

The reason for me asking, is that I'm trying to imagine how we would take the input for a schemavalidator, append it to the path.Expression of the attribute, and get to the referred-to attributes.

[bflad]

Oh goodness, you are absolutely right that I omitted that method. It's important to be able to merge expressions, especially in plan modifiers and validators. I'll get that pushed up shortly.

[bflad]

@detro I wound up adding the (path.Expression).Merge(path.Expression) path.Expression method and the (tfsdk.Config).PathMatches(path.Expression) path.Paths, (tfsdk.Plan).PathMatches(path.Expression) path.Paths, and (tfsdk.State).PathMatches(path.Expression) path.Paths methods, so this pull request should be more fully functional downstream for testing. Can you please take a fresh look? Thanks so much.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.