Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move funcmap and add template functions docs #41

Closed
wants to merge 2 commits into from
Closed

Move funcmap and add template functions docs #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a655228
move funcmap to its own sub package
nocturnalastro Jun 21, 2024
107c72d
Add documentation of templating helper functions
nocturnalastro Jun 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/templating-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Templating functions

On top of golangs normal templating we provide some functions to make writitng references easier.
The (sprig functions)[http://masterminds.github.io/sprig/] are included along with some other functions that can be found in the (subpackages pkg.go.dev page)[https://pkg.go.dev/github.com/openshift/kube-compare/pkg/funcmap#pkg-functions]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all some other functions are the functions supported by helm,
until we introduce any custom functions (that can take time because we still have not plan that),
i think its better to change it too the function supported be helm (without include). and i then i would add comment that we do try stay aligned but there may be drifts, to see the exact functions supported view the package docs


If you want to custom functions you can define them as a templates and include them a paths under `templateFunctionFiles` at the root of your reference `metadata.yml`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe an example or two (sprig && custom) would be nice!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you mean here?
Do you mean you want me to list a few or show a template with them in?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep that's it. Show a template with them...so like as a user I would like tips on how to incorporate spring/template funcs in my existing references! Also not sure what templateFunctionFiles is...a custom dir name? (but including an example should clear it up)

btw metadata.yml should be metadata.yaml? The file ext is somewhat hardcoded right?

Copy link
Contributor Author

@nocturnalastro nocturnalastro Jun 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok yeah I think that makes sense :)

templateFunctionFiles is an entry in the metadata file that can be used to load templates to be used as custom functions.
I'll check if there is documentation on that.

Good shout on the .yaml we should make it less so I'll make an issue for that.

