Re: [O] Directly search for Headlines?

[Thorsten Jolitz]

Ken Mankoff <address@hidden> writes:

> On 2014-07-07 at 11:19, Nick Dokos wrote:
>> John Durden <address@hidden> writes:
>>
>>> Can you search directly for headlines in all agenda-files, with the
>>> name of the headline, not tags? If so, how? If not, wouldn't this be
>>> useful?
>>>
>>
>> Try `s' in the agenda perhaps?
>
> Yes this feature would be useful. 
>
> "s" in agenda just saves all Org Buffers for me.

for me too

> My work-around is to search for "* Foo", but this doesn't find headlines
> with TODO items.

Internally, the necessary functionality already exists:

,----[ C-h f org-map-entries RET ]
| org-map-entries is a compiled Lisp function in `org.el'.
| 
| (org-map-entries FUNC &optional MATCH SCOPE &rest SKIP)
| 
| Call FUNC at each headline selected by MATCH in SCOPE.
| 
| [...] 
| MATCH is a tags/property/todo match as it is used in the agenda tags view.
| Only headlines that are matched by this query will be considered during
| the iteration.  When MATCH is nil or t, all headlines will be
| visited by the iteration.
| 
| SCOPE determines the scope of this command.  It can be any of:
| 
| nil     The current buffer, respecting the restriction if any
| tree    The subtree started with the entry at point
| region  The entries within the active region, if any
| region-start-level
|         The entries within the active region, but only those at
|         the same level than the first one.
| file    The current buffer, without restriction
| file-with-archives
|         The current buffer, and any archives associated with it
| agenda  All agenda files
| agenda-with-archives
|         All agenda files with any archive files associated with them
| (file1 file2 ...)
|         If this is a list, all files in the list will be scanned [...]
`----

or

,----[ C-h f org-element-map RET ]
| org-element-map is a compiled Lisp function in `org-element.el'.
| 
| (org-element-map DATA TYPES FUN &optional INFO FIRST-MATCH
| NO-RECURSION WITH-AFFILIATED)
| 
| Map a function on selected elements or objects.
| 
| DATA is a parse tree, an element, an object, a string, or a list
| of such constructs.  TYPES is a symbol or list of symbols of
| elements or objects types (see `org-element-all-elements' and
| `org-element-all-objects' for a complete list of types).  FUN is
| the function called on the matching element or object.  It has to
| accept one argument: the element or object itself.
| [...]
`----

One could either use something like this

#+begin_src emacs-lisp
  (defun tj/match-true-headlines-1 ()
    (interactive)
    (org-element-map
        (org-element-parse-buffer 'headline) 'headline
      (lambda (--entry)
        (let ((true-headline (org-element-property :title --entry)))
          (when (string-match "world" true-headline)
            true-headline)))))
#+end_src

#+results:
: tj/match-true-headlines-1

or like this

#+begin_src emacs-lisp
  (defun tj/match-true-headlines-2 ()
    (interactive)
    (org-map-entries
     (lambda ()
       (when (looking-at org-complex-heading-regexp)
         (let ((true-headline (match-string 4)))
           (when (string-match "world" true-headline)
             (org-no-properties true-headline)))))))
#+end_src

#+results:
: tj/match-true-headlines-2

Lets try some test headlines after evaluating the above src_blocks.

* Hello world
** What a wonderful world
** Nice work if you can get it
*** Don't get around much anymore
*** World music

#+begin_src emacs-lisp :results table
(tj/match-true-headlines-1)
#+end_src

#+results:
| Hello world | What a wonderful world | World music |


#+begin_src emacs-lisp :results table
  (delq nil (tj/match-true-headlines-2))
#+end_src

#+results:
| Hello world | What a wonderful world | World music |

So both versions match the correct headlines in this
*outorg-edit-buffer* (where I write my message-mode email in full
org-mode). 

I don't know if this can be done with existing Org Agenda
functionality (as always, its quite likely...)

If not, to be useful this should be integrated in the Org Agenda
framework. 

-- 
cheers,
Thorsten