bug#12217: 24.2.50; append-to-register: Provide a convenient key binding

bug#12217: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

Subject says it all.

24.2.50; append-to-register: Provide a convenient key binding

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

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


See attached patch.

Once patch goes through, I will submit a second part which updates
regs.texi.

Some context:

I usually to use M-x append-to-register (and with this patch `C-x r +')
to collect sexps.  I think it will be convenient to have the collected
snippets separated by a suitable separator. Is it OK if a default "\n"
be used? WDYT.  Note that this will be a departure from current
behaviour where the snippets are blindly concatenated.

ps: Patch should apply cleanly to below bzr version.

,----
| kjambunathan@debian-6:~/src/emacs/trunk$ bzr version-info
| revision-id: rgm@gnu.org-20120817072823-0zjgqf10g1d0vcf1
| date: 2012-08-17 00:28:23 -0700
| build-date: 2012-08-17 15:17:41 +0530
| revno: 109655
| branch-nick: trunk
`----


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: bug#12217-part-1.patch --]
[-- Type: text/x-diff, Size: 1890 bytes --]

=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2012-08-17 06:01:17 +0000
+++ lisp/ChangeLog	2012-08-17 09:45:08 +0000
@@ -1,3 +1,9 @@
+2012-08-17  Jambunathan K  <kjambunathan@gmail.com>
+
+	* register.el (increment-register): If register contains a string,
+	call `append-to-register'.  This way, `C-x r +' can be used to
+	invoke `append-to-register'.  See (Bug#12217).
+
 2012-08-17  Martin Rudalics  <rudalics@gmx.at>
 
 	* window.el (delete-window): Fix last fix.

=== modified file 'lisp/register.el'
--- lisp/register.el	2012-07-29 04:45:48 +0000
+++ lisp/register.el	2012-08-17 09:05:29 +0000
@@ -192,13 +192,25 @@
 			(string-to-number (match-string 0)))
 		    0))))
 
-(defun increment-register (number register)
-  "Add NUMBER to the contents of register REGISTER.
-Interactively, NUMBER is the prefix arg."
-  (interactive "p\ncIncrement register: ")
-  (or (numberp (get-register register))
-      (error "Register does not contain a number"))
-  (set-register register (+ number (get-register register))))
+(defun increment-register (prefix register)
+  "Augment contents of REGISTER.
+Interactively, PREFIX is in raw form.
+
+If REGISTER contains a number, add `prefix-numeric-value' of
+PREFIX to it.
+
+If REGISTER is empty or if it contains a string, call
+`append-to-register' with `delete-flag' set to PREFIX."
+  (interactive "P\ncIncrement register: ")
+  (let ((register-val (get-register register)))
+    (unless (or (not register-val)
+		(numberp register-val)
+		(stringp register-val))
+      (error "Register does not contain a number or string"))
+    (if (numberp register-val)
+	(let ((number (prefix-numeric-value prefix)))
+	  (set-register register (+ number register-val)))
+      (append-to-register register (region-beginning) (region-end) prefix))))
 
 (defun view-register (register)
   "Display what is contained in register named REGISTER.

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Stefan Monnier]

> Once patch goes through, I will submit a second part which updates
> regs.texi.

I think the change is OK.  I would prefer a single `cond' form with the
`error' in the last branch (instead of unless+if) so as to avoid
a redundant `numberp' check (not as a matter of efficiency, of course,
but maintenance).
If you send such an updated patch with the corresponding regs.texi
change, we'll install it.

> I usually to use M-x append-to-register (and with this patch `C-x r +')
> to collect sexps.  I think it will be convenient to have the collected
> snippets separated by a suitable separator. Is it OK if a default "\n"
> be used? WDYT.

I think I'd rather not add any separator by default.  In many cases
adding such a separator would render the command inconvenient, and in
many others the user can easily make sure the text he appends includes
an appropriate separator.

I can see cases where adding a separator could be handy, but I'm not
sure hardcoding "\n" would solve enough of those cases.  Maybe you could
prompt for a separator if the user provided a C-u prefix?


        Stefan

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

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


Attaching modified patch.  Patch is generated against revno: 109935.

