Add relative_path built-in function

.gitignore

@@ -15,3 +15,4 @@
 /test-utilities/Cargo.lock
 /test-utilities/target
 /tmp
+/3104issue.json

Cargo.toml

@@ -33,6 +33,7 @@ is_executable = "1.0.4"
 lexiclean = "0.0.1"
 libc = "0.2.0"
 num_cpus = "1.15.0"
+pathdiff = "0.2.3"
 percent-encoding = "2.3.1"
 rand = "0.9.0"
 regex = "1.10.4"

src/function.rs

@@ -84,6 +84,7 @@ pub(crate) fn get(name: &str) -> Option<Function> {
     "prepend" => Binary(prepend),
     "quote" => Unary(quote),
     "read" => Unary(read),
+    "relative_path" => Binary(relpath),
     "replace" => Ternary(replace),
     "replace_regex" => Ternary(replace_regex),
     "require" => Unary(require),
@@ -502,6 +503,22 @@ fn read(context: Context, filename: &str) -> FunctionResult {
     .map_err(|err| format!("I/O error reading `{filename}`: {err}"))
 }
 
+fn relpath(_context: Context, target: &str, base: &str) -> FunctionResult {
+  let base = match Utf8Path::new(base).canonicalize(){
+    Ok(b) => b,
+    Err(e) => return Err(format!("Canonicalize path {base} failed: {e}")),
+  };
+  let target = match Utf8Path::new(target).canonicalize(){
+    Ok(t) => t,
+    Err(e) => return Err(format!("Canonicalize path {target} failed: {e}")),
+  };
+  if let Some(rel) = pathdiff::diff_paths(&target, &base) {
+    Ok(rel.display().to_string())
+  } else {
+    Ok(target.display().to_string()) // fallback to absolute path
+  }
+}
+
 fn replace(_context: Context, s: &str, from: &str, to: &str) -> FunctionResult {
   Ok(s.replace(from, to))
 }

tests/functions.rs

@@ -1501,3 +1501,57 @@ fn read_file_not_found() {
     .stderr_regex(r"error: Call to function `read` failed: I/O error reading `bar`: .*")
     .failure();
 }
+
+#[test]
+fn relative_path() {
+  Test::new()
+    .justfile(
+      r"
+foo := relative_path('/usr/bin', '/usr/lib')
+"
+    )
+    .args(["--evaluate", "foo"])
+    .stdout("../bin")
+    .success();
+}
+
+#[test]
+fn relative_path_dont_exists() {
+  Test::new()
+    .justfile(
+      r"
+foo := relative_path('/foo/bar', '/qux/baz')
+"
+    ) // make sure these two dir doesn't exists on your system
+    .args(["--evaluate", "foo"])
+    .stderr_regex(r"error: Call to function `relative_path` failed: Canonicalize path .* failed: .*")
+    .failure();
+}
+
+#[cfg(target_os = "windows")]
+#[test]
+fn relative_path_windows() {
+  Test::new()
+    .justfile(
+      r"
+foo := relative_path('C:\usr\bin', 'C:\usr\lib')
+"
+    )
+    .args(["--evaluate", "foo"])
+    .stdout("..\\bin")
+    .success();
+}
+
+#[cfg(target_os = "windows")]
+#[test]
+fn relative_path_windows_none() {
+  Test::new()
+    .justfile(
+      r"
+foo := relative_path('C:\usr\bin', 'D:\usr\lib')
+"
+    )
+    .args(["--evaluate", "foo"])
+    .stdout("D:\\usr\\lib")
+    .success();
+}