Add specification packages

Add a go package that holds an unversioned alias of the API for
creating events. This let user import the versioned package and
have access to a simpler API which picks the right version of
each event based on the spec version.

There is still work to be done to support multiple versions, as
the context may vary across versions, which is not yet handled.

Signed-off-by: Andrea Frittoli <[email protected]>

README.md

@@ -12,10 +12,11 @@ Add the module as dependency using go mod:
 go get github.com/cdevents/sdk-go
 ```
 
-And import the module in your code
+And import the module in your code corresponding to the desired version of the specification.
+For CDEvents v0.3.x, use:
 
 ```golang
-import cdevents "github.com/cdevents/sdk-go/pkg/api"
+import cdevents "github.com/cdevents/sdk-go/pkg/api/v03"
 ```
 
 ## Create your first CDEvent

tools/generator.go

@@ -69,6 +69,7 @@ var (
 		"examples_test.go.tmpl",
 		"factory_test.go.tmpl",
 	}
+	specTemplateFileName = "docs.go.tmpl"
 
 	// Tool
 	capitalizer cases.Caser
@@ -106,7 +107,9 @@ type Data struct {
 }
 
 type AllData struct {
-	Slice []Data
+	Slice           []Data
+	SpecVersion     string
+	SpecVersionName string
 }
 
 func (d Data) OutputFile() string {
@@ -141,7 +144,7 @@ func main() {
 	for _, version := range SPEC_VERSIONS {
 		versioned_schema_folder := filepath.Join(PROJECT_ROOT, SPEC_FOLDER_PREFIX+version, SCHEMA_FOLDER)
 		log.Printf("Generating SDK files from templates: %s and schemas: %s into %s", TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER)
-		err = generate(TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER, "", GO_TYPES_NAMES)
+		err = generate(TEMPLATES, versioned_schema_folder, GEN_CODE_FOLDER, "", version, GO_TYPES_NAMES)
 		if err != nil {
 			log.Fatalf("%s", err.Error())
 		}
@@ -150,17 +153,19 @@ func main() {
 	// Generate SDK test files
 	test_schema_folder := filepath.Join(PROJECT_ROOT, TEST_SCHEMA_FOLDER, SCHEMA_FOLDER)
 	log.Printf("Generating SDK files from templates: %s and schemas: %s into %s", TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER)
-	err = generate(TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER, TEST_OUTPUT_PREFIX, GO_TYPES_TEST_NAMES)
+	err = generate(TEST_TEMPLATES, test_schema_folder, TEST_GEN_CODE_FOLDER, TEST_OUTPUT_PREFIX, "", GO_TYPES_TEST_NAMES)
 	if err != nil {
 		log.Fatalf("%s", err.Error())
 	}
 }
 
-func generate(templatesFolder, schemaFolder, genFolder, prefix string, goTypes map[string]string) error {
+func generate(templatesFolder, schemaFolder, genFolder, prefix, specVersion string, goTypes map[string]string) error {
 	// allData is used to accumulate data from all jsonschemas
 	// which is then used to run shared templates
 	allData := AllData{
-		Slice: make([]Data, 0),
+		Slice:           make([]Data, 0),
+		SpecVersion:     specVersion,
+		SpecVersionName: strings.Replace(specVersion, ".", "", -1),
 	}
 
 	allTemplates, err := template.ParseGlob(templatesFolder)
@@ -182,6 +187,20 @@ func generate(templatesFolder, schemaFolder, genFolder, prefix string, goTypes m
 		return err
 	}
 
+	// Process the spec template. Create the target folder is it doesn't exist
+	if specVersion != "" {
+		specFileFolder := filepath.Join(genFolder, specVersion)
+		err = os.MkdirAll(specFileFolder, os.ModePerm)
+		if err != nil {
+			return err
+		}
+		specFileName := filepath.Join(genFolder, specVersion, strings.TrimSuffix(specTemplateFileName, filepath.Ext(specTemplateFileName)))
+		err = executeTemplate(allTemplates, specTemplateFileName, specFileName, allData)
+		if err != nil {
+			return err
+		}
+	}
+
 	// Process example test files - only for real data
 	if prefix == "" {
 		for _, examplesTestsTemplateFileName := range examplesTestsTemplateFileNames {

tools/templates/docs.go.tmpl

@@ -0,0 +1,33 @@
+// Code generated by tools/generator. DO NOT EDIT.
+
+/*
+Copyright 2024 The CDEvents 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.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+// Package v03 contains method to create events that belong to the
+// CDEvents specification {{.SpecVersion}}.x
+
+package {{.SpecVersionName}}
+
+import "github.com/cdevents/sdk-go/pkg/api"
+
+{{- range $i, $data := .Slice }}
+type {{.Subject}}{{.Predicate}}Event = api.{{.Subject}}{{.Predicate}}EventV{{.VersionName}}
+func New{{.Subject}}{{.Predicate}}Event() (*{{.Subject}}{{.Predicate}}Event, error) {
+	return api.New{{.Subject}}{{.Predicate}}EventV{{.VersionName}}()
+}
+{{- end }}