/dubs_edit_juice

Vim editing features.

Primary LanguageVim ScriptGNU General Public License v3.0GPL-3.0

Dubs Vim — Edit Juice

About This Plugin

This plugin maps a bunch of editing-related features to key combinations to help delete text, select text, edit text, move the cursor around the buffer, and perform single-key text searches within the buffer.

This script originally started to make Vim emulate EditPlus, but it's grown considerably since then to just make Vim a more comfortable editor all around.

Installation

Installation is easy using the packages feature (see :help packages).

To install the package so that it will automatically load on Vim startup, use a start directory, e.g.,

mkdir -p ~/.vim/pack/landonb/start
cd ~/.vim/pack/landonb/start

If you want to test the package first, make it optional instead (see :help pack-add):

mkdir -p ~/.vim/pack/landonb/opt
cd ~/.vim/pack/landonb/opt

Clone the project to the desired path:

git clone https://github.com/landonb/dubs_edit_juice.git

If you installed to the optional path, tell Vim to load the package:

:packadd! dubs_edit_juice

Just once, tell Vim to build the online help:

:Helptags

Then whenever you want to reference the help from Vim, run:

:help dubs-edit-juice

Optional Vendor Plugins

You can enable additional functionality by installing the third-party plugins.

AutoAdapt

AutoAdapt will "automatically adapt timestamps, copyright notices, etc."

  • When you save a file, it'll check the header and footer and update any "Last Modified"-like lines, and it'll update the copyright years, too.
    • The Dubs Vim code tweaks the match algorithm to recognize and use commas in the copyright, e.g., "2009, 2011-2014" might become "2009, 2011-2015" or "2009, 2001-2014, 2016" depending on if the current year is 2015 or 2016. This might seem a little pretentious, but if you don't publish something some year, you can't claim a copyright on it that year. ALTMLU.
    • The match is also tightened so that it'll only occur if it matches at the beginning of the line, optionally after the start of a comment.

To install AutoAdapt and also a necessary support library, ingo-library, grab the latest Vimballs and let 'em loose. Be sure to specify an install directory so we can install to the Pathogen directory.

Download the support library to the appropriate packages directory.

mkdir -p ~/.vim/pack/vim-scripts/start/ingo-library
cd ~/.vim/pack/vim-scripts/start/ingo-library
wget -O ingo-library-1.022.vmb.gz \
   http://www.vim.org/scripts/download_script.php?src_id=22460
gvim ingo-library-1.022.vmb.gz

Install from Vim.

:UseVimball ~/.vim/pack/vim-scripts/start/ingo-library

Download AutoAdapt to a new Pathogen location.

mkdir ~/.vim/pack/vim-scripts/start/AutoAdapt
cd ~/.vim/pack/vim-scripts/start/AutoAdapt
wget -O AutoAdapt-1.10.vmb.gz \
   http://www.vim.org/scripts/download_script.php?src_id=21327
# You can run gunzip first, or you can just run gvim.
gvim AutoAdapt-1.10.vmb.gz

Install from Vim.

:UseVimball ~/.vim/pack/vim-scripts/start/AutoAdapt

Cleanup.

rm ~/.vim/pack/vim-scripts/start/AutoAdapt/AutoAdapt-1.10.vmb.gz
rm ~/.vim/pack/vim-scripts/start/ingo-library/ingo-library-1.022.vmb.gz

taglist

To unlock the tag list feature, install the taglist plugin.

mkdir ~/.vim/pack/vim-scripts/start/taglist
cd ~/.vim/pack/vim-scripts/start/taglist
wget -N http://downloads.sourceforge.net/project/vim-taglist/vim-taglist/4.6/taglist_46.zip
unzip taglist_46.zip
/bin/rm taglist_46.zip

Always-On Features (Not Mapped to Any Keys)

Smart Tabs

  • The Smart Tabs feature, located in dubs_edit_juice/plugin/ctab.vim, translates tabs to spaces if you're tabbing but not indenting, i.e., if only spaces precede the cursor to the start of the line, then tabs are added when <tab> is pressed, otherwise <spaces> are inserted instead. (See also, Indent with tabs, align with spaces.)

Recover from accidental Ctrl-U

