[PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Toby Cubitt]

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

Currently, capture templates provide no way of prompting for some text,
then inserting that text into multiple places in the template.

This patch allow you to do this, by adding %<n> escapes to the template
syntax (where <n> is a digit, 0 to 9), which expand to the text entered
for the nth prompt in the template (as specified in the template using
the usual %^{prompt} syntax).

Useful for populating a subtree with an entire sequence of related TODOs,
capturing a multi-step task.

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

[-- Attachment #2: 0001-Capture-Add-num-escapes-to-org-capture-templates.patch --]
[-- Type: text/x-patch, Size: 2663 bytes --]

From 0e917539324fdc32cd0878b0819cb28b79f30f01 Mon Sep 17 00:00:00 2001
From: "Toby S. Cubitt" <tsc25@cantab.net>
Date: Sat, 28 Jan 2012 17:04:05 +0100
Subject: [PATCH] Capture: Add %<num> escapes to org capture templates

* lisp/org-capture.el (org-capture-fill-template): Expand %<num>
escape sequences into text entered for <num>'th %^{PROMPT} escape.
---
 lisp/org-capture.el |   24 ++++++++++++++++++------
 1 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index f0afc70..2daca72 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -248,6 +248,8 @@ be replaced with content and expanded in this order:
               A default value and a completion table ca be specified like this:
               %^{prompt|default|completion2|completion3|...}.
   %?          After completing the template, position cursor here.
+  %<n>        Insert the text entered for at the nth %^{prompt}, where <n>
+              represents a digit, 0 to 9.
 
 Apart from these general escapes, you can access information specific to the
 link type that is created.  For example, calling `org-capture' in emails
@@ -1326,7 +1328,7 @@ The template may still contain \"%?\" for cursor positioning."
 	 (org-startup-folded nil)
 	 (org-inhibit-startup t)
 	 org-time-was-given org-end-time-was-given x
-	 prompt completions char time pos default histvar)
+	 prompt completions char time pos default histvar strings)
 
     (setq org-store-link-plist
 	  (plist-put org-store-link-plist :annotation v-a)
@@ -1468,11 +1470,21 @@ The template may still contain \"%?\" for cursor positioning."
 				   nil nil (list org-end-time-was-given)))
 	   (t
 	    (let (org-completion-use-ido)
-	      (insert (org-completing-read-no-i
-		       (concat (if prompt prompt "Enter string")
-			       (if default (concat " [" default "]"))
-			       ": ")
-		       completions nil nil nil histvar default)))))))
+	      (push (org-completing-read-no-i
+		     (concat (if prompt prompt "Enter string")
+			     (if default (concat " [" default "]"))
+			     ": ")
+		     completions nil nil nil histvar default)
+		    strings)
+	      (insert (car strings)))))))
+      ;; Replace %n escapes with nth %^{...} string
+      (setq strings (nreverse strings))
+      (goto-char (point-min))
+      (while (re-search-forward "%\\([1-9]\\)+" nil t)
+	(unless (org-capture-escaped-%)
+	  (replace-match
+	   (nth (1- (string-to-number (match-string 1))) strings)
+	   nil t)))
       ;; Make sure there are no empty lines before the text, and that
       ;; it ends with a newline character
       (goto-char (point-min))
-- 
1.7.8.5

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Bastien]

Hi Toby,

Toby Cubitt <tsc25@cantab.net> writes:

> Currently, capture templates provide no way of prompting for some text,
> then inserting that text into multiple places in the template.

Thanks for the patch, I applied it.

I also updated the documentation in doc/org.texi -- please provide
documentation in the patch containing code changes if relevant next
times.

One tiny thing: the documentation said that %0 would match the first
occurrence but while I tested the first occurrence was on %1, which
looks better to me.

So I updated the documentation accordingly.

Best,

-- 
 Bastien

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Toby Cubitt]

On Mon, Apr 23, 2012 at 02:54:31PM +0200, Bastien wrote:
> Toby Cubitt <tsc25@cantab.net> writes:
> 
> > Currently, capture templates provide no way of prompting for some text,
> > then inserting that text into multiple places in the template.
> 
> Thanks for the patch, I applied it.
> 
> I also updated the documentation in doc/org.texi -- please provide
> documentation in the patch containing code changes if relevant next
> times.

Ah, I forgot about the texinfo docs. Sorry. I'll try to remember them
next time.

> One tiny thing: the documentation said that %0 would match the first
> occurrence but while I tested the first occurrence was on %1, which
> looks better to me.
> 
> So I updated the documentation accordingly.

Yes, you're right, it starts from 1. That's what comes of adding the
documentation later, as an after-thought...(bad programming practice!)

And now I look at it again, there's a bug in the regexp (my fault): the
regexp "%\\([1-9]\\)+" currently matches any sequence of 1-9's, which is
clearly wrong. The two possible fixes are:

- Drop the final + from the regexp so that it reads "%\\([1-9]\\)", to
  match any single non-zero digit, as per the current docs. (The regexp
  group must be kept, because it's used later in the code.)

- Change the regexp to "%\\([1-9][0-9]*\\)", to match any positive
  integer, and update the docs accordingly.

It seems unlikely anyone would ever want to refer back to more than
9 prompts in a capture template. (I think back-references in Emacs
regexps are similarly limited to single digits).

On the other hand, whenever someone says "it seems unlikely anyone would
ever want to..." about Emacs, up pops someone who wants to do exactly
that ;-)

Your call. If you tell me which fix you prefer, I can supply a patch if
you want one (though the change is so small I imagine it'll be easier to
do it manually).

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Bastien]

Hi Toby,

Toby Cubitt <tsc25@cantab.net> writes:

> Ah, I forgot about the texinfo docs. Sorry. I'll try to remember them
> next time.

No problem.

> - Change the regexp to "%\\([1-9][0-9]*\\)", to match any positive
>   integer, and update the docs accordingly.

Please send a patch for this solution.

Thanks!

-- 
 Bastien

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Toby Cubitt]

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

On Mon, Apr 23, 2012 at 05:12:51PM +0200, Bastien wrote:
> Hi Toby,
> 
> Toby Cubitt <tsc25@cantab.net> writes:
> 
> > Ah, I forgot about the texinfo docs. Sorry. I'll try to remember them
> > next time.
> 
> No problem.
> 
> > - Change the regexp to "%\\([1-9][0-9]*\\)", to match any positive
> >   integer, and update the docs accordingly.
> 
> Please send a patch for this solution.

Attached (this time including a texinfo documentation update ;-)

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

[-- Attachment #2: 0001-org-capture.el-Fixed-bug-in-org-capture-templates-n-.patch --]
[-- Type: text/x-patch, Size: 2604 bytes --]

From 4407cd46e3cf8339a9c90d4dde8337b7dbaca048 Mon Sep 17 00:00:00 2001
From: "Toby S. Cubitt" <tsc25@cantab.net>
Date: Mon, 23 Apr 2012 17:20:19 +0200
Subject: [PATCH] org-capture.el: Fixed bug in org-capture-templates %<n>
 expandos

* lisp/org-capture.el (org-capture-fill-template): Fixed regexp for
  %<n> expandos to match any positive integer.
  (org-capture-templates): Updated docstring accordingly.

* doc/org.texi: Updated documentation accordingly.
---
 doc/org.texi        |    4 ++--
 lisp/org-capture.el |    6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index a25572d..bb98713 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -6700,8 +6700,8 @@ dynamic insertion of content.  The templates are expanded in the order given her
             @r{You may specify a default value and a completion table with}
             @r{%^@{prompt|default|completion2|completion3...@}.}
             @r{The arrow keys access a prompt-specific history.}
-%<n>        @r{Insert the text entered for at the nth %^{prompt}, where <n>}
-            @r{represents a digit, 1 to 9.}
+%<n>        @r{Insert the text entered at the nth %^{prompt}, where <n> is}
+            @r{a number, starting from 1.}
 %?          @r{After completing the template, position cursor here.}
 @end smallexample
 
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 7fbd438..d507cc2 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -248,8 +248,8 @@ be replaced with content and expanded in this order:
               A default value and a completion table ca be specified like this:
               %^{prompt|default|completion2|completion3|...}.
   %?          After completing the template, position cursor here.
-  %<n>        Insert the text entered for at the nth %^{prompt}, where <n>
-              represents a digit, 1 to 9.
+  %<n>        Insert the text entered at the nth %^{prompt}, where <n> is
+              a number, starting from 1.
 
 Apart from these general escapes, you can access information specific to the
 link type that is created.  For example, calling `org-capture' in emails
@@ -1480,7 +1480,7 @@ The template may still contain \"%?\" for cursor positioning."
       ;; Replace %n escapes with nth %^{...} string
       (setq strings (nreverse strings))
       (goto-char (point-min))
-      (while (re-search-forward "%\\([1-9]\\)+" nil t)
+      (while (re-search-forward "%\\([1-9][0-9]*\\)" nil t)
 	(unless (org-capture-escaped-%)
 	  (replace-match
 	   (nth (1- (string-to-number (match-string 1))) strings)
-- 
1.7.8.5

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Bastien]

Toby Cubitt <tsc25@cantab.net> writes:

> On Mon, Apr 23, 2012 at 05:12:51PM +0200, Bastien wrote:
>> Hi Toby,
>> 
>> Toby Cubitt <tsc25@cantab.net> writes:
>> 
>> > Ah, I forgot about the texinfo docs. Sorry. I'll try to remember them
>> > next time.
>> 
>> No problem.
>> 
>> > - Change the regexp to "%\\([1-9][0-9]*\\)", to match any positive
>> >   integer, and update the docs accordingly.
>> 
>> Please send a patch for this solution.
>
> Attached (this time including a texinfo documentation update ;-)

Applied, thanks!

-- 
 Bastien

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Bastien]

I've pushed a change to this new feature: 
http://orgmode.org/w/?p=org-mode.git;a=commit;h=1666b9

Using %n is not good, because it will match many escaped 
strings that you don't want to match.  Using %\n looks
good to me as it resonates with \1 in replace-regexp.

Toby, let me know if you agree with this change.

Thanks!

-- 
 Bastien

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Toby Cubitt]

On Tue, Apr 24, 2012 at 11:57:02AM +0200, Bastien wrote:
> I've pushed a change to this new feature: 
> http://orgmode.org/w/?p=org-mode.git;a=commit;h=1666b9
> 
> Using %n is not good, because it will match many escaped 
> strings that you don't want to match.  Using %\n looks
> good to me as it resonates with \1 in replace-regexp.
> 
> Toby, let me know if you agree with this change.

I'm fine with it. But I don't understand, what other escapes will it
match? None of the other % escapes documented in org-capture-templates
start with a digit, they all start with a letter or punctuation.

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Bastien]

Toby Cubitt <tsc25@cantab.net> writes:

> On Tue, Apr 24, 2012 at 11:57:02AM +0200, Bastien wrote:
>> I've pushed a change to this new feature: 
>> http://orgmode.org/w/?p=org-mode.git;a=commit;h=1666b9
>> 
>> Using %n is not good, because it will match many escaped 
>> strings that you don't want to match.  Using %\n looks
>> good to me as it resonates with \1 in replace-regexp.
>> 
>> Toby, let me know if you agree with this change.
>
> I'm fine with it. But I don't understand, what other escapes will it
> match? None of the other % escapes documented in org-capture-templates
> start with a digit, they all start with a letter or punctuation.

It is not the escapes from the capture template itself, but at the time
the capture buffer is prepared, links go to `org-make-link-string' which
calls `org-link-escape' which might in turn insert "%20" strings.

-- 
 Bastien

Re: [PATCH] Allow %<num> escapes to capture templates, expanded to text entered in <num>'th prompt

[Toby Cubitt]

On Tue, Apr 24, 2012 at 02:51:29PM +0200, Bastien wrote:
> Toby Cubitt <tsc25@cantab.net> writes:
> 
> > On Tue, Apr 24, 2012 at 11:57:02AM +0200, Bastien wrote:
> >> I've pushed a change to this new feature: 
> >> http://orgmode.org/w/?p=org-mode.git;a=commit;h=1666b9
> >> 
> >> Using %n is not good, because it will match many escaped 
> >> strings that you don't want to match.  Using %\n looks
> >> good to me as it resonates with \1 in replace-regexp.
> >> 
> >> Toby, let me know if you agree with this change.
> >
> > I'm fine with it. But I don't understand, what other escapes will it
> > match? None of the other % escapes documented in org-capture-templates
> > start with a digit, they all start with a letter or punctuation.
> 
> It is not the escapes from the capture template itself, but at the time
> the capture buffer is prepared, links go to `org-make-link-string' which
> calls `org-link-escape' which might in turn insert "%20" strings.

Ah, I get it now.

Your %\n syntax looks to be a good choice. I'll pull your changes and
update my org-capture-template setting.

Thanks!

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org