Spawn gengo/v2 (KEP 4402)

Makefile

@@ -0,0 +1,9 @@
+all:
+	go build ./...
+	go -C v2 build ./...
+
+test:
+	go test -race ./...
+	./hack/verify-examples.sh
+	go -C v2 test -race ./...
+	(cd v2 && ./hack/verify-examples.sh)

README.md

@@ -9,6 +9,8 @@
 [GoReport]: https://goreportcard.com/badge/github.com/kubernetes/gengo
 [GoReportStatus]: https://goreportcard.com/report/github.com/kubernetes/gengo
 
+NOTE: [`k8s.io/gengo/v2`](https://github.com/kubernetes/gengo/tree/master/v2) is the current development module.
+
 A package for generating things based on go files. This mechanism was first used
 in [Kubernetes code-generator](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/code-generator) and is split out here for ease of reuse and maintainability.
 

hack/verify-examples.sh

@@ -29,7 +29,7 @@ echo "Removing generated code"
 find ./examples -name "zz_generated.go" -type f -delete
 
 # Delete set-gen tests
-find ./examples/set-gen/sets -type f -maxdepth 1 -not -name "set_test.go" -not -name "doc.go" -delete
+find ./examples/set-gen/sets -maxdepth 1 -type f -not -name "set_test.go" -not -name "doc.go" -delete
 
 # Generate set-gen first since others depend on it
 echo "Generating example output..."

v2/README.md

@@ -0,0 +1,53 @@
+[![GoDoc Widget]][GoDoc]  [![GoReport]][GoReportStatus]
+
+[GoDoc]: https://godoc.org/k8s.io/gengo
+[GoDoc Widget]: https://godoc.org/k8s.io/gengo?status.svg
+[GoReport]: https://goreportcard.com/badge/github.com/kubernetes/gengo
+[GoReportStatus]: https://goreportcard.com/report/github.com/kubernetes/gengo
+
+# Gengo: a framework for building simple code generators
+
+This repo is used by Kubernetes to build some codegen tooling.  It is not
+intended to be general-purpose and makes some assumptions that may not hold
+outside of Kubernetes.
+
+In the past this repo was partially supported for external use (outside of the
+Kubernetes project overall), but that is no longer true.  We may change the API
+in incompatible ways, without warning.
+
+If you are not building something that is part of Kubernetes, DO NOT DEPEND ON
+THIS REPO.
+
+## New usage within Kubernetes
+
+Gengo is a very opinionated framework.  It is primarily aimed at generating Go
+code derived from types defined in other Go code, but it is possible to use it
+for other things (e.g. proto files).  Net new tools should consider using
+`golang.org/x/tools/go/packages` directly.  Gengo can serve as an example of
+how to do that.
+
+If you still decide you want to use gengo, see the
+[simple examples](./examples) in this repo or the more extensive tools in the
+Kubernetes [code-generator](https://github.com/kubernetes/code-generator/)
+repo.
+
+## Overview
+
+Gengo is used to build tools (generally a tool is a binary).  Each tool
+describes some number of `Targets`. A target is a single output package, which
+may be the same as the inputs (if the tool generates code alongside the inputs)
+or different.  Each `Target` describes some number of `Generators`.  A
+generator is responsible for emitting a single file into the target directory.
+
+Gengo helps the tool to load and process input packages, e.g. extracting type
+information and associating comments.  Each target will be offered every known
+type, and can filter that down to the set of types it cares about.  Each
+generator will be offered the result of the target's filtering, and can filter
+the set of types further.  Finally, the generator will be called to emit code
+for all of the remaining types.
+
+The `tracer` example in this repo can be used to examine all of the hooks.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.

v2/boilerplate/boilerplate.go.txt

@@ -0,0 +1,16 @@
+/*
+Copyright The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License 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.
+*/
+

v2/comments.go

@@ -0,0 +1,83 @@
+/*
+Copyright 2015 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License 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 gengo
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ExtractCommentTags parses comments for lines of the form:
+//
+//	'marker' + "key=value".
+//
+// Values are optional; "" is the default.  A tag can be specified more than
+// one time and all values are returned.  If the resulting map has an entry for
+// a key, the value (a slice) is guaranteed to have at least 1 element.
+//
+// Example: if you pass "+" for 'marker', and the following lines are in
+// the comments:
+//
+//	+foo=value1
+//	+bar
+//	+foo=value2
+//	+baz="qux"
+//
+// Then this function will return:
+//
+//	map[string][]string{"foo":{"value1, "value2"}, "bar": {""}, "baz": {"qux"}}
+func ExtractCommentTags(marker string, lines []string) map[string][]string {
+	out := map[string][]string{}
+	for _, line := range lines {
+		line = strings.Trim(line, " ")
+		if len(line) == 0 {
+			continue
+		}
+		if !strings.HasPrefix(line, marker) {
+			continue
+		}
+		// TODO: we could support multiple values per key if we split on spaces
+		kv := strings.SplitN(line[len(marker):], "=", 2)
+		if len(kv) == 2 {
+			out[kv[0]] = append(out[kv[0]], kv[1])
+		} else if len(kv) == 1 {
+			out[kv[0]] = append(out[kv[0]], "")
+		}
+	}
+	return out
+}
+
+// ExtractSingleBoolCommentTag parses comments for lines of the form:
+//
+//	'marker' + "key=value1"
+//
+// If the tag is not found, the default value is returned.  Values are asserted
+// to be boolean ("true" or "false"), and any other value will cause an error
+// to be returned.  If the key has multiple values, the first one will be used.
+func ExtractSingleBoolCommentTag(marker string, key string, defaultVal bool, lines []string) (bool, error) {
+	values := ExtractCommentTags(marker, lines)[key]
+	if values == nil {
+		return defaultVal, nil
+	}
+	if values[0] == "true" {
+		return true, nil
+	}
+	if values[0] == "false" {
+		return false, nil
+	}
+	return false, fmt.Errorf("tag value for %q is not boolean: %q", key, values[0])
+}

v2/comments_test.go

@@ -0,0 +1,86 @@
+/*
+Copyright 2015 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License 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 gengo
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestExtractCommentTags(t *testing.T) {
+	commentLines := []string{
+		"Human comment that is ignored.",
+		"+foo=value1",
+		"+bar",
+		"+foo=value2",
+		"+baz=qux,zrb=true",
+	}
+
+	a := ExtractCommentTags("+", commentLines)
+	e := map[string][]string{
+		"foo": {"value1", "value2"},
+		"bar": {""},
+		"baz": {"qux,zrb=true"},
+	}
+	if !reflect.DeepEqual(e, a) {
+		t.Errorf("Wanted %q, got %q", e, a)
+	}
+}
+
+func TestExtractSingleBoolCommentTag(t *testing.T) {
+	commentLines := []string{
+		"Human comment that is ignored.",
+		"+TRUE=true",
+		"+FALSE=false",
+		"+MULTI=true",
+		"+MULTI=false",
+		"+MULTI=multi",
+		"+NOTBOOL=blue",
+		"+EMPTY",
+	}
+
+	testCases := []struct {
+		key string
+		def bool
+		exp bool
+		err string // if set, ignore exp.
+	}{
+		{"TRUE", false, true, ""},
+		{"FALSE", true, false, ""},
+		{"MULTI", false, true, ""},
+		{"NOTBOOL", false, true, "is not boolean"},
+		{"EMPTY", false, true, "is not boolean"},
+		{"ABSENT", true, true, ""},
+		{"ABSENT", false, false, ""},
+	}
+
+	for i, tc := range testCases {
+		v, err := ExtractSingleBoolCommentTag("+", tc.key, tc.def, commentLines)
+		if err != nil && tc.err == "" {
+			t.Errorf("[%d]: unexpected failure: %v", i, err)
+		} else if err == nil && tc.err != "" {
+			t.Errorf("[%d]: expected failure: %v", i, tc.err)
+		} else if err != nil {
+			if !strings.Contains(err.Error(), tc.err) {
+				t.Errorf("[%d]: unexpected error: expected %q, got %q", i, tc.err, err)
+			}
+		} else if v != tc.exp {
+			t.Errorf("[%d]: unexpected value: expected %t, got %t", i, tc.exp, v)
+		}
+	}
+}