[PATCH] Implement history facility for org-occur searches

[PATCH] Implement history facility for org-occur searches

[Suvayu Ali]

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

Hi Bastien and everyone,

I wanted to implement a history facility for sparse trees. Since sparse
trees use org-occur and org-scan-tags any such facility would need to
be aware of both functions. My lisp foo proved to be too weak to
understand org-scan-tags, so I implemented this only for org-occur
searches.

With this patch one can traverse the sparse tree history for date,
regular expression and TODO keyword searches with the
org-occur-history-forward and org-occur-history-backward functions. One
can also call the org-occur-history-next function interactively to jump
to the nth history entry. This should also work for any other searches
that uses org-occur as the backend.

Please feel free to modify the patch if there are better ways to
implement this facility. Thank you.

-- 
Suvayu

Open source is the future. It sets us free.

[-- Attachment #2: 0001-Implement-history-facility-for-org-occur-searches.patch --]
[-- Type: text/x-patch, Size: 4838 bytes --]

From 11c36f42d1471629fd783aaf1db4aaf3d1d01ef6 Mon Sep 17 00:00:00 2001
From: Suvayu Ali <fatkasuvayu+linux@gmail.com>
Date: Tue, 23 Aug 2011 14:25:08 +0200
Subject: [PATCH] Implement history facility for org-occur searches

Changed function:
* org.el (org-occur): Add history functionality and corresponding
  documentation

New functions:
* org.el (org-occur-history-next): Function for history traversal
  (org-occur-history-forward) and (org-occur-history-backward):
  User funtions for moving forward and backward in search history

New variables:
* org.el (org-occur-match-history): Search history variable
  (org-occur-match-history-len): Search history size
---
 lisp/org.el |   65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index bbc6a75..d419a04 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12294,6 +12294,15 @@ (defvar org-occur-parameters nil
 as well.")
 (make-variable-buffer-local 'org-occur-parameters)
 
+;;;; Org occur history variables
+(defvar org-occur-match-history nil
+  "History list of `org-occur' searches.")
+(make-variable-buffer-local 'org-occur-match-history)
+(defcustom org-occur-match-history-len 10
+  "Length of `org-occur-match-history'."
+  :type 'integer
+  :group 'org)
+
 (defun org-occur (regexp &optional keep-previous callback)
   "Make a compact tree which shows all matches of REGEXP.
 The tree will show the lines where the regexp matches, and all higher
@@ -12303,7 +12312,15 @@ (defun org-occur (regexp &optional keep-previous callback)
 call to `org-occur' will be kept, to allow stacking of calls to this
 command.
 If CALLBACK is non-nil, it is a function which is called to confirm
-that the match should indeed be shown."
+that the match should indeed be shown.
+
+The org-occur search history is stored in the variable
+`org-occur-match-history'. The length of the history is determined by the
+variable `org-occur-match-history-len'. The function
+`org-occur-history-next' can be used to traverse the org-occur history.
+Two user functions `org-occur-history-forward' and
+`org-occur-history-backward' are provided to conveniently traverse the
+org-occur history one step at a time."
   (interactive "sRegexp: \nP")
   (when (equal regexp "")
     (error "Regexp cannot be empty"))
@@ -12322,7 +12339,17 @@ (defun org-occur (regexp &optional keep-previous callback)
 		  (save-match-data (funcall callback)))
 	  (setq cnt (1+ cnt))
 	  (when org-highlight-sparse-tree-matches
-	    (org-highlight-new-match (match-beginning 0) (match-end 0)))
+	    (org-highlight-new-match (match-beginning 0) (match-end 0))
+	    ;; remove duplicate element
+	    (setq org-occur-match-history
+		  (delete regexp org-occur-match-history))
+	    ;; add last search at the front
+	    (add-to-list 'org-occur-match-history regexp)
+	    ;; curtail history to max history length
+	    (if (eq org-occur-match-history-len
+		    (length org-occur-match-history))
+		(setq org-occur-match-history
+		      (butlast org-occur-match-history))))
 	  (org-show-context 'occur-tree))))
     (when org-remove-highlights-with-change
       (org-add-hook 'before-change-functions 'org-remove-occur-highlights
@@ -12360,6 +12387,40 @@ (defun org-occur-next-match (&optional n reset)
       (goto-char p1)
       (error "No more matches"))))
 
+(defun org-occur-history-next (steps)
+    "Traverse org occur history by STEPS steps in the forward direction
+with respect to the current position. The search history is saved after
+removing any duplicate searches. It is reordered to reflect the most
+recent search. Before traversing the history the following transformation
+is applied: STEPS MODULO `org-occur-match-history-len'.
+
+For negative STEPS, history traversal is done in the backward direction
+starting at the end of the history list. When called interactively it
+prompts for the number of steps."
+    (interactive "NSteps: ")
+    (let (match)
+      (if (< steps 0)
+	  (setq match
+		(car (last org-occur-match-history
+			   (mod (- steps) org-occur-match-history-len))))
+	(setq match (nth (mod steps org-occur-match-history-len)
+			 org-occur-match-history)))
+      (org-occur match)
+      (setq org-occur-match-history
+	    (delete match org-occur-match-history))
+      (add-to-list 'org-occur-match-history match t)))
+
+(defun org-occur-history-forward ()
+  "Repeat last org occur search."
+  (interactive)
+  (let ((steps (if org-occur-highlights 1 0)))
+    (org-occur-history-next steps)))
+
+(defun org-occur-history-backward ()
+  "Repeat last org occur search."
+  (interactive)
+  (org-occur-history-next -1))
+
 (defun org-show-context (&optional key)
   "Make sure point and context are visible.
 How much context is shown depends upon the variables
-- 
1.7.4.4

Re: [PATCH] Implement history facility for org-occur searches

[Carsten Dominik]

Hi Suvayu,

could you describe your use case for this addition?  When would you need
this above calling org-occur again and using the minibuffer
history to repeat your search?

- Carsten

On Aug 24, 2011, at 1:47 AM, Suvayu Ali wrote:

> Hi Bastien and everyone,
> 
> I wanted to implement a history facility for sparse trees. Since sparse
> trees use org-occur and org-scan-tags any such facility would need to
> be aware of both functions. My lisp foo proved to be too weak to
> understand org-scan-tags, so I implemented this only for org-occur
> searches.
> 
> With this patch one can traverse the sparse tree history for date,
> regular expression and TODO keyword searches with the
> org-occur-history-forward and org-occur-history-backward functions. One
> can also call the org-occur-history-next function interactively to jump
> to the nth history entry. This should also work for any other searches
> that uses org-occur as the backend.
> 
> Please feel free to modify the patch if there are better ways to
> implement this facility. Thank you.
> 
> -- 
> Suvayu
> 
> Open source is the future. It sets us free.
> <0001-Implement-history-facility-for-org-occur-searches.patch>

- Carsten

Re: [PATCH] Implement history facility for org-occur searches

[suvayu ali]

Hi Carsten,

Sorry, I somehow missed this email.

On Thu, Oct 6, 2011 at 9:54 AM, Carsten Dominik
<carsten.dominik@gmail.com> wrote:
> Hi Suvayu,
>
> could you describe your use case for this addition?  When would you need
> this above calling org-occur again and using the minibuffer
> history to repeat your search?
>

My use case was to easily traverse through a sequence of sparse-tree
searches. Something that I thought might be useful when searching in a
large file. My implementation is probably very suboptimal. I was
hoping to find a way to take a "snapshot" of a sparse tree view, and
then "undo" or "redo" a sparse tree view. By undo/redo I mean
restoring the visibility states of the trees and the highlighted
search text. However I couldn't find a way to get the "snapshot", so I
tried repeating the searches to achieve a similar result.

I have had time to think since I submitted the patch, maybe its
something very specific to how I use org and is probably more
appropriate as a local modification and not for inclusion in org (at
least not in its current form).

> - Carsten

Thanks a lot.

-- 
Suvayu

Open source is the future. It sets us free.

Re: [PATCH] Implement history facility for org-occur searches

[Carsten Dominik]

On 10.10.2011, at 09:47, suvayu ali wrote:

> Hi Carsten,
> 
> Sorry, I somehow missed this email.
> 
> On Thu, Oct 6, 2011 at 9:54 AM, Carsten Dominik
> <carsten.dominik@gmail.com> wrote:
>> Hi Suvayu,
>> 
>> could you describe your use case for this addition?  When would you need
>> this above calling org-occur again and using the minibuffer
>> history to repeat your search?
>> 
> 
> My use case was to easily traverse through a sequence of sparse-tree
> searches. Something that I thought might be useful when searching in a
> large file. My implementation is probably very suboptimal. I was
> hoping to find a way to take a "snapshot" of a sparse tree view, and
> then "undo" or "redo" a sparse tree view. By undo/redo I mean
> restoring the visibility states of the trees and the highlighted
> search text. However I couldn't find a way to get the "snapshot", so I
> tried repeating the searches to achieve a similar result.

We do have support for storing and setting outline visibility:

Take a look at the functions

   org-outline-overlay-data
   org-set-outline-overlay-data

and at the macro 

   org-save-outline-visibility

which uses the two functions described above.

If the searches are always the same, you might want to define them
as custom agenda commands.

> I have had time to think since I submitted the patch, maybe its
> something very specific to how I use org and is probably more
> appropriate as a local modification and not for inclusion in org (at
> least not in its current form).

OK, I will mark it rejected, feel free to come back when you have
something convincing (not only for us, but also convincing for you!) :)

- Carsten

> 
>> - Carsten
> 
> Thanks a lot.
> 
> -- 
> Suvayu
> 
> Open source is the future. It sets us free.

Re: [PATCH] Implement history facility for org-occur searches

[suvayu ali]

On Mon, Oct 10, 2011 at 8:16 PM, Carsten Dominik
<carsten.dominik@gmail.com> wrote:
>
> On 10.10.2011, at 09:47, suvayu ali wrote:
>>
>> My use case was to easily traverse through a sequence of sparse-tree
>> searches. Something that I thought might be useful when searching in a
>> large file. My implementation is probably very suboptimal. I was
>> hoping to find a way to take a "snapshot" of a sparse tree view, and
>> then "undo" or "redo" a sparse tree view. By undo/redo I mean
>> restoring the visibility states of the trees and the highlighted
>> search text. However I couldn't find a way to get the "snapshot", so I
>> tried repeating the searches to achieve a similar result.
>
> We do have support for storing and setting outline visibility:
>
> Take a look at the functions
>
>   org-outline-overlay-data
>   org-set-outline-overlay-data
>
> and at the macro
>
>   org-save-outline-visibility
>
> which uses the two functions described above.
>

Thanks a lot for these pointers Carsten!

>
> OK, I will mark it rejected, feel free to come back when you have
> something convincing (not only for us, but also convincing for you!) :)
>

Will do. :)


> - Carsten

Cheers,

-- 
Suvayu

Open source is the future. It sets us free.