Function: org-sort-list
org-sort-list is an interactive and byte-compiled function defined in
org-list.el.gz.
Signature
(org-sort-list &optional WITH-CASE SORTING-TYPE GETKEY-FUNC COMPARE-FUNC INTERACTIVE?)
Documentation
Sort list items.
The cursor may be at any item of the list that should be sorted. Sublists are not sorted. Checkboxes, if any, are ignored.
Sorting can be alphabetically, numerically, by date/time as given by a time stamp, by a property or by priority.
Comparing entries ignores case by default. However, with an optional argument WITH-CASE, the sorting considers case as well, if the current locale allows for it.
The command prompts for the sorting type unless it has been given to the function through the SORTING-TYPE argument, which needs to be a character, among ?n ?N ?a ?A ?t ?T ?f ?F ?x or ?X. Here is the detailed meaning of each character:
n Numerically, by converting the beginning of the item to a number.
a Alphabetically. Only the first line of item is checked.
t By date/time, either the first active time stamp in the entry, if
any, or by the first inactive one. In a timer list, sort the timers.
x By "checked" status of a check list.
Capital letters will reverse the sort order.
If the SORTING-TYPE is ?f or ?F, then GETKEY-FUNC specifies a function to be called with point at the beginning of the record. It must return a value that is compatible with COMPARE-FUNC, the function used to compare entries.
Sorting is done against the visible part of the headlines, it ignores hidden links.
A non-nil value for INTERACTIVE? is used to signal that this function is being called interactively.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/org/org-list.el.gz
(defun org-sort-list
(&optional with-case sorting-type getkey-func compare-func interactive?)
"Sort list items.
The cursor may be at any item of the list that should be sorted.
Sublists are not sorted. Checkboxes, if any, are ignored.
Sorting can be alphabetically, numerically, by date/time as given
by a time stamp, by a property or by priority.
Comparing entries ignores case by default. However, with an
optional argument WITH-CASE, the sorting considers case as well,
if the current locale allows for it.
The command prompts for the sorting type unless it has been given
to the function through the SORTING-TYPE argument, which needs to
be a character, among ?n ?N ?a ?A ?t ?T ?f ?F ?x or ?X. Here is
the detailed meaning of each character:
n Numerically, by converting the beginning of the item to a number.
a Alphabetically. Only the first line of item is checked.
t By date/time, either the first active time stamp in the entry, if
any, or by the first inactive one. In a timer list, sort the timers.
x By \"checked\" status of a check list.
Capital letters will reverse the sort order.
If the SORTING-TYPE is ?f or ?F, then GETKEY-FUNC specifies
a function to be called with point at the beginning of the
record. It must return a value that is compatible with COMPARE-FUNC,
the function used to compare entries.
Sorting is done against the visible part of the headlines, it
ignores hidden links.
A non-nil value for INTERACTIVE? is used to signal that this
function is being called interactively."
(interactive (list current-prefix-arg nil nil nil t))
(let* ((case-func (if with-case 'identity 'downcase))
(struct (org-list-struct))
(prevs (org-list-prevs-alist struct))
(start (org-list-get-list-begin (line-beginning-position) struct prevs))
(end (org-list-get-list-end (line-beginning-position) struct prevs))
(sorting-type
(or sorting-type
(progn
(message
"Sort plain list: [a]lpha [n]umeric [t]ime [f]unc [x]checked A/N/T/F/X means reversed:")
(read-char-exclusive))))
(dcst (downcase sorting-type))
(getkey-func
(and (= dcst ?f)
(or getkey-func
(and interactive?
(org-read-function "Function for extracting keys: "))
(error "Missing key extractor"))))
(sort-func
(cond
((= dcst ?a) #'org-string<)
((= dcst ?f)
(or compare-func
(and interactive?
(org-read-function
(concat "Function for comparing keys "
"(empty for default `sort-subr' predicate): ")
'allow-empty))))
((= dcst ?t) #'<)
((= dcst ?x) #'string<))))
(message "Sorting items...")
(save-restriction
(narrow-to-region start end)
(goto-char (point-min))
(let* ((case-fold-search nil)
(now (current-time))
(next-record (lambda ()
(skip-chars-forward " \r\t\n")
(or (eobp) (forward-line 0))))
(end-record (lambda ()
(goto-char (org-list-get-item-end-before-blank
(point) struct))))
(value-to-sort
(lambda ()
(when (looking-at "[ \t]*[-+*0-9.)]+\\([ \t]+\\[[- X]\\]\\)?[ \t]+")
(cond
((= dcst ?n)
(string-to-number
(org-sort-remove-invisible
(buffer-substring (match-end 0) (line-end-position)))))
((= dcst ?a)
(funcall case-func
(org-sort-remove-invisible
(buffer-substring
(match-end 0) (line-end-position)))))
((= dcst ?t)
(cond
;; If it is a timer list, convert timer to seconds
((org-at-item-timer-p)
(org-timer-hms-to-secs (match-string 1)))
((or (save-excursion
(re-search-forward org-ts-regexp (line-end-position) t))
(save-excursion (re-search-forward org-ts-regexp-both
(line-end-position) t)))
(org-time-string-to-seconds (match-string 0)))
(t (float-time now))))
((= dcst ?x) (or (and (stringp (match-string 1))
(match-string 1))
""))
((= dcst ?f)
(if getkey-func
(let ((value (funcall getkey-func)))
(if (stringp value)
(funcall case-func value)
value))
(error "Invalid key function `%s'" getkey-func)))
(t (error "Invalid sorting type `%c'" sorting-type)))))))
(sort-subr (/= dcst sorting-type)
next-record
end-record
value-to-sort
nil
sort-func)
;; Read and fix list again, as `sort-subr' probably destroyed
;; its structure.
(org-list-repair)
(run-hooks 'org-after-sorting-entries-or-items-hook)
(message "Sorting items...done")))))