feat: make map variables experiment (prop 2) generally available (#2081)

* feat: make map variables experiment (prop 2) generally available

* docs: remove map variables experiment page and update usage to include map variable info

Author: pd93

internal/experiments/experiments.go

@@ -44,7 +44,7 @@ func init() {
 	GentleForce = New("GENTLE_FORCE", 1)
 	RemoteTaskfiles = New("REMOTE_TASKFILES", 1)
 	AnyVariables = New("ANY_VARIABLES")
-	MapVariables = New("MAP_VARIABLES", 1, 2)
+	MapVariables = New("MAP_VARIABLES")
 	EnvPrecedence = New("ENV_PRECEDENCE", 1)
 }
 

taskfile/ast/var.go

@@ -1,12 +1,9 @@
 package ast
 
 import (
-	"strings"
-
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
-	"github.com/go-task/task/v3/internal/experiments"
 )
 
 // Var represents either a static or dynamic variable.
@@ -19,82 +16,26 @@ type Var struct {
 }
 
 func (v *Var) UnmarshalYAML(node *yaml.Node) error {
-	if experiments.MapVariables.Enabled() {
-
-		// This implementation is not backwards-compatible and replaces the 'sh' key with map variables
-		if experiments.MapVariables.Value == 1 {
-			var value any
-			if err := node.Decode(&value); err != nil {
-				return errors.NewTaskfileDecodeError(err, node)
-			}
-			// If the value is a string and it starts with $, then it's a shell command
-			if str, ok := value.(string); ok {
-				if str, ok = strings.CutPrefix(str, "$"); ok {
-					v.Sh = &str
-					return nil
-				}
-				if str, ok = strings.CutPrefix(str, "#"); ok {
-					v.Ref = str
-					return nil
-				}
-			}
-			v.Value = value
-			return nil
-		}
-
-		// This implementation IS backwards-compatible and keeps the 'sh' key and allows map variables to be added under the `map` key
-		if experiments.MapVariables.Value == 2 {
-			switch node.Kind {
-			case yaml.MappingNode:
-				key := node.Content[0].Value
-				switch key {
-				case "sh", "ref", "map":
-					var m struct {
-						Sh  *string
-						Ref string
-						Map any
-					}
-					if err := node.Decode(&m); err != nil {
-						return errors.NewTaskfileDecodeError(err, node)
-					}
-					v.Sh = m.Sh
-					v.Ref = m.Ref
-					v.Value = m.Map
-					return nil
-				default:
-					return errors.NewTaskfileDecodeError(nil, node).WithMessage(`%q is not a valid variable type. Try "sh", "ref", "map" or using a scalar value`, key)
-				}
-			default:
-				var value any
-				if err := node.Decode(&value); err != nil {
-					return errors.NewTaskfileDecodeError(err, node)
-				}
-				v.Value = value
-				return nil
-			}
-		}
-	}
-
 	switch node.Kind {
-
 	case yaml.MappingNode:
 		key := node.Content[0].Value
 		switch key {
-		case "sh", "ref":
+		case "sh", "ref", "map":
 			var m struct {
 				Sh  *string
 				Ref string
+				Map any
 			}
 			if err := node.Decode(&m); err != nil {
 				return errors.NewTaskfileDecodeError(err, node)
 			}
 			v.Sh = m.Sh
 			v.Ref = m.Ref
+			v.Value = m.Map
 			return nil
 		default:
-			return errors.NewTaskfileDecodeError(nil, node).WithMessage("maps cannot be assigned to variables")
+			return errors.NewTaskfileDecodeError(nil, node).WithMessage(`%q is not a valid variable type. Try "sh", "ref", "map" or using a scalar value`, key)
 		}
-
 	default:
 		var value any
 		if err := node.Decode(&value); err != nil {

website/docs/experiments/map_variables.mdx

@@ -1113,53 +1113,38 @@ variable types are supported:
 - `int`
 - `float`
 - `array`
+- `map`
 
 :::note
 
-Maps are not supported by default, but there is an
-[experiment][map-variables] that can be enabled to add support. If
-you're interested in this functionality, we would appreciate your feedback.
-:pray:
+Defining a map requires that you use a special `map` subkey (see example below).
 
-In the meantime, it is technically possible to define a map using a `ref` resolver and a templating function. For example:
-
-```yaml
-version: '3'
-
-tasks:
-  task-with-map:
-    vars:
-      FOO:
-        ref: dict "a" "1" "b" "2" "c" "3"
-    cmds:
-      - echo {{.FOO}}
-```
-
-```txt
-map[a:1 b:2 c:3]
-```
-
-OR by using the same technique with JSON:
+:::
 
 ```yaml
-version: '3'
+version: 3
 
 tasks:
-  task-with-map:
+  foo:
     vars:
-      JSON: '{"a": 1, "b": 2, "c": 3}'
-      FOO:
-        ref: "fromJson .JSON"
-    cmds:
-      - echo {{.FOO}}
+      STRING: 'Hello, World!'
+      BOOL: true
+      INT: 42
+      FLOAT: 3.14
+      ARRAY: [1, 2, 3]
+      MAP:
+        map: {A: 1, B: 2, C: 3}
+    cmds:
+      - 'echo {{.STRING}}'  # Hello, World!
+      - 'echo {{.BOOL}}'    # true
+      - 'echo {{.INT}}'     # 42
+      - 'echo {{.FLOAT}}'   # 3.14
+      - 'echo {{.ARRAY}}'   # [1 2 3]
+      - 'echo {{.ARRAY.0}}' # 1
+      - 'echo {{.MAP}}'     # map[A:1 B:2 C:3]
+      - 'echo {{.MAP.A}}'   # 1
 ```
 
-```txt
-map[a:1 b:2 c:3]
-```
-
-:::
-
 Variables can be set in many places in a Taskfile. When executing
 [templates][templating-reference], Task will look for variables in the order
 listed below (most important first):
@@ -1360,6 +1345,29 @@ tasks:
       - 'echo {{.FOO}}' # <-- FOO is just the letter 'A'
 ```
 
+### Parsing JSON/YAML into map variables
+
+If you have a raw JSON or YAML string that you want to process in Task, you can
+use a combination of the `ref` keyword and the `fromJson` or `fromYaml`
+templating functions to parse the string into a map variable. For example:
+
+```yaml
+version: '3'
+
+tasks:
+  task-with-map:
+    vars:
+      JSON: '{"a": 1, "b": 2, "c": 3}'
+      FOO:
+        ref: "fromJson .JSON"
+    cmds:
+      - echo {{.FOO}}
+```
+
+```txt
+map[a:1 b:2 c:3]
+```
+
 ## Looping over values
 
 Task allows you to loop over certain values and execute a command for each.
@@ -1508,7 +1516,7 @@ tasks:
         cmd: cat {{.ITEM}}
 ```
 
-You can also loop over arrays directly and maps:
+You can also loop over arrays and maps directly:
 
 ```yaml
 version: 3
@@ -2319,6 +2327,5 @@ if called by another task, either directly or as a dependency.
 
 {/* prettier-ignore-start */}
 [gotemplate]: https://golang.org/pkg/text/template/
-[map-variables]: ./experiments/map_variables.mdx
 [templating-reference]: ./reference/templating.mdx
 {/* prettier-ignore-end */}

website/docs/usage.mdx

@@ -276,7 +276,7 @@
         "^.*$": {
           "anyOf": [
             {
-              "type": ["boolean", "integer", "null", "number", "string", "object", "array"]
+              "type": ["boolean", "integer", "null", "number", "string", "array"]
             },
             {
               "$ref": "#/definitions/var_subkey"