Add experimental mode

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

cmd/gomplate/config.go

@@ -156,6 +156,10 @@ func cobraConfig(cmd *cobra.Command, args []string) (cfg *config.Config, err err
 	if err != nil {
 		return nil, err
 	}
+	cfg.Experimental, err = getBool(cmd, "experimental")
+	if err != nil {
+		return nil, err
+	}
 
 	cfg.LDelim, err = getString(cmd, "left-delim")
 	if err != nil {
@@ -249,5 +253,9 @@ func applyEnvVars(ctx context.Context, cfg *config.Config) (*config.Config, erro
 		cfg.SuppressEmpty = true
 	}
 
+	if !cfg.Experimental && conv.ToBool(env.Getenv("GOMPLATE_EXPERIMENTAL", "false")) {
+		cfg.Experimental = true
+	}
+
 	return cfg, nil
 }

cmd/gomplate/config_test.go

@@ -233,6 +233,25 @@ func TestApplyEnvVars(t *testing.T) {
 			&config.Config{SuppressEmpty: true},
 			&config.Config{SuppressEmpty: true},
 		},
+
+		{
+			"GOMPLATE_EXPERIMENTAL", "bogus",
+			false,
+			&config.Config{},
+			&config.Config{Experimental: false},
+		},
+		{
+			"GOMPLATE_EXPERIMENTAL", "true",
+			false,
+			&config.Config{},
+			&config.Config{Experimental: true},
+		},
+		{
+			"GOMPLATE_EXPERIMENTAL", "false",
+			false,
+			&config.Config{Experimental: true},
+			&config.Config{Experimental: true},
+		},
 	}
 
 	for i, d := range data {

cmd/gomplate/main.go

@@ -78,6 +78,13 @@ func newGomplateCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			ctx = config.ContextWithConfig(ctx, cfg)
+			if cfg.Experimental {
+				log.UpdateContext(func(c zerolog.Context) zerolog.Context {
+					return c.Bool("experimental", true)
+				})
+				log.Info().Msg("experimental functions and features enabled!")
+			}
 
 			log.Debug().Msgf("starting %s", cmd.Name())
 			log.Debug().
@@ -135,6 +142,8 @@ func initFlags(command *cobra.Command) {
 	command.Flags().String("left-delim", ldDefault, "override the default left-`delimiter` [$GOMPLATE_LEFT_DELIM]")
 	command.Flags().String("right-delim", rdDefault, "override the default right-`delimiter` [$GOMPLATE_RIGHT_DELIM]")
 
+	command.Flags().Bool("experimental", false, "enable experimental features [$GOMPLATE_EXPERIMENTAL]")
+
 	command.Flags().BoolP("verbose", "V", false, "output extra information about what gomplate is doing")
 
 	command.Flags().String("config", defaultConfigFile, "config file (overridden by commandline flags)")

data/datasource_git.go

@@ -26,7 +26,7 @@ import (
 )
 
 func readGit(source *Source, args ...string) ([]byte, error) {
-	ctx := context.Background()
+	ctx := context.TODO()
 	g := gitsource{}
 
 	u := source.URL

docs-src/content/functions/crypto.yml

@@ -55,6 +55,7 @@ funcs:
         $ gomplate -i '{{ crypto.PBKDF2 "foo" "bar" 1024 8 }}'
         32c4907c3c80792b
   - name: crypto.RSADecrypt
+    experimental: true
     description: |
       Decrypt an RSA-encrypted input and print the output as a string. Note that
       this may result in unreadable text if the decrypted payload is binary. See
@@ -87,6 +88,7 @@ funcs:
           -i '{{ base64.DecodeBytes .ciphertext | crypto.RSADecrypt .privKey }}'
         hello
   - name: crypto.RSADecryptBytes
+    experimental: true
     description: |
       Decrypt an RSA-encrypted input and output the decrypted byte array.
 
@@ -120,6 +122,7 @@ funcs:
           {{ crypto.RSADecryptBytes .privKey $enc | conv.ToString }}'
         hello
   - name: crypto.RSAEncrypt
+    experimental: true
     description: |
       Encrypt the input with RSA and the padding scheme from PKCS#1 v1.5.
 
@@ -158,6 +161,7 @@ funcs:
           Ciphertext in hex: {{ printf "%x" $enc }}'
         71729b87cccabb248b9e0e5173f0b12c01d9d2a0565bad18aef9d332ce984bde06acb8bb69334a01446f7f6430077f269e6fbf2ccacd972fe5856dd4719252ebddf599948d937d96ea41540dad291b868f6c0cf647dffdb5acb22cd33557f9a1ddd0ee6c1ad2bbafc910ba8f817b66ea0569afc06e5c7858fd9dc2638861fe7c97391b2f190e4c682b4aa2c9b0050081efe18b10aa8c2b2b5f5b68a42dcc06c9da35b37fca9b1509fddc940eb99f516a2e0195405bcb3993f0fa31bc038d53d2e7231dff08cc39448105ed2d0ac52d375cb543ca8a399f807cc5d007e2c44c69876d189667eee66361a393c4916826af77479382838cd4e004b8baa05636805a
   - name: crypto.RSAGenerateKey
+    experimental: true
     description: |
       Generate a new RSA Private Key and output in PEM-encoded PKCS#1 ASN.1 DER
       form.
@@ -184,6 +188,7 @@ funcs:
           {{ crypto.RSADecrypt $key $enc }}'
         hello
   - name: crypto.RSADerivePublicKey
+    experimental: true
     description: |
       Derive a public key from an RSA private key and output in PKIX ASN.1 DER
       form.

docs-src/content/functions/func_doc.md.tmpl

@@ -24,9 +24,23 @@ menu:
 
 {{ $data.preamble -}}
 
+{{- define "annotations" -}}
+{{ if has . "deprecated" }} _(deprecated)_{{ end -}}
+{{ if and (has . "experimental") (index . "experimental") }} _(experimental)_{{ end -}}
+{{ end -}}
+
 {{ range $_, $f := $data.funcs }}
-## {{ if has $f "rawName" }}{{ $f.rawName }}{{ else }}`{{ $f.name }}`{{ if has $f "deprecated" }} _(deprecated)_
-**Deprecation Notice:** {{ $f.deprecated }}{{ end }}{{ end }}
+## {{ if has $f "rawName" -}}
+{{ $f.rawName }}{{ else }}`{{ $f.name }}`{{ end }}{{ template "annotations" $f }}
+{{ if has $f "deprecated" -}}
+**Deprecation Notice:** {{ $f.deprecated }}
+{{ end -}}
+{{ if and (has . "experimental") (index . "experimental") -}}
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
+{{ end -}}
+
 {{ if has $f "alias" }}
 **Alias:** `{{$f.alias}}`
 {{ end }}

docs/content/config.md

@@ -148,6 +148,18 @@ Use the rendered output as the [`postExec`](#postexec) command's standard input.
 Must be used in conjuction with [`postExec`](#postexec), and will override
 any [`outputFiles`](#outputfiles) settings.
 
+## `experimental`
+
+See [`--experimental`](../usage/#--experimental). Can also be set with the `GOMPLATE_EXPERIMENTAL=true` environment variable.
+
+Some functions and features are provided for early feedback behind the `experimental` configuration option. These features may change before being permanently enabled, and [feedback](https://github.com/hairyhenderson/gomplate/issues/new) is requested from early adopters!
+
+Experimental functions are marked in the documentation with an _"(experimental)"_ annotation.
+
+```yaml
+experimental: true
+```
+
 ## `in`
 
 See [`--in`/`-i`](../usage/#--file-f---in-i-and---out-o).

docs/content/functions/crypto.md

@@ -75,7 +75,10 @@ $ gomplate -i '{{ crypto.PBKDF2 "foo" "bar" 1024 8 }}'
 32c4907c3c80792b
 ```
 
-## `crypto.RSADecrypt`
+## `crypto.RSADecrypt` _(experimental)_
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
 
 Decrypt an RSA-encrypted input and print the output as a string. Note that
 this may result in unreadable text if the decrypted payload is binary. See
@@ -120,7 +123,10 @@ $ gomplate -c ciphertext=env:///ENCRYPTED -c privKey=./testPrivKey \
 hello
 ```
 
-## `crypto.RSADecryptBytes`
+## `crypto.RSADecryptBytes` _(experimental)_
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
 
 Decrypt an RSA-encrypted input and output the decrypted byte array.
 
@@ -166,7 +172,10 @@ $ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \
 hello
 ```
 
-## `crypto.RSAEncrypt`
+## `crypto.RSAEncrypt` _(experimental)_
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
 
 Encrypt the input with RSA and the padding scheme from PKCS#1 v1.5.
 
@@ -217,7 +226,10 @@ $ gomplate -c pubKey=./testPubKey \
 71729b87cccabb248b9e0e5173f0b12c01d9d2a0565bad18aef9d332ce984bde06acb8bb69334a01446f7f6430077f269e6fbf2ccacd972fe5856dd4719252ebddf599948d937d96ea41540dad291b868f6c0cf647dffdb5acb22cd33557f9a1ddd0ee6c1ad2bbafc910ba8f817b66ea0569afc06e5c7858fd9dc2638861fe7c97391b2f190e4c682b4aa2c9b0050081efe18b10aa8c2b2b5f5b68a42dcc06c9da35b37fca9b1509fddc940eb99f516a2e0195405bcb3993f0fa31bc038d53d2e7231dff08cc39448105ed2d0ac52d375cb543ca8a399f807cc5d007e2c44c69876d189667eee66361a393c4916826af77479382838cd4e004b8baa05636805a
 ```
 
-## `crypto.RSAGenerateKey`
+## `crypto.RSAGenerateKey` _(experimental)_
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
 
 Generate a new RSA Private Key and output in PEM-encoded PKCS#1 ASN.1 DER
 form.
@@ -258,7 +270,10 @@ $ gomplate -i '{{ $key := crypto.RSAGenerateKey 2048 -}}
 hello
 ```
 
-## `crypto.RSADerivePublicKey`
+## `crypto.RSADerivePublicKey` _(experimental)_
+**Experimental:** This function is [_experimental_][experimental] and may be enabled with the [`--experimental`][experimental] flag.
+
+[experimental]: ../config/#experimental
 
 Derive a public key from an RSA private key and output in PKIX ASN.1 DER
 form.

docs/content/usage.md

@@ -274,6 +274,12 @@ HELLO WORLD
 
 Note that multiple inputs are not yet supported when using this option.
 
+### `--experimental`
+
+Use this flag to enable experimental functionality. See the docs for the
+[`experimental`](../config/#experimental) configuration option for more
+information.
+
 ## Post-template command execution
 
 Gomplate can launch other commands when template execution is successful. Simply

funcs.go

@@ -1,34 +1,51 @@
 package gomplate
 
 import (
+	"context"
 	"text/template"
 
 	"github.com/hairyhenderson/gomplate/v3/data"
 	"github.com/hairyhenderson/gomplate/v3/funcs"
+	"github.com/hairyhenderson/gomplate/v3/internal/config"
 )
 
-// Funcs - The function mappings are defined here!
+// Funcs -
+// Deprecated: use CreateFuncs instead
 func Funcs(d *data.Data) template.FuncMap {
+	ctx := context.Background()
+	cfg := config.FromContext(ctx)
+	return CreateFuncs(config.ContextWithConfig(ctx, cfg), d)
+}
+
+// CreateFuncs - function mappings are created here
+func CreateFuncs(ctx context.Context, d *data.Data) template.FuncMap {
 	f := template.FuncMap{}
-	funcs.AddDataFuncs(f, d)
-	funcs.AWSFuncs(f)
-	funcs.AddGCPFuncs(f)
-	funcs.AddBase64Funcs(f)
-	funcs.AddNetFuncs(f)
-	funcs.AddReFuncs(f)
-	funcs.AddStringFuncs(f)
-	funcs.AddEnvFuncs(f)
-	funcs.AddConvFuncs(f)
-	funcs.AddTimeFuncs(f)
-	funcs.AddMathFuncs(f)
-	funcs.AddCryptoFuncs(f)
-	funcs.AddFileFuncs(f)
-	funcs.AddFilePathFuncs(f)
-	funcs.AddPathFuncs(f)
-	funcs.AddSockaddrFuncs(f)
-	funcs.AddTestFuncs(f)
-	funcs.AddCollFuncs(f)
-	funcs.AddUUIDFuncs(f)
-	funcs.AddRandomFuncs(f)
+	addToMap(f, funcs.CreateDataFuncs(ctx, d))
+	addToMap(f, funcs.CreateAWSFuncs(ctx))
+	addToMap(f, funcs.CreateGCPFuncs(ctx))
+	addToMap(f, funcs.CreateBase64Funcs(ctx))
+	addToMap(f, funcs.CreateNetFuncs(ctx))
+	addToMap(f, funcs.CreateReFuncs(ctx))
+	addToMap(f, funcs.CreateStringFuncs(ctx))
+	addToMap(f, funcs.CreateEnvFuncs(ctx))
+	addToMap(f, funcs.CreateConvFuncs(ctx))
+	addToMap(f, funcs.CreateTimeFuncs(ctx))
+	addToMap(f, funcs.CreateMathFuncs(ctx))
+	addToMap(f, funcs.CreateCryptoFuncs(ctx))
+	addToMap(f, funcs.CreateFileFuncs(ctx))
+	addToMap(f, funcs.CreateFilePathFuncs(ctx))
+	addToMap(f, funcs.CreatePathFuncs(ctx))
+	addToMap(f, funcs.CreateSockaddrFuncs(ctx))
+	addToMap(f, funcs.CreateTestFuncs(ctx))
+	addToMap(f, funcs.CreateCollFuncs(ctx))
+	addToMap(f, funcs.CreateUUIDFuncs(ctx))
+	addToMap(f, funcs.CreateRandomFuncs(ctx))
 	return f
 }
+
+// addToMap - add src's entries to dst
+func addToMap(dst, src map[string]interface{}) {
+	for k, v := range src {
+		dst[k] = v
+	}
+}

funcs/aws.go

@@ -1,6 +1,7 @@
 package funcs
 
 import (
+	"context"
 	"sync"
 
 	"github.com/hairyhenderson/gomplate/v3/aws"
@@ -24,17 +25,32 @@ func AWSNS() *Funcs {
 
 // AWSFuncs -
 func AWSFuncs(f map[string]interface{}) {
+	f2 := CreateAWSFuncs(context.Background())
+	for k, v := range f2 {
+		f[k] = v
+	}
+}
+
+// CreateAWSFuncs -
+func CreateAWSFuncs(ctx context.Context) map[string]interface{} {
+	f := map[string]interface{}{}
+	ns := AWSNS()
+	ns.ctx = ctx
+
 	f["aws"] = AWSNS
 
 	// global aliases - for backwards compatibility
-	f["ec2meta"] = AWSNS().EC2Meta
-	f["ec2dynamic"] = AWSNS().EC2Dynamic
-	f["ec2tag"] = AWSNS().EC2Tag
-	f["ec2region"] = AWSNS().EC2Region
+	f["ec2meta"] = ns.EC2Meta
+	f["ec2dynamic"] = ns.EC2Dynamic
+	f["ec2tag"] = ns.EC2Tag
+	f["ec2region"] = ns.EC2Region
+	return f
 }
 
 // Funcs -
 type Funcs struct {
+	ctx context.Context
+
 	meta     *aws.Ec2Meta
 	info     *aws.Ec2Info
 	kms      *aws.KMS

funcs/base64.go

@@ -1,6 +1,7 @@
 package funcs
 
 import (
+	"context"
 	"sync"
 
 	"github.com/hairyhenderson/gomplate/v3/base64"
@@ -20,11 +21,22 @@ func Base64NS() *Base64Funcs {
 
 // AddBase64Funcs -
 func AddBase64Funcs(f map[string]interface{}) {
-	f["base64"] = Base64NS
+	for k, v := range CreateBase64Funcs(context.Background()) {
+		f[k] = v
+	}
+}
+
+// CreateBase64Funcs -
+func CreateBase64Funcs(ctx context.Context) map[string]interface{} {
+	ns := Base64NS()
+	ns.ctx = ctx
+	return map[string]interface{}{"base64": Base64NS}
 }
 
 // Base64Funcs -
-type Base64Funcs struct{}
+type Base64Funcs struct {
+	ctx context.Context
+}
 
 // Encode -
 func (f *Base64Funcs) Encode(in interface{}) (string, error) {