Function: org-tags-view

org-tags-view is an autoloaded, interactive and byte-compiled function defined in org-agenda.el.gz.

Signature

(org-tags-view &optional TODO-ONLY MATCH)

Documentation

Show all headlines for all org-agenda-files(var)/org-agenda-files(fun) matching a TAGS criterion.

The prefix arg TODO-ONLY limits the search to TODO entries.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
;;; Agenda tags match

;;;###autoload
(defun org-tags-view (&optional todo-only match)
  "Show all headlines for all `org-agenda-files' matching a TAGS criterion.
The prefix arg TODO-ONLY limits the search to TODO entries."
  (interactive "P")
  (when org-agenda-overriding-arguments
    (setq todo-only (car org-agenda-overriding-arguments)
	  match (nth 1 org-agenda-overriding-arguments)))
  (let* ((org-tags-match-list-sublevels
	  org-tags-match-list-sublevels)
	 (completion-ignore-case t)
	 (org--matcher-tags-todo-only todo-only)
	 rtn rtnall files file pos matcher
	 buffer)
    (when (and (stringp match) (not (string-match "\\S-" match)))
      (setq match nil))
    (catch 'exit
      (setq org-agenda-buffer-name
	    (org-agenda--get-buffer-name
	     (and org-agenda-sticky
		  (if (stringp match)
		      (format "*Org Agenda(%s:%s)*"
			      (or org-keys (or (and todo-only "M") "m"))
			      match)
		    (format "*Org Agenda(%s)*"
			    (or (and todo-only "M") "m"))))))
      (setq matcher (org-make-tags-matcher match))
      ;; Prepare agendas (and `org-tag-alist-for-agenda') before
      ;; expanding tags within `org-make-tags-matcher'
      (org-agenda-prepare (concat "TAGS " match))
      (setq match (car matcher)
	    matcher (cdr matcher))
      (org-compile-prefix-format 'tags)
      (org-set-sorting-strategy 'tags)
      (setq org-agenda-query-string match)
      (setq org-agenda-redo-command
	    (list 'org-tags-view
		  `(quote ,org--matcher-tags-todo-only)
		  `(if current-prefix-arg nil ,org-agenda-query-string)))
      (setq files (org-agenda-files nil 'ifmode)
	    rtnall nil)
      (while (setq file (pop files))
	(catch 'nextfile
	  (org-check-agenda-file file)
	  (setq buffer (if (file-exists-p file)
			   (org-get-agenda-file-buffer file)
			 (error "No such file %s" file)))
	  (if (not buffer)
	      ;; If file does not exist, error message to agenda
	      (setq rtn (list
			 (format "ORG-AGENDA-ERROR: No such org-file %s" file))
		    rtnall (append rtnall rtn))
	    (with-current-buffer buffer
	      (unless (derived-mode-p 'org-mode)
		(error "Agenda file %s is not in Org mode" file))
	      (save-excursion
		(save-restriction
		  (if (eq buffer org-agenda-restrict)
		      (narrow-to-region org-agenda-restrict-begin
					org-agenda-restrict-end)
		    (widen))
		  (setq rtn (org-scan-tags 'agenda
					   matcher
					   org--matcher-tags-todo-only))
		  (setq rtnall (append rtnall rtn))))))))
      (org-agenda--insert-overriding-header
        (with-temp-buffer
	  (insert "Headlines with TAGS match: ")
	  (add-text-properties (point-min) (1- (point))
			       (list 'face 'org-agenda-structure
				     'short-heading
				     (concat "Match: " match)))
	  (setq pos (point))
	  (insert match "\n")
	  (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-filter))
	  (setq pos (point))
	  (unless org-agenda-multi
	    (insert (substitute-command-keys
		     "Press \
\\<org-agenda-mode-map>`\\[universal-argument] \\[org-agenda-redo]' \
to search again\n")))
	  (add-text-properties pos (1- (point))
			       (list 'face 'org-agenda-structure-secondary))
	  (buffer-string)))
      (org-agenda-mark-header-line (point-min))
      (when rtnall
	(insert (org-agenda-finalize-entries rtnall 'tags) "\n"))
      (goto-char (point-min))
      (or org-agenda-multi (org-agenda-fit-window-to-buffer))
      (add-text-properties
       (point-min) (point-max)
       `(org-agenda-type tags
			 org-last-args (,org--matcher-tags-todo-only ,match)
			 org-redo-cmd ,org-agenda-redo-command
			 org-series-cmd ,org-cmd))
      (org-agenda-finalize)
      (setq buffer-read-only t))))