Add file path join to stdlib (#1698)

* add file path join to stdlib

* Update docs/sources/reference/stdlib/file.md

Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

---------

Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

CHANGELOG.md

@@ -10,6 +10,10 @@ internal API changes are not present.
 Main (unreleased)
 -----------------
 
+### Features
+
+- Add the function `path_join` to the stdlib. (@wildum)
+
 ### Bugfixes
 
 - Update yet-another-cloudwatch-exporter from v0.60.0 vo v0.61.0: (@morremeyer)

docs/sources/reference/stdlib/file.md

@@ -0,0 +1,24 @@
+---
+canonical: https://grafana.com/docs/alloy/latest/reference/stdlib/file/
+description: Learn about file functions
+menuTitle: file
+title: file
+---
+
+# file
+
+The `file` namespace contains functions related to files.
+
+## file.path_join
+
+The `file.path_join` function joins any number of path elements into a single path, separating them with an OS-specific separator.
+
+### Examples
+
+```
+> file.path_join()
+""
+
+> file.path_join("this/is", "a/path")
+"this/is/a/path"
+```

syntax/internal/stdlib/stdlib.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"maps"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/grafana/alloy/syntax/alloytypes"
@@ -53,13 +54,18 @@ var Identifiers = map[string]interface{}{
 	"array":    array,
 	"encoding": encoding,
 	"string":   str,
+	"file":     file,
 }
 
 func init() {
 	// Adds the deprecatedIdentifiers to the map of valid identifiers.
 	maps.Copy(Identifiers, DeprecatedIdentifiers)
 }
 
+var file = map[string]interface{}{
+	"path_join": filepath.Join,
+}
+
 var encoding = map[string]interface{}{
 	"from_json":   jsonDecode,
 	"from_yaml":   yamlDecode,

syntax/vm/vm_stdlib_test.go

@@ -215,6 +215,30 @@ func TestStdlib_StringFunc(t *testing.T) {
 	}
 }
 
+func TestStdlibFileFunc(t *testing.T) {
+	tt := []struct {
+		name   string
+		input  string
+		expect interface{}
+	}{
+		{"file.path_join", `file.path_join("this/is", "a/path")`, "this/is/a/path"},
+		{"file.path_join empty", `file.path_join()`, ""},
+	}
+
+	for _, tc := range tt {
+		t.Run(tc.name, func(t *testing.T) {
+			expr, err := parser.ParseExpression(tc.input)
+			require.NoError(t, err)
+
+			eval := vm.New(expr)
+
+			rv := reflect.New(reflect.TypeOf(tc.expect))
+			require.NoError(t, eval.Evaluate(nil, rv.Interface()))
+			require.Equal(t, tc.expect, rv.Elem().Interface())
+		})
+	}
+}
+
 func BenchmarkConcat(b *testing.B) {
 	// There's a bit of setup work to do here: we want to create a scope holding
 	// a slice of the Person type, which has a fair amount of data in it.