>> Once patch goes through, I will submit a second part which updates
>> regs.texi.
>
> I think the change is OK.  I would prefer a single `cond' form with the
> `error' in the last branch (instead of unless+if) so as to avoid
> a redundant `numberp' check (not as a matter of efficiency, of course,
> but maintenance).
> If you send such an updated patch with the corresponding regs.texi
> change, we'll install it.

Done.

>> I usually to use M-x append-to-register (and with this patch `C-x r +')
>> to collect sexps.  I think it will be convenient to have the collected
>> snippets separated by a suitable separator. Is it OK if a default "\n"
>> be used? WDYT.
>
> I think I'd rather not add any separator by default.  

> In many cases adding such a separator would render the command
> inconvenient, and in many others the user can easily make sure the
> text he appends includes an appropriate separator.

> I can see cases where adding a separator could be handy, but I'm not
> sure hardcoding "\n" would solve enough of those cases.  

> Maybe you could prompt for a separator if the user provided a C-u
> prefix?

Prefix is used as a `delete-flag' already ...

I have introduced an extra indirection via a `separator-register' (which
is nil by default) Now what gets used as a separator - a newline, a
double newline, a comma or a tab - is under user control.

There is already one user - that is me - who will find this feature
useful.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: bug-12217.patch --]
[-- Type: text/x-diff, Size: 7114 bytes --]

=== modified file 'doc/emacs/ChangeLog'
--- doc/emacs/ChangeLog	2012-09-07 10:27:11 +0000
+++ doc/emacs/ChangeLog	2012-09-08 18:04:28 +0000
@@ -1,3 +1,9 @@
+2012-09-08  Jambunathan K  <kjambunathan@gmail.com>
+
+	* regs.texi (Text Registers): `C-x r +' can now be used instead of
+	M-x append-to-register.  New option `separator-register'.
+	(Number Registers): Mention that `C-x r +' is polymorphic.
+
 2012-09-07  Chong Yidong  <cyd@gnu.org>
 
 	* windows.texi (Window Choice): Don't mention obsolete

=== modified file 'doc/emacs/regs.texi'
--- doc/emacs/regs.texi	2012-05-27 01:25:06 +0000
+++ doc/emacs/regs.texi	2012-09-08 17:14:13 +0000
@@ -92,6 +92,13 @@
 Insert text from register @var{r} (@code{insert-register}).
 @item M-x append-to-register @key{RET} @var{r}
 Append region to text in register @var{r}.
+
+@kindex C-x r +
+When register @var{r} contains text, you can use @kbd{C-x r +}
+(@code{increment-register}) to append to that register.  Note that
+command @kbd{C-x r +} behaves differently if @var{r} contains a
+number.  @xref{Number Registers}.
+
 @item M-x prepend-to-register @key{RET} @var{r}
 Prepend region to text in register @var{r}.
 @end table
@@ -116,6 +123,19 @@
 the region text to the text in the register instead of
 @emph{appending} it.
 
+@vindex separator-register
+  When you are collecting text using @code{append-to-register} and
+@code{prepend-to-register}, you may want to separate individual
+collected pieces using a separator.  In that case, configure a
+@code{separator-register} and store the separator text in to that
+register.  For example, to get double newlines as text separator
+during the collection process, you can use the following setting.
+
+@example
+(setq separator-register ?+)
+(set-register separator-register "\n\n")
+@end example
+
 @kindex C-x r i
 @findex insert-register
   @kbd{C-x r i @var{r}} inserts in the buffer the text from register
@@ -191,8 +211,10 @@
 @item C-u @var{number} C-x r + @var{r}
 @kindex C-x r +
 @findex increment-register
-Increment the number in register @var{r} by @var{number}
-(@code{increment-register}).
+If @var{r} contains a number, increment the number in that register by
+@var{number}.  Note that command @kbd{C-x r +}
+(@code{increment-register}) behaves differently if @var{r} contains
+text.  @xref{Text Registers}.
 @item C-x r i @var{r}
 Insert the number from register @var{r} into the buffer.
 @end table

=== modified file 'etc/NEWS'
--- etc/NEWS	2012-09-07 10:27:11 +0000
+++ etc/NEWS	2012-09-08 17:31:09 +0000
@@ -182,6 +182,13 @@
 delete-trailing-whitespace command should delete trailing lines at the
 end of the buffer.  It defaults to t.
 
++++
+** `C-x r +' is now overloaded to invoke `append-to-register.
++++
+** New option `separator-register'.  Separator register stores
+separator text for use with M-x append-to-register and M-x
+prepend-to-register.  See manual for details.
+
 ** Search changes
 
 *** Global `M-s _' starts a symbol (identifier) incremental search,

