GNU Info

(elisp)Sorting

---

Next: Columns Prev: Auto Filling Up: Text

---

Enter node , (file) or (file)node

Sorting Text
============

   The sorting functions described in this section all rearrange text in
a buffer.  This is in contrast to the function `sort', which rearranges
the order of the elements of a list (Note: Rearrangement).  The
values returned by these functions are not meaningful.

 - Function: sort-subr reverse nextrecfun endrecfun &optional
          startkeyfun endkeyfun
     This function is the general text-sorting routine that subdivides a
     buffer into records and then sorts them.  Most of the commands in
     this section use this function.

     To understand how `sort-subr' works, consider the whole accessible
     portion of the buffer as being divided into disjoint pieces called
     "sort records".  The records may or may not be contiguous, but they
     must not overlap.  A portion of each sort record (perhaps all of
     it) is designated as the sort key.  Sorting rearranges the records
     in order by their sort keys.

     Usually, the records are rearranged in order of ascending sort key.
     If the first argument to the `sort-subr' function, REVERSE, is
     non-`nil', the sort records are rearranged in order of descending
     sort key.

     The next four arguments to `sort-subr' are functions that are
     called to move point across a sort record.  They are called many
     times from within `sort-subr'.

       1. NEXTRECFUN is called with point at the end of a record.  This
          function moves point to the start of the next record.  The
          first record is assumed to start at the position of point
          when `sort-subr' is called.  Therefore, you should usually
          move point to the beginning of the buffer before calling
          `sort-subr'.

          This function can indicate there are no more sort records by
          leaving point at the end of the buffer.

       2. ENDRECFUN is called with point within a record.  It moves
          point to the end of the record.

       3. STARTKEYFUN is called to move point from the start of a
          record to the start of the sort key.  This argument is
          optional; if it is omitted, the whole record is the sort key.
          If supplied, the function should either return a non-`nil'
          value to be used as the sort key, or return `nil' to indicate
          that the sort key is in the buffer starting at point.  In the
          latter case, ENDKEYFUN is called to find the end of the sort
          key.

       4. ENDKEYFUN is called to move point from the start of the sort
          key to the end of the sort key.  This argument is optional.
          If STARTKEYFUN returns `nil' and this argument is omitted (or
          `nil'), then the sort key extends to the end of the record.
          There is no need for ENDKEYFUN if STARTKEYFUN returns a
          non-`nil' value.

     As an example of `sort-subr', here is the complete function
     definition for `sort-lines':

          ;; Note that the first two lines of doc string
          ;; are effectively one line when viewed by a user.
          (defun sort-lines (reverse beg end)
            "Sort lines in region alphabetically;\
           argument means descending order.
          Called from a program, there are three arguments:
          REVERSE (non-nil means reverse order),\
           BEG and END (region to sort).
          The variable `sort-fold-case' determines\
           whether alphabetic case affects
          the sort order.
            (interactive "P\nr")
            (save-excursion
              (save-restriction
                (narrow-to-region beg end)
                (goto-char (point-min))
                (sort-subr reverse 'forward-line 'end-of-line))))

     Here `forward-line' moves point to the start of the next record,
     and `end-of-line' moves point to the end of record.  We do not pass
     the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
     is used as the sort key.

     The `sort-paragraphs' function is very much the same, except that
     its `sort-subr' call looks like this:

          (sort-subr reverse
                     (function
                       (lambda ()
                         (while (and (not (eobp))
                                (looking-at paragraph-separate))
                           (forward-line 1))))
                     'forward-paragraph)

     Markers pointing into any sort records are left with no useful
     position after `sort-subr' returns.

 - User Option: sort-fold-case
     If this variable is non-`nil', `sort-subr' and the other buffer
     sorting functions ignore case when comparing strings.

 - Command: sort-regexp-fields reverse record-regexp key-regexp start
          end
     This command sorts the region between START and END alphabetically
     as specified by RECORD-REGEXP and KEY-REGEXP.  If REVERSE is a
     negative integer, then sorting is in reverse order.

     Alphabetical sorting means that two sort keys are compared by
     comparing the first characters of each, the second characters of
     each, and so on.  If a mismatch is found, it means that the sort
     keys are unequal; the sort key whose character is less at the
     point of first mismatch is the lesser sort key.  The individual
     characters are compared according to their numerical character
     codes in the Emacs character set.

     The value of the RECORD-REGEXP argument specifies how to divide
     the buffer into sort records.  At the end of each record, a search
     is done for this regular expression, and the text that matches it
     is taken as the next record.  For example, the regular expression
     `^.+$', which matches lines with at least one character besides a
     newline, would make each such line into a sort record.  Note:
     Regular Expressions, for a description of the syntax and meaning
     of regular expressions.

     The value of the KEY-REGEXP argument specifies what part of each
     record is the sort key.  The KEY-REGEXP could match the whole
     record, or only a part.  In the latter case, the rest of the
     record has no effect on the sorted order of records, but it is
     carried along when the record moves to its new position.

     The KEY-REGEXP argument can refer to the text matched by a
     subexpression of RECORD-REGEXP, or it can be a regular expression
     on its own.

     If KEY-REGEXP is:

    `\DIGIT'
          then the text matched by the DIGITth `\(...\)' parenthesis
          grouping in RECORD-REGEXP is the sort key.

    `\&'
          then the whole record is the sort key.

    a regular expression
          then `sort-regexp-fields' searches for a match for the regular
          expression within the record.  If such a match is found, it
          is the sort key.  If there is no match for KEY-REGEXP within
          a record then that record is ignored, which means its
          position in the buffer is not changed.  (The other records
          may move around it.)

     For example, if you plan to sort all the lines in the region by the
     first word on each line starting with the letter `f', you should
     set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'.  The
     resulting expression looks like this:

          (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
                              (region-beginning)
                              (region-end))

     If you call `sort-regexp-fields' interactively, it prompts for
     RECORD-REGEXP and KEY-REGEXP in the minibuffer.

 - Command: sort-lines reverse start end
     This command alphabetically sorts lines in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 - Command: sort-paragraphs reverse start end
     This command alphabetically sorts paragraphs in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 - Command: sort-pages reverse start end
     This command alphabetically sorts pages in the region between
     START and END.  If REVERSE is non-`nil', the sort is in reverse
     order.

 - Command: sort-fields field start end
     This command sorts lines in the region between START and END,
     comparing them alphabetically by the FIELDth field of each line.
     Fields are separated by whitespace and numbered starting from 1.
     If FIELD is negative, sorting is by the -FIELDth field from the
     end of the line.  This command is useful for sorting tables.

 - Command: sort-numeric-fields field start end
     This command sorts lines in the region between START and END,
     comparing them numerically by the FIELDth field of each line.  The
     specified field must contain a number in each line of the region.
     Fields are separated by whitespace and numbered starting from 1.
     If FIELD is negative, sorting is by the -FIELDth field from the
     end of the line.  This command is useful for sorting tables.

 - Command: sort-columns reverse &optional beg end
     This command sorts the lines in the region between BEG and END,
     comparing them alphabetically by a certain range of columns.  The
     column positions of BEG and END bound the range of columns to sort
     on.

     If REVERSE is non-`nil', the sort is in reverse order.

     One unusual thing about this command is that the entire line
     containing position BEG, and the entire line containing position
     END, are included in the region sorted.

     Note that `sort-columns' uses the `sort' utility program, and so
     cannot work properly on text containing tab characters.  Use `M-x
     untabify' to convert tabs to spaces before sorting.