eintr: what-line
6.2 ‘what-line’
===============
The ‘what-line’ command tells you the number of the line in which the
cursor is located. The function illustrates the use of the
‘save-restriction’ and ‘save-excursion’ commands. Here is the original
text of the function:
(defun what-line ()
"Print the current line number (in the buffer) of point."
(interactive)
(save-restriction
(widen)
(save-excursion
(beginning-of-line)
(message "Line %d"
(1+ (count-lines 1 (point)))))))
(In recent versions of GNU Emacs, the ‘what-line’ function has been
expanded to tell you your line number in a narrowed buffer as well as
your line number in a widened buffer. The recent version is more
complex than the version shown here. If you feel adventurous, you might
want to look at it after figuring out how this version works. You will
probably need to use ‘C-h f’ (‘describe-function’). The newer version
uses a conditional to determine whether the buffer has been narrowed.
(Also, it uses ‘line-number-at-pos’, which among other simple
expressions, such as ‘(goto-char (point-min))’, moves point to the
beginning of the current line with ‘(forward-line 0)’ rather than
‘beginning-of-line’.)
The ‘what-line’ function as shown here has a documentation line and
is interactive, as you would expect. The next two lines use the
functions ‘save-restriction’ and ‘widen’.
The ‘save-restriction’ special form notes whatever narrowing is in
effect, if any, in the current buffer and restores that narrowing after
the code in the body of the ‘save-restriction’ has been evaluated.
The ‘save-restriction’ special form is followed by ‘widen’. This
function undoes any narrowing the current buffer may have had when
‘what-line’ was called. (The narrowing that was there is the narrowing
that ‘save-restriction’ remembers.) This widening makes it possible for
the line counting commands to count from the beginning of the buffer.
Otherwise, they would have been limited to counting within the
accessible region. Any original narrowing is restored just before the
completion of the function by the ‘save-restriction’ special form.
The call to ‘widen’ is followed by ‘save-excursion’, which saves the
location of the cursor (i.e., of point), and restores it after the code
in the body of the ‘save-excursion’ uses the ‘beginning-of-line’
function to move point.
(Note that the ‘(widen)’ expression comes between the
‘save-restriction’ and ‘save-excursion’ special forms. When you write
the two ‘save- ...’ expressions in sequence, write ‘save-excursion’
outermost.)
The last two lines of the ‘what-line’ function are functions to count
the number of lines in the buffer and then print the number in the echo
area.
(message "Line %d"
(1+ (count-lines 1 (point)))))))
The ‘message’ function prints a one-line message at the bottom of the
Emacs screen. The first argument is inside of quotation marks and is
printed as a string of characters. However, it may contain a ‘%d’
expression to print a following argument. ‘%d’ prints the argument as a
decimal, so the message will say something such as ‘Line 243’.
The number that is printed in place of the ‘%d’ is computed by the
last line of the function:
(1+ (count-lines 1 (point)))
What this does is count the lines from the first position of the buffer,
indicated by the ‘1’, up to ‘(point)’, and then add one to that number.
(The ‘1+’ function adds one to its argument.) We add one to it because
line 2 has only one line before it, and ‘count-lines’ counts only the
lines _before_ the current line.
After ‘count-lines’ has done its job, and the message has been
printed in the echo area, the ‘save-excursion’ restores point to its
original position; and ‘save-restriction’ restores the original
narrowing, if any.