From ad09164d0c1ca3b665da7d2d9d9235411c6fb1dc Mon Sep 17 00:00:00 2001
From: Sizhe Zhao <prc.zhao@outlook.com>
Date: Thu, 27 Mar 2025 00:58:32 +0800
Subject: [PATCH] docs: document unsafeGetAttrPos

Closes https://git.lix.systems/lix-project/lix/issues/770.

See also https://github.com/NixOS/nix/pull/12760.

Change-Id: Ibe7a9a41a84f749e3e9bedce8da28039fa6e6d2f
---
 lix/libexpr/builtins/unsafeGetAttrPos.md | 17 +++++++++++++++++
 lix/libexpr/meson.build                  |  1 +
 lix/libexpr/primops.cc                   |  6 ------
 3 files changed, 18 insertions(+), 6 deletions(-)
 create mode 100644 lix/libexpr/builtins/unsafeGetAttrPos.md

diff --git a/lix/libexpr/builtins/unsafeGetAttrPos.md b/lix/libexpr/builtins/unsafeGetAttrPos.md
new file mode 100644
index 000000000..4241d12a7
--- /dev/null
+++ b/lix/libexpr/builtins/unsafeGetAttrPos.md
@@ -0,0 +1,17 @@
+---
+name: unsafeGetAttrPos
+args: [s, attrset]
+---
+`unsafeGetAttrPos` returns the position of the original definition (possibly
+before operations like set merges) of the attribute named *s* from *attrset*.
+
+If the position couldn't be determined (for example the set was produced by
+builtin functions like `mapAttrs`), `null` will be returned instead, otherwise
+a attrset will be returned, and it has the following attributes:
+
+- `file` (string)
+- `line` (number)
+- `column` (number)
+
+This is unsafe because it allows us to distinguish sets that compare equal but
+are defined at different locations.
diff --git a/lix/libexpr/meson.build b/lix/libexpr/meson.build
index 03a61a83e..9b029e562 100644
--- a/lix/libexpr/meson.build
+++ b/lix/libexpr/meson.build
@@ -147,6 +147,7 @@ builtin_definitions = files(
   'builtins/tryEval.md',
   'builtins/typeOf.md',
   'builtins/unsafeDiscardOutputDependency.md',
+  'builtins/unsafeGetAttrPos.md',
   'builtins/zipAttrsWith.md',
   # keep-sorted end
 )
diff --git a/lix/libexpr/primops.cc b/lix/libexpr/primops.cc
index 21265f7f3..890d4c667 100644
--- a/lix/libexpr/primops.cc
+++ b/lix/libexpr/primops.cc
@@ -1721,12 +1721,6 @@ static void prim_unsafeGetAttrPos(EvalState & state, const PosIdx pos, Value * *
         state.mkPos(v, i->pos);
 }
 
-static RegisterPrimOp primop_unsafeGetAttrPos(PrimOp {
-    .name = "__unsafeGetAttrPos",
-    .arity = 2,
-    .fun = prim_unsafeGetAttrPos,
-});
-
 // access to exact position information (ie, line and colum numbers) is deferred
 // due to the cost associated with calculating that information and how rarely
 // it is used in practice. this is achieved by creating thunks to otherwise