lib: implement `sourcepath()` function

The sourcepath() function allows querying the filesystem path of the source
file currently being executed by ucode.

The optional depth argument can be used to walk up the include stack to
determine the path of the file that included the current file, the path of
the parent file of the parent file and so on.

By specifying a truish value as second argument, only the directory portion
of the source file path is returned. This is useful to e.g. discover
ressources relative to the current source file directory.

Signed-off-by: Jo-Philipp Wich <jo@mein.io>

1 files changed, 19 insertions, 0 deletions

diff --git a/README.md b/README.md
index fc3c1da..929d261 100644
--- a/README.md
+++ b/README.md
@@ -1173,3 +1173,22 @@ performed. If a non-string value is supplied as subject, it is converted into
 a string before being matched.
 
 Returns `true` when the subject matches the pattern or `false` when not.
+
+#### 6.59. `sourcepath([depth [, dironly]])`
+
+Determine the path of the source file currently being executed by ucode.
+
+The optional `depth` parameter allows walking up the call stack to determine
+the path of the parent sources including or requiring the current source file.
+If unspecified, the `depth` defaults to `0`, that is the currently executed
+file.
+
+If a truish value is passed in `dironly`, only the directory portion of the
+source file path is returned.
+
+If the ucode interpreter executes code from stdin or a code fragment passed
+via `-s` switch, the function returns `null` since there is no associated
+file path.
+
+If `depth` exceeds the size of the call stack, the function returns `null`
+as well.