bug#73308: [PATCH] Add file-to-register and buffer-to-register.

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Barra Ó Catháin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1363 bytes --]

Tags: patch

Tags: patch

This patch adds two new functions and keybindings for them,
file-to-register and buffer-to-register.

These functions make it simpler to put a file/buffer into a register,
which I have personally found to be useful when working with projects
where I don't wish to disturb the point or to pull up notes files.

(Previously submitted, but I was unfortunately unable to follow it up at
the time due to life getting busy!)

Questions and comments appreciated, previously assigned copyright.

In GNU Emacs 29.4 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.43,
cairo version 1.18.0)
Windowing system distributor 'The X.Org Foundation', version 11.0.12101013
System Description: Arch Linux

Configured using:
 'configure --sysconfdir=/etc --prefix=/usr --libexecdir=/usr/lib
 --with-tree-sitter --localstatedir=/var --with-cairo
 --disable-build-details --with-harfbuzz --with-libsystemd
 --with-modules --with-x-toolkit=gtk3 'CFLAGS=-march=x86-64
 -mtune=generic -O2 -pipe -fno-plt -fexceptions -Wp,-D_FORTIFY_SOURCE=3
 -Wformat -Werror=format-security -fstack-clash-protection
 -fcf-protection -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -g
 -ffile-prefix-map=/build/emacs/src=/usr/src/debug/emacs -flto=auto'
 'LDFLAGS=-Wl,-O1 -Wl,--sort-common -Wl,--as-needed -Wl,-z,relro
 -Wl,-z,now -Wl,-z,pack-relative-relocs -flto=auto''


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-file-to-register-and-buffer-to-register.patch --]
[-- Type: text/patch, Size: 7058 bytes --]

From 29a160f087a0e530e415a9f2676abb390c54f910 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Barra=20=C3=93=20Cath=C3=A1in?= <barra@ocathain.ie>
Date: Tue, 17 Sep 2024 00:11:11 +0100
Subject: [PATCH] Add file-to-register and buffer-to-register.

* lisp/bindings.el (ctl-x-r-map):
Add bindings to the register keymap for the two new
functions. 'F' for file-to-register and 'B' for
buffer-to-register.

* lisp/register.el (register-command-info): Registers the two
new functions, file-to-register and buffer-to-register as
commands.

(file-to-register):
New function, stores a file into a register. Used interactively,
prompts for REGISTER using `register-read-with-preview'. With a
prefix-argument, prompts for FILE-NAME using `read-file-name',
otherwise, uses the currently visited file or directory for
FILE-NAME.

(buffer-to-register):
New function, stores a buffer into a register. Used
interactively, prompts for REGISTER using
`register-read-with-preview'. With a prefix-argument, prompts
for BUFFER-NAME using `read-buffer', otherwise, uses the current
buffer.

* doc/emacs/regs.texi (File and Buffer Registers):
Added documentation for the new file-to-register and
buffer-to-register commands, replacing the elisp snippet that
was used previously.
---
 doc/emacs/regs.texi | 55 ++++++++++++++++++++++++---------------------
 lisp/bindings.el    |  4 +++-
 lisp/register.el    | 41 +++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 26 deletions(-)

diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 734d704a272..446b42395ba 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -289,41 +289,46 @@ File and Buffer Registers
 @section Keeping File and Buffer Names in Registers
 @cindex saving file name in a register
 @cindex saving buffer name in a register
+@kindex C-x r F
+@kindex C-x r B
 
   If you visit certain file names frequently, you can visit them more
-conveniently if you put their names in registers.  Here's the Lisp code
-used to put a file @var{name} into register @var{r}:
+conveniently if you put their names in registers.  Here's how you can
+put a file into a buffer.
 
