====== VIM - Abbreviations ======

VIM allows abbreviations to be set.

This can support:

  * To automate things in insert mode.
  * To make it quicker to type a long word or sentence with just a few characters.
  * Correcting Typos.

----

===== The Basics =====

Abbreviations can be assigned with the command **:ab[breviate]**. 

To have abbreviations only work whilst in insert mode use **:iabbrev**:

<code bash>
:iabbrev [<expr>] [<buffer>] {abbreviation} {expansion}
</code>

<WRAP info>
**NOTE:**  

  * Anything inside a **[]** is optional. 
  * **<expr>** means that you could use a vimscript expression to create the expansion.
  * **<buffer>** means that it only applies to the current buffer.
  * **abbreviation** is the thing you type and that will be replaced by the **expansion**.

</WRAP>

----

===== Examples =====

<code vim>
:ab Lunix Linux
:ab hapy happy
:ab hte the
:ab BTC The Big Cat
:ab myemail someemail@somewhere.com

:iabbrev Lunix Linux
</code>

<WRAP info>
**NOTE:**  The words will be automatically corrected just after you typed them.
</WRAP>

<WRAP important>
**WARNING:**  Be careful with the abbreviations that are set, as they may prevent using a term for another purpose.

  * For example, an entry for **BTC** might want to be entered without expanding into the separate words.

  * To avoid expansion in insert mode, type **CTRL-V** after the last character of the abbreviation (on Windows, type **CTRL-Q** instead of **CTRL-V**).

</WRAP>

----

===== Advanced Usage =====

Abbreviations can use special sequences like **<CR>** (the enter key), **<Up>**, **<Tab>** and many more.

  * This gives us the power to move around the cursor and create more elaborate snippets.

<code vim>
:iabbrev <buffer> con console.log();<Left><Left>
</code>

...converts to:

<code bash>
console.log( );
</code>


<WRAP info>
**NOTE:**  The **<buffer>** is used to prevent this being available in every buffer, just the ones where I can use valid javascript syntax.

  * There is a space between the parenthesis in the log function, because we chose to "expand it" with the space key.
    * Vim will replace the abbreviation after we press a "non-keyword character" and that character will be inserted after the expansion is done.
    * Basically all the letters and a few special characters are considered "keyword characters" and anything that is not in that set will begin the expansion.
    * Might want to check **:help 'iskeyword'** for more details.
    * If that extra space is not wanted then you can begin the expansion with the sequence **<C-]>**, that is CTRL + closing bracket.

</WRAP>

----

===== Advanced Usage 2 =====

<code vim>
:iabbrev <buffer> iife@ (async function() {})();<Left><Left><Left><Left><Left><CR><CR><Up>
</code>

...converts to:

<code bash>
(async function() {

})();
</code>

<WRAP info>
**NOTE:**  When the **iife@** is typed it will do the conversion.

  * The **@** sign in this case is not important.  It is just a silly convention that is followed to make it clear this will be expanded into something else. 

</WRAP>

----

==== Escaping insert mode ====

All those **<Left>**s can quickly become very complex.  A better way is to escape insert mode and go into normal mode.

We can "press" **<Esc>** to go to normal mode and take advantage of all the vim goodness we can do in that mode. So, we could rewrite it like this.

<code vim>
:iabbrev <buffer> iife@ (async function() {})();<Esc>4hi<CR><CR><Up>
</code>

<WRAP info>
**NOTE:**  The same snippet is now a bit less awful.

  * We replaced the five **<Left>**s with **<Esc>4hi**, a bit more cryptic but shorter.
    * In VIM, you would press that **4hi** yourself.
    * In fact, since we are just entering in insert mode to make one command (4h) and then going back we could simplify it a little bit.

</WRAP>

<code vim>
:iabbrev <buffer> iife@ (async function() {})();<C-o>4h<CR><CR><Up>
</code>

<WRAP info>
**NOTE:**  Now we use **<C-o>** (control + o) to go to normal mode, make one command and immediately go back to insert mode.
</WRAP>


----


===== File Specific Abbreviations =====

Abbreviations can also be set in autocommands to make file specific abbreviations automatically. 

If you put something like this in your .vimrc.

<file bash .vimrc>
:autocmd FileType html,javascript,typescript,vue
  \ :iabbrev <buffer> some-abbreviation some-expansion
</file>  

<WRAP info>
**NOTE:**  It would make **some-abbreviation** available to you in html, javascript, typescript and vue files.
</WRAP>

----

====== To remove all abbreviations ======

<code vim>
:abclear
</code>