dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

README.md (9456B)


      1 # expand-region.el [![Build Status](https://secure.travis-ci.org/magnars/expand-region.el.png)](http://travis-ci.org/magnars/expand-region.el) [![Coverage Status](https://coveralls.io/repos/magnars/expand-region.el/badge.svg?branch=master&service=github)](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/>.