FR: headline iteration API

[Adam Spiers <orgmode@adamspiers.org>]

Hi all,

I would like to propose a new extensibility feature: an API for
iterating over all the headlines in a given buffer/file or set of
buffers/files.  In a manner similar to mapcar, this would allow you to
execute an elisp function for each headline which could do anything
you want.  It would *not* have any mandatory side-effects such as
modifying any buffer etc. - that would be left to the extension
developer to do.  Having said that, an API set of helper functions for
things like "increase the priority of this headline" or "add a tag to
this headline" would enrich the possible applications, although those
helper functions probably mostly exist already, even if they are not
explicitly documented as an API at the moment?

Anyway, example use cases:

  - Generating custom reports containing arbitrary combinations
    of things like the following:

    - (count of number of) items ...
      - grouped by TODO keyword state
      - grouped by tag
      - grouped by category
      - grouped by "area of responsibility"
      - grouped by priority
      - with a scheduled date/time
      - with a scheduled date/time in the past
      - with a scheduled date/time within a certain period
      - with a deadline
      - with a deadline missed
      - with a deadline within a certain period

    - amount of time scheduled for a particular type of
      TODO/tag/category/priority (e.g. to ensure that you are planning
      to spend your time evenly across various areas of
      responsibility, this would greatly assist with GTD-like
      "30,000ft and above" reviews)

    - actions taken during minuting of a meeting, grouped by owner

I am sure there are many other really cool ideas which the community
could come up with.  Reports could even be auto-generated via
`after-save-hook' or similar.

Obviously the agenda generation code has a lot of sophisticated
iteration capabilities already built in - without looking at the code,
I am wildly guessing that with some refactoring this logic could maybe
be reused, so that a new headline iteration API would support existing
mechanisms such as tag searches, org-agenda-skip, and sorting?  If so,
IMHO that would be really amazingly powerful :-)

Would be very interested in everyone's thoughts.  Thanks!
Adam