=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2012-09-07 20:14:55 +0000
+++ lisp/ChangeLog	2012-09-08 17:39:03 +0000
@@ -1,3 +1,13 @@
+2012-09-08  Jambunathan K  <kjambunathan@gmail.com>
+
+	* register.el (register): New group.
+	(separator-register): New user option.
+	(increment-register): Route it to `append-to-register', if
+	register contains text.  Implication is that `C-x r +' can now be
+	used for appending to a text register.
+	(append-to-register, prepend-to-register): Add separator based on
+	`separator-register.
+
 2012-09-07  Stefan Monnier  <monnier@iro.umontreal.ca>
 
 	* emacs-lisp/byte-run.el (defun): Tweak message.  Simplify code.

=== modified file 'lisp/register.el'
--- lisp/register.el	2012-07-29 04:45:48 +0000
+++ lisp/register.el	2012-09-08 14:12:42 +0000
@@ -76,6 +76,22 @@
 A list of the form (FRAME-CONFIGURATION POSITION)
  represents a saved frame configuration plus a saved value of point.")
 
+(defgroup register nil
+  "Register commands."
+  :group 'convenience
+  :version "24.2.50")
+
+(defcustom separator-register nil
+  "Use contents of this register to separate collected text.
+
+When collecting text with
+`append-to-register' (resp. `prepend-to-register') contents of
+this register is added to the beginning (resp. end) of the marked
+text."
+  :group 'register
+  :type '(choice (const :tag "None" nil)
+		 (character :tag "Use register" :value ?+)))
+
 (defun get-register (register)
   "Return contents of Emacs register named REGISTER, or nil if none."
   (cdr (assq register register-alist)))
@@ -192,13 +208,24 @@
 			(string-to-number (match-string 0)))
 		    0))))
 
-(defun increment-register (number register)
-  "Add NUMBER to the contents of register REGISTER.
-Interactively, NUMBER is the prefix arg."
-  (interactive "p\ncIncrement register: ")
-  (or (numberp (get-register register))
-      (error "Register does not contain a number"))
-  (set-register register (+ number (get-register register))))
+(defun increment-register (prefix register)
+  "Augment contents of REGISTER.
+Interactively, PREFIX is in raw form.
+
+If REGISTER contains a number, add `prefix-numeric-value' of
+PREFIX to it.
+
+If REGISTER is empty or if it contains text, call
+`append-to-register' with `delete-flag' set to PREFIX."
+  (interactive "P\ncIncrement register: ")
+  (let ((register-val (get-register register)))
+    (cond
+     ((numberp register-val)
+      (let ((number (prefix-numeric-value prefix)))
+	(set-register register (+ number register-val))))
+     ((or (not register-val) (stringp register-val))
+      (append-to-register register (region-beginning) (region-end) prefix))
+     (t (error "Register does not contain a number or text")))))
 
 (defun view-register (register)
   "Display what is contained in register named REGISTER.
@@ -349,10 +376,11 @@
 START and END are buffer positions indicating what to append."
   (interactive "cAppend to register: \nr\nP")
   (let ((reg (get-register register))
-        (text (filter-buffer-substring start end)))
+        (text (filter-buffer-substring start end))
+	(separator (and separator-register (get-register separator-register))))
     (set-register
      register (cond ((not reg) text)
-                    ((stringp reg) (concat reg text))
+                    ((stringp reg) (concat reg separator text))
                     (t (error "Register does not contain text")))))
   (cond (delete-flag
 	 (delete-region start end))
@@ -366,10 +394,11 @@
 START and END are buffer positions indicating what to prepend."
   (interactive "cPrepend to register: \nr\nP")
   (let ((reg (get-register register))
-        (text (filter-buffer-substring start end)))
+        (text (filter-buffer-substring start end))
+	(separator (and separator-register (get-register separator-register))))
     (set-register
      register (cond ((not reg) text)
-                    ((stringp reg) (concat text reg))
+                    ((stringp reg) (concat text separator reg))
                     (t (error "Register does not contain text")))))
   (cond (delete-flag
 	 (delete-region start end))

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Stefan Monnier]

