diff --git a/lua/custom/practice/MULTICURSOR_TUTOR.tutor b/lua/custom/practice/MULTICURSOR_TUTOR.tutor new file mode 100644 index 00000000..50a2204c --- /dev/null +++ b/lua/custom/practice/MULTICURSOR_TUTOR.tutor @@ -0,0 +1,255 @@ +# Welcome to the multicursor.nvim Tutorial + +# Chapter 1: Multi-Cursor Basics + +multicursor.nvim allows you to have multiple cursors in your buffer, letting you edit multiple lines or words simultaneously. It's like having a superpower for repetitive editing tasks. + +This tutorial is designed to be interactive. To learn these commands, you must practice them on the text provided. If you make a mistake, remember that pressing `` will clear all additional cursors and return you to a single cursor. + +# Lesson 1.1: ADDING CURSORS LINEARLY + +** To add a cursor on the line above or below, use the `` and `` keys. ** + +1. Move the cursor to the first line below marked ✗. +2. Press the `` key twice. You should now see three cursors. +3. Press `i` to enter Insert mode and type " -> " at the beginning of the lines. +4. Press `` to return to Normal mode and clear the cursors. + +✗ item one +✗ item two +✗ item three + +5. Now try adding cursors above. Move the cursor to the third item. +6. Press the `` key twice. +7. Press `A` to append at the end of the lines and type " (done)". +8. Press ``. + +9. Sometimes you want to add a cursor but skip a line. Use `` or ``. +10. Move to the first line below. Use `` then `` then ``. +11. You should have cursors on lines 1, 2, and 4, skipping line 3. +12. Change "bad" to "good" using `cw` and ``. + +✗ bad apple +Keep this one +✗ bad orange +✗ bad banana + +11. When you are comfortable adding and skipping cursors, move to Lesson 1.2. + +# Lesson 1.2: WORD MATCHING + +** To add a cursor to the next occurrence of the word under the cursor, press `n`. For the previous occurrence, press `N`. Use `s` to skip the next match and `S` to skip the previous match. ** + +1. Move the cursor to the first "apple" in the text below. +2. Press `n` repeatedly until all "apple" words have cursors. +3. Press `cw` and type "fruit" then press ``. +4. Press `` to clear the cursors. + +✗ apple is red. +The apple is tasty. +An apple a day keeps the doctor away. + +5. Now try skipping a match. Move the cursor to "error". +6. Press `n` to select the second "error", then `s` to skip the third one, then `n` again to select the fourth. +7. Use `cw` to change "error" to "warning" on the selected cursors. +8. Press ``. + +✗ error: file not found +✗ error: disk full +This is a normal line. +✗ error: network timeout +✗ error: permission denied + +9. To select EVERY occurrence of a word in the whole document, use `A`. +10. Move to "TODO". Press `A`. +11. Change "TODO" to "DONE" using `cw` and ``. + +✗ TODO: Fix bug A +✗ TODO: Fix bug B +✗ TODO: Fix bug C + +12. Move to Lesson 1.3. + +# Lesson 1.3: MANAGING CURSORS + + ** If you have multiple cursors, you can move the "main" cursor with `` (next) and `` (previous), or delete a specific cursor with `x`. ** + +1. Use `` to create three cursors on the lines below. +2. Press `` to move the focus to the cursor below. +3. Press `x` to delete that specific cursor. +4. You should now have only two cursors. +5. Press `` to clear. + +✗ Line 1 +✗ Line 2 +✗ Line 3 + +6. You can also "disable" cursors with ``. This means only the main cursor moves, but the others stay put. +7. Create three cursors on the lines below. +8. Press ``. Move the main cursor to the end of the line. Notice the others didn't move. +9. Press `` again to re-enable them, or `` to clear them. + +✗ Cursor A +✗ Cursor B +✗ Cursor C + +10. Move to Lesson 2.1. + +# Chapter 2: ADVANCED SELECTIONS + +# Lesson 2.1: THE GA OPERATOR + +** The `ga` command adds a cursor to every line in the current paragraph or visual selection. ** + +1. Move the cursor to the block of text below. +2. Press `ga`. You should now have a cursor on every line of the paragraph. +3. Press `I` (Shift+i) and type " " (two spaces) to indent the whole block. +4. Press ``. + +✗ This is a block +✗ of text that +✗ needs to be +✗ indented. + +5. Now try it with a visual selection. +6. Press `v`, select the first three lines below, then press `ga`. +7. Change the start of the lines to "S" using `cw` and ``. + +✗ Small +✗ small +✗ small +Big + +8. Move to Lesson 2.2. + +# Lesson 2.2: VISUAL BLOCK EDITING + +** In Visual mode, `I` and `A` allow you to insert or append text across all selected cursors. ** + +1. Press `v` and select the lines below. +2. Press `I` (Shift+i) and type "Fixed: " then press ``. +3. Notice how "Fixed: " was added to the start of every selected line. + +✗ Error 404 +✗ Error 500 +✗ Error 502 + +4. Now try appending. Press `v` and select the lines below. +5. Press `A` (Shift+a) and type " [PROCESSED]" then press ``. + +✗ Data A +✗ Data B +✗ Data C + +6. Move to Lesson 2.3. + +# Lesson 2.3: ALIGNMENT AND TRANSPOSITION + +** Use `a` to align cursor columns and `t` to transpose text between cursors. ** + +1. Create cursors on the lines below using ``. +2. Move the cursors so they are at the `=` signs. +3. Press `a`. The cursors should now be aligned in a straight vertical column. +4. Use `i` and space to create a consistent gap. + +✗ var_a = 10 +✗ long_variable_name = 20 +✗ b = 30 + +5. Transposing allows you to swap text between cursors. +6. Create cursors on the two lines below. +7. Use `v` to select the word "First" and the word "Second". +8. Press `t`. The words should have swapped positions. + +✗ First +✗ Second + +9. Move to Lesson 2.4. + +# Lesson 2.4: VISUAL SELECTION TOOLS + +** In Visual mode, `S` splits the selection by a regex separator, and `M` adds cursors for all matches of a pattern within the selection. ** + +1. Move the cursor to the text below. +2. Press `v` and select "apple,banana,cherry". +3. Press `S`, type `,` and press ``. +4. You should now have three cursors, one on each fruit. +5. Press `` to clear. + +✗ apple,banana,cherry + +6. Now try matching. Press `v` and select the block below. +7. Press `M`, type `\d+` (to match numbers) and press ``. +8. Cursors should appear on all numbers. Change them to "X" using `rX`. +9. Press ``. + +✗ item 1 +✗ item 2 +✗ item 3 + +10. Move to Lesson 3.1. + + +# Chapter 3: POWER USER TOOLS + +# Lesson 3.1: SEQUENCE INCREMENT + +** Use `g` to increment numbers in a sequence across all cursors. ** + +1. Use `` to create cursors on the lines below. +2. Place all cursors on the "0" characters. +3. Press `g` repeatedly. +4. The numbers should increment as 1, 2, 3... instead of all becoming 1. + +✗ Item 0 +✗ Item 0 +✗ Item 0 + +5. Use `g` to decrement them back to 0. + +6. Move to Lesson 3.2. + +# Lesson 3.2: SEARCH-BASED CURSORS + +** Use `/n` and `/N` to add cursors based on a search, `/s` and `/S` to skip matches, and `/A` for all matches. ** + +1. Type `/test` `` to search for "test". +2. Press `/n` several times to add cursors to each "test" match. +3. Change "test" to "prod" using `cw` and ``. + +✗ this is a test +Another test here. +No test in this line. +A final test. + +4. Try `/A` to immediately select all matches of the current search. +5. Move to Lesson 3.3. + +# Lesson 3.3: DIAGNOSTICS CURSORS + +** If you have an LSP configured, you can add cursors to diagnostic errors with `]d` and `[d`. ** + +1. Move to the lines below. If you see diagnostic markers (like ⚠ or ✘), use `]d` to add a cursor to the next error. +2. Use `[d` for the previous error. +3. This allows you to fix multiple linting errors across the file quickly. + +✗ local x = 10 -- unused variable +✗ print(y) -- undefined variable y + +(Note: This requires a working LSP to see the effects). + +# LESSON SUMMARY + +1. Linear addition: ``, `` (Add), ``, `` (Skip). +2. Word matching: `n` (Next), `N` (Prev), `s` (Skip Next), `S` (Skip Prev), `A` (All). +3. Management: `` (Next Cursor), `` (Prev Cursor), `x` (Delete main), `` (Disable/Toggle), `` (Clear). +4. Selection: `ga` (Paragraph/Selection lines), `I`/`A` in Visual (Block Insert/Append). +5. Advanced: `a` (Align), `t` (Transpose), `g`/`g` (Sequence Inc/Dec). +6. Search/Diag: `/n` (Search next), `/N` (Search prev), `/s` (Search skip), `/A` (Search all), `]d`/`[d` (Diagnostic add). + +# CONCLUSION + +You have completed the multicursor.nvim tutorial! +Multi-cursors are a powerful way to avoid repetitive editing. The key is to combine these selection methods with your existing Neovim motions and operators. + +To practice further, try using these commands in your own code! diff --git a/lua/custom/practice/TUTOR b/lua/custom/practice/TUTOR new file mode 100644 index 00000000..ee4e8173 --- /dev/null +++ b/lua/custom/practice/TUTOR @@ -0,0 +1,1018 @@ +# Welcome to the Neovim Tutorial + +# Chapter 1 + +Neovim is a very powerful editor that has many commands, too many to explain in +a tutorial such as this. This tutorial is designed to describe enough of the +commands that you will be able to easily use Neovim as an all-purpose editor. + +It is IMPORTANT to remember that this tutorial is set up to teach by use. That +means that you need to do the exercises to learn them properly. If you only +read the text, you will soon forget what is most important! + +For now, make sure that your Caps-Lock is off and press the `j`{normal} key enough +times to move the cursor so that Lesson 0 completely fills the screen. + +# Lesson 0 + +NOTE: The commands in the lessons will modify the text, but those changes +won't be saved. Don't worry about messing things up; just remember that +pressing []() and then [u](u) will undo the latest change. + +This tutorial is interactive, and there are a few things you should know. +- Type []() on links [like this](holy-grail ) to open the linked help section. +- Or simply type [K](K) on any word to find its documentation! +- You can close this help window with `:q`{vim} ``{normal} + +When there is a ✗ sign at the left, you will be required to modify text. +Once you have done the changes correctly, the ✗ sign at the left will change +to ✓. I imagine you can already see how neat Neovim can be. + +Other times, you'll be prompted to run a command (I'll explain this later): + + `:help`{vim} ``{normal} + +or press a sequence of keys +~~~ normal + 0fd3wP$P +~~~ +Text within <'s and >'s (like ``{normal}) describes a key to press +instead of text to type. + +Now, move to the next lesson (use the `j`{normal} key to scroll down). + +# Lesson 1.1: MOVING THE CURSOR + +** To move the cursor, press the `h`, `j`, `k`, `l` keys as indicated. ** + + ↑ + k Hint: The `h`{normal} key is at the left and moves left. + ← h l → The `l`{normal} key is at the right and moves right. + j The `j`{normal} key looks like a down arrow. + ↓ + + 1. Move the cursor around the screen until you are comfortable. + + 2. Hold down the down key (`j`{normal}) until it repeats. + Now you know how to move to the next lesson. + + 3. Using the down key, move to Lesson 1.2. + +NOTE: If you are ever unsure about something you typed, press to place + you in Normal mode. Then retype the command you wanted. + +NOTE: The cursor keys should also work. But using hjkl you will be able to + move around much faster, once you get used to it. + +# Lesson 1.2: EXITING NEOVIM + +!! NOTE: Before executing any of the steps below, read the entire lesson !! + + 1. Press the key (to make sure you are in Normal mode). + + 2. Type: + + `:q!`{vim} ``{normal} + + This quits the editor, DISCARDING any changes you have made. + + 3. Open Neovim and get back here by executing the command that got you into + this tutorial. That might be: + + `:Tutor`{vim} ``{normal} + + 4. If you have these steps memorized and are confident, execute steps + 1 through 3 to exit and re-enter the editor. + +NOTE: [:q!](:q) ``{normal} discards any changes you made. In a few lessons you + will learn how to save the changes to a file. + + 5. Move the cursor down to Lesson 1.3. + +# Lesson 1.3: TEXT EDITING: DELETION + +** Press `x`{normal} to delete the character under the cursor. ** + + 1. Move the cursor to the line below marked ✗. + + 2. To fix the errors, move the cursor until it is on top of the + character to be deleted. + + 3. Press [the x key](x) to delete the unwanted character. + + 4. Repeat steps 2 through 4 until the sentence is correct. + +The ccow jumpedd ovverr thhe mooon. + + 5. Now that the line is correct, go on to Lesson 1.4. + +NOTE: As you go through this tutorial, do not try to memorize everything, + your Neovim vocabulary will expand with usage. Consider returning to + this tutorial periodically for a refresher. + +# Lesson 1.4: TEXT EDITING: INSERTION + +** Press `i`{normal} to insert text. ** + + 1. Move the cursor to the first line below marked ✗. + + 2. To make the first line the same as the second, move the cursor on top + of the first character AFTER where the text is to be inserted. + + 3. Press `i`{normal} and type in the necessary additions. + + 4. As each error is fixed press ``{normal} to return to Normal mode. + Repeat steps 2 through 4 to correct the sentence. + +There is text misng this . +There is some text missing from this line. + + 5. When you are comfortable inserting text move to Lesson 1.5. + +# Lesson 1.5: TEXT EDITING: APPENDING + +** Press `A`{normal} to append text. ** + + 1. Move the cursor to the first line below marked ✗. + It does not matter on what character the cursor is in that line. + + 2. Press [A](A) and type in the necessary additions. + + 3. As the text has been appended press ``{normal} to return to Normal + mode. + + 4. Move the cursor to the second line marked ✗ and repeat + steps 2 and 3 to correct this sentence. + +There is some text missing from th +There is some text missing from this line. +There is also some text miss +There is also some text missing here. + + 5. When you are comfortable appending text move to Lesson 1.6. + +# Lesson 1.6: EDITING A FILE + +** Use `:wq`{vim} to write a file and quit. ** + +!! NOTE: Before executing any of the steps below, read the entire lesson !! + + 1. Exit this tutorial as you did in Lesson 1.2: `:q!`{vim} + Or, if you have access to another terminal, do the following there. + + 2. At the shell prompt type this command: +~~~ sh + $ nvim tutor +~~~ + 'nvim' is the command to start the Nvim editor, 'tutor' is the name of + the file you wish to edit. Use a file that may be changed. + + 3. Insert and delete text as you learned in the previous lessons. + + 4. Save the file with changes and exit Neovim with: +~~~ cmd + :wq +~~~ + Note you'll need to press `` to execute the command. + + 5. If you have quit this tutorial in step 1, restart and move down + to the following summary. + + 6. After reading and understanding the above steps: do them. + +# Lesson 1 SUMMARY + + 1. The cursor is moved using either the arrow keys or the hjkl keys. + h (left) j (down) k (up) l (right) + + 2. To start Neovim from the shell prompt type: +~~~ sh + $ nvim FILENAME +~~~ + 3. To exit Neovim type: ``{normal} `:q!`{vim} ``{normal} to trash all changes. + OR type: ``{normal} `:wq`{vim} ``{normal} to save the changes. + + 4. To delete the character at the cursor type: `x`{normal} + + 5. To insert or append text type: + `i`{normal} insert text ``{normal} insert before the cursor. + `A`{normal} append text ``{normal} append after the line. + +NOTE: Pressing ``{normal} will place you in Normal mode or will cancel + an unwanted and partially completed command. + +Now continue with Lesson 2. + +# Lesson 2.1: DELETION COMMANDS + +** Type `dw`{normal} to delete a word. ** + + 1. Press ``{normal} to make sure you are in Normal mode. + + 2. Move the cursor to the line below marked ✗. + + 3. Move the cursor to the beginning of a word that needs to be deleted. + + 4. Type [d](d)[w](w) to make the word disappear. + +There are a some words fun that don't belong paper in this sentence. + + 5. Repeat steps 3 and 4 until the sentence is correct and go to Lesson 2.2. + +# Lesson 2.2: MORE DELETION COMMANDS + +** Type `d$`{normal} to delete to the end of the line. ** + + 1. Press ``{normal} to make sure you are in Normal mode. + + 2. Move the cursor to the line below marked ✗. + + 3. Move the cursor to the end of the correct line (AFTER the first . ). + + 4. Type `d$`{normal} to delete to the end of the line. + +Somebody typed the end of this line twice. end of this line twice. + + 5. Move on to Lesson 2.3 to understand what is happening. + +# Lesson 2.3: ON OPERATORS AND MOTIONS + +Many commands that change text are made from an [operator](operator) and a [motion](navigation). +The format for a delete command with the [d](d) delete operator is as follows: + + d motion + + Where: + d - is the delete operator. + motion - is what the operator will operate on (listed below). + + A short list of motions: + [w](w) - until the start of the next word, EXCLUDING its first character. + [e](e) - to the end of the current word, INCLUDING the last character. + [$]($) - to the end of the line, INCLUDING the last character. + + Thus typing `de`{normal} will delete from the cursor to the end of the word. + +NOTE: Pressing just the motion while in Normal mode without an operator + will move the cursor as specified. + +# Lesson 2.4: USING A COUNT FOR A MOTION + +** Typing a number before a motion repeats it that many times. ** + + 1. Move the cursor to the start of the line marked ✓ below. + + 2. Type `2w`{normal} to move the cursor two words forward. + + 3. Type `3e`{normal} to move the cursor to the end of the third word forward. + + 4. Type `0`{normal} ([zero](0)) to move to the start of the line. + + 5. Repeat steps 2 and 3 with different numbers. + +This is just a line with words you can move around in. + + 6. Move on to Lesson 2.5. + +# Lesson 2.5: USING A COUNT TO DELETE MORE + +** Typing a number with an operator repeats it that many times. ** + +In the combination of the delete operator and a motion mentioned above you +insert a count before the motion to delete more: + d number motion + + 1. Move the cursor to the first UPPER CASE word in the line marked ✗. + + 2. Type `d2w`{normal} to delete the two UPPER CASE words + + 3. Repeat steps 1 and 2 with a different count to delete the consecutive + UPPER CASE words with one command + +This ABC DE line FGHI JK LMN OP of words is Q RS TUV cleaned up. + +# Lesson 2.6: OPERATING ON LINES + +** Type `dd`{normal} to delete a whole line. ** + +Due to the frequency of whole line deletion, the designers of Vi decided +it would be easier to simply type two d's to delete a line. + + 1. Move the cursor to the second line in the phrase below. + + 2. Type [dd](dd) to delete the line. + + 3. Now move to the fourth line. + + 4. Type `2dd`{normal} to delete two lines. + +1) Roses are red, +2) Mud is fun, +3) Violets are blue, +4) I have a car, +5) Clocks tell time, +6) Sugar is sweet +7) And so are you. + +# Lesson 2.7: THE UNDO COMMAND + +** Press `u`{normal} to undo the last commands, `U`{normal} to fix a whole line. ** + + 1. Move the cursor to the line below marked ✗ and place it on the first error. + + 2. Type `x`{normal} to delete the first unwanted character. + + 3. Now type `u`{normal} to undo the last command executed. + + 4. This time fix all the errors on the line using the `x`{normal} command. + + 5. Now type a capital `U`{normal} to return the line to its original state. + + 6. Now type `u`{normal} a few times to undo the `U`{normal} and preceding commands. + + 7. Now type ``{normal} (Control + R) a few times to redo the commands. + +Fiix the errors oon thhis line and reeplace them witth undo. + + 8. These are very useful commands. Now move on to the Lesson 2 Summary. + +# Lesson 2 SUMMARY + + 1. To delete from the cursor up to the next word type: `dw`{normal} + + 2. To delete from the cursor to the end of a line type: `d$`{normal} + + 3. To delete a whole line type: `dd`{normal} + + 4. To repeat a motion prepend it with a number: `2w`{normal} + + 5. The format for a change command is: + + operator [number] motion + + where: + + operator - is what to do, such as [d](d) for delete + [number] - is an optional count to repeat the motion + motion - moves over the text to operate on, such as: + [w](w) (word), + [$]($) (to the end of line), etc. + + 6. To move to the start of the line use a zero: [0](0) + + 7. To undo previous actions, type: `u`{normal} (lowercase u) + To undo all the changes on a line, type: `U`{normal} (capital U) + To undo the undos, type: ``{normal} + +# Lesson 3.1: THE PUT COMMAND + +** Type `p`{normal} to put previously deleted text after the cursor. ** + + 1. Move the cursor to the first `--->` line below. + + 2. Type `dd`{normal} to delete the line and store it in a Neovim register. + + 3. Move the cursor to the c) line, ABOVE where the deleted line should go. + + 4. Type `p`{normal} to put the line below the cursor. + + 5. Repeat steps 2 through 4 to put all the lines in correct order. + +---> d) Can you learn too? +---> b) Violets are blue, +---> c) Intelligence is learned, +---> a) Roses are red, + +NOTE: You can also put the text before the cursor with `P`{normal} (capital P). + +# Lesson 3.2: THE REPLACE COMMAND + +** Type `rx`{normal} to replace the character at the cursor with x. ** + + 1. Move the cursor to the first line below marked ✗. + + 2. Move the cursor so that it is on top of the first error. + + 3. Type `r`{normal} and then the character which should be there. + + 4. Repeat steps 2 and 3 until the first line is equal to the second one. + +Whan this lime was tuoed in, someone presswd some wrojg keys! +When this line was typed in, someone pressed some wrong keys! + + 5. Now move on to Lesson 3.3. + +NOTE: Remember that you should be learning by doing, not memorizing. + +# Lesson 3.3: THE CHANGE OPERATOR + +** To change until the end of a word, type `ce`{normal}. ** + + 1. Move the cursor to the first line below marked ✗. + + 2. Place the cursor on the "u" in "lubw". + + 3. Type `ce`{normal} and the correct word (in this case, type "ine" ). + + 4. Press ``{normal} and move to the next character that needs to be changed. + + 5. Repeat steps 3 and 4 until the first sentence is the same as the second. + +This lubw has a few wptfd that mrrf changing usf the change operator. +This line has a few words that need changing using the change operator. + +Notice that [c](c)e deletes the word and places you in Insert mode. + +# Lesson 3.4: MORE CHANGES USING `c`{normal} + +** The change operator is used with the same motions as delete. ** + + 1. The change operator works in the same way as delete. The format is: + + c [number] motion + + 2. The motions are the same, such as `w`{normal} (word) and `$`{normal} (end of line). + + 3. Move to the first line below marked ✗. + + 4. Move the cursor to the first error. + + 5. Type `c$`{normal} and type the rest of the line like the second and press ``{normal}. + +The end of this line needs some help to make it like the second. +The end of this line needs to be corrected using the c$ command. + +NOTE: You can use the Backspace key to correct mistakes while typing. + +# Lesson 3 SUMMARY + + 1. To put back text that has just been deleted, type [p](p). This puts the + deleted text AFTER the cursor (if a line was deleted it will go on the + line below the cursor). + + 2. To replace the character under the cursor, type [r](r) and then the + character you want to have there. + + 3. The [change operator](c) allows you to change from the cursor to where + the motion takes you. Type `ce`{normal} to change from the cursor to the + end of the word, `c$`{normal} to change to the end of a line, etc. + + 4. The format for change is: + + c [number] motion + +Now go on to the next lesson. + +# Lesson 4.1: CURSOR LOCATION AND FILE STATUS + +** Type ``{normal} to show your location in a file and the file status. + Type `{count}G`{normal} to move to line {count} in the file. ** + +NOTE: Read the entire lesson before executing any of these steps!! + + 1. Hold down the ``{normal} key and press `g`{normal}. We call this ``{normal}. + A message will appear at the bottom of the page with the filename and + the position in the file. Remember the line number for Step 3. + +NOTE: You may see the cursor position in the lower right corner of the + screen. This happens when the ['ruler']('ruler') option is set. + + 2. Press [G](G) to move you to the bottom of the file. + Type [gg](gg) to move you to the start of the file. + + 3. Type the number of the line you were on and then `G`{normal}. This will + return you to the line you were on when you first pressed ``{normal}. + + 4. If you feel confident to do this, execute steps 1 through 3. + +# Lesson 4.2: THE SEARCH COMMAND + +** Type `/`{normal} followed by a phrase to search for the phrase. ** + + 1. In Normal mode type the `/`{normal} character. Notice that it and the + cursor appear at the bottom of the screen as with the `:`{normal} command. + + 2. Now type 'errroor' ``{normal}. This is the word you want to search for. + + 3. To search for the same phrase again, simply type [n](n). + To search for the same phrase in the opposite direction, type [N](N). + + 4. To search for a phrase in the backward direction, use [?](?) instead of `/`{normal}. + + 5. To go back to where you came from press ``{normal}. + (keep ``{normal} pressed down while pressing the letter `o`{normal}). + Repeat to go back further. ``{normal} goes forward. + +"errroor" is not the way to spell error; errroor is an error. + +NOTE: When the search reaches the end of the file it will continue at the + start, unless the ['wrapscan']('wrapscan') option has been reset. + +# Lesson 4.3: MATCHING PARENTHESES SEARCH + +** Type `%`{normal} to find a matching ), ], or }. ** + + 1. Place the cursor on any (, [, or { in the line below marked ✓. + + 2. Now type the [%](%) character. + + 3. The cursor will move to the matching parenthesis or bracket. + + 4. Type `%`{normal} to move the cursor to the other matching bracket. + + 5. Move the cursor to another (, ), [, ], {, or } and see what `%`{normal} does. + +This ( is a test line with ('s, ['s, ] and {'s } in it. )) + +NOTE: This is very useful in debugging a program with unmatched parentheses! + +# Lesson 4.4: THE SUBSTITUTE COMMAND + +** Type `:s/old/new/g` to substitute "new" for "old". ** + + 1. Move the cursor to the line below marked ✗. + + 2. Type +~~~ cmd + :s/thee/the/ +~~~ + NOTE: The [:s](:s) command only changed the first match of "thee" in the line. + + 3. Now type +~~~ cmd + :s/thee/the/g +~~~ + Adding the g [flag](:s_flags) means to substitute globally in the line, + change all occurrences of "thee" in the line. + +Usually thee best time to see thee flowers is in thee spring. + + 4. To change every occurrence of a character string between two lines, type +~~~ cmd + :#,#s/old/new/g +~~~ + where # are the line numbers of the range of lines where the + substitution is to be done (i.e., `1,3` means from line 1 to line 3, inclusive). + + Type +~~~ cmd + :%s/old/new/g +~~~ + to change every occurrence in the whole file. + + Type +~~~ cmd + :%s/old/new/gc +~~~ + to find every occurrence in the whole file, with a prompt whether to + substitute or not. + +NOTE: You can also select the lines you want to substitute first using Visual mode. + This will be explained more in a future lesson. + +# Lesson 4 SUMMARY + + 1. ``{normal} displays your location and the file status. + `G`{normal} moves to the end of the file. + number `G`{normal} moves to that line number. + `gg`{normal} moves to the first line. + + 2. Typing `/`{normal} followed by a phrase searches FORWARD for the phrase. + Typing `?`{normal} followed by a phrase searches BACKWARD for the phrase. + After a search type `n`{normal} to find the next occurrence in the same + direction or `N`{normal} to search in the opposite direction. + ``{normal} takes you back to older positions, ``{normal} to + newer positions. + + 3. Typing `%`{normal} while the cursor is on a (, ), [, ], {, or } goes to its + match. + + 4. To substitute new for the first old in a line type +~~~ cmd + :s/old/new +~~~ + To substitute new for all olds on a line type +~~~ cmd + :s/old/new/g +~~~ + To substitute phrases between two line #'s type +~~~ cmd + :#,#s/old/new/g +~~~ + To substitute all occurrences in the file type +~~~ cmd + :%s/old/new/g +~~~ + To ask for confirmation each time add 'c' +~~~ cmd + :%s/old/new/gc +~~~ + +# Lesson 5.1: HOW TO EXECUTE AN EXTERNAL COMMAND + +** Type `:!`{vim} followed by an external command to execute that command. ** + + 1. Type the familiar command `:`{normal} to set the cursor at the bottom of + the screen. This allows you to enter a command-line command. + + 2. Now type the [!](!cmd) (exclamation point) character. This allows you to + execute any external shell command. + + 3. As an example type "ls" following the "!" and then hit ``{normal}. + This will show you a listing of your directory, just as if you were + at the shell prompt. + +NOTE: It is possible to execute any external command this way, and you + can include arguments. + +NOTE: All `:`{vim} commands are executed when you press ``{normal}. + +# Lesson 5.2: MORE ON WRITING FILES + +** To save the changes made to the text, type `:w`{vim} FILENAME. ** + + 1. Type `:!ls`{vim} to get a listing of your directory. + You already know you must hit ``{normal} after this. + + 2. Choose a filename that does not exist yet, such as TEST. + + 3. Now type: +~~~ cmd + :w TEST +~~~ + (where TEST is the filename you chose.) + + 4. This saves the current file under the name TEST. + To verify this, type `:!ls`{vim} again to see your directory. + +NOTE: If you were to exit Neovim and start it again with `nvim TEST`, the file + would be an exact copy of the tutorial when you saved it. + + 5. Now remove the file by typing: +~~~ cmd + :!rm TEST +~~~ +# Lesson 5.3: SELECTING TEXT TO WRITE + +** To save part of the file, type `v`{normal} motion `:w FILENAME`{vim}. ** + + 1. Move the cursor to this line. + + 2. Press [v](v) and move the cursor to the fifth item below. Notice that the + text is highlighted. + + 3. Press the `:`{normal} character. At the bottom of the screen + + `:'<,'>`{vim} + + will appear. + + 4. Type + + `w TEST`{vim} + + where TEST is a filename that does not exist yet. Verify that you see + + `:'<,'>w TEST`{vim} + + before you press ``{normal}. + + 5. Neovim will write the selected lines to the file TEST. Use `:!ls`{vim} to see it. + Do not remove it yet! We will use it in the next lesson. + +NOTE: Pressing [v](v) starts [Visual selection](visual-mode). You can move the cursor around to + make the selection bigger or smaller. Then you can use an operator to + do something with the text. For example, `d`{normal} deletes the text. + +# Lesson 5.4: RETRIEVING AND MERGING FILES + +** To retrieve the contents of a file, type `:r FILENAME`{vim}. ** + + 1. Place the cursor just above this line. + +NOTE: After executing Step 2 you will see text from Lesson 5.3. Then move + DOWN to see this lesson again. Press `u`{normal} to undo after you are done. + + 2. Now retrieve your TEST file using the command + + `:r TEST`{vim} + + where TEST is the name of the file you used. + The file you retrieve is placed below the cursor line. + + 3. To verify that a file was retrieved, cursor back and notice that there + are now two copies of Lesson 5.3, the original and the retrieved version. + +NOTE: You can also read the output of an external command. For example, + + `:r !ls`{vim} + + reads the output of the `ls` command and puts it below the cursor. + +# Lesson 5 SUMMARY + + 1. [:!command](:!cmd) executes an external command. + + Some useful examples are: + `:!ls `{vim} - shows a directory listing + `:!rm FILENAME`{vim} - removes file FILENAME + + 2. [:w](:w) FILENAME writes the current Neovim file to disk with + name FILENAME. + + 3. [v](v) motion :w FILENAME saves the Visually selected lines in file + FILENAME. + + 4. [:r](:r) FILENAME retrieves disk file FILENAME and puts it + below the cursor position. + + 5. [:r !ls](:r!) reads the output of the ls command and + puts it below the cursor position. + +# Lesson 6.1: THE OPEN COMMAND + +** Type `o`{normal} to open a line below the cursor and place you in Insert mode. ** + + 1. Move the cursor to the line below marked ✓. + + 2. Type the lowercase letter `o`{normal} to [open](o) up a line BELOW the + cursor and place you in Insert mode. + + 3. Now type some text and press ``{normal} to exit Insert mode. Remove your opened lines after you're done. + +After typing `o`{normal} the cursor is placed on the open line in Insert mode. + + 4. To open up a line ABOVE the cursor, simply type a [capital O](O), rather + than a lowercase `o`{normal}. Try this on the line below. Remove your opened lines after you're done. + +Open up a line above this by typing O while the cursor is on this line. + +# Lesson 6.2: THE APPEND COMMAND + +** Type `a`{normal} to insert text AFTER the cursor. ** + + 1. Move the cursor to the start of the line below marked ✗. + + 2. Press `e`{normal} until the cursor is on the end of "li". + + 3. Type the lowercase letter `a`{normal} to [append](a) text AFTER the cursor. + + 4. Complete the word like the line below it. Press ``{normal} to exit Insert mode. + + 5. Use `e`{normal} to move to the next incomplete word and repeat steps 3 and 4. + +This li will allow you to pract appendi text to a line. +This line will allow you to practice appending text to a line. + +NOTE: [a](a), [i](i), and [A](A) all go to the same Insert mode, the only + difference is where the characters are inserted. + +# Lesson 6.3: ANOTHER WAY TO REPLACE + +** Type a capital `R`{normal} to replace more than one character. ** + + 1. Move the cursor to the first line below marked ✗. Move the cursor to + the beginning of the first "xxx". + + 2. Now press `R`{normal} ([capital R](R)) and type the number below it in the + second line, so that it replaces the "xxx". + + 3. Press ``{normal} to leave [Replace mode](mode-replace). Notice that + the rest of the line remains unmodified. + + 4. Repeat the steps to replace the remaining "xxx". + +Adding 123 to xxx gives you xxx. +Adding 123 to 456 gives you 579. + +NOTE: Replace mode is like Insert mode, but every typed character + replaces an existing character. + +# Lesson 6.4: COPY AND PASTE TEXT + +** Use the `y`{normal} operator to copy text and `p`{normal} to put it. ** + + 1. Go to the line marked with ✓ below and place the cursor after "a)". + + 2. Start Visual mode with `v`{normal} and move the cursor to just before + "first". + + 3. Type `y`{normal} to [yank](yank) (copy) the highlighted text. + + 4. Move the cursor to the end of the next line: `j$`{normal} + + 5. Type `p`{normal} to [put](put) (paste) the text. + + 6. Press `a`{normal} and then type "second". Press ``{normal} to leave + Insert mode. + + 7. Use Visual mode to select "item.", yank it with `y`{normal}, move to the + end of the next line with `j$`{normal} and put the text there with `p`{normal} + +a) This is the first item. +b) + +NOTE: You can use `y`{normal} as an operator: `yw`{normal} yanks one word. + +NOTE: You can use `P`{normal} to put before the cursor, rather than after. + +# Lesson 6.5: SET OPTION + +** Set an option so search and substitute commands ignore case. ** + +There are many settings in Neovim that you can configure to suit your needs. + + 1. Search for 'ignore' by entering: `/ignore` + Repeat several times by pressing `n`{normal}. + + 2. Set the 'ic' (Ignore case) option by entering: +~~~ cmd + :set ic +~~~ + 3. Now search for 'ignore' again by pressing `n`{normal}. + Notice that Ignore and IGNORE are now also found. + + 4. Set the 'hlsearch' and 'incsearch' options: +~~~ cmd + :set hls is +~~~ + 5. Now type the search command again and see what happens: /ignore + + 6. To disable ignoring case enter: +~~~ cmd + :set noic +~~~ + 7. To invert the value of a setting, prepend it with "inv": +~~~ cmd + :set invic +~~~ +NOTE: To remove the highlighting of matches enter: +~~~ cmd + :nohlsearch +~~~ +NOTE: If you want to ignore case for just one search command, use [\c](/\c) + in the phrase: /ignore\c + +# Lesson 6 SUMMARY + + 1. Type `o`{normal} to open a line BELOW the cursor and start Insert mode. + Type `O`{normal} to open a line ABOVE the cursor. + + 2. Type `a`{normal} to insert text AFTER the cursor. + Type `A`{normal} to insert text after the end of the line. + + 3. The `e`{normal} command moves to the end of a word. + + 4. The `y`{normal} operator copies text, `p`{normal} pastes it. + + 5. Typing a capital `R`{normal} enters Replace mode until ``{normal} is + pressed. + + 6. Typing "[:set](:set) xxx" sets the option "xxx". Some options are: + + 'ic' 'ignorecase' ignore upper/lower case when searching + 'is' 'incsearch' show partial matches for a search phrase + 'hls' 'hlsearch' highlight all matching phrases + + You can either use the long or the short option name. + + 7. Prepend "no" to switch an option off: +~~~ cmd + :set noic +~~~ + 8. Prepend "inv" to invert an option: +~~~ cmd + :set invic +~~~ +# Lesson 7.1: GETTING HELP + +** Use the online help system. ** + +Neovim has a comprehensive online help system. + +To get started, try one of these two: + + - press the ``{normal} key (if you have one) + - type `:help`{vim} + +Read the text in the help window to find out how the help works. +Type ``{normal} to jump from one window to another. +Type `:q`{vim} to close the help window. + +You can find help on just about any subject, by giving an argument to the +":help" command. Try these (don't forget to press ): +~~~ cmd + :help w + :help c_CTRL-D + :help insert-index + :help user-manual +~~~ +# Lesson 7.2: COMPLETION + +** Command line completion with ``{normal} and ``{normal}. ** + + 1. List the contents of the current directory: `:!ls`{vim} + + 2. Type the start of a command: `:e`{vim} + + 3. Press ``{normal} and Neovim will show a list of commands beginning with "e". + + 4. Press ``{normal} and Neovim will show a menu with possible completions + (or complete the match, if the entered command is unique, e.g. + ":ed``{normal}" will be completed to ":edit"). + + 5. Use ``{normal} or ``{normal} to go to the next match. Or use + ``{normal} or ``{normal} to go to the previous match. + + 6. Choose the entry `edit`{vim}. Now you can see that the word `edit`{vim} + have been automatically inserted to the command line. + + 7. Now add a space and the start of an existing file name: `:edit FIL`{vim} + + 8. Press ``{normal}. Vim will show a completion menu with list of file + names that start with `FIL` + +NOTE: Completion works for many commands. It is especially useful for `:help`{vim}. + +# Lesson 7.3: CONFIGURING NVIM + +Neovim is a very configurable editor. You can customise it any way you like. To +start using more features, create a vimrc file, which can be "init.lua" if you +want to use Lua, or "init.vim" if you want to use Vimscript. We'll use +"init.lua" in this lesson. + + 1. Start editing the "init.lua" file. + + `:exe 'edit' stdpath('config')..'/init.lua'`{vim} + + 2. Copy the example configuration in Lua to your "init.lua" file. + + `:read $VIMRUNTIME/example_init.lua`{vim} + + 3. Write the file (also creates any missing parent directories): + + `:w ++p`{vim} + + 4. Next time you start Neovim, you can quickly open this vimrc file with: + + `:e $MYVIMRC`{vim} + +# Lesson 7 SUMMARY + + 1. Type `:help`{vim} + or press ``{normal} or ``{normal} to open a help window. + + 2. Type `:help TOPIC`{vim} to find help on TOPIC. + + 3. Type ``{normal} to jump to another window + + 4. Type `:q`{vim} to close the help window + + 5. While in command mode, press ``{normal} to see possible completions. + Press ``{normal} to use the completion menu and select a match. + + 6. Create your configuration file to save your preferred settings. You can + revisit it with `:e $MYVIMRC`{vim}. + +# What's next? + +Run `:help nvim-quickstart`{vim} for more information on extending Nvim. + +# CONCLUSION + +This concludes Chapter 1 of the Vim Tutor. Consider continuing with +[Chapter 2](@tutor:vim-02-beginner). + +This was intended to give a brief overview of the Neovim editor, just enough to +allow you to use it fairly easily. It is far from complete as Neovim has +many many more commands. Consult the help often. +There are also countless great tutorials and videos to be found online. +Here's a bunch of them: + +- *Learn Vim Progressively*: + https://yannesposito.com/Scratch/en/blog/Learn-Vim-Progressively/ +- *Learning Vim in 2014*: + https://benmccormick.org/learning-vim-in-2014/ +- *Vimcasts*: + http://vimcasts.org/ +- *Vim Video-Tutorials by Derek Wyatt*: + http://derekwyatt.org/vim/tutorials/ +- *Learn Vimscript the Hard Way*: + https://learnvimscriptthehardway.stevelosh.com/ +- *7 Habits of Effective Text Editing*: + https://www.moolenaar.net/habits.html +- *vim-galore*: + https://github.com/mhinz/vim-galore + +If you prefer a book, *Practical Vim* by Drew Neil is recommended often +(the sequel, *Modern Vim*, includes material specific to Neovim). + +This tutorial was written by Michael C. Pierce and Robert K. Ware, Colorado +School of Mines using ideas supplied by Charles Smith, Colorado State +University. E-mail: bware@mines.colorado.edu. + +Modified for Vim by Bram Moolenaar. +Modified for vim-tutor-mode by Felipe Morales. +Modified for Neovim by Rory Nesbitt. + +// vim: nowrap