evcc-io/util/templates/template.go

package templates

import (
	"bytes"
	_ "embed"
	"fmt"
	"slices"
	"strconv"
	"strings"
	"text/template"

	"github.com/Masterminds/sprig/v3"
)

// Template describes is a proxy device for use with cli and automated testing
type Template struct {
	TemplateDefinition

	title  string
	titles []string
}

// GuidedSetupEnabled returns true if there are linked templates or >1 usage
func (t *Template) GuidedSetupEnabled() bool {
	_, p := t.ParamByName(ParamUsage)
	return len(t.Linked) > 0 || (len(p.Choice) > 1 && p.IsAllInOne())
}

// UpdateParamWithDefaults adds default values to specific param name entries
func (t *Template) UpdateParamsWithDefaults() error {
	for i, p := range t.Params {
		if index, resultMapItem := ConfigDefaults.ParamByName(strings.ToLower(p.Name)); index > -1 {
			t.Params[i].OverwriteProperties(resultMapItem)
		}
	}

	return nil
}

// validate the template (only rudimentary for now)
func (t *Template) Validate() error {
	for _, c := range t.Capabilities {
		if !slices.Contains(ValidCapabilities, c) {
			return fmt.Errorf("invalid capability '%s' in template %s", c, t.Template)
		}
	}

	for _, c := range t.Countries {
		if !c.IsValid() {
			return fmt.Errorf("invalid country code '%s' in template %s", c, t.Template)
		}
	}

	for _, r := range t.Requirements.EVCC {
		if !slices.Contains(ValidRequirements, r) {
			return fmt.Errorf("invalid requirement '%s' in template %s", r, t.Template)
		}
	}

	for _, p := range t.Params {
		if p.IsDeprecated() {
			continue
		}

		if p.Description.String("en") == "" || p.Description.String("de") == "" {
			return fmt.Errorf("description for param %s cant be empty in template %s", p.Name, t.Template)
		}

		maxLength := 50
		actualLength := max(len(p.Description.String("en")), len(p.Description.String("de")))
		if actualLength > maxLength {
			return fmt.Errorf("description for param %s is too long in template %s. allowed: %d. actual length: %d. use help field for details instead.", p.Name, t.Template, maxLength, actualLength)
		}

		switch p.Name {
		case ParamUsage:
			for _, c := range p.Choice {
				if !slices.Contains(UsageStrings(), c) {
					return fmt.Errorf("invalid usage choice '%s' in template %s", c, t.Template)
				}
			}
		case ParamModbus:
			for _, c := range p.Choice {
				if !slices.Contains(ValidModbusChoices, c) {
					return fmt.Errorf("invalid modbus choice '%s' in template %s", c, t.Template)
				}
			}
		}
	}

	return nil
}

// set the language title by combining all product titles
func (t *Template) SetCombinedTitle(lang string) {
	if len(t.titles) == 0 {
		t.resolveTitles(lang)
	}

	t.title = strings.Join(t.titles, "/")
}

// set the title for this templates
func (t *Template) SetTitle(title string) {
	t.title = title
}

// return the title for this template
func (t *Template) Title() string {
	return t.title
}

// return the language specific product titles
func (t *Template) Titles(lang string) []string {
	if len(t.titles) == 0 {
		t.resolveTitles(lang)
	}

	return t.titles
}

// set the language specific product titles
func (t *Template) resolveTitles(lang string) {
	for _, p := range t.Products {
		t.titles = append(t.titles, p.Title(lang))
	}
}

// add the referenced base Params and overwrite existing ones
func (t *Template) ResolvePresets() error {
	currentParams := make([]Param, len(t.Params))
	copy(currentParams, t.Params)
	t.Params = []Param{}
	for _, p := range currentParams {
		if p.Preset != "" {
			base, ok := ConfigDefaults.Presets[p.Preset]
			if !ok {
				return fmt.Errorf("could not find preset definition: %s", p.Preset)
			}

			t.Params = append(t.Params, base.Params...)
			continue
		}

		if i, _ := t.ParamByName(p.Name); i > -1 {
			// take the preset values as a base and overwrite it with param values
			p.OverwriteProperties(t.Params[i])
			t.Params[i] = p
		} else {
			t.Params = append(t.Params, p)
		}
	}

	return nil
}

// check if the provided group exists
func (t *Template) ResolveGroup() error {
	if t.Group == "" {
		return nil
	}

	_, ok := ConfigDefaults.DeviceGroups[t.Group]
	if !ok {
		return fmt.Errorf("could not find devicegroup definition: %s", t.Group)
	}

	return nil
}

// return the language specific group title
func (t *Template) GroupTitle(lang string) string {
	tl := ConfigDefaults.DeviceGroups[t.Group]
	return tl.String(lang)
}

// Defaults returns a map of default values for the template
func (t *Template) Defaults(renderMode int) map[string]interface{} {
	values := make(map[string]interface{})
	for _, p := range t.Params {
		values[p.Name] = p.DefaultValue(renderMode)
	}

	return values
}

