align-region

align-region is a compiled Lisp function in `align.el'.

(align-region BEG END SEPARATE RULES EXCLUDE-RULES &optional FUNC)

Align a region based on a given set of alignment rules.
BEG and END specify the region to be aligned. Either may be nil, in
which case the range will stop at the nearest section division (see
`align-region-separate', and `align-region-heuristic' for more
information').

The region will be divided into separate alignment sections based on
the value of SEPARATE.

RULES and EXCLUDE-RULES are a pair of lists describing how to align
the region, and which text areas within it should be excluded from
alignment. See the `align-rules-list' for more information on the
required format of these two lists.

If FUNC is specified, no text will be modified. What `align-region'
will do with the rules is to search for the alignment areas, as it
regularly would, taking account for exclusions, and then call FUNC,
first with the beginning and ending of the region to be aligned
according to that rule (this can be different for each rule, if BEG
and END were nil), and then with the beginning and ending of each
text region that the rule would have applied to.

The signature of FUNC should thus be:

(defun my-align-function (beg end mode)
"If MODE is a rule (a list), return t if BEG to END are to be searched.
Otherwise BEG to END will be a region of text that matches the rule's
definition, and MODE will be non-nil if any changes are necessary."
(unless (and mode (listp mode))
(message "Would have aligned from %d to %d..." beg end)))

This feature (of passing a FUNC) is used internally to locate the
position of exclusion areas, but could also be used for any other
purpose where you might want to know where the regions that the
aligner would have dealt with are.