Basically, break the undo block (<Ctrl-g>u) before undoing so insertions consist of more than a single modification. This avoids a problem where undoing in insert mode and then undoing in command mode loses deleted text that cannot be recovered (i.e., isn't part of any undo block).

Features Bound to Key Commands

Searching Buffers

Commands for searching for text within a file.

Key Mapping Description Notes
/ Start a buffer search

Press the forward slash key to start a buffer search in the window wherein your cursor lies. The cursor will jump to matches as you type; hit Enter when you're done typing the search command.

Hint: If you type lowercase characters only, the search is case-insensitive, but if you use one or more uppercase characters, the search is case sensitive.

<F3> Forward and Backward Search Matches

After you've started a buffer search, use <F3> or n to search forward through the buffer, and use <Shift-F3> and N (i.e., Shift-'n') to search backwards through the buffer.

Hint: The search wraps at the end of the buffer; when it wraps, you'll see the scroll bar elevator jump and you'll see a message highlighted in red in the status window that reads, "search hit TOP, continuing at BOTTOM", or, conversely, "search hit BOTTOM, continuing at TOP".

<Shift-F3> Backward Search Match Like <F3>, but go to the previous result, possibly wrapping at the start of the file and continuing from the end, back up to the cursor.
n and N Forward and Backward Search Matches Same as <F3> and <Shift-F3>, respectively.
<F1> Search Buffer for Word Under Cursor

If there's a selection, searches the buffer for that, otherwise selects the word under the cursor and searches for that. This is a shortcut to / in a sense.

Hint: To start searching a buffer for a term, put the cursor on that term, hit <F1> and then use <F3> to continue searching the file.

Caveat: If the search term is lowercase, you'll get case-insensitive matches, but if the search term is mixed- or upper-case, you'll get case-sensitive matches.

<Shift-F1> Highlight Word Under Cursor on Start Search Like <F1> -- starts a search for the word under the cursor -- but doesn't jump to the next match, but rather the cursor stays put.
* Restrictive Search Selected or Under Cursor The star-search is a Vim builtin. It does a case-insensitive "word-search" for the word under the cursor, that is, it only matches exact words. It also excludes special characters, like hyphens, but it combines words across underscores. It does not match supersets (unlike <F1> where, e.g., 'ord' matches 'word'). So, e.g., starting a *-search on 'john_doe' would match 'John_doe' but not 'john-doe', and starting a *-search on the reverse, i.e., on the first half of 'john-doe', would match just 'john' or 'John' or 'JOHN', etc.). The set of word delimiters is obviously customizable.
# Restrictive Search in Reverse Like * search, but backward through the buffer.
<Ctrl-H> Hide Search Highlights After you initiate a search, the matching words in the buffers are highlighted. To disable the highlight, type <Ctrl-H>
\vl Toggle * Whitespace Behavior VeryLiteral defaults to off, such that selecting text with trailing whitespace and then pressing * to start a match matches the same text but ignores whitespace, e.g., "it " (with a space) matches "it" (without a space). You probably won't ever use this command, since you'll normally use * in insert or command mode for the word under the cursor, rather than selecting text first and using * in visual mode.
\s Search and Replace in Buffer

To substitute matching text throughout a file, select the text you want to replace and hit backslash and then 's'. You'll see a partially-completed command ready for you to type the replacement text. Hit return, and then hit 'y' to confirm each replacement or hit 'a' to do 'em all.

Caveat: the search-and-replace starts at the cursor and continues until the end of the file but it doesn't wrap around.

Hint: You'll notice that you are completing a builtin Vim search-n-replace command; if you'd like to do case-sensitive matching, add an 'I' to the end of the search, i.e., :.,$s/Find_Me/Replace_Me/gcI

\S Search and Replace in All Files Listed in Quickfix

This is similar to \s but it searches and replaces text in all of the files listed in the quickfix window.

  • Hint: Do an <F4> or \g search to populate the Quickfix window (these two commands are part of dubs_grep_steady).
  • Double-click the first entry in the Quickfix search results to open that buffer.
  • Highlight the text you want to replace and then hit \ and then S.
  • Type the replacement text and hit return, and the plugin will find and replace in all of the files in the Quickfix list.

Caveat: If you are not happy with the results, you'll have to <Ctrl-Z> each file that was edited; fortunately, a single Ctrl-Z undoes all of the changes in each buffer.

(FIXME: We could make a :bufdo to run Ctrl-Z once in each open buffer.)

Caveat: If a substring of your replacement text matches the original text, the function will endlessly recurse, oops! Just type <Ctrl-C> to stop it.

Editing and Formatting Text

