Function: org-priority

org-priority is an interactive and byte-compiled function defined in org.el.gz.

Signature

(org-priority &optional ACTION)

Documentation

Change the priority of an item.

When called interactively with a C-u (universal-argument) prefix, show the priority in the minibuffer instead of changing it.

When called programmatically, ACTION can be set, up, down, remove, an uppercase alphabetic character A through Z, or an integer 0 through 64, inclusive. If a lower-case character is passed as ACTION or entered via interactive prompt, it will automatically be converted to uppercase.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defun org-priority (&optional action)
  "Change the priority of an item.

When called interactively with a `\\[universal-argument]' prefix,
show the priority in the minibuffer instead of changing it.

When called programmatically, ACTION can be `set', `up', `down', `remove', an
uppercase alphabetic character A through Z, or an integer 0 through 64,
inclusive.  If a lower-case character is passed as ACTION or entered via
interactive prompt, it will automatically be converted to uppercase."
  (interactive "P")
  (if (equal action '(4))
      (org-priority-show)
    (unless org-priority-enable-commands
      (user-error "Priority commands are disabled"))
    ;; If action was not provided, default to "set", which will prompt the user
    (setq action (or action 'set))
    (let ((is-numeric-priority (org-priority-number-p org-priority-lowest))
	  current-value new-value new-value-string has-existing-cookie remove)
      (save-excursion
	(org-back-to-heading t)
	(when (looking-at org-priority-regexp)
	  (let ((ms (match-string 2)))
	    (setq current-value (org-priority-to-value ms)
		  has-existing-cookie t)))
	(cond
	 ((eq action 'remove)
	  (setq remove t new-value ?\s))
         ;; set and a value are treated similarly, but only if the
         ;; value is a valid priority
	 ((or (eq action 'set)
	      (org-priority-valid-value-p action))
	  (if (not (eq action 'set))
	      (setq new-value action)
	    (setq
	     new-value
             (let* ((msg (format "Priority %s-%s, SPC to remove: "
                                 (org-priority-to-string org-priority-highest)
                                 (org-priority-to-string org-priority-lowest)))
                    ;; Read input as a string if the current high/low range could
                    ;; be two digits. Otherwise, we can just read a single
                    ;; character and save the user from pressing <enter>
                    (s (if (and is-numeric-priority
                                (>= org-priority-lowest 10))
                           (read-string msg)
                         (char-to-string (read-char-exclusive msg)))))
               ;; Space is a special value indicating removal. For numeric
               ;; priorities, parse the numeric value or ensure an upper case
               ;; character (and convert back to a character for validation)
               (if (string-equal s " ")
                   ?\s
                 (if is-numeric-priority
                     (progn
                       ;; Validate the input string to ensure it's a valid value because
                       ;; string-to-number returns zero for a non-numeric string, which could
                       ;; be a valid priority
                       (unless (string-match-p org-priority-value-regexp s)
                         (user-error "Priority must be a number between `%s' and `%s'"
                                     (org-priority-to-string org-priority-highest)
                                     (org-priority-to-string org-priority-lowest)))
                       (string-to-number s))
                   ;; Validation of non-numerics is handled next
                   (string-to-char (upcase s)))))))
          ;; After reading interactive input, set removal flag if needed and
          ;; perform validation on the new value
	  (cond
           ((equal new-value ?\s) (setq remove t))
	   ((not (org-priority-valid-value-p new-value))
	    (user-error "Priority must be between `%s' and `%s'"
                        (org-priority-to-string org-priority-highest)
                        (org-priority-to-string org-priority-lowest)))))
	 ((eq action 'up)
	  (setq new-value (if has-existing-cookie
			(1- current-value)  ; normal cycling
		      ;; last priority was empty
		      (if (eq last-command this-command)
			  org-priority-lowest  ; wrap around empty to lowest
			;; default
			(if org-priority-start-cycle-with-default
			    org-priority-default
			  (1- org-priority-default))))))
	 ((eq action 'down)
	  (setq new-value (if has-existing-cookie
			(1+ current-value)  ; normal cycling
		      ;; last priority was empty
		      (if (eq last-command this-command)
			  org-priority-highest  ; wrap around empty to highest
			;; default
			(if org-priority-start-cycle-with-default
			    org-priority-default
			  (1+ org-priority-default))))))
	 (t (user-error (concat "Invalid action: `%s'.  Action must be one of "
                                "`up', `down', `set', `remove' or a value "
                                "between `%s' and `%s'")
                        action
                        (org-priority-to-string org-priority-highest)
                        (org-priority-to-string org-priority-lowest))))
        ;; Check against the current high/low range if we need to wrap
	(when (not (org-priority-valid-value-p new-value))
	  (if (and (memq action '(up down))
		   (not has-existing-cookie) (not (eq last-command this-command)))
	      ;; `new-value' is from default priority
	      (error
	       "The default can not be set, see `org-priority-default' why")
	    ;; normal cycling: `new-value' is beyond highest/lowest priority
	    ;; and is wrapped around to the empty priority
	    (setq remove t)))
        (setq new-value-string
              (if remove
                  "removed"
                (org-priority-to-string new-value)))
	(if has-existing-cookie
	    (if remove
		(replace-match "" t t nil 1)
	      (replace-match new-value-string t t nil 2))
	  (if remove
	      (user-error "No priority cookie found in line")
	    (let ((case-fold-search nil)) (looking-at org-todo-line-regexp))
	    (if (match-end 2)
		(progn
		  (goto-char (match-end 2))
		  (insert " [#" new-value-string "]"))
	      (goto-char (match-beginning 3))
	      (insert "[#" new-value-string "] "))))
	(when org-auto-align-tags (org-align-tags)))
      (if remove
	  (message "Priority removed")
	(message "Priority of current item set to %s" new-value-string)))))