-@smallexample
-(set-register @var{r} '(file . @var{name}))
-@end smallexample
-
-@need 3000
-@noindent
-For example,
-
-@smallexample
-(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
-@end smallexample
-
-@noindent
-puts the file name shown in register @samp{z}.
+@table @kbd
+@item C-x r F @var{r}
+@kindex C-x r F
+@findex file-to-register
+Store the currently visited file or directory into register @var{r} (@code{file-to-register}).
+@item C-u C-x r F @var{r}
+@kindex C-x r F
+@findex file-to-register
+Prompt for a file, and store into register @var{r} (@code{file-to-register}).
+@end table
 
   To visit the file whose name is in register @var{r}, type @kbd{C-x r j
 @var{r}}.  (This is the same command used to jump to a position or
 restore a frame configuration.)
 
-  Similarly, if there are certain buffers you visit frequently, you
-can put their names in registers.  For instance, if you visit the
-@samp{*Messages*} buffer often, you can use the following snippet to
-put that buffer into the @samp{m} register:
+  Similarly, if there are certain buffers you visit frequently, you can
+put their names in registers. You can use the following command to put a
+buffer into a register.
 
-@smallexample
-(set-register ?m '(buffer . "*Messages*"))
-@end smallexample
+@table @kbd
+@item C-x r B @var{r}
+@kindex C-x r B
+@findex buffer-to-register
+Store the current buffer into register @var{r} (@code{buffer-to-register}).
+@item C-u C-x r B @var{r}
+@kindex C-x r B
+@findex buffer-to-register
+Prompt for a buffer, and store into register @var{r} (@code{buffer-to-register}).
+@end table
 
-  To switch to the buffer whose name is in register @var{r}, type
-@kbd{C-x r j @var{r}}.
+  To visit the buffer whose name is in register @var{r}, type @kbd{C-x r
+  j @var{r}}. (This is the same command used to jump to a position or
+  restore a frame configuration.)
 
 @node Keyboard Macro Registers
 @section Keyboard Macro Registers
diff --git a/lisp/bindings.el b/lisp/bindings.el
index 6b34c5750c1..06a488fa9fa 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -1574,7 +1574,9 @@ ctl-x-r-map
   "n"     #'number-to-register
   "+"     #'increment-register
   "w"     #'window-configuration-to-register
-  "f"     #'frameset-to-register)
+  "f"     #'frameset-to-register
+  "F"     #'file-to-register
+  "B"     #'buffer-to-register)
 (define-key ctl-x-map "r" ctl-x-r-map)
 
 (define-key esc-map "q" 'fill-paragraph)
diff --git a/lisp/register.el b/lisp/register.el
index 497848ded1e..01be41314c5 100644
--- a/lisp/register.el
+++ b/lisp/register.el
@@ -300,6 +300,18 @@ register-command-info
    :act 'set
    :noconfirm (memq register-use-preview '(nil never))
    :smatch t))
+(cl-defmethod register-command-info ((_command (eql file-to-register)))
+  (make-register-preview-info
+   :types '(all)
+   :msg "File to register `%s'"
+   :act 'set
+   :noconfirm (memq register-use-preview '(nil never))))
+(cl-defmethod register-command-info ((_command (eql buffer-to-register)))
+  (make-register-preview-info
+   :types '(all)
+   :msg "Buffer to register `%s'"
+   :act 'set
+   :noconfirm (memq register-use-preview '(nil never))))
 
 (defun register-preview-forward-line (arg)
   "Move to next or previous line in register preview buffer.
@@ -688,6 +700,35 @@ jump-to-register
   (let ((val (get-register register)))
     (register-val-jump-to val delete)))
 
+(defun file-to-register (file-name register)
+  "Inserts FILE-NAME in REGISTER.
+To visit the file, use \\[jump-to-register].
+
+Interactively, prompts for REGISTER using `register-read-with-preview'.
+With a prefix-argument, prompts for FILE-NAME using `read-file-name',
+otherwise, uses the currently visited file or directory for FILE-NAME."
+  (interactive (list (if (eq current-prefix-arg nil)
+                         (if (eq major-mode 'dired-mode)
+                             (dired-current-directory)
+                           (buffer-file-name))
+                       (read-file-name "File: "))
+                (register-read-with-preview "File to register: ")))
+  (unless (eq file-name nil)
+    (set-register register (cons 'file file-name))))
+
+(defun buffer-to-register (buffer register)
+  "Inserts BUFFER in REGISTER.
+To visit the buffer, use \\[jump-to-register].
+
+Interactively, prompts for REGISTER using `register-read-with-preview'.
+With a prefix-argument, prompts for BUFFER-NAME using `read-buffer',
+otherwise, uses the current buffer."
+  (interactive (list (if (eq current-prefix-arg nil)
+                         (current-buffer)
+                       (read-buffer "Buffer: "))
+                     (register-read-with-preview "Buffer to register: ")))
+  (set-register register (cons 'buffer buffer)))
+
 (cl-defgeneric register-val-jump-to (_val _arg)
   "Execute the \"jump\" operation of VAL.
 VAL is the contents of a register as returned by `get-register'.
-- 
2.46.1

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Eli Zaretskii]

> List-Unsubscribe-Post: List-Unsubscribe=One-Click
> Date: Tue, 17 Sep 2024 00:32:40 +0100
> From:  Barra Ó Catháin via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> This patch adds two new functions and keybindings for them,
> file-to-register and buffer-to-register.
> 
> These functions make it simpler to put a file/buffer into a register,
> which I have personally found to be useful when working with projects
> where I don't wish to disturb the point or to pull up notes files.
> 
> (Previously submitted, but I was unfortunately unable to follow it up at
> the time due to life getting busy!)
> 
> Questions and comments appreciated, previously assigned copyright.

Thierry, any comments to these additions?

> * lisp/bindings.el (ctl-x-r-map):
> Add bindings to the register keymap for the two new
> functions. 'F' for file-to-register and 'B' for
> buffer-to-register.
> 
> * lisp/register.el (register-command-info): Registers the two
> new functions, file-to-register and buffer-to-register as
> commands.
> 
> (file-to-register):
> New function, stores a file into a register. Used interactively,
> prompts for REGISTER using `register-read-with-preview'. With a
> prefix-argument, prompts for FILE-NAME using `read-file-name',
> otherwise, uses the currently visited file or directory for
> FILE-NAME.
> 
> (buffer-to-register):
> New function, stores a buffer into a register. Used
> interactively, prompts for REGISTER using
> `register-read-with-preview'. With a prefix-argument, prompts
> for BUFFER-NAME using `read-buffer', otherwise, uses the current
> buffer.

This is not exactly the format of log entries which we prefer.  See
"git log" for examples and CONTRIBUTE for explanations.

> +@table @kbd
> +@item C-x r F @var{r}
> +@kindex C-x r F
> +@findex file-to-register
> +Store the currently visited file or directory into register @var{r} (@code{file-to-register}).
> +@item C-u C-x r F @var{r}
> +@kindex C-x r F
> +@findex file-to-register
> +Prompt for a file, and store into register @var{r} (@code{file-to-register}).

First, @*index index entries should appear _before_ the @item lines,
so that Info-index places you on the line created from @item, not
after it.

And second, the above defines two identical @kindex entries "C-x r F"
that both point to the same page, and that is not useful.  We should
keep only one of them.  The same about the 2 identical @findex
entries.  (Actually, you have 3 identical @kindex entries.)

More importantly, we usually index the detailed descriptions of the
commands in the body of the section, not the abstract at its
beginning.  E.g., look at how this is done in a node "Position
Registers".

> +  Similarly, if there are certain buffers you visit frequently, you can
> +put their names in registers. You can use the following command to put a
> +buffer into a register.     ^^

Our conventions are to leave two spaces between sentences, per US
English.

> -@smallexample
> -(set-register ?m '(buffer . "*Messages*"))
> -@end smallexample
> +@table @kbd
> +@item C-x r B @var{r}
> +@kindex C-x r B
> +@findex buffer-to-register
> +Store the current buffer into register @var{r} (@code{buffer-to-register}).
> +@item C-u C-x r B @var{r}
> +@kindex C-x r B
> +@findex buffer-to-register
> +Prompt for a buffer, and store into register @var{r} (@code{buffer-to-register}).
> +@end table

It is best to have at the beginning of a node a single @table with the
abstract of all the commands described by the node.  So please make
one @table out of these two.

> +(defun file-to-register (file-name register)
> +  "Inserts FILE-NAME in REGISTER.
> +To visit the file, use \\[jump-to-register].
> +
> +Interactively, prompts for REGISTER using `register-read-with-preview'.
> +With a prefix-argument, prompts for FILE-NAME using `read-file-name',
> +otherwise, uses the currently visited file or directory for FILE-NAME."

Our style in doc string is to use "Insert", "prompt", "use", etc., at
least in the first sentence of the doc string, which gives the summary
of what the function does.

> +(defun buffer-to-register (buffer register)
> +  "Inserts BUFFER in REGISTER.
> +To visit the buffer, use \\[jump-to-register].
> +
> +Interactively, prompts for REGISTER using `register-read-with-preview'.
> +With a prefix-argument, prompts for BUFFER-NAME using `read-buffer',
> +otherwise, uses the current buffer."

Likewise here.

Finally, this warrants a NEWS entry to announce the new commands.

Thanks.

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Thierry Volpiatto]

[-- Attachment #1: Type: text/plain, Size: 5808 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> List-Unsubscribe-Post: List-Unsubscribe=One-Click
>> Date: Tue, 17 Sep 2024 00:32:40 +0100
>> From:  Barra Ó Catháin via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> This patch adds two new functions and keybindings for them,
>> file-to-register and buffer-to-register.
>> 
>> These functions make it simpler to put a file/buffer into a register,
>> which I have personally found to be useful when working with projects
>> where I don't wish to disturb the point or to pull up notes files.
>> 
>> (Previously submitted, but I was unfortunately unable to follow it up at
>> the time due to life getting busy!)
>> 
>> Questions and comments appreciated, previously assigned copyright.
>
> Thierry, any comments to these additions?

One comment about buffer-to-register:

More or less you can have the same with point-to-register, the advantage
is that when you kill the buffer, the register-alist entry is turned in
a file-query entry (when buffer is representing a file of course), for
example from register.el buffer:

C-x r <SPC> RET

register-alist entry:
(115 . #<marker at 27354 in register.el>)

Now kill the the buffer, the register-alist entry is turned in:
(115 file-query "/home/thierry/work/emacs/lisp/register.el" 27354)

This is why I guess such functions where never added to register.el.

OTOH they provide an alternative which is easier to find as most users
don't know about this feature (buffer => file-qurey).

BTW I suggest you use for buffer-to-register an entry something like
(buffer-name . marker), this way register-swap-out will be able
to transform it like point-to-register does. Need also to add a add-hook
call like point-to-register does.

>> * lisp/bindings.el (ctl-x-r-map):
>> Add bindings to the register keymap for the two new
>> functions. 'F' for file-to-register and 'B' for
>> buffer-to-register.
>> 
>> * lisp/register.el (register-command-info): Registers the two
>> new functions, file-to-register and buffer-to-register as
>> commands.
>> 
>> (file-to-register):
>> New function, stores a file into a register. Used interactively,
>> prompts for REGISTER using `register-read-with-preview'. With a
>> prefix-argument, prompts for FILE-NAME using `read-file-name',
>> otherwise, uses the currently visited file or directory for
>> FILE-NAME.
>> 
>> (buffer-to-register):
>> New function, stores a buffer into a register. Used
>> interactively, prompts for REGISTER using
>> `register-read-with-preview'. With a prefix-argument, prompts
>> for BUFFER-NAME using `read-buffer', otherwise, uses the current
>> buffer.
>
> This is not exactly the format of log entries which we prefer.  See
> "git log" for examples and CONTRIBUTE for explanations.
>
>> +@table @kbd
>> +@item C-x r F @var{r}
>> +@kindex C-x r F
>> +@findex file-to-register
>> +Store the currently visited file or directory into register @var{r} (@code{file-to-register}).
>> +@item C-u C-x r F @var{r}
>> +@kindex C-x r F
>> +@findex file-to-register
>> +Prompt for a file, and store into register @var{r} (@code{file-to-register}).
>
> First, @*index index entries should appear _before_ the @item lines,
> so that Info-index places you on the line created from @item, not
> after it.
>
> And second, the above defines two identical @kindex entries "C-x r F"
> that both point to the same page, and that is not useful.  We should
> keep only one of them.  The same about the 2 identical @findex
> entries.  (Actually, you have 3 identical @kindex entries.)
>
> More importantly, we usually index the detailed descriptions of the
> commands in the body of the section, not the abstract at its
> beginning.  E.g., look at how this is done in a node "Position
> Registers".
>
>> +  Similarly, if there are certain buffers you visit frequently, you can
>> +put their names in registers. You can use the following command to put a
>> +buffer into a register.     ^^
>
> Our conventions are to leave two spaces between sentences, per US
> English.
>
>> -@smallexample
>> -(set-register ?m '(buffer . "*Messages*"))
>> -@end smallexample
>> +@table @kbd
>> +@item C-x r B @var{r}
>> +@kindex C-x r B
>> +@findex buffer-to-register
>> +Store the current buffer into register @var{r} (@code{buffer-to-register}).
>> +@item C-u C-x r B @var{r}
>> +@kindex C-x r B
>> +@findex buffer-to-register
>> +Prompt for a buffer, and store into register @var{r} (@code{buffer-to-register}).
>> +@end table
>
> It is best to have at the beginning of a node a single @table with the
> abstract of all the commands described by the node.  So please make
> one @table out of these two.
>
>> +(defun file-to-register (file-name register)
>> +  "Inserts FILE-NAME in REGISTER.
>> +To visit the file, use \\[jump-to-register].
>> +
>> +Interactively, prompts for REGISTER using `register-read-with-preview'.
>> +With a prefix-argument, prompts for FILE-NAME using `read-file-name',
>> +otherwise, uses the currently visited file or directory for FILE-NAME."
>
> Our style in doc string is to use "Insert", "prompt", "use", etc., at
> least in the first sentence of the doc string, which gives the summary
> of what the function does.
>
>> +(defun buffer-to-register (buffer register)
>> +  "Inserts BUFFER in REGISTER.
>> +To visit the buffer, use \\[jump-to-register].
>> +
>> +Interactively, prompts for REGISTER using `register-read-with-preview'.
>> +With a prefix-argument, prompts for BUFFER-NAME using `read-buffer',
>> +otherwise, uses the current buffer."
>
> Likewise here.
>
> Finally, this warrants a NEWS entry to announce the new commands.
>
> Thanks.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Thierry Volpiatto <thievol@posteo.net> writes:

> More or less you can have the same with point-to-register, the advantage
> is that when you kill the buffer, the register-alist entry is turned in
> a file-query entry (when buffer is representing a file of course), for
> example from register.el buffer:
>
> C-x r <SPC> RET

I'm worrying a bit: with this patch we would have 3 different types of
registers that would really be very similar.  The user would have to
think about which is appropriate when setting the register.  Or - if the
question doesn't matter - why have 3 different types?


Michael.

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Barra Ó Catháin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Thank you, Eli, will look at this either tommorrow or the day after and
clean up the patch.

For my own sake:
- Clean up the git log entries.
- Place index entries before the item, and fix the duplication for
kindex (I don't even honestly know how I managed to get it into that
state, I remember writing the two commands but clearly I'm
misremembering)
- Bring descriptions more in line with the style, see position registers
- Two spaces, US english
- One table, not two.
- Verb at start of doc string
- News entry.

Thanks for your time.
-----
Barra

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Barra Ó Catháin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Thanks, Thierry. I'll look into how point-to-register does things and
see if I can improve things alongside. 

Thanks for your time!
-----
Barra

Thierry Volpiatto <thievol@posteo.net> writes:

> One comment about buffer-to-register:
>
> More or less you can have the same with point-to-register, the advantage
> is that when you kill the buffer, the register-alist entry is turned in
> a file-query entry (when buffer is representing a file of course), for
> example from register.el buffer:
>
> C-x r <SPC> RET
>
> register-alist entry:
> (115 . #<marker at 27354 in register.el>)
>
> Now kill the the buffer, the register-alist entry is turned in:
> (115 file-query "/home/thierry/work/emacs/lisp/register.el" 27354)
>
> This is why I guess such functions where never added to register.el.
>
> OTOH they provide an alternative which is easier to find as most users
> don't know about this feature (buffer => file-qurey).
>
> BTW I suggest you use for buffer-to-register an entry something like
> (buffer-name . marker), this way register-swap-out will be able
> to transform it like point-to-register does. Need also to add a add-hook
> call like point-to-register does.

bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Barra Ó Catháin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Perhaps the easiest way to demonstrate the differences I saw in their
usage is to explain why I chose to wrote them and not use
point-to-register:

I use buffer-to-register when I'm working with lots of different buffers
but I don't wish to disturb the point when switching back to them. For
example, running long commands in a shell window or even just different
files that I'm bouncing between, rather than dancing with switching
buffers through one of the other means. 

I use file-to-register to pre-load notes files into registers on
startup. It visually makes more sense to read in an init-file. Frankly,
in interactive use I haven't found a real use for file-to-register, but
I also saw no reason not to bind it. I think the main benefit to this is
discoverability. 

Let me know if I can clarify anything for you further with this.
-----
Barra

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>> More or less you can have the same with point-to-register, the advantage
>> is that when you kill the buffer, the register-alist entry is turned in
>> a file-query entry (when buffer is representing a file of course), for
>> example from register.el buffer:
>>
>> C-x r <SPC> RET
>
> I'm worrying a bit: with this patch we would have 3 different types of
> registers that would really be very similar.  The user would have to
> think about which is appropriate when setting the register.  Or - if the
> question doesn't matter - why have 3 different types?
>
>
> Michael.