Add absolute optional parameter to line-number-at-pos (Bug#26417)

* lisp/simple.el (line-number-at-pos): Add a second optional
  argument 'absolute'.
* test/list/simple-tests.el: Add tests for 'line-number-at-pos'.

doc/lispref/positions.texi

@@ -432,11 +432,16 @@ prints a message reporting the number of lines, words, and characters
 in the buffer, or in the region if the region is active.
 @end deffn
 
-@defun line-number-at-pos &optional pos
+@defun line-number-at-pos &optional pos absolute
 @cindex line number
 This function returns the line number in the current buffer
-corresponding to the buffer position @var{pos}.  If @var{pos} is @code{nil}
+corresponding to the buffer position @var{pos}.  If @var{pos} is
-or omitted, the current buffer position is used.
+@code{nil} or omitted, the current buffer position is used. If
+@var{absolute} is @code{nil}, the default, counting starts at
+@code{(point-min)}, so the value refers to the contents of the
+accessible portion of the (potentially narrowed) buffer.  If
+@var{absolute} is non-@code{nil}, ignore any narrowing and return
+the absolute line number.
 @end defun
 
 @ignore

etc/NEWS

@@ -1228,6 +1228,13 @@ or its files before 'delete-directory' gets to them.
 *** New error type 'user-search-failed' like 'search-failed' but
 avoids debugger like 'user-error'.
 
++++
+** The function 'line-number-at-pos' now takes a second optional
+argument 'absolute'. If this parameter is nil, the default, this
+function keeps on returning the line number taking potential narrowing
+into account. If this parameter is non-nil, the function ignores
+narrowing and returns the absolute line number.
+
 ** Changes in Frame- and Window- Handling
 
 +++

lisp/simple.el

@@ -1270,18 +1270,25 @@ and the greater of them is not at the start of a line."
 		done)))
 	(- (buffer-size) (forward-line (buffer-size)))))))
 
-(defun line-number-at-pos (&optional pos)
+(defun line-number-at-pos (&optional pos absolute)
-  "Return (narrowed) buffer line number at position POS.
+  "Return buffer line number at position POS.
 If POS is nil, use current buffer location.
-Counting starts at (point-min), so the value refers
+
-to the contents of the accessible portion of the buffer."
+If ABSOLUTE is nil, the default, counting starts
+at (point-min), so the value refers to the contents of the
+accessible portion of the (potentially narrowed) buffer.  If
+ABSOLUTE is non-nil, ignore any narrowing and return the
+absolute line number."
+  (save-restriction
+    (when absolute
+      (widen))
     (let ((opoint (or pos (point))) start)
       (save-excursion
         (goto-char (point-min))
         (setq start (point))
         (goto-char opoint)
         (forward-line 0)
-      (1+ (count-lines start (point))))))
+        (1+ (count-lines start (point)))))))
 
 (defun what-cursor-position (&optional detail)
   "Print info on cursor position (on screen and within buffer).

test/lisp/simple-tests.el

@@ -448,5 +448,54 @@ See Bug#21722."
         (call-interactively #'eval-expression)
         (should (equal (current-message) "66 (#o102, #x42, ?B)"))))))
 
+(ert-deftest line-number-at-pos-in-widen-buffer ()
+  (let ((target-line 3))
+    (with-temp-buffer
+      (insert "a\nb\nc\nd\n")
+      (goto-char (point-min))
+      (forward-line (1- target-line))
+      (should (equal (line-number-at-pos) target-line))
+      (should (equal (line-number-at-pos nil t) target-line)))))
+
+(ert-deftest line-number-at-pos-in-narrow-buffer ()
+  (let ((target-line 3))
+    (with-temp-buffer
+      (insert "a\nb\nc\nd\n")
+      (goto-char (point-min))
+      (forward-line (1- target-line))
+      (narrow-to-region (line-beginning-position) (line-end-position))
+      (should (equal (line-number-at-pos) 1))
+      (should (equal (line-number-at-pos nil t) target-line)))))
+
+(ert-deftest line-number-at-pos-keeps-restriction ()
+  (with-temp-buffer
+    (insert "a\nb\nc\nd\n")
+    (goto-char (point-min))
+    (forward-line 2)
+    (narrow-to-region (line-beginning-position) (line-end-position))
+    (should (equal (line-number-at-pos) 1))
+    (line-number-at-pos nil t)
+    (should (equal (line-number-at-pos) 1))))
+
+(ert-deftest line-number-at-pos-keeps-point ()
+  (let (pos)
+    (with-temp-buffer
+      (insert "a\nb\nc\nd\n")
+      (goto-char (point-min))
+      (forward-line 2)
+      (setq pos (point))
+      (line-number-at-pos)
+      (line-number-at-pos nil t)
+      (should (equal pos (point))))))
+
+(ert-deftest line-number-at-pos-when-passing-point ()
+  (let (pos)
+    (with-temp-buffer
+      (insert "a\nb\nc\nd\n")
+      (should (equal (line-number-at-pos 1) 1))
+      (should (equal (line-number-at-pos 3) 2))
+      (should (equal (line-number-at-pos 5) 3))
+      (should (equal (line-number-at-pos 7) 4)))))
+
 (provide 'simple-test)
 ;;; simple-test.el ends here