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