Function: align-regexp

align-regexp is an autoloaded, interactive and byte-compiled function defined in align.el.gz.

Signature

(align-regexp BEG END REGEXP &optional GROUP SPACING REPEAT)

Documentation

Align the current region using an ad-hoc rule read from the minibuffer.

BEG and END mark the limits of the region. Interactively, this function prompts for the regular expression REGEXP to align with.

For example, let's say you had a list of phone numbers, and wanted to align them so that the opening parentheses would line up:

    Fred (123) 456-7890
    Alice (123) 456-7890
    Mary-Anne (123) 456-7890
    Joe (123) 456-7890

There is no predefined rule to handle this, but interactively, all you would have to do is to mark the region, call align-regexp and enter "(".

REGEXP must contain at least one parenthesized subexpression, typically whitespace of the form "\\\\(\\\\s-*\\\\)", but in interactive use, this is automatically added to the start of your regular expression after you enter it. Interactively, you only need to supply the characters to be lined up, and any preceding whitespace is replaced.

Non-interactively (or if you specify a prefix argument), you must enter the full regular expression, including the subexpression. Interactively, the function also then prompts for which subexpression parenthesis GROUP (default 1) within REGEXP to modify, the amount of SPACING (default align-default-spacing) to use, and whether or not to REPEAT the rule throughout the line.

See align-rules-list for more information about these options.

The non-interactive form of the previous example would look something like:
  (align-regexp (point-min) (point-max) "\\\\(\\\\s-*\\\\)(")

This function is a nothing more than a small wrapper that helps you construct a rule to pass to align-region, which does the real work.

Probably introduced at or before Emacs version 26.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/align.el.gz
;;;###autoload
(defun align-regexp (beg end regexp &optional group spacing repeat)
  "Align the current region using an ad-hoc rule read from the minibuffer.
BEG and END mark the limits of the region.  Interactively, this function
prompts for the regular expression REGEXP to align with.

For example, let's say you had a list of phone numbers, and wanted to
align them so that the opening parentheses would line up:

    Fred (123) 456-7890
    Alice (123) 456-7890
    Mary-Anne (123) 456-7890
    Joe (123) 456-7890

There is no predefined rule to handle this, but interactively,
all you would have to do is to mark the region, call `align-regexp'
and enter \"(\".

REGEXP must contain at least one parenthesized subexpression,
typically whitespace of the form \"\\\\(\\\\s-*\\\\)\", but in
interactive use, this is automatically added to the start of your
regular expression after you enter it.  Interactively, you only
need to supply the characters to be lined up, and any preceding
whitespace is replaced.

Non-interactively (or if you specify a prefix argument), you must
enter the full regular expression, including the subexpression.
Interactively, the function also then prompts for which
subexpression parenthesis GROUP (default 1) within REGEXP to
modify, the amount of SPACING (default `align-default-spacing')
to use, and whether or not to REPEAT the rule throughout the
line.

See `align-rules-list' for more information about these options.

The non-interactive form of the previous example would look something like:
  (align-regexp (point-min) (point-max) \"\\\\(\\\\s-*\\\\)(\")

This function is a nothing more than a small wrapper that helps you
construct a rule to pass to `align-region', which does the real work."
  (interactive
   (append
    (list (region-beginning) (region-end))
    (if current-prefix-arg
	(list (read-string "Complex align using regexp: "
                          "\\(\\s-*\\)" 'align-regexp-history)
	      (string-to-number
	       (read-string
		"Parenthesis group to modify (justify if negative): " "1"))
	      (string-to-number
	       (read-string "Amount of spacing (or column if negative): "
			    (number-to-string align-default-spacing)))
	      (y-or-n-p "Repeat throughout line? "))
      (list (concat "\\(\\s-*\\)"
		    (read-string "Align regexp: "))
	    1 align-default-spacing nil))))
  (or group (setq group 1))
  (or spacing (setq spacing align-default-spacing))
  (let ((rule
	 (list (list nil (cons 'regexp regexp)
		     (cons 'group (abs group))
		     (if (< group 0)
			 (cons 'justify t)
		       (cons 'bogus nil))
		     (if (>= spacing 0)
			 (cons 'spacing spacing)
		       (cons 'column (abs spacing)))
		     (cons 'repeat repeat)))))
    (align-region beg end 'entire rule nil nil)))