README.md (9921B)
1 [](http://travis-ci.org/magnars/expand-region.el) 2 [](https://coveralls.io/github/magnars/expand-region.el) 3 [](https://elpa.gnu.org/packages/expand-region.html) 4 [](https://melpa.org/#/expand-region) 5 [](https://stable.melpa.org/#/expand-region) 6 7 # expand-region.el 8 9 Expand region increases the selected region by semantic units. Just keep 10 pressing the key until it selects what you want. 11 12 An example: 13 14 (setq alphabet-start "abc def") 15 16 With the cursor at the `c`, it starts by marking the entire word `abc`, then 17 expand to the contents of the quotes `abc def`, then to the entire quote 18 `"abc def"`, then to the contents of the sexp `setq alphabet-start "abc def"` 19 and finally to the entire sexp. 20 21 You can set it up like this: 22 23 (require 'expand-region) 24 (global-set-key (kbd "C-=") 'er/expand-region) 25 26 If you expand too far, you can contract the region by pressing `-` (minus key), 27 or by prefixing the shortcut you defined with a negative argument: `C-- C-=`. 28 29 ## Maintenance warning 30 31 I use this package every day, and have been doing so for years. It just works. 32 At least, it works for all my use cases. And if it breaks somehow, I fix it. 33 34 However, it has become painfully clear to me that I don't have time to fix 35 problems I don't have. It's been years since I could keep pace with the issues 36 and pull requests. Whenever I try, I keep getting feedback that my fix isn't 37 good enough by some standard I don't particularly care about. 38 39 So, I have closed the issue tracker and the pull requests. I hope you can 40 happily use this package, just like I do. If it doesn't work for you, then I'm 41 sorry. Thankfully Emacs is infinitely malleable, you can probably fix it 42 yourself. 43 44 TLDR: *I am still maintaining this package*, but I am no longer crowdsourcing a list of issues. 45 46 ## Video 47 48 You can [watch an intro to expand-region at Emacs Rocks](http://emacsrocks.com/e09.html). 49 50 ## Installation 51 52 I highly recommend installing expand-region through elpa. 53 54 It's available on [MELPA](https://melpa.org/): 55 56 M-x package-install expand-region 57 58 Via [use-package](https://github.com/jwiegley/use-package): 59 60 (use-package expand-region 61 :bind ("C-=" . er/expand-region)) 62 63 ## Language support 64 65 Expand region works fairly well with most languages, due to the general 66 nature of the basic expansions: 67 68 er/mark-word 69 er/mark-symbol 70 er/mark-symbol-with-prefix 71 er/mark-next-accessor 72 er/mark-method-call 73 er/mark-inside-quotes 74 er/mark-outside-quotes 75 er/mark-inside-pairs 76 er/mark-outside-pairs 77 er/mark-comment 78 er/mark-url 79 er/mark-email 80 er/mark-defun 81 82 However, most languages also will benefit from some specially crafted 83 expansions. For instance, expand-region comes with these extra expansions for 84 html-mode: 85 86 er/mark-html-attribute 87 er/mark-inner-tag 88 er/mark-outer-tag 89 90 You can add your own expansions to the languages of your choice simply by 91 creating a function that looks around point to see if it's inside or looking 92 at the construct you want to mark, and if so - mark it. 93 94 There's plenty of examples to look at in these files. 95 96 After you make your function, add it to a buffer-local version of 97 the `er/try-expand-list`. 98 99 **Example:** 100 101 Let's say you want expand-region to also mark paragraphs and pages in 102 text-mode. Incidentally Emacs already comes with `mark-paragraph` and 103 `mark-page`. To add it to the try-list, do this: 104 105 (defun er/add-text-mode-expansions () 106 (make-variable-buffer-local 'er/try-expand-list) 107 (setq er/try-expand-list (append 108 er/try-expand-list 109 '(mark-paragraph 110 mark-page)))) 111 112 (add-hook 'text-mode-hook 'er/add-text-mode-expansions) 113 114 Add that to its own file, and add it to the `expand-region.el`-file, 115 where it says "Mode-specific expansions" 116 117 **Warning:** Badly written expansions might slow down expand-region 118 dramatically. Remember to exit quickly before you start traversing 119 the entire document looking for constructs to mark. 120 121 ## Contribute 122 123 If you make some nice expansions for your favorite mode, it would be 124 great if you opened a pull-request. The repo is at: 125 126 https://github.com/magnars/expand-region.el 127 128 All changes must be accompanied by feature tests. 129 They are written in [Ecukes](http://ecukes.info), a Cucumber for Emacs. 130 131 To fetch the test dependencies, install 132 [cask](https://github.com/rejeep/cask.el) if you haven't already, 133 then: 134 135 $ cd /path/to/expand-region 136 $ cask 137 138 Run the tests with: 139 140 $ ./run-tests.sh 141 142 If feature tests are missing for the mode you are changing, please make 143 sure to add a set of basic tests around the functionality you're changing. 144 145 ## Contributors 146 147 * [Josh Johnston](https://github.com/joshwnj) contributed `er/contract-region` 148 * [Le Wang](https://github.com/lewang) contributed consistent handling of the mark ring, expanding into pairs/quotes just left of the cursor, and general code clean-up. 149 * [Raimon Grau](https://github.com/kidd) added support for when transient-mark-mode is off. 150 * [Roland Walker](https://github.com/rolandwalker) added option to copy the contents of the most recent action to a register, and some fixes. 151 * [Damien Cassou](https://github.com/DamienCassou) added option to continue expanding/contracting with fast keys after initial expand. 152 * [Sylvain Rousseau](https://github.com/thisirs) fixed loads of little annoyances. 153 * [Ryan Mulligan](https://github.com/ryantm) cleaned up a lot of byte compilation warnings. 154 * [Lefteris Karapetsas](https://github.com/LefterisJP) added subword-mode expansions. 155 156 ### Language specific contributions 157 158 * [Matt Briggs](https://github.com/mbriggs), [Jorge Dias](https://github.com/diasjorge) and [Le Wang](https://github.com/lewang) contributed Ruby expansions. 159 * [Ivan Andrus](https://github.com/gvol), [fgeller](https://github.com/fgeller), [edmccard](https://github.com/edmccard) and [Rotem Yaari](https://github.com/vmalloc) contributed Python expansions. 160 * [François Févotte](https://github.com/ffevotte) contributed C and C++ expansions. 161 * [Ivan Andrus](https://github.com/gvol) contributed text-mode, LaTeX-mode and nxml-mode expansions. 162 * [Gleb Peregud](https://github.com/gleber) contributed Erlang expansions. 163 * [Mark Hepburn](https://github.com/markhepburn) contributed Octave expansions. 164 * [Rotem Yaari](https://github.com/vmalloc) also contributed an adapter for the region expansion in web-mode. 165 * [Kang-min Liu](https://github.com/gugod) contributed Perl expansions. 166 * [Alexis Gallagher](https://github.com/algal) contributs Standard ML expansions. 167 * [Matt Price](https://github.com/titaniumbones) improved on org-mode expansions. 168 * [Maksim Grinman](https://github.com/maksle) added inner-quotes expansion for nxml-mode. 169 * [Andrea Orru](https://github.com/AndreaOrru) added `expand-region-smart-cursor`. 170 171 Thanks! 172 173 ## Changelog 174 175 ### From 0.11 to 0.12 (WIP) 176 177 * Option `expand-region-subword-enabled` to enable subword expansions 178 * Improve web-mode expansions (Renato F) 179 * Fixes for cc-mode expansions (Wilfred Hughes) 180 * Fixes for org-mode expansions (Wilfred Hughes) 181 * Fix unnecessary unfolding in org-mode 182 * Fix bug with transient-mark-mode (Russell Black) 183 * Fix problems with auto-loading (Philippe Vaucher, Wilfred Hughes) 184 185 ### From 0.10 to 0.11 186 187 * Option `expand-region-smart-cursor` to keep cursor at beginning of region if it is there (Andrea Orru) 188 * Add subword-mode expansions (Lefteris Karapetsas) 189 * Improve enh-ruby-mode expansions (Ryan Davis) 190 * Improve nxml-mode expansions (Maksim Grinman) 191 * Improve org-mode expansions (Matt Price) 192 * Improve js-mode expansions 193 * Better performance 194 * Lots of bugfixes 195 196 ### From 0.9 to 0.10 197 198 * Smarter expansion of ruby heredoc contents (Steve Purcell) 199 * Add enh-ruby-mode expansions (Bradley Wright) 200 * Add basic expansion er/mark-defun 201 * Big cleanup of byte compilation warnings (Ryan Mulligan) 202 * Better performance 203 * Lots of bugfixes 204 205 ### From 0.8 to 0.9 206 207 * Improve org-, clojure-, python-, latex-, cc- and ruby-modes 208 * Add basic expansions: email and url 209 * Add sml-mode expansions (Alexis Gallagher) 210 * Add cperl-mode expansions (Kang-min Liu) 211 * Add octave-mode expansions (Mark Hepburn) 212 * Add web-mode expansions (Rotem Yaari) 213 * Use Carton for dev-dependencies 214 * Fix bad behavior in minibuffer (Sylvain Rousseau) 215 * More robust comment expansions 216 * Improve loading of expansions for all major modes 217 218 ### From 0.7 to 0.8 219 220 * Improve js-, ruby-, python- and latex-modes 221 * Support built-in javascript-mode 222 * Handle narrowed buffers correctly 223 * Include mode-specific expansions when autoloading 224 * Provide option to copy the contents of the most recent action to a register 225 * Add cc-mode specific expansions 226 * Add customization to turn off skipping whitespace when expanding 227 * Continue expanding/contracting with one key press (optional) 228 229 ## License 230 231 Copyright (C) 2011-2019 Magnar Sveen 232 233 Author: Magnar Sveen <magnars@gmail.com> 234 Keywords: marking region 235 236 This program is free software; you can redistribute it and/or modify 237 it under the terms of the GNU General Public License as published by 238 the Free Software Foundation, either version 3 of the License, or 239 (at your option) any later version. 240 241 This program is distributed in the hope that it will be useful, 242 but WITHOUT ANY WARRANTY; without even the implied warranty of 243 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 244 GNU General Public License for more details. 245 246 You should have received a copy of the GNU General Public License 247 along with this program. If not, see <http://www.gnu.org/licenses/>.