bcmertz / expand-region.el

Emacs extension to increase selected region by semantic units.

expand-region.el

Expand region increases the selected region by semantic units. Just keep pressing the key until it selects what you want.

An example:

(setq alphabet-start "abc def")

With the cursor at the c, it starts by marking the entire word abc, then expand to the contents of the quotes abc def, then to the entire quote "abc def", then to the contents of the sexp setq alphabet-start "abc def" and finally to the entire sexp.

You can set it up like this:

(require 'expand-region)
(global-set-key (kbd "C-=") 'er/expand-region)

If you expand too far, you can contract the region by pressing - (minus key), or by prefixing the shortcut you defined with a negative argument: C-- C-=.

Maintenance warning

I use this package every day, and have been doing so for years. It just works. At least, it works for all my use cases. And if it breaks somehow, I fix it.

However, it has become painfully clear to me that I don't have time to fix problems I don't have. It's been years since I could keep pace with the issues and pull requests. Whenever I try, I keep getting feedback that my fix isn't good enough by some standard I don't particularly care about.

So, I have closed the issue tracker and the pull requests. I hope you can happily use this package, just like I do. If it doesn't work for you, then I'm sorry. Thankfully Emacs is infinitely malleable, you can probably fix it yourself.

TLDR: I am still maintaining this package, but I am no longer crowdsourcing a list of issues.

Video

You can watch an intro to expand-region at Emacs Rocks.

Installation

I highly recommend installing expand-region through elpa.

It's available on MELPA:

M-x package-install expand-region

Via use-package:

(use-package expand-region
  :bind ("C-=" . er/expand-region))

Customization / Adding new keybindings

In order to add new keybindings, one can use emacs advice to define them. Here we show how to add keybindings for jumping the cursor to the beginning or end of the selected region

(advice-add 'er/prepare-for-more-expansions-internal :override #'er-custom/prepare-for-more-expansions-internal)

(defun er-custom/prepare-for-more-expansions-internal (repeat-key-str)
  "CUSTOM Return bindings and a message to inform user about them given REPEAT-KEY-STR."
  (let ((msg (format "Type %s to expand again" repeat-key-str))
        (bindings (list (cons repeat-key-str '(er/expand-region 1)))))
    ;; If contract and expand are on the same binding, ignore contract
    (unless (string-equal repeat-key-str expand-region-contract-fast-key)
      (setq msg (concat msg (format ", %s to contract" expand-region-contract-fast-key)))
      (push (cons expand-region-contract-fast-key '(er/contract-region 1)) bindings))
    ;; If reset and either expand or contract are on the same binding, ignore reset
    (unless (or (string-equal repeat-key-str expand-region-reset-fast-key)
                (string-equal expand-region-contract-fast-key expand-region-reset-fast-key))
      (setq msg (concat msg (format ", %s to reset" expand-region-reset-fast-key)))
      (push (cons expand-region-reset-fast-key '(er/expand-region 0)) bindings))
    (setq msg (concat msg (format ", > to jump end" expand-region-eor-fast-key)))
    (push (cons expand-region-eor-fast-key '(move-to-region-end)) bindings)
    (setq msg (concat msg (format ", < to jump beginning" expand-region-bor-fast-key)))
    (push (cons expand-region-bor-fast-key '(move-to-region-beginning)) bindings)
    (cons msg bindings)))

(advice-add 'er/expand-region :override #'er-custom/expand-region)

(defun er-custom/expand-region (arg)
  "Increase selected region by semantic units.

With prefix argument expands the region that many times.
If prefix argument is negative calls `er/contract-region'.
If prefix argument is 0 it resets point and mark to their state
before calling `er/expand-region' for the first time ARG."
  (interactive "p")
  (if (< arg 1)
      (er/contract-region (- arg))
    (er--prepare-expanding)
    (while (>= arg 1)
      (setq arg (- arg 1))
      (when (eq 'early-exit (er--expand-region-1))
        (setq arg 0)))
    (when (and expand-region-fast-keys-enabled
               (not (memq last-command '(er/expand-region er/contract-region move-to-region-end move-to-region-beginning))))
      (er/prepare-for-more-expansions))))

(defcustom expand-region-eor-fast-key "."
  "Key to use after an initial expand/contract to go to end of region."
  :group 'expand-region
  :type 'string)

(defcustom expand-region-bor-fast-key ","
  "Key to use after an initial expand/contract to go to end of region."
  :group 'expand-region
  :type 'string)

(defun move-to-region-beginning ()
  "Move cursor to end of active region if there is one."
  (interactive "")
  (if (use-region-p)
      (goto-char (region-beginning))))

(defun move-to-region-end ()
  "Move cursor to end of active region if there is one."
  (interactive "")
  (if (use-region-p)
      (goto-char (region-end))))

Language support

Expand region works fairly well with most languages, due to the general nature of the basic expansions:

er/mark-word
er/mark-symbol
er/mark-symbol-with-prefix
er/mark-next-accessor
er/mark-method-call
er/mark-inside-quotes
er/mark-outside-quotes
er/mark-inside-pairs
er/mark-outside-pairs
er/mark-comment
er/mark-url
er/mark-email
er/mark-defun

However, most languages also will benefit from some specially crafted expansions. For instance, expand-region comes with these extra expansions for html-mode:

er/mark-html-attribute
er/mark-inner-tag
er/mark-outer-tag

You can add your own expansions to the languages of your choice simply by creating a function that looks around point to see if it's inside or looking at the construct you want to mark, and if so - mark it.

There's plenty of examples to look at in these files.

After you make your function, add it to a buffer-local version of the er/try-expand-list.

Example:

Let's say you want expand-region to also mark paragraphs and pages in text-mode. Incidentally Emacs already comes with mark-paragraph and mark-page. To add it to the try-list, do this:

(defun er/add-text-mode-expansions ()
  (make-variable-buffer-local 'er/try-expand-list)
  (setq er/try-expand-list (append
                            er/try-expand-list
                            '(mark-paragraph
                              mark-page))))

(add-hook 'text-mode-hook 'er/add-text-mode-expansions)

Add that to its own file, and add it to the expand-region.el-file, where it says "Mode-specific expansions"

Warning: Badly written expansions might slow down expand-region dramatically. Remember to exit quickly before you start traversing the entire document looking for constructs to mark.

Contribute

If you make some nice expansions for your favorite mode, it would be great if you opened a pull-request. The repo is at:

https://github.com/magnars/expand-region.el

All changes must be accompanied by feature tests. They are written in Ecukes, a Cucumber for Emacs.

To fetch the test dependencies, install cask if you haven't already, then:

$ cd /path/to/expand-region
$ cask

Run the tests with:

$ ./run-tests.sh

If feature tests are missing for the mode you are changing, please make sure to add a set of basic tests around the functionality you're changing.

Contributors

• Josh Johnston contributed er/contract-region
• Le Wang contributed consistent handling of the mark ring, expanding into pairs/quotes just left of the cursor, and general code clean-up.
• Raimon Grau added support for when transient-mark-mode is off.
• Roland Walker added option to copy the contents of the most recent action to a register, and some fixes.
• Damien Cassou added option to continue expanding/contracting with fast keys after initial expand.
• Sylvain Rousseau fixed loads of little annoyances.
• Ryan Mulligan cleaned up a lot of byte compilation warnings.
• Lefteris Karapetsas added subword-mode expansions.

Language specific contributions

• Matt Briggs, Jorge Dias and Le Wang contributed Ruby expansions.
• Ivan Andrus, fgeller, edmccard and Rotem Yaari contributed Python expansions.
• François Févotte contributed C and C++ expansions.
• Ivan Andrus contributed text-mode, LaTeX-mode and nxml-mode expansions.
• Gleb Peregud contributed Erlang expansions.
• Mark Hepburn contributed Octave expansions.
• Rotem Yaari also contributed an adapter for the region expansion in web-mode.
• Kang-min Liu contributed Perl expansions.
• Alexis Gallagher contributs Standard ML expansions.
• Matt Price improved on org-mode expansions.
• Maksim Grinman added inner-quotes expansion for nxml-mode.
• Andrea Orru added expand-region-smart-cursor.

Thanks!

Changelog

From 0.11 to 0.12 (WIP)

• Option expand-region-subword-enabled to enable subword expansions
• Improve web-mode expansions (Renato F)
• Fixes for cc-mode expansions (Wilfred Hughes)
• Fixes for org-mode expansions (Wilfred Hughes)
• Fix unnecessary unfolding in org-mode
• Fix bug with transient-mark-mode (Russell Black)
• Fix problems with auto-loading (Philippe Vaucher, Wilfred Hughes)

From 0.10 to 0.11

• Option expand-region-smart-cursor to keep cursor at beginning of region if it is there (Andrea Orru)
• Add subword-mode expansions (Lefteris Karapetsas)
• Improve enh-ruby-mode expansions (Ryan Davis)
• Improve nxml-mode expansions (Maksim Grinman)
• Improve org-mode expansions (Matt Price)
• Improve js-mode expansions
• Better performance
• Lots of bugfixes

From 0.9 to 0.10

• Smarter expansion of ruby heredoc contents (Steve Purcell)
• Add enh-ruby-mode expansions (Bradley Wright)
• Add basic expansion er/mark-defun
• Big cleanup of byte compilation warnings (Ryan Mulligan)
• Better performance
• Lots of bugfixes

From 0.8 to 0.9

• Improve org-, clojure-, python-, latex-, cc- and ruby-modes
• Add basic expansions: email and url
• Add sml-mode expansions (Alexis Gallagher)
• Add cperl-mode expansions (Kang-min Liu)
• Add octave-mode expansions (Mark Hepburn)
• Add web-mode expansions (Rotem Yaari)
• Use Carton for dev-dependencies
• Fix bad behavior in minibuffer (Sylvain Rousseau)
• More robust comment expansions
• Improve loading of expansions for all major modes

From 0.7 to 0.8

• Improve js-, ruby-, python- and latex-modes
• Support built-in javascript-mode
• Handle narrowed buffers correctly
• Include mode-specific expansions when autoloading
• Provide option to copy the contents of the most recent action to a register
• Add cc-mode specific expansions
• Add customization to turn off skipping whitespace when expanding
• Continue expanding/contracting with one key press (optional)

License

Copyright (C) 2011-2019 Magnar Sveen

Author: Magnar Sveen [email protected] Keywords: marking region

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.