Add fs.relative_to()

Returns a relative path from arg 2 to arg 1 similar to
os.path.relpath().

2 files changed, 31 insertions, 0 deletions

diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md
index cc67355..bf9ddba 100644
--- a/docs/markdown/Fs-module.md
+++ b/docs/markdown/Fs-module.md
@@ -224,6 +224,20 @@ fs.stem('foo/bar/baz.dll.a')  # baz.dll
    project. If the file specified by `path` is a `files()` object it
    cannot refer to a built file.
 
+### relative_to
+
+*Since 1.3.0*
+
+Return a relative filepath. In event a relative path could not be found, the
+absolute path of `to` is returned. Relative path arguments will be assumed to be
+relative to `meson.current_source_dir()`.
+
+Has the following positional arguments:
+   - to `str | file | custom_tgt | custom_idx | tgt`: end path
+   - from `str | file | custom_tgt | custom_idx | tgt`: start path
+
+returns:
+   - a string
 
 ### copyfile
 
diff --git a/docs/markdown/snippets/fs_relative_to.md b/docs/markdown/snippets/fs_relative_to.md
new file mode 100644
index 0000000..82e6a42
--- /dev/null
+++ b/docs/markdown/snippets/fs_relative_to.md
@@ -0,0 +1,17 @@
+## `fs.relative_to()`
+
+The `fs` module now has a `relative_to` method. The method will return the
+relative path from argument one to argument two, if one exists. Otherwise, the
+absolute path to argument one is returned.
+
+```meson
+assert(fs.relative_to('c:\\prefix\\lib', 'c:\\prefix\\bin') == '..\\lib')
+assert(fs.relative_to('c:\\proj1\\foo', 'd:\\proj1\\bar') == 'c:\\proj1\\foo')
+assert(fs.relative_to('prefix\\lib\\foo', 'prefix') == 'lib\\foo')
+
+assert(fs.relative_to('/prefix/lib', '/prefix/bin') == '../lib')
+assert(fs.relative_to('prefix/lib/foo', 'prefix') == 'lib/foo')
+```
+
+In addition to strings, it can handle files, custom targets, custom target
+indices, and build targets.