GPLv3+

org-super-agenda
****************

— The Detailed Node Listing —

Installation

Usage

Group selectors

FAQ

Changelog

Development

1 Introduction
**************

This package lets you "supercharge" your Org daily/weekly agenda.  The
idea is to group items into sections, rather than having them all in one
big list.

   Now you can sort-of do this already with custom agenda commands, but
when you do that, you lose the daily/weekly aspect of the agenda: items
are no longer shown based on deadline/scheduled timestamps, but are
shown no-matter-what.

   So this package filters the results from
‘org-agenda-finalize-entries’, which runs just before items are inserted
into agenda views.  It runs them through a set of filters that separate
them into groups.  Then the groups are inserted into the agenda buffer,
and any remaining items are inserted at the end.  Empty groups are not
displayed.

   The end result is your standard daily/weekly agenda, but arranged
into groups defined by you.  You might put items with certain tags in
one group, habits in another group, items with certain todo keywords in
another, and items with certain priorities in another.  The
possibilities are only limited by the grouping functions.

   The primary use of this package is for the daily/weekly agenda, made
by the ‘org-agenda-list’ command, but it also works for other agenda
views, like ‘org-tags-view’, ‘org-todo-list’, ‘org-search-view’, etc.

2 Contents
**********

   • • •
        • • • • •

3 Screenshots
*************

Here’s what a normal agenda looks like:

   Here’s what the "super" agenda looks like:

   There are also a few .

4 Installation
**************

4.1 MELPA
=========

Just install the ‘org-super-agenda’ package!

4.2 Manual installation
=======================

If you want to install manually, you must also install these packages:

   • Emacs >= 26.1
   • ‘dash’ >= 2.13
   • ‘ht’ >=2.2
   • ‘org-mode’ >= 9.0
   • ‘s’ >= 1.10
   • ‘ts’

   Then put ‘org-super-agenda.el’ in your ‘load-path’, and eval
‘(require 'org-super-agenda)’.

5 Usage
*******

  1. Enable ‘org-super-agenda-mode’.
  2. Set the variable ‘org-super-agenda-groups’ as desired (see example
     below).

     *Note:* In order for groups to be automatically, persistently
     applied to all agenda buffers, the variable
     ‘org-super-agenda-groups’ _must be set in the global scope_ (e.g.
     with ‘setq’ in your init file, or using the customization
     interface).  Alternatively, it can be ‘let’-bound in lisp code that
     calls ‘org-agenda’ commands, but in that case, the setting _will
     not persist across agenda commands_ (so after refreshing an agenda
     buffer by pressing ‘g’, there will be no groups).
  3. Run an Org agenda command.
  4. Start the day with confidence, knowing that nothing important has
     been lost in the jumble of _ahem_ overdue items.

5.1 Examples
============

At first you might feel bewildered by all the options.  Never fear, are
here!

   Here’s the code for the screenshots above.  You can test it quickly
by evaluating this code block:

     (let ((org-super-agenda-groups
            '(;; Each group has an implicit boolean OR operator between its selectors.
              (:name "Today"  ; Optionally specify section name
                     :time-grid t  ; Items that appear on the time grid
                     :todo "TODAY")  ; Items that have this TODO keyword
              (:name "Important"
                     ;; Single arguments given alone
                     :tag "bills"
                     :priority "A")
              ;; Set order of multiple groups at once
              (:order-multi (2 (:name "Shopping in town"
                                      ;; Boolean AND group matches items that match all subgroups
                                      :and (:tag "shopping" :tag "@town"))
                               (:name "Food-related"
                                      ;; Multiple args given in list with implicit OR
                                      :tag ("food" "dinner"))
                               (:name "Personal"
                                      :habit t
                                      :tag "personal")
                               (:name "Space-related (non-moon-or-planet-related)"
                                      ;; Regexps match case-insensitively on the entire entry
                                      :and (:regexp ("space" "NASA")
                                                    ;; Boolean NOT also has implicit OR between selectors
                                                    :not (:regexp "moon" :tag "planet")))))
              ;; Groups supply their own section names when none are given
              (:todo "WAITING" :order 8)  ; Set order of this section
              (:todo ("SOMEDAY" "TO-READ" "CHECK" "TO-WATCH" "WATCHING")
                     ;; Show this group at the end of the agenda (since it has the
                     ;; highest number). If you specified this group last, items
                     ;; with these todo keywords that e.g. have priority A would be
                     ;; displayed in that group instead, because items are grouped
                     ;; out in the order the groups are listed.
                     :order 9)
              (:priority<= "B"
                           ;; Show this section after "Today" and "Important", because
                           ;; their order is unspecified, defaulting to 0. Sections
                           ;; are displayed lowest-number-first.
                           :order 1)
              ;; After the last group, the agenda will display items that didn't
              ;; match any of these groups, with the default order position of 99
              )))
       (org-agenda nil "a"))

   The groups apply to all agenda commands (at least, every one that
calls ‘org-agenda-finalize-entries’).  You can set different groups for
custom commands by setting ‘org-super-agenda-groups’ in the custom
command’s ‘settings’ list (see the description for
‘org-agenda-custom-commands’).  You can disable grouping by binding
‘org-super-agenda-groups’ to nil around a call to an agenda command, or
you can disable it globally by disabling the mode.