>> Maybe you could prompt for a separator if the user provided a C-u
>> prefix?
> Prefix is used as a `delete-flag' already ...

The way I read the current binding of C-x r + (increment-register), it
only uses the prefix to specify the number to add to the register, which
in the case of string concatenation is of no use.

So we can use the prefix of C-x + either the way you do in your current
patch (i.e. to specify the delete-flag of append-to-register) or we can
use it to specify the separator.

I understand that deleting the text is a common need, but you can do
that with C-x + C-w instead of C-u C-x +, so maybe it's OK to use C-u
for the separator.

> I have introduced an extra indirection via a `separator-register' (which
> is nil by default) Now what gets used as a separator - a newline, a
> double newline, a comma or a tab - is under user control.

I've renamed it to register-separator, because I'd rather that
register.el move (ever so slowly) to obey the "register-" prefix.


        Stefan "Installed, thank you!"

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

> I've renamed it to register-separator, because I'd rather that
> register.el move (ever so slowly) to obey the "register-" prefix.

Looks like you failed to mark some files in work-area
before the commmit.

I still see references to separator-register in *.el file, NEWS and
Changelog files.

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Andreas Schwab]

Jambunathan K <kjambunathan@gmail.com> writes:

> I have introduced an extra indirection via a `separator-register' (which
> is nil by default) Now what gets used as a separator - a newline, a
> double newline, a comma or a tab - is under user control.

Why the extra indirection?  Why not just make it a string and use it
directly?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Jambunathan K <kjambunathan@gmail.com> writes:
>
>> I have introduced an extra indirection via a `separator-register'
>> (which is nil by default) Now what gets used as a separator - a
>> newline, a double newline, a comma or a tab - is under user control.
>
> Why the extra indirection?  Why not just make it a string and use it
> directly?

In short, Function before form and it is also about some workflows being
less intrusive than others.

Let's look at some use-cases.

Use-case-1 (A concrete one)

    I find myself collecting sexps.  (This is going to happen more as I
    plan to explore more new codebases.)

    When I look at existing code - with an intention to prepare some
    patch - I find myself collecting recipes from 2 or 3 places.  I then
    "insert" it in to target location and put them together.  Since the
    recipes are collected from 2 or 3 places, they need to be visually
    separated.  Going forward I will store "double newline" (read
    paragraph) as separator for these recipe blocks.

    Note: Org exporters are moving to new framework.  Now when I am
    re-implementing some features in my (own) org-e-odt.el, I find
    myself collecting recipes from org-export.el, org-e-latex.el and
    felt sorry that the sexps are not visually separated.

Use-case-2 (Contrived one)

    Now let's say I am a language learner and I am looking at a French
    article from within Emacs.  As I read through the article, I see
    some words that need to be looked up.  Instead of immediate lookup,
    I may store the word or a phrase in a register and later insert in
    to my language notes for further refinement.  In this case, I may
    want to separate them with a newline or even better something like
    an Org-table.

    In that case, in my scratch buffer I will type something like this
    in scratch buffer, C-x r s + it and then collect away.  I can then
    paste that in to my Notes buffer and then re-align it using Org.


    --8<---------------cut here---------------start------------->8---
    |
    |
    --8<---------------cut here---------------end--------------->8---


    This is how the collected table looks like

    ,----
    | Now|
    | |looked|
    | |immediate|
    | |further
    `----

A string or a separator register
================================

It is easy for me to do "C-x r s" a separator rather to do a "M: (setq
separator "")".  There is lesser context switch.  A separator register
"guarantees" that the words are separated.  This frees one from
remembering to store the surrounding separator and just focus on
collection process.




> Andreas.

bug#12217: [PATCH] Re: 24.2.50; append-to-register: Provide a convenient key binding

[Jambunathan K]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Jambunathan K <kjambunathan@gmail.com> writes:
>
>> I have introduced an extra indirection via a `separator-register' (which
>> is nil by default) Now what gets used as a separator - a newline, a
>> double newline, a comma or a tab - is under user control.
>
> Why the extra indirection?  Why not just make it a string and use it
> directly?

Why registers when there is a kill ring? A text register is but a kill
ring.

Register is a framework and hence abstract.  

The original authors needed it badly, took trouble to implement it, but
unfortunately failed to document what new workflows they enable.  (I see
some references to number registers being used in conjunction with
macros - just about it.)  Now a user is left to his own device to
contrive how a register should be used.  It is like an incomplete
sentence begging for ....

Btw, no registers were killed in the preparation of the patch.

> Andreas.