introduce pkg/fieldpath for processing field paths (#248)

In attempting to implement the nested field path support for different
source and target field Go types, I realized I needed a support package
that made working with field paths easier, including taking a field path
and finding a ShapeRef within an Output shape that matched the field
path.

This patch introduces a new `pkg/fieldpath` package with a simple `Path`
struct containing a variety of utility methods, as shown in this example
Go code snippet:

```go
import (
        "fmt"

	awssdkmodel "github.com/aws/aws-sdk-go/private/model/api"
        "github.com/aws-controllers-k8s/code-generator/pkg/fieldpath"
        "github.com/aws-controllers-k8s/code-generator/pkg/sdk"
)

...

p := fieldpath.FromString("Crawler.Schedule.ScheduleExpression")

// Will print "true"
fmt.Println(p.HasPrefix("Crawler.Schedule"))

// Will print "false"
fmt.Println(p.HasPrefix("crawler.Schedule"))

// Will print "true"
fmt.Println(p.HasPrefixFold("crawler.Schedule"))

// Will print "ScheduleExpression"
fmt.Println(p.Back())

// Will print "Crawler"
fmt.Println(p.Front())

// Find the shape within the GetCrawlerResponse shape that contains the
// field referred to by the path...
helper := sdk.NewHelper("/path/to/apis", genCfg)
api := helper.API("glue")
crawlerOutputShape := api.Shapes["GetCrawlerResponse"]

schedExpressionShape := p.ShapeRef(crawlerOutputShape)
// Will print "ScheduleExpression"
fmt.Println(schedExpressionShape.ShapeName)
```
Note that we support list and map type field paths using a single-dot
notation since we are only looking at field types and not **values**
within the list or map.

Signed-off-by: Jay Pipes <[email protected]>

Related: aws-controllers-k8s/community#1078

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license.

Author: jaypipes

pkg/fieldpath/path.go

@@ -0,0 +1,243 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"). You may
+// not use this file except in compliance with the License. A copy of the
+// License is located at
+//
+//     http://aws.amazon.com/apache2.0/
+//
+// or in the "license" file accompanying this file. This file is distributed
+// on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+package fieldpath
+
+import (
+	"encoding/json"
+	"strings"
+
+	awssdkmodel "github.com/aws/aws-sdk-go/private/model/api"
+)
+
+// Path provides a JSONPath-like struct and field-member "route" to a
+// particular field within a resource. Path implements json.Marshaler
+// interface.
+type Path struct {
+	parts []string
+}
+
+// String returns the dotted-notation representation of the Path
+func (p *Path) String() string {
+	return strings.Join(p.parts, ".")
+}
+
+// MarshalJSON returns the JSON encoding of a Path object.
+func (p *Path) MarshalJSON() ([]byte, error) {
+	// Since json.Marshal doesn't encode unexported struct fields we have to
+	// copy the Path instance into a new struct object with exported fields.
+	// See https://github.com/aws-controllers-k8s/community/issues/772
+	return json.Marshal(
+		struct {
+			Parts []string
+		}{
+			p.parts,
+		},
+	)
+}
+
+// Pop removes the last part from the Path and returns it.
+func (p *Path) Pop() (part string) {
+	if len(p.parts) > 0 {
+		part = p.parts[len(p.parts)-1]
+		p.parts = p.parts[:len(p.parts)-1]
+	}
+	return part
+}
+
+// Front returns the first part of the Path or empty string if the Path has no
+// parts.
+func (p *Path) Front() string {
+	if len(p.parts) == 0 {
+		return ""
+	}
+	return p.parts[0]
+}
+
+// PopFront removes the first part of the Path and returns it.
+func (p *Path) PopFront() (part string) {
+	if len(p.parts) > 0 {
+		part = p.parts[0]
+		p.parts = p.parts[1:]
+	}
+	return part
+}
+
+// Back returns the last part of the Path or empty string if the Path has no
+// parts.
+func (p *Path) Back() string {
+	if len(p.parts) == 0 {
+		return ""
+	}
+	return p.parts[len(p.parts)-1]
+}
+
+// PushBack adds a new part to the end of the Path.
+func (p *Path) PushBack(part string) {
+	p.parts = append(p.parts, part)
+}
+
+// Copy returns a new Path that is a copy of this Path
+func (p *Path) Copy() *Path {
+	return &Path{p.parts}
+}
+
+// Empty returns true if there are no parts to the Path
+func (p *Path) Empty() bool {
+	return len(p.parts) == 0
+}
+
+// ShapeRef returns an aws-sdk-go ShapeRef within the supplied ShapeRef that
+// matches the Path. Returns nil if no matching ShapeRef could be found.
+//
+// Assume a ShapeRef that looks like this:
+//
+//  authShapeRef := &awssdkmodel.ShapeRef{
+//    ShapeName: "Author",
+//    Shape: &awssdkmodel.Shape{
+//      Type: "structure",
+//      MemberRefs: map[string]*awssdkmodel.ShapeRef{
+//        "Name": &awssdkmodel.ShapeRef{
+//          ShapeName: "Name",
+//          Shape: &awssdkmodel.Shape{
+//            Type: "string",
+//          },
+//        },
+//        "Address": &awssdkmodel.ShapeRef{
+//          ShapeName: "Address",
+//          Shape: &awssdkmodel.Shape{
+//            Type: "structure",
+//            MemberRefs: map[string]*awssdkmodel.ShapeRef{
+//              "State": &awssdkmodel.ShapeRef{
+//                ShapeName: "StateCode",
+//                Shape: &awssdkmodel.Shape{
+//                  Type: "string",
+//                },
+//              },
+//              "Country": &awssdkmodel.ShapeRef{
+//                ShapeName: "CountryCode",
+//                Shape: &awssdkmodel.Shape{
+//                  Type: "string",
+//                },
+//              },
+//            },
+//          },
+//        },
+//      },
+//    },
+//  }
+//
+// If I have the following Path:
+//
+// p := fieldpath.FromString("Author.Address.Country")
+//
+// calling p.ShapeRef(authShapeRef) would return the following:
+//
+// &awssdkmodel.ShapeRef{
+//   ShapeName: "CountryCode",
+//   Shape: &awssdkmodel.Shape{
+//     Type: "string",
+//   },
+// },
+func (p *Path) ShapeRef(
+	subject *awssdkmodel.ShapeRef,
+) *awssdkmodel.ShapeRef {
+	if subject == nil || p == nil || len(p.parts) == 0 {
+		return nil
+	}
+
+	// We first check that the first part in the path matches the supplied
+	// subject shape's name.
+	var compare *awssdkmodel.ShapeRef = subject
+	cp := p.Copy()
+	cur := cp.PopFront()
+	if compare.ShapeName != cur {
+		return nil
+	}
+	// And then we walk through the path, searching through the supplied
+	// ShapeRef for a member ShapeRef matching each path element.
+	for !cp.Empty() {
+		cur = cp.PopFront()
+		if compare = memberShapeRef(compare, cur); compare == nil {
+			return nil
+		}
+	}
+	return compare
+}
+
+// memberShapeRef returns the named member ShapeRef of the supplied
+// ShapeRef
+func memberShapeRef(
+	shapeRef *awssdkmodel.ShapeRef,
+	memberName string,
+) *awssdkmodel.ShapeRef {
+	if shapeRef.ShapeName == memberName {
+		return shapeRef
+	}
+	switch shapeRef.Shape.Type {
+	case "structure":
+		return shapeRef.Shape.MemberRefs[memberName]
+	case "list":
+		return memberShapeRef(&shapeRef.Shape.MemberRef, memberName)
+	case "map":
+		return memberShapeRef(&shapeRef.Shape.ValueRef, memberName)
+	}
+	return nil
+}
+
+// HasPrefix returns true if the supplied string, delimited on ".", matches
+// p.parts up to the length of the supplied string.
+// e.g. if the Path p represents "A.B":
+//  subject "A" -> true
+//  subject "A.B" -> true
+//  subject "A.B.C" -> false
+//  subject "B" -> false
+//  subject "A.C" -> false
+func (p *Path) HasPrefix(subject string) bool {
+	subjectSplit := strings.Split(subject, ".")
+
+	if len(subjectSplit) > len(p.parts) {
+		return false
+	}
+
+	for i, s := range subjectSplit {
+		if p.parts[i] != s {
+			return false
+		}
+	}
+
+	return true
+}
+
+// HasPrefixFold is the same as HasPrefix but uses case-insensitive comparisons
+func (p *Path) HasPrefixFold(subject string) bool {
+	subjectSplit := strings.Split(subject, ".")
+
+	if len(subjectSplit) > len(p.parts) {
+		return false
+	}
+
+	for i, s := range subjectSplit {
+		if !strings.EqualFold(p.parts[i], s) {
+			return false
+		}
+	}
+
+	return true
+}
+
+// FromString returns a new Path from a dotted-notation string, e.g.
+// "Author.Name".
+func FromString(dotted string) *Path {
+	return &Path{strings.Split(dotted, ".")}
+}