5.2 Group selectors
===================

Each group selector creates a group in the agenda containing the items
it matches and consumes those items; any items it doesn’t match are
passed to the next group selector.  The selector ‘:discard’ is an
exception: it consumes any items it matches without creating an agenda
group and passes through the rest to the next selector.

   Each group selector takes an argument which can be a single atom or a
list, e.g.  ‘:tag’ takes a string or list of strings.  Some selectors
are predicates, like ‘:deadline’ or ‘:habit’; for consistency, they also
take an argument, but it is ignored.

   *Note:* The order of items may not be preserved after grouping due to
the implementation’s using hash tables.  Future versions may address
this shortcoming.

5.2.1 Keywords
--------------

‘:name’
     Optionally, set group name header.  May be a string; or the symbol
     ‘none’, in which case no header will be inserted.  If ‘:name’ is
     not set at all, the group will be named automatically.
‘:face’
     A _face_ to apply to items in the group.  If _face_ is a plist
     containing ‘:append t’, it will be appended.  See function
     ‘add-face-text-property’.
‘:transformer’
     Used to transform item strings before display.  Either a function
     called with one argument, the item string, or a sexp, in which case
     the item string is bound to ‘it’.

5.2.2 Special selectors
-----------------------

Every selector requires an argument, even if it’s just ‘t’, e.g.
‘:anything’, ‘:auto-category’, ‘:auto-group’, and ‘:discard’.

‘:and’
     Group ITEMS that match all selectors in GROUP.
‘:anything’
     Select every item, no matter what.  This is probably most useful
     with ‘:discard’, because it doesn’t actually test anything, so it’s
     faster than, e.g.  ‘:regexp "."’, which has to get the entry text
     for every item.
‘:auto-category’
     This automatically groups items by their category (usually the
     filename it’s in, without the ‘.org’ suffix).
‘:auto-dir-name’
     This automatically groups items by the directory name of their
     source buffer.
‘:auto-group’
     This selects items that have the ‘agenda-group’ Org property set.
     By setting this property for a subtree, every item in it will be
     sorted into an agenda group by that name and placed into the agenda
     where the ‘:auto-group’ selector is ().
‘:auto-map’
     This automatically groups items by the value returned when applying
     each item to the given function as a string from the agenda buffer
     ().  The function should return a string to be used as the grouping
     key and as the header for its group.
‘:auto-outline-path’
     This automatically groups items by their outline path hierarchy,
     like ‘Plans/Take over the universe/Take over the moon’.
‘:auto-parent’
     This automatically groups items by their parent heading.  This is
     surprisingly handy, especially if you group tasks hierarchically by
     project and use agenda restrictions to limit the agenda to a
     subtree.
‘:auto-planning’
     This automatically groups items by their earliest of scheduled date
     or deadline, formatted according to variable
     ‘org-super-agenda-date-format’.
‘:auto-priority’
     This automatically groups items by their priority.
‘:auto-property’
     This automatically groups items by the value of the given property
     ().
‘:auto-tags’
     This automatically groups items by all of their tags (i.e.  items
     with exactly the same tags, in any order, will be grouped
     together).
‘:auto-todo’
     This automatically groups items by their to-do keyword.
‘:auto-ts’
     This automatically groups items by the date of their latest
     timestamp anywhere in the entry, formatted according to variable
     ‘org-super-agenda-date-format’.  With argument ‘reverse’, groups
     are sorted newest-first.
‘:discard’
     Discard items that match selectors.  Any groups processed after
     this one will not see discarded items.  You might use this at the
     beginning or end of a list of groups, either to narrow down the
     list of items (used in combination with ‘:not’), or to exclude
     items you’re not interested in.
