docs(vrl): add new path related documents (#23935)

add path related documents

Co-authored-by: Pavlos Rontidis <[email protected]>
Co-authored-by: Thomas <[email protected]>

Author: 3 people

website/cue/reference/remap/functions/basename.cue

@@ -0,0 +1,53 @@
+package metadata
+
+remap: functions: basename: {
+	category: "String"
+	description: """
+		Returns the filename component of the given `path`. This is similar to the Unix `basename` command.
+		If the path ends in a directory separator, the function returns the name of the directory.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The path from which to extract the basename."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not a valid string.",
+	]
+	return: types: ["string", "null"]
+
+	examples: [
+		{
+			title: "Extract basename from file path"
+			source: """
+				basename!("/usr/local/bin/vrl")
+				"""
+			return: "vrl"
+		},
+		{
+			title: "Extract basename from file path with extension"
+			source: """
+				basename!("/home/user/file.txt")
+				"""
+			return: "file.txt"
+		},
+		{
+			title: "Extract basename from directory path"
+			source: """
+				basename!("/home/user/")
+				"""
+			return: "user"
+		},
+		{
+			title: "Root directory has no basename"
+			source: """
+				basename!("/")
+				"""
+			return: null
+		},
+	]
+}

website/cue/reference/remap/functions/dirname.cue

@@ -0,0 +1,60 @@
+package metadata
+
+remap: functions: dirname: {
+	category: "String"
+	description: """
+		Returns the directory component of the given `path`. This is similar to the Unix `dirname` command.
+		The directory component is the path with the final component removed.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The path from which to extract the directory name."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not a valid string.",
+	]
+	return: types: ["string"]
+
+	examples: [
+		{
+			title: "Extract dirname from file path"
+			source: """
+				dirname!("/usr/local/bin/vrl")
+				"""
+			return: "/usr/local/bin"
+		},
+		{
+			title: "Extract dirname from file path with extension"
+			source: """
+				dirname!("/home/user/file.txt")
+				"""
+			return: "/home/user"
+		},
+		{
+			title: "Extract dirname from directory path"
+			source: """
+				dirname!("/home/user/")
+				"""
+			return: "/home"
+		},
+		{
+			title: "Root directory dirname is itself"
+			source: """
+				dirname!("/")
+				"""
+			return: "/"
+		},
+		{
+			title: "Relative files have current directory as dirname"
+			source: """
+				dirname!("file.txt")
+				"""
+			return: "."
+		},
+	]
+}

website/cue/reference/remap/functions/split_path.cue

@@ -0,0 +1,53 @@
+package metadata
+
+remap: functions: split_path: {
+	category: "String"
+	description: """
+		Splits the given `path` into its constituent components, returning an array of strings.
+		Each component represents a part of the file system path hierarchy.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The path to split into components."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not a valid string.",
+	]
+	return: types: ["array"]
+
+	examples: [
+		{
+			title: "Split path with trailing slash"
+			source: """
+				split_path!("/home/user/")
+				"""
+			return: ["/", "home", "user"]
+		},
+		{
+			title: "Split path from file path"
+			source: """
+				split_path!("/home/user")
+				"""
+			return: ["/", "home", "user"]
+		},
+		{
+			title: "Split path from root"
+			source: """
+				split_path!("/")
+				"""
+			return: ["/"]
+		},
+		{
+			title: "Empty path returns empty array"
+			source: """
+				split_path!("")
+				"""
+			return: []
+		},
+	]
+}