feat: add joinEnv and joinUrl string functions and 2 new system vars (#2408)

compiler.go

@@ -202,11 +202,13 @@ func (c *Compiler) getSpecialVars(t *ast.Task, call *Call) (map[string]string, e
 	// across platforms. This prevents issues with backslashes being interpreted
 	// as escape sequences when paths are used in shell commands on Windows.
 	allVars := map[string]string{
-		"TASK_EXE":         filepath.ToSlash(os.Args[0]),
+		"TASK_EXE":            filepath.ToSlash(os.Args[0]),
-		"ROOT_TASKFILE":    filepath.ToSlash(filepathext.SmartJoin(c.Dir, c.Entrypoint)),
+		"ROOT_TASKFILE":       filepath.ToSlash(filepathext.SmartJoin(c.Dir, c.Entrypoint)),
-		"ROOT_DIR":         filepath.ToSlash(c.Dir),
+		"ROOT_DIR":            filepath.ToSlash(c.Dir),
-		"USER_WORKING_DIR": filepath.ToSlash(c.UserWorkingDir),
+		"USER_WORKING_DIR":    filepath.ToSlash(c.UserWorkingDir),
-		"TASK_VERSION":     version.GetVersion(),
+		"TASK_VERSION":        version.GetVersion(),
+		"PATH_LIST_SEPARATOR": string(os.PathListSeparator),
+		"FILE_PATH_SEPARATOR": string(os.PathSeparator),
 	}
 	if t != nil {
 		allVars["TASK"] = t.Task

internal/summary/summary.go

@@ -285,7 +285,9 @@ func isEnvVar(key string, envVars map[string]bool) bool {
 		key == "TASKFILE_DIR" ||
 		key == "USER_WORKING_DIR" ||
 		key == "ALIAS" ||
-		key == "MATCH" {
+		key == "MATCH" ||
+		key == "PATH_LIST_SEPARATOR" ||
+		key == "FILE_PATH_SEPARATOR" {
 		return true
 	}
 	return envVars[key]

internal/templater/funcs.go

@@ -3,6 +3,8 @@ package templater
 import (
 	"maps"
 	"math/rand/v2"
+	"os"
+	"path"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -21,8 +23,8 @@ var templateFuncs template.FuncMap
 
 func init() {
 	taskFuncs := template.FuncMap{
-		"OS":           os,
+		"OS":           goos,
-		"ARCH":         arch,
+		"ARCH":         goarch,
 		"numCPU":       runtime.NumCPU,
 		"catLines":     catLines,
 		"splitLines":   splitLines,
@@ -33,6 +35,8 @@ func init() {
 		"splitArgs":    splitArgs,
 		"IsSH":         IsSH, // Deprecated
 		"joinPath":     filepath.Join,
+		"joinEnv":      joinEnv,
+		"joinUrl":      joinUrl,
 		"relPath":      filepath.Rel,
 		"absPath":      filepath.Abs,
 		"merge":        merge,
@@ -57,11 +61,11 @@ func init() {
 	maps.Copy(templateFuncs, taskFuncs)
 }
 
-func os() string {
+func goos() string {
 	return runtime.GOOS
 }
 
-func arch() string {
+func goarch() string {
 	return runtime.GOARCH
 }
 
@@ -95,6 +99,14 @@ func IsSH() bool {
 	return true
 }
 
+func joinEnv(elem ...string) string {
+	return strings.Join(elem, string(os.PathListSeparator))
+}
+
+func joinUrl(elem ...string) string {
+	return path.Join(elem...)
+}
+
 func merge(base map[string]any, v ...map[string]any) map[string]any {
 	cap := len(v)
 	for _, m := range v {

website/src/docs/reference/templating.md

@@ -249,6 +249,32 @@ tasks:
       - echo "Working {{.USER_WORKING_DIR}}"
 ```
 
+#### `FILE_PATH_SEPARATOR`
+
+- **Type**: `string`
+- **Description**: OS-specific path separator: Windows = `\`, others = `/`
+
+::: info
+
+> See `joinPath` in [Path Functions](#path-functions) for joining filesystem paths for use with
+> file system operations.
+
+:::
+
+### Environment Variables
+
+#### `PATH_LIST_SEPARATOR`
+
+- **Type**: `string`
+- **Description**: OS-specific path separator for environment variables: Windows = `;`, others = `:`
+
+::: info
+
+> See `joinEnv` in [Environment Variable Functions](#environment-variable-functions) for joining
+> paths for use in environment variables.
+
+:::
+
 ### Status
 
 #### `CHECKSUM`
@@ -597,9 +623,9 @@ tasks:
 tasks:
   platform:
     cmds:
-      - echo "OS {{OS}}"                         # linux, darwin, windows, etc.
+      - echo "OS {{OS}}"                    # linux, darwin, windows, etc.
-      - echo "Architecture {{ARCH}}"             # amd64, arm64, etc.
+      - echo "Architecture {{ARCH}}"        # amd64, arm64, etc.
-      - echo "CPU cores {{numCPU}}"              # Number of CPU cores
+      - echo "CPU cores {{numCPU}}"         # Number of CPU cores
       - echo "Building for {{OS}}/{{ARCH}}"
 ```
 
@@ -613,11 +639,52 @@ tasks:
       OUTPUT_DIR: 'dist'
       BINARY_NAME: 'myapp'
     cmds:
-      - echo "{{.WIN_PATH | toSlash}}"                          # Convert to forward slashes
+      - echo "{{.WIN_PATH | toSlash}}"                      # Convert to forward slashes
-      - echo "{{.WIN_PATH | fromSlash}}"                        # Convert to OS-specific slashes
+      - echo "{{.WIN_PATH | fromSlash}}"                    # Convert to OS-specific slashes
-      - echo "{{joinPath .OUTPUT_DIR .BINARY_NAME}}"            # Join path elements
+      - echo "{{joinPath .OUTPUT_DIR .BINARY_NAME}}"        # Join path elements
-      - echo "Relative {{relPath .ROOT_DIR .TASKFILE_DIR}}"    # Get relative path
+      - echo "Relative {{relPath .ROOT_DIR .TASKFILE_DIR}}" # Get relative path
-      - echo '{{absPath "../sibling"}}'                         # Resolve to an absolute path
+      - echo '{{absPath "../sibling"}}'                     # Resolve to an absolute path
+```
+
+#### Environment Variable Functions
+
+```yaml
+tasks:
+  paths:
+    vars:
+      WIN_PATH1: 'C:\Users\Person\bin'
+      WIN_PATH2: 'C:\Shared\bin'
+    cmds:
+      # Join paths for Windows ENV vars:
+      # C:\Users\Person\bin;C:\Shared\bin
+      - echo "{{joinEnv .WIN_PATH1 .WIN_PATH2}}"
+```
+
+```yaml
+tasks:
+  paths:
+    vars:
+      POSIX_PATH1: '/users/person/.local/bin'
+      POSIX_PATH2: '/usr/bin'
+    cmds:
+      # Join paths for POSIX ENV vars:
+      # /users/person/.local/bin:/usr/bin
+      - echo "{{joinEnv .POSIX_PATH1 .POSIX_PATH2}}"
+```
+
+#### URLs
+
+```yaml
+tasks:
+  paths:
+    vars:
+      SERVER: 'http://localhost'
+      PATH1: 'path1'
+      PATH2: 'path2'
+    cmds:
+      # Join paths for URL:
+      # http://localhost/path1/path2
+      - echo "{{joinUrl .SERVER .PATH1 .PATH2}}"
 ```
 
 ### Data Structure Functions