// SetParamDefault updates the default value of a param
func (t *Template) SetParamDefault(name string, value string) {
	for i, p := range t.Params {
		if p.Name == name {
			t.Params[i].Default = value
			return
		}
	}
}

// return the param with the given name
func (t *Template) ParamByName(name string) (int, Param) {
	for i, p := range t.Params {
		if strings.EqualFold(p.Name, name) {
			return i, p
		}
	}
	return -1, Param{}
}

// Usages returns the list of supported usages
func (t *Template) Usages() []string {
	if i, p := t.ParamByName(ParamUsage); i > -1 {
		return p.Choice
	}

	return nil
}

// return all modbus choices defined in the template
func (t *Template) ModbusChoices() []string {
	if i, p := t.ParamByName(ParamModbus); i > -1 {
		return p.Choice
	}

	return nil
}

//go:embed proxy.tpl
var proxyTmpl string

// RenderProxyWithValues renders the proxy template
func (t *Template) RenderProxyWithValues(values map[string]interface{}, lang string) ([]byte, error) {
	tmpl, err := template.New("yaml").Funcs(sprig.FuncMap()).Parse(proxyTmpl)
	if err != nil {
		panic(err)
	}

	t.ModbusParams("", values)

	for index, p := range t.Params {
		v, ok := values[p.Name]
		if !ok {
			continue
		}

		switch p.Type {
		case TypeList:
			for _, e := range v.([]string) {
				t.Params[index].Values = append(p.Values, p.yamlQuote(e))
			}
		default:
			switch v := v.(type) {
			case string:
				t.Params[index].Value = p.yamlQuote(v)
			case int:
				t.Params[index].Value = strconv.Itoa(v)
			}
		}
	}

	// remove params with no values
	var newParams []Param
	for _, param := range t.Params {
		if !param.IsRequired() {
			switch param.Type {
			case TypeList:
				if len(param.Values) == 0 {
					continue
				}
			default:
				if param.Value == "" {
					continue
				}
			}
		}
		newParams = append(newParams, param)
	}

	t.Params = newParams

	out := new(bytes.Buffer)
	data := map[string]interface{}{
		"Template": t.Template,
		"Params":   t.Params,
	}
	err = tmpl.Execute(out, data)

	return bytes.TrimSpace(out.Bytes()), err
}

// RenderResult renders the result template to instantiate the proxy
func (t *Template) RenderResult(renderMode int, other map[string]any) ([]byte, map[string]any, error) {
	values := t.Defaults(renderMode)
	if err := mergeMaps(other, values); err != nil {
		return nil, values, err
	}

	t.ModbusValues(renderMode, values)

	res := make(map[string]interface{})

	// TODO this is an utterly horrible hack
	//
	// When decoding the actual values ("other" parameter) into the
	// defaults-populated map, mismatching key case will create multiple
	// map entries for the same parameter.
	// The code below tries to select the best, i.e. non-empty, value for the
	// parameter and assigns it to the result key.
	// The actual key name is taken from the parameter to make it unique.
	// Since predefined properties are not matched by actual parameters using
	// ParamByName(), the lower case key name is used instead.
	// All keys *must* be assigned or rendering will create "<no value>" artifacts.

	for key, val := range values {
		out := strings.ToLower(key)

		i, p := t.ParamByName(key)
		if i == -1 {
			if !slices.Contains(predefinedTemplateProperties, out) {
				return nil, values, fmt.Errorf("invalid key: %s", key)
			}
		} else if p.IsDeprecated() {
			continue
		} else {
			out = p.Name
		}

		// TODO move yamlQuote to explicit quoting in templates, see https://github.com/evcc-io/evcc/issues/10742

		switch typed := val.(type) {
		case []interface{}:
			var list []string
			for _, v := range typed {
				list = append(list, p.yamlQuote(fmt.Sprintf("%v", v)))
			}
			if res[out] == nil || len(res[out].([]interface{})) == 0 {
				res[out] = list
			}

		case []string:
			var list []string
			for _, v := range typed {
				list = append(list, p.yamlQuote(v))
			}
			if res[out] == nil || len(res[out].([]string)) == 0 {
				res[out] = list
			}

		default:
			if res[out] == nil || res[out].(string) == "" {
				// prevent rendering nil interfaces as "<nil>" string
				var s string
				if val != nil {
					s = p.yamlQuote(fmt.Sprintf("%v", val))
				}
				res[out] = s
			}
		}
	}

	tmpl, err := baseTmpl.Clone()
	if err == nil {
		tmpl, err = FuncMap(tmpl).Parse(t.Render)
	}
	if err != nil {
		return nil, res, err
	}

	out := new(bytes.Buffer)
	err = tmpl.Execute(out, res)

	return bytes.TrimSpace(out.Bytes()), res, err
}