Key Mapping Description Notes
<F2> 'Paragraphize' Selected text Formats the selected text to be 80-characters wide or less. Uses the 'par' program.
<Shift-F2> Narrow 'Paragraphize' Selected text Same as <F2> but formats the selected text to be 60-characters wide or less.
<Ctrl-Shift-F2> Mediumish 'Paragraphize' Selected text Same as <F2> but formats the selected text to be 70-characters wide or less.
<Alt-Shift-F2> Adaptive 'Paragraphize' Selected text Same as <F2> but formats the selected text to be as wide as first selected line.
<Ctrl-Q><Shift-Click> Block Select

When you select text normally, you select a sequence of characters. But if your text file is pretty-printed (with well-formatted columns and whatnot) you can select text as a "block".

First, enter command mode, then hit <Ctrl-Q> and then <Shift-Click> elsewhere to make a block selection. You can copy, paste and cut block selections like you can normal sequence selections.

(Note: In default Vim, this command is mapped to Ctrl-V, but Ctrl-V is paste, yo! =) so we've remapped Vim's Ctrl-V to Ctrl-Q so we can use Ctrl-V for paste (and since we're using Ctrl-Q for block select, if you want to quit, try <Alt-f>x).)

Quadruple-Click Block Select Uber-secret block select motion. Click four times fast!
<Ctrl-Enter> New Line without Comment Leader Normally, Vim is super smart and starts your new lines with the previous line's comment leader. I.e., in Python, if you're typing a comment, when you hit return, you'll get a new octothorpe at the correctly tabbed column so you can continue typing your comment. But if you're done typing your comment and want to start typing code, hit <Ctrl-Enter> to start a new line with the comment leader.
<Ctrl-Z> and <Ctrl-Y> Undo and Redo

<Ctrl-Z> and <Ctrl-Y> work like most apps, undoing and redoing. This would not be so special if the plugin had not had to change Vim's default: in default Vim, when in select mode, Ctrl-Z lowercases what's selected. But with this plugin, even when text is selected, Ctrl-Z just undoes what was dud.

Hint: If you pine for the lowercase operation, select text and then type <Ctrl-o>gu<DOWN>

f/ and f\ Change Slashes

Use f/ and f\ to change the direction of slashes.

Press f/ to change every backslash to a forward slash in the current line; use f \ to do the opposite.

Hint: This is useful for converting Windows OS directory paths to Linux/Mac, and vice versa.

qq and q and Q Record and Playback Keystrokes

This is a shortcut to playback the recording in the q register.

  1. Start recording with qq.
  2. End recording with q (or with <Ctrl-o>q if in Insert mode).
  3. Playback with Q.
<Ctrl-C> Copy <Ctrl-Insert> and <Shift-Insert> are aliases for <Ctrl-C> and <Ctrl-V>, which are aliases for copy and paste, respectively and respectively.
<Shift-Insert> Copy  
<Ctrl-V> Paste  
<Shift-Insert> Paste  
<Ctrl-T> Transpose Characters Swaps the two characters on either side of the cursor.
r Replace Character When in command mode, move the blocky cursor over a character, type 'r', and then type a character to replace the character under the cursor.
<Ctrl-Shift-Backspace> Delete to Start of Line  
<Ctrl-Backspace> Delete to Start of Word  
<Ctrl-Shift-Delete> Delete to End of Line  
<Alt-Delete> Delete to End of Line  
<Ctrl-Delete> Delete to End of Word  
<Shift-Alt-Delete> Remove Line  
<Ctrl-Shift-Left> Select to Cursor-Left  
<Ctrl-Shift-Right> Select to Cursor-Right  
<Alt-Shift-Left> Select from Cursor to Start of Line Same as <Shift-Home>, or v0.
<Alt-Shift-Right> Select from Cursor to End of Line Same as <Shift-End>, or v$.
<Ctrl-Shift-PageUp> Select from Cursor to First Line of Window Executes vH; same as <Alt-Shift-Up>.
<Ctrl-Shift-PageDown> Select from Cursor to Last Line of Window Executes vL; same as <Alt-Shift-Down>.
<Alt-Shift-Up> Select from Cursor to First Line of Window Executes vH; same as <Ctrl-Shift-PageUp>.
<Alt-Shift-Down> Select from Cursor to Last Line of Window Executes vL; same as <Ctrl-Shift-PageDown>.
<Tab> and <Shift-Tab> Indent and Undent Selected Text

Select some text in one or more lines and use <Tab> and <Shift-Tab> to indent and undent the text according to the current tab width (and using tabs or spaces as appropriate).

Caveat: Cindent is too smart and won't shift octothorpes that are in the first column (because it thinks they're pre-compilation macros); [lb] has tried but failed to find a way around this, but he likes the other things that Cindent is good for.

