-File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
-
-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 divides a
- buffer into records and 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; they may
- 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.
- Called from a program, there are three arguments:
- REVERSE (non-nil means reverse order),
- and BEG and END (the region to sort)."
- (interactive "P\nr")
- (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 ()
- (skip-chars-forward "\n \t\f")))
- 'forward-paragraph)
-
- - 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 values.
- Since Emacs uses the ASCII character set, the ordering in that set
- determines alphabetical order.
-
- 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 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.
-
-\1f
-File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
-
-Counting Columns
-================
-
- The column functions convert between a character position (counting
-characters from the beginning of the buffer) and a column position
-(counting screen characters from the beginning of a line).
-
- A character counts according to the number of columns it occupies on
-the screen. This means control characters count as occupying 2 or 4
-columns, depending upon the value of `ctl-arrow', and tabs count as
-occupying a number of columns that depends on the value of `tab-width'
-and on the column where the tab begins. *Note Usual Display::.
-
- Column number computations ignore the width of the window and the
-amount of horizontal scrolling. Consequently, a column value can be
-arbitrarily high. The first (or leftmost) column is numbered 0.
-
- - Function: current-column
- This function returns the horizontal position of point, measured in
- columns, counting from 0 at the left margin. The column position
- is the sum of the widths of all the displayed representations of
- the characters between the start of the current line and point.
-
- For an example of using `current-column', see the description of
- `count-lines' in *Note Text Lines::.
-
- - Function: move-to-column COLUMN &optional FORCE
- This function moves point to COLUMN in the current line. The
- calculation of COLUMN takes into account the widths of the
- displayed representations of the characters between the start of
- the line and point.
-
- If column COLUMN is beyond the end of the line, point moves to the
- end of the line. If COLUMN is negative, point moves to the
- beginning of the line.
-
- If it is impossible to move to column COLUMN because that is in
- the middle of a multicolumn character such as a tab, point moves
- to the end of that character. However, if FORCE is non-`nil', and
- COLUMN is in the middle of a tab, then `move-to-column' converts
- the tab into spaces so that it can move precisely to column
- COLUMN. Other multicolumn characters can cause anomalies despite
- FORCE, since there is no way to split them.
-
- The argument FORCE also has an effect if the line isn't long
- enough to reach column COLUMN; in that case, it says to add
- whitespace at the end of the line to reach that column.
-
- If COLUMN is not an integer, an error is signaled.
-
- The return value is the column number actually moved to.
-
-\1f
-File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
-
-Indentation
-===========
-
- The indentation functions are used to examine, move to, and change
-whitespace that is at the beginning of a line. Some of the functions
-can also change whitespace elsewhere on a line. Columns and indentation
-count from zero at the left margin.
-
-* Menu:
-
-* Primitive Indent:: Functions used to count and insert indentation.
-* Mode-Specific Indent:: Customize indentation for different modes.
-* Region Indent:: Indent all the lines in a region.
-* Relative Indent:: Indent the current line based on previous lines.
-* Indent Tabs:: Adjustable, typewriter-like tab stops.
-* Motion by Indent:: Move to first non-blank character.
-
-\1f
-File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
-
-Indentation Primitives
-----------------------
-
- This section describes the primitive functions used to count and
-insert indentation. The functions in the following sections use these
-primitives.
-
- - Function: current-indentation
- This function returns the indentation of the current line, which is
- the horizontal position of the first nonblank character. If the
- contents are entirely blank, then this is the horizontal position
- of the end of the line.
-
- - Command: indent-to COLUMN &optional MINIMUM
- This function indents from point with tabs and spaces until COLUMN
- is reached. If MINIMUM is specified and non-`nil', then at least
- that many spaces are inserted even if this requires going beyond
- COLUMN. Otherwise the function does nothing if point is already
- beyond COLUMN. The value is the column at which the inserted
- indentation ends.
-
- - User Option: indent-tabs-mode
- If this variable is non-`nil', indentation functions can insert
- tabs as well as spaces. Otherwise, they insert only spaces.
- Setting this variable automatically makes it local to the current
- buffer.
-
-\1f
-File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
-
-Indentation Controlled by Major Mode
-------------------------------------
-
- An important function of each major mode is to customize the <TAB>
-key to indent properly for the language being edited. This section
-describes the mechanism of the <TAB> key and how to control it. The
-functions in this section return unpredictable values.
-
- - Variable: indent-line-function
- This variable's value is the function to be used by <TAB> (and
- various commands) to indent the current line. The command
- `indent-according-to-mode' does no more than call this function.
-
- In Lisp mode, the value is the symbol `lisp-indent-line'; in C
- mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
- Fundamental mode, Text mode, and many other modes with no standard
- for indentation, the value is `indent-to-left-margin' (which is the
- default value).
-
- - Command: indent-according-to-mode
- This command calls the function in `indent-line-function' to
- indent the current line in a way appropriate for the current major
- mode.
-
- - Command: indent-for-tab-command
- This command calls the function in `indent-line-function' to indent
- the current line; except that if that function is
- `indent-to-left-margin', it calls `insert-tab' instead. (That is
- a trivial command that inserts a tab character.)
-
- - Command: newline-and-indent
- This function inserts a newline, then indents the new line (the one
- following the newline just inserted) according to the major mode.
-
- It does indentation by calling the current `indent-line-function'.
- In programming language modes, this is the same thing <TAB> does,
- but in some text modes, where <TAB> inserts a tab,
- `newline-and-indent' indents to the column specified by
- `left-margin'.
-
- - Command: reindent-then-newline-and-indent
- This command reindents the current line, inserts a newline at
- point, and then reindents the new line (the one following the
- newline just inserted).
-
- This command does indentation on both lines according to the
- current major mode, by calling the current value of
- `indent-line-function'. In programming language modes, this is
- the same thing <TAB> does, but in some text modes, where <TAB>
- inserts a tab, `reindent-then-newline-and-indent' indents to the
- column specified by `left-margin'.
-
-\1f
-File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
-
-Indenting an Entire Region
---------------------------
-
- This section describes commands that indent all the lines in the
-region. They return unpredictable values.
-
- - Command: indent-region START END TO-COLUMN
- This command indents each nonblank line starting between START
- (inclusive) and END (exclusive). If TO-COLUMN is `nil',
- `indent-region' indents each nonblank line by calling the current
- mode's indentation function, the value of `indent-line-function'.
-
- If TO-COLUMN is non-`nil', it should be an integer specifying the
- number of columns of indentation; then this function gives each
- line exactly that much indentation, by either adding or deleting
- whitespace.
-
- If there is a fill prefix, `indent-region' indents each line by
- making it start with the fill prefix.
-
- - Variable: indent-region-function
- The value of this variable is a function that can be used by
- `indent-region' as a short cut. You should design the function so
- that it will produce the same results as indenting the lines of the
- region one by one, but presumably faster.