feat: Add encoding template directive

Author: twpayne

assets/chezmoi.io/docs/reference/templates/directives.md

@@ -37,6 +37,33 @@ inherited by templates called from the file.
     # [[ "true" ]]
     ```
 
+## Encoding
+
+Templates are always written in UTF-8 with no byte order mark.
+
+By default, the result of executing a template is also UTF-8 with no
+byte order mark but this can be transformed into another encoding with the
+template directive:
+
+    chezmoi:template:encoding=$ENCODING
+
+where `$ENCODING` is one of:
+
+| Encoding        | Description                                  |
+| --------------- | -------------------------------------------- |
+| `utf-8`         | UTF-8 with no byte order mark                |
+| `utf-8-bom`     | UTF-8 with a byte order mark                 |
+| `utf-16-be`     | Big-endian UTF-16 with no byte order mark    |
+| `utf-16-be-bom` | Big-endian UTF-16 with a byte order mark     |
+| `utf-16-le`     | Little-endian UTF-16 with no byte order mark |
+| `utf-16-le-bom` | Little-endian UTF-16 with a byte order mark  |
+
+!!! example
+
+    ```
+    {{/* chezmoi:template:encoding=utf-16-le */}}
+    ```
+
 ## Format indent
 
 By default, chezmoi's `toJson`, `toToml`, and `toYaml` template functions use

internal/chezmoi/template.go

@@ -3,6 +3,7 @@ package chezmoi
 import (
 	"bytes"
 	"encoding/json"
+	"fmt"
 	"maps"
 	"strconv"
 	"strings"
@@ -12,6 +13,8 @@ import (
 	"github.com/mattn/go-runewidth"
 	"github.com/mitchellh/copystructure"
 	"github.com/pelletier/go-toml/v2"
+	"golang.org/x/text/encoding"
+	"golang.org/x/text/encoding/unicode"
 )
 
 // A Template extends text/template.Template with support for directives.
@@ -23,6 +26,7 @@ type Template struct {
 
 // TemplateOptions are template options that can be set with directives.
 type TemplateOptions struct {
+	Encoding       encoding.Encoding
 	Funcs          template.FuncMap
 	FormatIndent   string
 	LeftDelimiter  string
@@ -107,7 +111,12 @@ func (t *Template) Execute(data any) ([]byte, error) {
 	if err := t.template.ExecuteTemplate(&builder, t.name, data); err != nil {
 		return nil, err
 	}
-	return []byte(replaceLineEndings(builder.String(), t.options.LineEnding)), nil
+
+	result := []byte(replaceLineEndings(builder.String(), t.options.LineEnding))
+	if t.options.Encoding != nil {
+		return t.options.Encoding.NewEncoder().Bytes(result)
+	}
+	return result, nil
 }
 
 // parseAndRemoveDirectives updates o by parsing all template directives in data
@@ -126,6 +135,23 @@ func (o *TemplateOptions) parseAndRemoveDirectives(data []byte) ([]byte, error)
 			key := string(keyValuePairMatch[1])
 			value := maybeUnquote(string(keyValuePairMatch[2]))
 			switch key {
+			case "encoding":
+				switch value {
+				case "utf-8":
+					o.Encoding = unicode.UTF8
+				case "utf-8-bom":
+					o.Encoding = unicode.UTF8BOM
+				case "utf-16-be":
+					o.Encoding = unicode.UTF16(unicode.BigEndian, unicode.IgnoreBOM)
+				case "utf-16-be-bom":
+					o.Encoding = unicode.UTF16(unicode.BigEndian, unicode.UseBOM)
+				case "utf-16-le":
+					o.Encoding = unicode.UTF16(unicode.LittleEndian, unicode.IgnoreBOM)
+				case "utf-16-le-bom":
+					o.Encoding = unicode.UTF16(unicode.LittleEndian, unicode.UseBOM)
+				default:
+					return nil, fmt.Errorf("%s: unknown encoding", value)
+				}
 			case "format-indent":
 				o.FormatIndent = value
 			case "format-indent-width":

internal/cmd/testdata/scripts/templatedirectives.txtar

@@ -1,7 +1,13 @@
+hexdecode golden/encoding.hex
+
 # test --left-delimiter and --right-delimiter flags to chezmoi execute-template
 exec chezmoi execute-template --left-delimiter=[[ --right-delimiter=]] '[[ "ok" ]]'
 stdout ^ok$
 
+# test that the encoding can be set in files
+exec chezmoi cat $HOME${/}encoding
+cmp stdout golden/encoding
+
 # test that missing key behavior can be set in files
 exec chezmoi cat $HOME${/}missing-key
 cmp stdout golden/missing-key
@@ -10,13 +16,19 @@ cmp stdout golden/missing-key
 exec chezmoi cat $HOME${/}nested-template
 cmp stdout golden/nested-template
 
+-- golden/encoding.hex --
+fffe                                                     # UTF-16 BOM
+480065006c006c006f002c00200077006f0072006c00640021000a00 # "Hello, world!\n"
 -- golden/missing-key --
 <no value>
 -- golden/nested-template --
 (nested)
 -- home/user/.local/share/chezmoi/.chezmoitemplates/nested --
 # chezmoi:template:left-delimiter=(( right-delimiter=))
 ((- . -))
+-- home/user/.local/share/chezmoi/encoding.tmpl --
+# chezmoi:template:encoding=utf-16-le-bom
+Hello, world!
 -- home/user/.local/share/chezmoi/missing-key.tmpl --
 # chezmoi:template:missing-key=default
 {{ .MissingKey }}