<Ctrl-P> and <Ctrl-L> Swap Paragraphs

<Ctrl-P> swaps the paragraph under the cursor with the paragraph above.

<Ctrl-L> swaps in with the paragraph below.

\O Open hyperlink under cursor or selected.  

Common Buffer Commands

Some cursor-, scrolling-, and selecting-related standard Vim and custom Dubs Vim commands.

Key Mapping Description Notes
gg First Line Move the cursor and scroll to the top of the buffer.
G Last Line Move the cursor and scroll to the bottom of the buffer.
[0-9]+ G Specific Line Type a line number and then G to jump the cursor to that line number.
<Ctrl-PageUp> Move Cursor to Window Top Moves the cursor to the first line of the window (not the buffer) without scrolling the buffer.
<Ctrl-PageDown> Move Cursor to Window Bottom Moves the cursor to the bottom of the window without scrolling the buffer.
<Alt-Up> and <Alt-Down> Move Cursor to Window Top/Bottom Same as <Ctrl-PageUp> and <Ctrl-PageDown>, respectively.
M Move Cursor to Window Middle Moves the cursor to the middle of the window without scrolling the buffer.
<Alt-F12> Start Editing at Window Middle This is an obscure command: Moves the cursor to the middle of the window without scrolling the buffer and starts an edit session.
<Alt-Left> and <Alt-Right> Move Cursor to Line Start/End These do the same thing as <HOME> and <END>: it moves the cursor to the first column of the current line or to the last column.
<Ctrl-Left> and <Ctrl-Right> Move Cursor to Word Start/End Moves the cursor one word at a time either left or right; moves across newline boundaries.
<Ctrl-Up> and <Ctrl-Down> Cursorless Scroll Scrolls the buffer without moving the cursor. Not quite the same as a simple <PageUp> or <PageDown> because this command moves the cursor to the first or last line in the window the first time you use it, and it only scrolls the buffer if the cursor is already at the top or bottom of the window (i.e., the second and subsequent times you use it). Note: In Vim-ease, this action is called scrolling the window "in the buffer".
<Shift>-other keys Select text motion Shift can be combined with most of the cursor movement commands above to select the text that the cursor flies over.

Developer Commands

Mostly built-in command reference, but a few Dubs Vim commands, too.

Highlights:

  • Map <Ctlr-]> to work in Insert and Visual modes (by default, jumping to the tag under the cursor or selected text only works in Normal mode).
    • Also map <Alt-]> to jump back to the last tag, since another Dubs Vim plugin overrides the built-in <Ctrl-t> to be transpose.
  • Enable wildmode. In Insert mode, use <Ctrl-N> to cycle through an auto-completion list from your tags file. Completion happens according to wildmode. See also :help cmdline-completion.
Key Mapping Description Notes
<Ctrl-]> Jump to Definition

Jumps to the definition of the function named under the cursor.

Hint: You can return to the tag from which you jumped using <Alt-]>.

