[PATCH v3 1/2] emacs: User-defined sections in notmuch-hello
Michal Sojka
sojkam1 at fel.cvut.cz
Wed Jul 6 04:34:13 PDT 2011
Hi,
this is definitely better than the first version I was using! Thanks.
See other comments below.
On Tue, 05 Jul 2011, Daniel Schoepe wrote:
> This patch makes the notmuch-hello screen fully customizable
> by allowing the user to add and remove arbitrary sections. It
> also provides some convenience functions for constructing sections,
> e.g. showing the unread message count for each tag.
>
> This is done by specifying a list of functions that will be run
> when notmuch-hello is invoked.
> ---
> emacs/notmuch-hello.el | 609 +++++++++++++++++++++++++++++++-----------------
> 1 files changed, 393 insertions(+), 216 deletions(-)
>
> diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
> index 65fde75..9c18caa 100644
> --- a/emacs/notmuch-hello.el
> +++ b/emacs/notmuch-hello.el
> @@ -55,26 +55,6 @@
> :type 'boolean
> :group 'notmuch)
>
> -(defcustom notmuch-hello-tag-list-make-query nil
> - "Function or string to generate queries for the all tags list.
I'm not sure it is a good thing to remove customizations that are
included in a released version. Some users may configure it and their
configuration disappear when they install a new version. Is there a way
to migrate this settings to a new, section-based one?
> -This variable controls which query results are shown for each tag
> -in the \"all tags\" list. If nil, it will use all messages with
> -that tag. If this is set to a string, it is used as a filter for
> -messages having that tag (equivalent to \"tag:TAG and (THIS-VARIABLE)\").
> -Finally this can be a function that will be called for each tag and
> -should return a filter for that tag, or nil to hide the tag."
> - :type '(choice (const :tag "All messages" nil)
> - (const :tag "Unread messages" "tag:unread")
> - (const :tag "Custom filter" string)
> - (const :tag "Custom filter function" function))
> - :group 'notmuch)
> -
> -(defcustom notmuch-hello-hide-tags nil
> - "List of tags to be hidden in the \"all tags\"-section."
> - :type '(repeat string)
> - :group 'notmuch)
> -
> (defface notmuch-hello-logo-background
> '((((class color)
> (background dark))
> @@ -123,6 +103,75 @@ Typically \",\" in the US and UK and \".\" in Europe."
>
> (defvar notmuch-hello-recent-searches nil)
>
> +(define-widget 'notmuch-hello-tags-section 'lazy
> + "Customize-type for notmuch-hello tag-list sections."
> + :tag "Customized tag-list"
This is IMHO still hard to understand only from looking at the
customization widget. Ideally, I'd like to see somewhere a paragraph
like this: "This displays a list of all tags, optionally hiding some of
them. It is also possible to filter the list of messages matching each
tag by an additional filter query. Similarly, the count of messages
displayed next to the buttons can be generated by applying another
filter to the tag query."
Actually, when reading the above paragraph, it still seems a way too
complex. What about the following: I do not think it has sense to list
custom tags with zero counts - I think everybody would use
:hide-empty-tags all the time. Then, the result of listing all tags with
'notmuch search-tags', filtering them with 'filter' and throwing away
empty tags, would be the same as running 'notmuch search-tags filter'
and then finding the counts by 'notmuch count tag:TAG and filter'. One
of the advantage of this approach is that it would probably be faster to
generate the section, because you won't query the counts of all tags if
your filter matches only a few of them.
Additionally, as I didn't read carefully your previous discussions about
the additional filter for counts, I do not see much use for it. If you
only want to see which tags has unread messages, you can simply add a
new section with (:make-query "tag:unread") and you would get what you
want. You can also disable all-tags sections.
So my proposal is to forget about different queries for filters and
counts and having here only the following options: filter, hide-tags and
hide-if-empty.
Then, the documentation would be simple: "This section displays buttons
for all tags of messages matching a FILTER. Optionally, some of these
tags may be hidden."
Is there a use case, which is not covered by this?
> + :type
> + (let ((opts
> + '((:title (string :tag "Title for this section"))
> + (:make-query (string :tag "Filter for each tag"))
> + (:make-count (string :tag "Different query to generate counts"))
> + (:hide-tags (repeat :tag "Tags that will be hidden" string))
I can imagine, that :hide-tags could also be a (list of) regexp(es).
> + (:initially-hidden (boolean :tag "Hide this on startup?"))
This is IMHO not needed here, as you always has to enable this section
manually.
> + (:hide-empty-tags (boolean :tag "Hide tags with no matching messages"))
> + (:hide-if-empty (boolean :tag "Hide if empty")))))
> + `(list (const :tag "" notmuch-hello-insert-tags-section)
> + (plist :inline t :options ,opts))))
> +
> +(define-widget 'notmuch-hello-query-section 'lazy
> + "Customize-type for custom saved-search-like sections"
> + :tag "Customized queries section"
> + :type
> + '(list (const :tag "" notmuch-hello-insert-query-list)
> + (string :tag "Title for this section")
> + (repeat :tag "Queries"
> + (cons (string :tag "Name") (string :tag "Query")))
> + (plist :inline t
> + :options
> + ((:initially-hidden (boolean :tag "Hide this on startup?"))
Not needed (see above).
> + (:hide-empty-tags
Rename to :hide-empty-queries.
> + (boolean :tag "Hide tags with no matching messages"))
Hide queries...
> + (:hide-if-empty (boolean :tag "Hide if empty"))))))
> +
> +(defcustom notmuch-hello-sections
> + (list #'notmuch-hello-insert-header
> + #'notmuch-hello-insert-saved-searches
> + #'notmuch-hello-insert-search
> + #'notmuch-hello-insert-recent-searches
> + #'notmuch-hello-insert-alltags
> + #'notmuch-hello-insert-footer)
> + "Sections for notmuch-hello.
> +
> +Each entry of this list should be a function of no arguments that
> +should return if notmuch-hello-target is produced as part of its
What is notmuch-hello-target? I guess I know what it is from reading the
code, but if I didn't read the code, this mentioning it here would be of
little value for me. Perhaps make the notmuch-hello-target clickable and
document it below.
> +output and nil otherwise. For convenience an element can also be
> +a list of the form (FUNC ARG1 ARG2 .. ARGN) in which case FUNC
> +will be applied to the rest of the list.
> +
> +The functions will be run to construct the content of the
> +notmuch-hello buffer in the order they appear in this list."
> + :group 'notmuch
> + :type
> + '(repeat
> + (choice (function-item notmuch-hello-insert-header)
> + (function-item notmuch-hello-insert-saved-searches)
> + (function-item notmuch-hello-insert-search)
> + (function-item notmuch-hello-insert-recent-searches)
> + (function-item notmuch-hello-insert-alltags)
> + (function-item notmuch-hello-insert-footer)
> + (function-item notmuch-hello-insert-inbox)
> + notmuch-hello-tags-section
> + notmuch-hello-query-section
> + (function :tag "Custom function"))))
> +
> +;; only defined to avoid compilation warnings about free variables
> +(defvar notmuch-hello-target nil)
Add the documentation as discussed above. Additionally, it seems that
having only the label in this variable is not enough, since the same
label can appear in multiple sections. Perhaps, we need both the title
of the section and the label here.
> +(defvar notmuch-hello-hidden-sections nil
> + "List of query sections whose contents are hidden")
"List of section titles whose...
> +
> +(defvar notmuch-hello-first-run t)
> +
> (defun notmuch-hello-remember-search (search)
> (if (not (member search notmuch-hello-recent-searches))
> (push search notmuch-hello-recent-searches))
> @@ -173,8 +222,8 @@ Typically \",\" in the US and UK and \".\" in Europe."
> (message "Saved '%s' as '%s'." search name)
> (notmuch-hello-update)))
>
> -(defun notmuch-hello-longest-label (tag-alist)
> - (or (loop for elem in tag-alist
> +(defun notmuch-hello-longest-label (searches-alist)
> + (or (loop for elem in searches-alist
> maximize (length (car elem)))
> 0))
>
> @@ -238,12 +287,71 @@ should be. Returns a cons cell `(tags-per-line width)'."
> (* tags-per-line (+ 9 1))))
> tags-per-line))))
>
> -(defun notmuch-hello-insert-tags (tag-alist widest target)
> - (let* ((tags-and-width (notmuch-hello-tags-per-line widest))
> +(defun notmuch-hello-filtered-query (query filter)
> + "Constructs a query to search all messages matching QUERY and FILTER.
> +
> +If FILTER is a string, it is directly used in the returned query.
> +
> +If FILTER is a function, it is called with QUERY as a parameter and
> +the string it returns is used as the filter.
> +
> +Otherwise, FILTER is ignored.
> +"
> + (cond
> + ((functionp filter)
> + (let ((result (funcall filter query)))
> + (and result (concat query " and (" result ")"))))
> + ((stringp filter)
> + (concat query " and (" filter ")"))
> + (t (concat query))))
> +
> +(defun notmuch-hello-query-counts (query-alist &rest options)
> + "Compute list of counts of matched messages from QUERY-ALIST.
> +
> +QUERY-ALIST must be a list containing elements of the form (NAME . QUERY)
> +or (NAME QUERY COUNT-QUERY). If the latter form is used,
> +COUNT-QUERY specifies an alternate query to be used to generate
> +the count for the associated query.
> +
> +The result is the list of elements of the form (NAME QUERY COUNT).
> +
> +The values :hide-empty-searches, :make-query and :make-count from
> +options will be handled as specified for
> +`notmuch-hello-insert-searches'."
> + (notmuch-remove-if-not
> + #'identity
> + (mapcar
> + (lambda (elem)
> + (let* ((name (car elem))
> + (query-and-count (if (consp (cdr elem))
> + ;; do we have a different query for the message count?
> + (cons (second elem) (third elem))
> + (cons (cdr elem) (cdr elem))))
> + (message-count
> + (string-to-number
> + (notmuch-saved-search-count
> + (notmuch-hello-filtered-query (cdr query-and-count)
> + (or (plist-get options :make-count)
> + (plist-get options :make-query)))))))
> + (and (or (not (plist-get options :hide-empty-searches)) (> message-count 0))
> + (list name (notmuch-hello-filtered-query
> + (car query-and-count) (plist-get options :make-query))
> + message-count))))
> + query-alist)))
> +
> +(defun notmuch-hello-insert-buttons (searches)
> + "Insert buttons for SEARCHES.
> +
> +SEARCHES must be a list containing lists of the form (NAME QUERY COUNT), where
> +QUERY is the query to start when the button for the corresponding entry is
> +activated. COUNT should be the number of messages matching the query.
> +Such a list can be computed with `notmuch-hello-query-counts'."
> + (let* ((widest (notmuch-hello-longest-label searches))
> + (tags-and-width (notmuch-hello-tags-per-line widest))
> (tags-per-line (car tags-and-width))
> (widest (cdr tags-and-width))
> (count 0)
> - (reordered-list (notmuch-hello-reflect tag-alist tags-per-line))
> + (reordered-list (notmuch-hello-reflect searches tags-per-line))
> ;; Hack the display of the buttons used.
> (widget-push-button-prefix "")
> (widget-push-button-suffix "")
> @@ -253,13 +361,13 @@ should be. Returns a cons cell `(tags-per-line width)'."
> (mapc (lambda (elem)
> ;; (not elem) indicates an empty slot in the matrix.
> (when elem
> - (let* ((name (car elem))
> - (query (cdr elem))
> + (let* ((name (first elem))
> + (query (second elem))
> + (count (third elem))
> (formatted-name (format "%s " name)))
> (widget-insert (format "%8s "
> - (notmuch-hello-nice-number
> - (string-to-number (notmuch-saved-search-count query)))))
> - (if (string= formatted-name target)
> + (notmuch-hello-nice-number count)))
> + (if (string= formatted-name notmuch-hello-target)
> (setq found-target-pos (point-marker)))
> (widget-create 'push-button
> :notify #'notmuch-hello-widget-search
> @@ -277,7 +385,7 @@ should be. Returns a cons cell `(tags-per-line width)'."
> (setq count (1+ count))
> (if (eq (% count tags-per-line) 0)
> (widget-insert "\n")))
> - reordered-list)
> + searches)
>
> ;; If the last line was not full (and hence did not include a
> ;; carriage return), insert one now.
> @@ -325,59 +433,268 @@ should be. Returns a cons cell `(tags-per-line width)'."
> (fset 'notmuch-hello-mode-map notmuch-hello-mode-map)
>
> (defun notmuch-hello-mode ()
> - "Major mode for convenient notmuch navigation. This is your entry portal into notmuch.
> + "Major mode for convenient notmuch navigation. This is your entry portal into notmuch.
>
> Complete list of currently available key bindings:
>
> \\{notmuch-hello-mode-map}"
> - (interactive)
> - (kill-all-local-variables)
> - (use-local-map notmuch-hello-mode-map)
> - (setq major-mode 'notmuch-hello-mode
> - mode-name "notmuch-hello")
> - ;;(setq buffer-read-only t)
> -)
> -
> -(defun notmuch-hello-generate-tag-alist ()
> + (interactive)
> + (kill-all-local-variables)
> + (use-local-map notmuch-hello-mode-map)
> + (setq major-mode 'notmuch-hello-mode
> + mode-name "notmuch-hello")
> + ;;(setq buffer-read-only t)
Don't we want to get rid of this line?
> + )
> +
> +(defun notmuch-hello-generate-tag-alist (&optional hide-tags filter-query filter-count)
> "Return an alist from tags to queries to display in the all-tags section."
> (notmuch-remove-if-not
> - #'cdr
> + #'identity
> (mapcar (lambda (tag)
> - (cons tag
> - (cond
> - ((functionp notmuch-hello-tag-list-make-query)
> - (concat "tag:" tag " and ("
> - (funcall notmuch-hello-tag-list-make-query tag) ")"))
> - ((stringp notmuch-hello-tag-list-make-query)
> - (concat "tag:" tag " and ("
> - notmuch-hello-tag-list-make-query ")"))
> - (t (concat "tag:" tag)))))
> + (let ((query (notmuch-hello-filtered-query (concat "tag:" tag)
> + filter-query)))
> + (when query
> + (if filter-count
> + (list tag (notmuch-hello-filtered-query tag filter-query)
> + (notmuch-hello-filtered-query (concat "tag:" tag)
> + filter-count))
> + (cons tag (notmuch-hello-filtered-query
> + (concat "tag:" tag) filter-query))))))
> (notmuch-remove-if-not
> (lambda (tag)
> - (not (member tag notmuch-hello-hide-tags)))
> + (not (member tag hide-tags)))
> (process-lines notmuch-command "search-tags")))))
>
> +(defun notmuch-hello-insert-header ()
> + "Insert the default notmuch-hello header."
> + (when notmuch-show-logo
> + (let ((image notmuch-hello-logo))
> + ;; The notmuch logo uses transparency. That can display poorly
> + ;; when inserting the image into an emacs buffer (black logo on
> + ;; a black background), so force the background colour of the
> + ;; image. We use a face to represent the colour so that
> + ;; `defface' can be used to declare the different possible
> + ;; colours, which depend on whether the frame has a light or
> + ;; dark background.
> + (setq image (cons 'image
> + (append (cdr image)
> + (list :background (face-background 'notmuch-hello-logo-background)))))
> + (insert-image image))
> + (widget-insert " "))
> +
> + (widget-insert "Welcome to ")
> + ;; Hack the display of the links used.
> + (let ((widget-link-prefix "")
> + (widget-link-suffix ""))
> + (widget-create 'link
> + :notify (lambda (&rest ignore)
> + (browse-url notmuch-hello-url))
> + :help-echo "Visit the notmuch website."
> + "notmuch")
> + (widget-insert ". ")
> + (widget-insert "You have ")
> + (widget-create 'link
> + :notify (lambda (&rest ignore)
> + (notmuch-hello-update))
> + :help-echo "Refresh"
> + (notmuch-hello-nice-number
> + (string-to-number (car (process-lines notmuch-command "count")))))
> + (widget-insert " messages.")))
Perhaps you want to end this (and also all other) section with an empty
line so that the order of sections doesn't matter. I use sections in
this order: header, inbox, saved-searches and there is no space between
header and inbox and two spaces between inbox and saved-searches.
> +(defun notmuch-hello-insert-saved-searches ()
> + "Insert the saved-searches section."
> + (let ((searches (notmuch-hello-query-counts
> + notmuch-saved-searches
> + :hide-empty-searches (not notmuch-show-empty-saved-searches)))
> + found-target-pos final-target-pos)
> + (when searches
> + (widget-insert "\nSaved searches: ")
And here you want to remove the "\n" from the beginning.
> + (widget-create 'push-button
> + :notify (lambda (&rest ignore)
> + (customize-variable 'notmuch-saved-searches))
> + "edit")
> + (widget-insert "\n\n")
> + (setq final-target-pos (point-marker))
> + (let ((start (point)))
> + (setq found-target-pos
> + (notmuch-hello-insert-buttons searches))
> + (if found-target-pos
> + (setq final-target-pos found-target-pos))
> + (indent-rigidly start (point) notmuch-hello-indent)
> + final-target-pos))))
> +
> +(defun notmuch-hello-insert-search ()
> + "Insert a search widget."
> + (widget-insert "Search: ")
> + (setq notmuch-hello-search-bar-marker (point-marker))
> + (widget-create 'editable-field
> + ;; Leave some space at the start and end of the
> + ;; search boxes.
> + :size (max 8 (- (window-width) notmuch-hello-indent
> + (length "Search: ")))
> + :action (lambda (widget &rest ignore)
> + (notmuch-hello-search (widget-value widget)))))
> +
> +(defun notmuch-hello-insert-recent-searches ()
> + "Insert recent searches."
> + (when notmuch-hello-recent-searches
> + (widget-insert "\nRecent searches: ")
> + (widget-create 'push-button
> + :notify (lambda (&rest ignore)
> + (setq notmuch-hello-recent-searches nil)
> + (notmuch-hello-update))
> + "clear")
> + (widget-insert "\n\n")
> + (let ((start (point))
> + (nth 0))
> + (mapc '(lambda (search)
> + (let ((widget-symbol (intern (format "notmuch-hello-search-%d" nth))))
> + (set widget-symbol
> + (widget-create 'editable-field
> + ;; Don't let the search boxes be
> + ;; less than 8 characters wide.
> + :size (max 8
> + (- (window-width)
> + ;; Leave some space
> + ;; at the start and
> + ;; end of the
> + ;; boxes.
> + (* 2 notmuch-hello-indent)
> + ;; 1 for the space
> + ;; before the
> + ;; `[save]' button. 6
> + ;; for the `[save]'
> + ;; button.
> + 1 6))
> + :action (lambda (widget &rest ignore)
> + (notmuch-hello-search (widget-value widget)))
> + search))
> + (widget-insert " ")
> + (widget-create 'push-button
> + :notify (lambda (widget &rest ignore)
> + (notmuch-hello-add-saved-search widget))
> + :notmuch-saved-search-widget widget-symbol
> + "save"))
> + (widget-insert "\n")
> + (setq nth (1+ nth)))
> + notmuch-hello-recent-searches)
> + (indent-rigidly start (point) notmuch-hello-indent))))
> +
> +(defun notmuch-hello-insert-searches (title query-alist &rest options)
> + "Insert a section with TITLE showing a list of buttons made from QUERY-ALIST.
> +
> +QUERY-ALIST must be a list containing elements of the form (NAME . QUERY)
> +or (NAME QUERY COUNT-QUERY). If the latter form is used,
> +COUNT-QUERY specifies an alternate query to be used to generate
> +the count for the associated item.
> +
> +Supports the following entries in OPTIONS as a plist:
> +:initially-hidden - if non-nil, section will be hidden on startup
> +:hide-empty-searches - hide buttons with no matching messages
> +:hide-if-empty - hide if no buttons would be shown
> + (only makes sense with :hide-empty-searches)
> +:make-query - This can be a function that takes a tag as its argument and
> + returns a filter to be used for the query for that tag or nil to hide the
> + tag. This can also be a string that is used as a filter for messages with that tag.
> +:make-count - Seperate query to generate the count that should be displayed for each
> + tag. Accepts the same values as :make-query"
Again, I'm not sure that the distinction between the normal query and
count query is needed now.
> + (widget-insert title)
> + (if (and notmuch-hello-first-run (plist-get options :initially-hidden))
> + (add-to-list 'notmuch-hello-hidden-sections title))
> + (let ((is-hidden (member title notmuch-hello-hidden-sections))
> + (start (point)))
> + (if is-hidden
> + (widget-create 'push-button
> + :notify `(lambda (widget &rest ignore)
> + (setq notmuch-hello-hidden-sections
> + (delete ,title notmuch-hello-hidden-sections))
> + (notmuch-hello-update))
> + "show")
> + (widget-create 'push-button
> + :notify `(lambda (widget &rest ignore)
> + (add-to-list 'notmuch-hello-hidden-sections
> + ,title)
> + (notmuch-hello-update))
> + "hide"))
> + (widget-insert "\n")
> + (let (target-pos
> + (searches (apply 'notmuch-hello-query-counts query-alist options)))
> + (when (and (not is-hidden)
> + (or (not (plist-get options :hide-if-empty))
> + searches))
> + (widget-insert "\n")
> + (setq target-pos
> + (notmuch-hello-insert-buttons searches))
> + (indent-rigidly start (point) notmuch-hello-indent)
> + target-pos))))
> +
> +(defun notmuch-hello-insert-tags-section (&optional title &rest options)
> + "Insert a section displaying all tags and message counts for each.
> +
> +TITLE defaults to \"All tags: \".
> +Allowed options are those accepted by `notmuch-hello-insert-searches' and the
> +following:
> +
> +:hide-tags - List of tags that should be excluded."
> + (apply 'notmuch-hello-insert-searches
> + (or title "All tags: ")
> + (notmuch-hello-generate-tag-alist
> + (plist-get options :hide-tags)
> + (plist-get options :make-query)
> + (plist-get options :make-count))
> + options))
> +
> +(defun notmuch-hello-insert-inbox ()
> + "Show an entry for each saved search and inboxed messages for each tag"
> + (notmuch-hello-insert-searches "What's in your inbox: "
> + (append
> + (notmuch-saved-searches)
> + (notmuch-hello-generate-tag-alist))
> + :make-query "tag:inbox"
> + :hide-empty-searches t))
> +
> +(defun notmuch-hello-insert-alltags ()
> + "Insert a section displaying all tags and associated message counts"
> + (notmuch-hello-insert-tags-section nil :initially-hidden
> + (not notmuch-show-all-tags-list)))
> +
> +(defun notmuch-hello-insert-footer ()
> + "Insert the notmuch-hello footer."
> + (let ((start (point)))
> + (widget-insert "Type a search query and hit RET to view matching threads.\n")
> + (when notmuch-hello-recent-searches
> + (widget-insert "Hit RET to re-submit a previous search. Edit it first if you like.\n")
> + (widget-insert "Save recent searches with the `save' button.\n"))
> + (when notmuch-saved-searches
> + (widget-insert "Edit saved searches with the `edit' button.\n"))
> + (widget-insert "Hit RET or click on a saved search or tag name to view matching threads.\n")
> + (widget-insert "`=' refreshes this screen. `s' jumps to the search box. `q' to quit.\n")
> + (let ((fill-column (- (window-width) notmuch-hello-indent)))
> + (center-region start (point)))))
I might be useful to include here a link to the customization of this
page. Maybe, it would be useful to have notmuch-hello subgroup in
customization interface and link to this group. But creation of the
subgroup should be definitely in a separate patch.
Thanks again for such a great functionality.
-Michal
More information about the notmuch
mailing list