‘:not’
     Group ITEMS that match no selectors in GROUP.
        • Note that the ‘:not’ group selector _creates_ a group with
          items it _does not_ match; it can be combined with ‘:discard’
          to discard items that _don’t_ match.  For example, ‘(:discard
          (:not (:priority "A")))’ as the first selector would mean that
          only priority ‘A’ items would appear in the agenda, while
          ‘(:discard (:priority "C"))’ would mean that any priority ‘C’
          items would not appear in the agenda.
‘:order’
     A number setting the order sections will be displayed in the
     agenda, lowest number first.  Defaults to ‘0’.
‘:order-multi’
     Set the order of multiple groups at once, like ‘(:order-multi (2
     (groupA) (groupB) ...))’ to set the order of these groups to 2.
‘:take’
     Take the first N items in GROUP.  If N is negative, take the last N
     items.  For example, ‘(:take (-3 group))’ will take the last 3
     items from the group.  The remainder of items are discarded.  Note:
     The order of entries from GROUP is not guaranteed to be preserved,
     so ‘:take’ may not always show expected entries.

5.2.3 Normal selectors
----------------------

These selectors take one argument alone, or multiple arguments in a
list.

‘:category’
     Group items that match any of the given categories.  Argument may
     be a string or list of strings.
‘:children’
     Select any item that has child entries.  Argument may be ‘t’ to
     match if it has any children, ‘nil’ to match if it has no children,
     ‘todo’ to match if it has children with any to-do keywords, or a
     string to match if it has children with certain to-do keywords.
     You might use this to select items that are project top-level
     headings.  Be aware that this may be very slow in non-daily/weekly
     agenda views because of its recursive nature.
‘:date’
     Group items that have a date associated.  Argument can be ‘t’ to
     match items with any date, ‘nil’ to match items without a date, or
     ‘today’ to match items with today’s date.  The ‘ts-date’
     text-property is matched against.
‘:deadline’
     Group items that have a deadline.  Argument can be ‘t’ (to match
     items with any deadline), ‘nil’ (to match items that have no
     deadline), ‘past’ (to match items with a deadline in the past),
     ‘today’ (to match items whose deadline is today), or ‘future’ (to
     match items with a deadline in the future).  Argument may also be
     given like ‘before DATE’ or ‘after DATE’ where DATE is a date
     string that ‘org-time-string-to-absolute’ can process.
‘:effort<’
     Group items that are less than (or equal to) the given effort.
     Argument is a time-duration string, like ‘5’ or ‘0:05’ for 5
     minutes.
‘:effort>’
     Group items that are higher than (or equal to) the given effort.
     Argument is a time-duration string, like ‘5’ or ‘0:05’ for 5
     minutes.
‘:file-path’
     Group items whose buffers’ filename paths match any of the given
     regular expressions.
‘:habit’
     Group habit items (items which have a ‘STYLE: habit’ Org property).
‘:heading-regexp’
     Group items whose headings match any of the given regular
     expressions.
‘:log’
     Group Agenda Log Mode items.  Argument may be ‘close’ or ‘closed’
     to select items closed today; ‘clock’ or ‘clocked’ to select items
     clocked today; ‘changed’ or ‘state’ to select items whose to-do
     state was changed today; ‘t’ to select any logged item, or ‘nil’ to
     select any non-logged item.  (See also variable
     ‘org-agenda-log-mode-items’.)  Note that these items may also be
     matched by the ‘:time-grid’ selector, so if you want these
     displayed in their own group, you may need to select them in a
     group before a group containing the ‘:time-grid’ selector.
‘:pred’
     Group items if any of the given predicate functions return non-nil
     when called with each item as a string from the agenda buffer ().
‘:priority’
     Group items that match any of the given priorities.  Argument may
     be a string or list of strings, which should be the priority
     letter, e.g.  ‘A’.
‘:priority>’
     Group items that are higher than the given priority, e.g.  ‘C’.
‘:priority>=’
     Group items that are higher than or equal to the given priority,
     e.g.  ‘B’.
‘:priority<’
     Group items that are lower than the given priority, e.g.  ‘A’.
‘:priority<=’
     Group items that are lower than or equal to the given priority,
     e.g.  ‘B’.
‘:property’
     Group items with a property, optionally matching a value.  Argument
     may be a property name string, or a list of property name string
     and either value string or predicate with which to test the value.
‘:regexp’
     Group items that match any of the given regular expressions.
‘:scheduled’
     Group items that are scheduled.  Argument can be ‘t’ (to match
     items scheduled for any date), ‘nil’ (to match items that are not
     schedule), ‘past’ (to match items scheduled for the past), ‘today’
     (to match items scheduled for today), or ‘future’ (to match items
     scheduled for the future).  Argument may also be given like ‘before
     DATE’ or ‘after DATE’ where DATE is a date string that
     ‘org-time-string-to-absolute’ can process.
