[#520] Expose fn straight-chase-emulated-symlink

README.md

@@ -100,6 +100,7 @@ chat][gitter-badge]][gitter]
     + [Integration with Hydra](#integration-with-hydra)
   * [Miscellaneous](#miscellaneous)
 - [Developer manual](#developer-manual)
+  * [Low-level functions](#low-level-functions)
 - [Trivia](#trivia)
   * [Comments and docstrings](#comments-and-docstrings)
 - [Contributing](#contributing)
@@ -2660,7 +2661,14 @@ details and design decisions that power `straight.el` behind the
 scenes. It assumes you have already read the [user manual][#user] and
 the [conceptual overview][#concepts].
 
-Unfortunately, I haven't yet had time to write it. See [#51].
+More to be written here in future. See [#51].
+
+### Low-level functions
+
+* The function `straight-chase-emulated-symlink` is provided in order
+  for external packages to correctly handle the emulated symlinks
+  created by `straight.el` when `straight-use-symlinks` is nil. See,
+  for example, [#520].
 
 ## Trivia
 
@@ -3027,6 +3035,7 @@ the version lock file. This addresses issues [#58], [#66], and [#294].
 [#357]: https://github.com/raxod502/straight.el/issues/357
 [#425]: https://github.com/raxod502/straight.el/issues/425
 [#508]: https://github.com/raxod502/straight.el/issues/508
+[#520]: https://github.com/raxod502/straight.el/issues/520
 
 [auto-compile]: https://github.com/tarsius/auto-compile
 [borg]: https://github.com/emacscollective/borg

straight.el

@@ -4064,23 +4064,41 @@ the build directory, creating a pristine set of symlinks."
         (make-directory (file-name-directory build-file) 'parents)
         (straight--symlink-recursively repo-file build-file)))))
 
+(defvar straight-symlink-emulation-mode)
+
+(defun straight-chase-emulated-symlink (filename)
+  "Check if FILENAME is an emulated symlink.
+Return nil if it's not. Return the link target if it is. Return
+`broken' if it seems like it should be, but it can't be resolved
+to an existing file. See `straight-symlink-emulation-mode'."
+  (when straight-symlink-emulation-mode
+    (let ((build-dir (straight--build-dir)))
+      (when (straight--path-prefix-p build-dir filename)
+        ;; Remove the ~/.emacs.d/straight/build/ part, and get the
+        ;; corresponding path under straight/links/.
+        (let* ((relative-path (substring filename (length build-dir)))
+               (link-record (straight--links-file relative-path)))
+          (if (file-exists-p link-record)
+              (let ((target
+                     (with-temp-buffer
+                       (insert-file-contents-literally link-record)
+                       (buffer-string))))
+                (if (or (string-empty-p target)
+                        (not (file-exists-p target)))
+                    'broken
+                  target))
+            'broken))))))
+
 (defun straight-maybe-emulate-symlink ()
   "If visiting an emulated symlink, visit the link target instead.
 See `straight-symlink-emulation-mode'."
-  (let ((build-dir (straight--build-dir)))
-    (when (and buffer-file-name
-               (straight--path-prefix-p build-dir buffer-file-name))
-      ;; Remove the ~/.emacs.d/straight/build/ part, and get the
-      ;; corresponding path under straight/links/.
-      (let* ((relative-path (substring buffer-file-name (length build-dir)))
-             (link-record (straight--links-file relative-path)))
-        (if (file-exists-p link-record)
-            (find-alternate-file
-             (with-temp-buffer
-               (insert-file-contents-literally link-record)
-               (buffer-string)))
-          (straight--output
-           "Broken symlink, you are not editing the real file"))))))
+  (when buffer-file-name
+    (pcase (straight-chase-emulated-symlink buffer-file-name)
+      (`nil)
+      (`broken
+       (straight--output
+        "Broken symlink, you are not editing the real file"))
+      (target (find-alternate-file target)))))
 
 (define-minor-mode straight-symlink-emulation-mode
   "Minor mode for emulating symlinks in the software layer.