3 changes: 2 additions & 1 deletion pkg/compare/compare.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import (

jsonpatch "github.com/evanphx/json-patch"
"github.com/gosimple/slug"
"github.com/openshift/kube-compare/pkg/funcmap"
"github.com/openshift/kube-compare/pkg/groups"
"github.com/samber/lo"
"github.com/spf13/cobra"
Expand Down Expand Up @@ -638,7 +639,7 @@ No CRs are unmatched to reference CRs
{{- end }}
`
var buf bytes.Buffer
tmpl, _ := template.New("Summary").Funcs(template.FuncMap{"toYaml": toYAML}).Parse(t)
tmpl, _ := template.New("Summary").Funcs(template.FuncMap{"toYaml": funcmap.ToYAML}).Parse(t)
_ = tmpl.Execute(&buf, s)
return strings.TrimSpace(buf.String())
}
Expand Down
6 changes: 4 additions & 2 deletions pkg/compare/parsing.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import (
"path/filepath"
"text/template"

"github.com/openshift/kube-compare/pkg/funcmap"
"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
"sigs.k8s.io/yaml"
)
Expand Down Expand Up @@ -148,13 +149,14 @@ func parseYaml[T any](fsys fs.FS, filePath string, structType *T, fileNotFoundEr
func parseTemplates(templateReference []*ReferenceTemplate, functionTemplates []string, fsys fs.FS) ([]*ReferenceTemplate, error) {
var errs []error
for _, temp := range templateReference {
parsedTemp, err := template.New(path.Base(temp.Path)).Funcs(FuncMap()).ParseFS(fsys, temp.Path)
parsedTemp, err := template.New(path.Base(temp.Path)).Funcs(funcmap.FuncMap()).ParseFS(fsys, temp.Path)
if err != nil {
errs = append(errs, fmt.Errorf(templatesCantBeParsed, temp.Path, err))
continue
}
// recreate template with new name that includes path from reference root:
parsedTemp, _ = template.New(temp.Path).Funcs(FuncMap()).AddParseTree(temp.Path, parsedTemp.Tree)
parsedTemp, _ = template.New(temp.Path).Funcs(funcmap.FuncMap()).AddParseTree(temp.Path, parsedTemp.Tree)

if len(functionTemplates) > 0 {
parsedTemp, err = parsedTemp.ParseFS(fsys, functionTemplates...)
if err != nil {
Expand Down
44 changes: 22 additions & 22 deletions pkg/compare/funcmap.go → pkg/funcmap/funcmap.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// SPDX-License-Identifier:Apache-2.0

package compare
package funcmap

import (
"bytes"
Expand Down Expand Up @@ -35,13 +35,13 @@ func FuncMap() template.FuncMap {

// Add some extra functionality
extra := template.FuncMap{
"toToml": toTOML,
"toYaml": toYAML,
"fromYaml": fromYAML,
"fromYamlArray": fromYAMLArray,
"toJson": toJSON,
"fromJson": fromJSON,
"fromJsonArray": fromJSONArray,
"toToml": ToTOML,
"toYaml": ToYAML,
"fromYaml": FromYAML,
"fromYamlArray": FromYAMLArray,
"toJson": ToJSON,
"fromJson": FromJSON,
"fromJsonArray": FromJSONArray,
}

for k, v := range extra {
Expand All @@ -51,11 +51,11 @@ func FuncMap() template.FuncMap {
return f
}

// toYAML takes an interface, marshals it to yaml, and returns a string. It will
// ToYAML takes an interface, marshals it to yaml, and returns a string. It will
// always return a string, even on marshal error (empty string).
//
// This is designed to be called from a template.
func toYAML(v any) string {
func ToYAML(v any) string {
data, err := yaml.Marshal(v)
if err != nil {
// Swallow errors inside of a template.
Expand All @@ -64,13 +64,13 @@ func toYAML(v any) string {
return strings.TrimSuffix(string(data), "\n")
}

// fromYAML converts a YAML document into a map[string]any.
// FromYAML converts a YAML document into a map[string]any.
//
// This is not a general-purpose YAML parser, and will not parse all valid
// YAML documents. Additionally, because its intended use is within templates
// it tolerates errors. It will insert the returned error message string into
// m["Error"] in the returned map.
func fromYAML(str string) map[string]any {
func FromYAML(str string) map[string]any {
m := map[string]any{}

if err := yaml.Unmarshal([]byte(str), &m); err != nil {
Expand All @@ -79,13 +79,13 @@ func fromYAML(str string) map[string]any {
return m
}

// fromYAMLArray converts a YAML array into a []any.
// FromYAMLArray converts a YAML array into a []any.
//
// This is not a general-purpose YAML parser, and will not parse all valid
// YAML documents. Additionally, because its intended use is within templates
// it tolerates errors. It will insert the returned error message string as
// the first and only item in the returned array.
func fromYAMLArray(str string) []any {
func FromYAMLArray(str string) []any {
a := []any{}

if err := yaml.Unmarshal([]byte(str), &a); err != nil {
Expand All @@ -94,11 +94,11 @@ func fromYAMLArray(str string) []any {
return a
}

// toTOML takes an interface, marshals it to toml, and returns a string. It will
// ToTOML takes an interface, marshals it to toml, and returns a string. It will
// always return a string, even on marshal error (empty string).
//
// This is designed to be called from a template.
func toTOML(v any) string {
func ToTOML(v any) string {
b := bytes.NewBuffer(nil)
e := toml.NewEncoder(b)
err := e.Encode(v)
Expand All @@ -108,11 +108,11 @@ func toTOML(v any) string {
return b.String()
}

// toJSON takes an interface, marshals it to json, and returns a string. It will
// ToJSON takes an interface, marshals it to json, and returns a string. It will
// always return a string, even on marshal error (empty string).
//
// This is designed to be called from a template.
func toJSON(v any) string {
func ToJSON(v any) string {
data, err := json.Marshal(v)
if err != nil {
// Swallow errors inside of a template.
Expand All @@ -121,13 +121,13 @@ func toJSON(v any) string {
return string(data)
}

// fromJSON converts a JSON document into a map[string]any.
// FromJSON converts a JSON document into a map[string]any.
//
// This is not a general-purpose JSON parser, and will not parse all valid
// JSON documents. Additionally, because its intended use is within templates
// it tolerates errors. It will insert the returned error message string into
// m["Error"] in the returned map.
func fromJSON(str string) map[string]any {
func FromJSON(str string) map[string]any {
m := make(map[string]any)

if err := json.Unmarshal([]byte(str), &m); err != nil {
Expand All @@ -136,13 +136,13 @@ func fromJSON(str string) map[string]any {
return m
}

// fromJSONArray converts a JSON array into a []any.
// FromJSONArray converts a JSON array into a []any.
//
// This is not a general-purpose JSON parser, and will not parse all valid
// JSON documents. Additionally, because its intended use is within templates
// it tolerates errors. It will insert the returned error message string as
// the first and only item in the returned array.
func fromJSONArray(str string) []any {
func FromJSONArray(str string) []any {
a := []any{}

if err := json.Unmarshal([]byte(str), &a); err != nil {
Expand Down