‘:tag’
     Group items that match any of the given tags.  Argument may be a
     string or list of strings.
‘:time-grid’
     Group items that appear on the time grid.
‘:todo’
     Group items that match any of the given TODO keywords.  Argument
     may be a string or list of strings, or ‘t’ to match any keyword, or
     ‘nil’ to match only non-todo items.

5.3 Tips
========

   • An info page (org-super-agenda) is included, with the
     contents of this readme file.
   • Group headers use the keymap ‘org-super-agenda-header-map’,
     allowing you to bind keys in that map which will take effect when
     point is on a header.
        • For example, origami
          (https://github.com/gregsexton/origami.el) works with
          ‘org-super-agenda’ buffers without any extra configuration.
          Just activate ‘origami-mode’ in the agenda buffer and use the
          command ‘origami-toggle-node’ to fold groups.  You can bind,
          e.g.  ‘TAB’ to that command in the header map, and then you
          can easily collapse groups as if they were an outline.  You
          might even fold some automatically ().

6 FAQ
*****

6.1 Why are some items not displayed even though I used group selectors for them?
=================================================================================

This is a common misunderstanding of how this package works.  As written
in the introduction, it does not _collect_ items.  It only _groups_
items that are collected by Org Agenda or ‘org-ql’.  So if your Agenda
command or ‘org-ql’ query does not collect certain items, they will not
be displayed, regardless of what ‘org-super-agenda’ groups you
configure.

   org-ql (https://github.com/alphapapa/org-ql) provides an easier way
to write queries to generate agenda-like views that can be grouped with
‘org-super-agenda’.

6.2 Why did a group disappear when I moved it to the end of the list?
=====================================================================

As explained in the usage instructions and shown in the example, items
are collected into groups in the order the groups are listed, and empty
groups are not shown.  To display a group out of the order in which
groups are listed, use ‘:order’.

7 Changelog
***********

7.1 1.3-pre
===========

*Added*
   • Selector ‘:property’, which groups items with a property,
     optionally also matching a value or predicate.  (Thanks to Per
     Weijnitz (https://github.com/weipe).)
   • Special selector ‘:take’, which limits the number of items
     displayed in a group.  (Thanks to Pete Kazmier
     (https://github.com/pkazmier).)
   • Option ‘org-super-agenda-hide-empty-groups’, which hides empty
     groups.  (Thanks to Christian Schwarzgruber
     (https://github.com/cslux).)
   • Option ‘org-super-agenda-keep-order’, which re-sorts items after
     grouping to preserve their original sort order.  (Thanks to
     Alexander-Miller (https://github.com/Alexander-Miller).)
   • Selector ‘:auto-ts’ may be given the argument ‘reverse’ to sort the
     groups newest-first.
   • Option ‘org-super-agenda-final-group-separator’, which is a
     separator inserted after the final agenda group.  (Thanks to Tyler
     Funnell (https://github.com/funnell).)

7.2 1.2
=======

*Added*
   • Selector ‘:auto-planning’, which groups items by their earliest of
     scheduled date or deadline, formatted according to variable
     ‘org-super-agenda-date-format’.
   • Selector ‘:auto-ts’, which groups items by the date of their latest
     timestamp anywhere in the entry, formatted according to variable
     ‘org-super-agenda-date-format’.
   • Selector ‘:auto-tags’, which groups items by all of their tags.
   • Option ‘org-super-agenda-date-format’, used to format date headers
     in the ‘:auto-date’ selector.
   • To-do keyword faces are applied to keywords in group headers.
   • Option ‘org-super-agenda-header-separator’ may also be a character,
     which is automatically repeated to the window width.  (Thanks to
     YUE Daian (https://github.com/sheepduke).)
   • Option ‘org-super-agenda-header-properties’.  It sets
     ‘org-agenda-structural-header’ by default, which enables navigating
     to headers with the default ‘M-{’ / ‘M-}’ bindings in agenda
     buffers.  (Thanks to Abdul-Lateef Haji-Ali
     (https://github.com/haji-ali).)
   • Option ‘org-super-agenda-header-prefix’, a string prepended to
     group headers.  (#108
     (https://github.com/alphapapa/org-super-agenda/issues/108).  Thanks
     to Christian Schwarzgruber (https://github.com/cslux).)

   *Changed*
   • Group headers face is now appended to face list instead of
     overriding it.
   • Minimum Emacs version requirement is now 26.1 (required by ‘ts’
     library).

   *Fixed*
   • ‘:children todo’ group selection (#75
     (https://github.com/alphapapa/org-super-agenda/issues/75)).
     (Thanks to Ben Leggett (https://github.com/bleggett) and Elric
     Milon (https://github.com/whirm).)
   • ‘:children’ group headings.
   • Don’t show blank lines for disabled headers (i.e.  with ‘:name
     none’ and ‘org-super-agenda-header-separator’ set to an empty
     string).  (Fixes #105
     (https://github.com/alphapapa/org-super-agenda/issues/105).  Thanks
     to Florian Schrödl (https://github.com/floscr).)

   *Updated*
   • Tests updated for Org 9.2.4.

   *Internal*
   • ‘org-habit’ is now loaded when ‘org-super-agenda’ is loaded.  This
     avoids issues, real and potential, and should not cause any
     problems.
   • Variable ‘org-super-agenda-allow-unsafe-groups’ may be used to
     disable groups which call arbitrary functions (e.g.  when called
     from other packages that may read code from untrusted origins).

7.3 1.1.1
=========

*Fixed*
   • Selector ‘:auto-dir-name’ did not handle items without markers

7.4 1.1
=======

*Additions*
   • Keyword ‘:face’, used to apply faces to items in groups.
   • Keyword ‘:transformer’, used to transform items in groups.
   • Option ‘org-super-agenda-header-separator’, which can, e.g.  be set
     to an empty string for a more compact view.  (Thanks to Sébastien
     Delafond (https://github.com/sdelafond).)
   • Face ‘org-super-agenda-header’, which can be used to customize
     group headers.  (Thanks to Christian Schwarzgruber
     (https://github.com/cslux).)
   • Selector ‘:auto-map’, which groups items by the value returned when
     applying items to a function.
   • Selector ‘:file-path’, which groups items by regular expressions
     matched against their buffers’ filename paths.
   • Selector ‘:pred’, which matches if any of the given predicate
     functions return non-nil when called with the item string from the
     agenda buffer.
   • Selector ‘:auto-dir-name’, which groups items by the directory name
     of their source buffer.
   • Selector ‘:auto-parent’, which groups items by their parent
     heading.
   • Selector ‘:auto-todo’, which groups items by their to-do keyword.
   • Selector ‘:auto-priority’, which groups items by their priority.
   • Option ‘org-super-agenda-unmatched-name’, used to change the name
     of the unmatched group.  (Thanks to Marcin Swieczkowski
     (https://github.com/m-cat).)

   *Internal*
   • Refactor auto-groups with macro.

7.5 1.0.3
=========

*Fixed*
   • Require ‘seq’ library.  (Fixes #54.  Thanks to Rick Hanson
     (https://github.com/cryptorick).)

7.6 1.0.2
=========

*Fixed*
   • Byte-compiler warnings.

7.7 1.0.1
=========

*Fixes*
   • Initialize ‘org-super-agenda-header-map’ to a copy of
     ‘org-agenda-mode-map’.  (Fixes #50
     (https://github.com/alphapapa/org-super-agenda/issues/50).  Thanks
     to Yiufung Cheong (https://github.com/yiufung).)

7.8 1.0.0
=========

First tagged version.

8 Development
*************

Contributions and feedback are welcome.

   If you find this useful, I’d appreciate if you would share a
screenshot or two of your agenda views using it (minus any private data,
of course).  I’d like to get ideas for how to better organize my agenda.
:)

8.1 Bugs
========

   • The ‘org-search-view’ agenda command does not seem to set the
     ‘todo-state’ text property for items it finds, so the ‘:todo’
     selector doesn’t work with it.  We should be able to work around
     this by getting the todo state for each item manually, but we have
     to make sure that we only do that when necessary, otherwise it
     might be slow.  And I wouldn’t be surprised if there are other
     selectors that don’t work with this or other commands, but
     ‘org-agenda-list’ should work fine, and ‘org-tags-view’ and
     ‘org-todo-list’ seem to work.

8.2 Tests
=========

It’s easy to run the tests:

  1. Install Cask (https://github.com/cask/cask).
  2. From the repo root directory, run ‘cask install’, which installs
     Emacs and package dependencies into the ‘.cask’ directory.
  3. Run ‘make test’.

9 Credits
*********

   • Thanks to Balaji Sivaraman (https://github.com/balajisivaraman) for
     contributing the ‘:category’ selector.
   • Thanks to Michael Welle (https://github.com/hmw42) for contributing
     the customizable ‘auto-group’ Org property name.