<Alt-]> Jump to Last Tag Jumps to the tag used by the last <Ctrl-]> command. Dubs Vim adds the <Alt-]> mapping because it remaps the built-in <Ctrl-T> to be transpose (also, it feels weird that the opposite of <Ctrl-]> is <Ctrl-t>, two combinations that seem unrelated; at least <Ctrl-]> and <Alt-]> share one of the same keys).
<Ctrl-N> Auto-Complete Using Tags After typing the first characters of a keyword, type <Ctrl-n> to bring up an inline list of matching tags. It's not the smartest auto-complete -- the command doesn't suss out object types or anything -- but it's at least something. You can also type <Ctrl-X><Ctrl-]> to start autocomplete. See :help ins-completion for complete deets.
% Jump Between Parentheses/Braces/Brackets Jumps from an open brace, bracket, #if, parenthesis, etc., to the corresponding closing brace, bracket, #endif, parenthesis, etc.
[{ Jump Back to the { Jumps back to the { at the start of the current code block.
gd Jump to a Declaration Jumps from the use of a variable to its local definition.
\tab Toggle Tab Highlighting Type backslash and then t a b to enable or disable tab highlighting. When enabled, tabs will be shown with a solid blue underline.

Note

FIXME: <Ctrl-P> should be the opposite of <Ctrl-N> (it should reverse one item at a time through the tag list) but it doesn't work. It might be conflicting with MoveParagraphUp().

Obscure (Rarely Used) But Useful Commands

Key Mapping Description Notes
:TabMessage [cmd] Send Vim output to New Tab Vim commands sometimes have output and sometimes that output is very long but Vim forces you to view it through a 'less'-ish lens, and sometimes you cannot easily copy the output data. Use :TabMessage to execute a command and copy the output to a new Tab window, where you can peruse and copy it freely.
:: Run Highlighted Text as Vim Command Starts the highlighted text as a Vim command, i.e., type 'help', highlight it, hit ':', hit Enter, and you'll see the Vim help window.
:Lorem Lorum Ipsum Dump Pastes the first paragraph of Lorum Ipsum at the prompt.
<Ctrl-o>g<Ctrl-g> Count Selected Characters  
m{char} / '{char} Set a / Return to Bookmark Sets and Jumps to virtual line marks.
:DiffOrig Diff Buffer Against File See the difference between the current buffer and the file it was loaded from, thus the changes you've made since you last saved.

The Alt-Shift Mappings

The alt-shift commands show and hide special windows.

Key Mapping Description Notes
<Shift-Alt-1> Toggle ASCII Character Table

Decimal and Hexadecimal 8-bit character set (based on CharTab).

Hint: Hit b to toggle between bases (radices). To return to the previous buffer, hit q, <ESC> or <Shift-Alt-1>.

<Shift-Alt-6> Toggle Tag list

Show/Hide the Tag List window.

Calls :TlistToggle. See :help taglist.

Hint: Run ctags on your code to make a tags file first, and then :set tags=<path,path,...> in Vim to point to the tags file. You can setup different tags for different file types and projects; see dubs_file_finder/dubs_projects.vim, which you can customize.

Hints, Tricks, and Step Throughs

Vim Duplicate Line

Use yy or Y to copy the line. Use dd to delete (cut) the line.

Use p to paste the copied or deleted text after the current line.

Use P to paste the copied or deleted text before the current line.

Use Vp to overwrite the target line.

HINT: yyp will copy and paste the current line.

BONUS HINT: You cannot use period . to repeat the previous yyp.

E.g., to find all occurrences of a variable and duplicate each line, because you want to add a new, similar variable:

  • Press <ESC> to enter command mode.
  • Press <F1> over a word to start the find.
  • Press <HOME> to get ready.
  • Press qq to start recording.
  • Press <F3> to find the next match.
  • Press yyp to duplicate the line.
  • Pree <DOWN> to move the cursor down a line.
  • Press q to stop recording.
  • Press Q to repeat the operation -- find the next match and duplicate the line.

Digraphs -- "A combination of two letters representing one sound, as in ph and ey"

Digraphs let you type Unicode characters.

E.g., type the three keys, <Ctrl-l> e ' (control-l, e, apostrophe) to produce the symbol é.

NOTE: Vim normally maps the digraph function to <Ctrl-k>, but Dubs Vim maps it to <Ctrl-l>. Dubs Vim uses <Ctrl-j> and <Ctrl-k> for traversing buffers backwards and forwards.

Useful Digraphs

A few examples.

Type <Ctrl-l> followed by the two characters in the left column.

Civics:

O K   ✓     Check Mark
X X   ✗     Ballot X

Mathematics:

D G   °     DeGree
+ -   ±     Plus-Minus [So obvious!]
M y   µ     Micro sign [For spelling µziq]

Slices:

1 4   ¼     Quarter! ["Vulgar Fraction One Quarter"]
1 2   ½     Half! ["Vulgar Fraction One Half"]
3 4   ¾     Trips! ["Vulgar Fraction Three Quarters"]

Diacritics:

e '   é     L’accent aigu
e `   è     L’accent grave

Astrological:

* 2   ★     Black Star [David Bowie]
* 1   ☆     White Star

Edicts:

C o   ©     Copyright
R g   ®     Registered sign

Quadratic:

f S   ■     Black Square ("fS": think, "Full Square")
O S   □     White Square ("OS": think, "Open Square")

You can also find emojis online to copy-paste, e.g.,:

🏄 🏊 👕 🍹 🌠 🃏 🚴 🔥 🌲 🚬 🌿 👎 👍 👌 👻 🍍 💀 🍆 🐚

Punctuation and Symbols:

• · ߷ ๏ ‣ ․ ‥ … ※ ⁂ ⁕ ⁖ ⁓ ⸮ ⸰ ︙ ︰ ・ 𐬼 𐬽

Footnote Symbology Typography:

§ ∆ ∇ ♪ ♫ ∫ ← ┼ ◊ † ‡ ° ※ ¶

And you can dig into your own font file, e.g.,:

charmap --font="Hack Regular 9"

See :help digraph for the list of defined digraphs.