#+BEGIN_EXAMPLE ________ ___ _____ __ | '_ ` _ \ / _ \/ _ \ \ /\ / / | | | | | | __/ (_) \ V V / |_| |▁| |▁|\___|\___/ \_/\_/ Modal Editing Of Wonder #+END_EXAMPLE ** INTRODUCTION ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ Welcome to Meow! Meow is a modal-editing package for Emacs, inspired by Kakoune. This is tutorial aims to help both new and experienced Emacs users get started with or migrate to Meow as easily as possible. This tutorial assumes you are using the QWERTY keybindings configuration included in Meow's GitHub repo, but any customized configs based on it should work as well. Just pay attention to the actual commands prefixed with ~meow-~, and replace the suggested keys with your own keybindings. Similarly, if you are using non-QWERTY keyboard layouts, there is no need to change back to QWERTY layout. Instead, simply press the keys that are bound with Meow's corresponding commands. Keep in mind that Meow comes with sane defaults and nothing more. You are free to modify any default key bindings to meet your own expectations. In the Basics section, you will learn about the basics of movement and editing. This will give you a feel for Meow. *TODO* need to add more details about each section. In the second section, you will learn more advanced functionalities such as 'expand' and 'inner-of-thing', which will enable you to move faster and select smarter. #+BEGIN_QUOTE If the cat comes up and it sits in my lap, I want to hear the sound of the cat purring, not the fans of the computer. -- Linus Torvalds #+END_QUOTE ** BASICS ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ 🐾 MODES In "modal editing", users interact with the text through .---, modes. There are *five* modes in Meow and the most used two │ i │ are *NORMAL* and *INSERT*. If you set up Meow properly, at `---' the bottom left you should see NORMAL, indicating you are ~meow-insert~ now in normal mode. Make sure Caps Lock is OFF and press ~i~. The indicator turns to INSERT and you are able to type .---, in characters as usual. This is insert mode. Press ~ESC~ or │ESC│ ~C-[~ to leave it and return to normal mode. The other `---' three modes are *MOTION*, *KEYPAD*, and *BEACON*. These modes will be explained in the third part. 🐾 MOVEMENT The movement in a buffer (representations of the content .---, of a file opened in Emacs) can be done using the arrow keys. │ ↑ │ When pressed, the cursor will move one column/row in the .---'---'---, corresponding direction. Hold any of ~←~, ~↑~, ~→~, ~↓~ to │ ← │ ↓ │ → │ continue the movement until where you want to stop. `---'---'---` However, furthering the tradition of mode-based editors, .---,---,---,---, the ~h~, ~j~, ~k~, ~l~ keys are often used for the same │ h │ j │ k │ l │ purpose, and will respectively move the cursor to the `---'---'---'---` left, down, up, right by one, when hit. Using those keys ↕ ↕ ↕ ↕ is the recommended way of moving around in a buffer. .---,---,---,---, If you're not familiar with this concept, the proximity │ ← │ ↓ │ ↑ │ → │ of those four keys with the rest of the lettered keys `---'---'---'---` on a ~qwerty~ layout allows faster interaction with the cursor position than if the user had to move their hand to reach the arrow keys. 🐾 SELECTION -- SINGLE WORD .---, But moving like this is still tedious. Meow offers more │ e │ when it comes to moving the cursor. Move the cursor to the `---' beginning of any word and press ~e~, you will see this word ~meow-next-word~ has been selected and the cursor moves to its end. Press ~e~ again to move to the next word and select it. .---, You probably have noticed this type of selection ignores │ E │ hyphenated words such as "real-world" and variable names in `---' snake case like "my_phone". To deal with these cases, Meow ~meow-next-symbol~ offers another augmented movement command: ~E~ (hold ~Shift~ and press ~e~). .---, .---, To move backward word-wise or symbol-wise, press key ~b~ or │ b │ │ B │ ~B~ respectively. `---' `---' ~meow-back-word/symbol~ .---, To cancel the current selection, there are several ways in │ g │ Meow. The easiest one is to just move the cursor using any `---' of the basic movement keys like left and right. But since the cursor also gets moved, this method may not always achieve the desired effect. Meow provides a much nicer command at your disposal: ~g~ (~meow-cancel-selection~). 🐾 SELECTION -- A CLOSER LOOK While you move using the above-mentioned commands, you also select. Let's take a closer look at them. It's therefore important to know this key idea behind Meow: *Movement means selection*. One advantage of this behavior is that users immediately get two useful positions each time they move (and select): the start and end of a selection. ▒▒▒ - context In the following illustrations, symbol ▒ denotes the text ▋ - cursor around the target /word/. ⇡ and ⇣ indicate where the cursor word - target word was before the movement, while ▋shows the cursor position ␣ - blank space (and shape) after the movement/selection. ⇡ ⇣ - position If you press ~e~ when the cursor is right at the start of an ▒▒▒cats▋▒▒▒ arbitrary word, you will select just the word (no hyphen). ⇡ The cursor moves to its end and stops there. at word start Press ~e~ again, and now you see something different. This ▒▒▒␣meow▋▒▒▒ time, the word /meow/ plus a blank space gets selected. Press ~e~ a few more times, and you will find Meow keeps moving and selecting in this way. 🐾 SELECTION -- A CLOSER LOOK .---, The two useful positions, the start and end of the current │ i │ selection, makes it easy to /insert/ or /append/ text before `---' or after the selected. This also works for other kinds of ~meow-insert~ selected range (chunk of words or lines) in the following sections. .---, With a /word/ selected, press ~i~, and you will enter insert │ a │ mode. Now if you start typing, the characters will be placed `---' before the beginning of your selection. In contrast, hitting ~meow-append~ ~a~ will also place you in insert mode, but this time you append text to the end. You might think this is just like Vim. Not exactly. In Vim, movement commands don't select any thing by default. It also requires more keys to insert or append to a selected range in the visual mode. When there is no text selected, ~a~ and ~i~ will behave the same. This is reasonable because Meow tries to insert or append to a zero-width region. If you really want the Vim-like ~a~ and ~i~, add to your init.el: #+BEGIN_SRC emacs-lisp ;; vim-like inserting and appending (setq meow-use-cursor-position-hack t) #+END_SRC #+BEGIN_QUOTE A cat takes more interest in your code than your spouse or your boss. -- Michael DiSibio #+END_QUOTE ** SELECTING I ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ 🐾 SELECTION -- WORD CLUSTER Suppose you want to select a chunk of words instead of a .---, .---, single one, you can extend the word-level selection with │ e │+│0-9│ ~meow-expand-N~, where ~N~ is a digit of 0-9. You may have `---' `---' already noticed in the previous section that when you hit ~meow-expand-[0-9]~ ~e~ or ~b~ to move and select, there are digits (0-9) blinking at the end of the words ahead of the current selection (or behind, if you select backward). Take the below sentence as an example: ▒▒▒▒With Meow comes the power of modal editing.▒▒▒▒ └─────── to select ──────┘ To select the last five words, first move the cursor to "t" of "the" and then type ~e~. You will see some digits show up and soon disappear: ▒▒▒▒With Meow comes the powe1 o2 moda3 editin4.▒▒▒▒ ↱└─┘ ⇡ ⇡ ⇡ ⇡ selected ↣↣↣ select forward ↣↣↣ All but the selected words have their last letter replaced with a digit. If you feel the digit hints disappear too quickly, you may want to add the following line to your init.el: #+BEGIN_SRC emacs-lisp ;; show expand hints for a longer time (set meow-expand-hint-remove-delay 1.5) #+END_SRC 🐾 SELECTION -- LINE Wanna select more? Great! Let's select lines this time. In .---, normal mode, type ~x~. The current line will be selected. │ x │ Press ~x~ again, you will select yet another line! You can `---' keep doing this until you include all the lines you want. ~meow-line~ Using Emacs keybindings ~ctrl-p/n~ will expand your current selection backward or forward accordingly. It's worth mentioning that ~meow-expand-x~ will automatically function at line level when you select lines. Suppose you have the first line selected in the text below: ┌─────────────── selected ──────────────┐ The Naming of Cats is a difficult matter, 1t isn’t just one of your holiday games; 2ou may think at first I’m as mad as a hatter 3hen I tell you, a cat must have THREE DIFFERENT NAMES. .---, Hit 3 and the selection will expand to the beginning of the │ ; │ 3rd line, *without* selecting it. What's more, Meow is `---' flexible enough to do this in a reversed manner. Type ~;~ to ~meow-reverse~ try it out yourself. #+BEGIN_QUOTE Managing senior programmers is like herding cats. -- Dave Platt #+END_QUOTE ** EDITING ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ 🐾 REPLACING / DELETING Now that you can move around and select stuff, it's time to make changes to buffer content. There are five frequently used keys for changing text in normal mode: ~c~, ~d~, ~p~, ~s~, ~u~. .---, To change a word, select the word first (~e~) and then press │ c │ the key ~c~. You will find you are in insert mode. Of course, `---' you can expand the selection and then change all of them. ~meow-change~ Similarly, to change a whole line, select it with ~x~ and then change (~c~) it. Again, you can expand the selection to include multiple lines and replace them with new text. .---, To delete a single character, press the key ~d~. Note this │ d │ command by default deletes forward, meaning it will delete `---' the white space right in front of a selection. If there is ~meow-delete~ nothing selected, it removes the character under the current cursor. The key ~D~, when pressed, will delete backward (~meow-backward-delete~). .---, If you want to delete the selected object (word, phrase or │ s │ line), press ~s~. Note, if there is no selection at all, `---' pressing the key ~s~ will act as if you pressed ~C-k~ (kill ~meow-kill~ rest of current line or one or more lines). 🐾 COPYING / PASTING .---, However, there are times when you want to just copy the │ y │ selected text. In that case, press the key ~y~ after you `---' select some text. Note, this *must* be used with selection. ~meow-save~ .---, In Emacs, to kill means to cut, meaning you can yank (or │ p │ paste) the killed text. To do so, press the key ~p~. If you `---' killed an entire line, then ~p~ will yank it right above the ~meow-yank~ current line. .---, If you later changed your mind and would like to undo the │ u │ changes, press ~u~ a few times. *TODO*: explain ~U~? `---' next: open-above and open-below ~meow-undo~ It's also very often that you want to insert a new line .---, above or below the current line. In normal mode, press │ I │ ~I~ (or ~Shift~ + ~i~) to insert one line above. To insert `---' one line below, press ~A~ (or ~Shift~ + ~a~). There is no ~meow-open-above~ need to select the current line before inserting, but you can if you want to and then insert anyway. It's worth .---, mentioning that inserting always uses the cursor line as its │ A │ base. This is indeed quite intuitive. Suppose you have `---' selected three lines forward so the cursor line is the last ~meow-open-below~ one. Now if you insert either above or below, the new line will be put above or under the last line of your selection. #+BEGIN_QUOTE I are programmer. I make computer beep, boop, beep, beep, boop. /\_/\ ( o.o ) > - < #+END_QUOTE ** SELECTING II ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ 🐾 SELECTING INSIDE In programming, it's often the case that a string or a block .---, of code need to be selected. Meow provides a set of rich and │ , │_. consistent commands to make the movement and selection even `---' │`.---, more flexible. │ │ g │ │ `---' Example: to select a string within double quotes, move the │`.---, cursor anywhere inside the quotation marks and then press │ │ r │ the key ~,~. You will see a buffer pops up showing you the │ `---' a series of keys and their corresponding selecting ranges. │`.---, In this case, hit ~g~ to select the string. Note that the │ │ c │ double quotes are not included. This is expected because of │ `---' the name: *inner-of-thing*. You are encouraged to try out `.---, other inner-of-thing commands that are not listed here. Some │ l │ of them, however, may make more sense when you are coding in `---' Lisp languages such as Emacs Lisp. 🐾 SELECTING BOUNDS It would be limited or even useless if Meow could select .---, only within the boundary of objects. Fortunately, that's not │ . │_. true. In the above example, if you want to also include the `---' │`.---, quotes on both ends, press ~.~ and then ~g~. The name for │ │ g │ selection of this type is also straightforward: │ `---' *bounds-of-thing*. Commonly used boundary markers are round │`.---, brackets or parentheses ~()~, brackets ~[]~, curly braces │ │ r │ ~{}~ and single quotation marks ~'~. Note, in Lisp dialects, │ `---' a single quote is an important primitive and is used alone, │`.---, that is, not surrounding text in pairs. So there is no │ │ c │ single-quoted string at all in these languages. In others, │ `---' such as Python or JavaScript, you can expect selecting a `.---, single-quoted string is exactly the same as targeting │ l │ double-quoted ones. Now you have seen three different ways `---' of selecting a single line, why not compare them to see the difference? You will be surprised by Meow's power! 🐾 SELECTING TO START/END Similarly, there is another pair of commands that allow you .---, .---, to start selecting from the current point to the beginning │ [ │ │ ] │ or end of an object (e.g string, line, paragraph). This is `---' `---' useful, say, when you want to a delete a string from the middle till its end. 🐾 SELECTING BLOCKS .---, Although *bounds-of-thing* makes it a matter of two-key hit │ o │ to select the bracketed content. There is yet one more `---' choice in Meow: ~o~. This time, just a single key! Move the ~meow-block~ cursor inside any pair of brackets and press the key ~o~. It acts as if you pressed ~.~ + ~r~ or the similar for other types of brackets. Keep pressing ~o~, and you will see it .---, automatically expands the range to the outer blocks. │ O │ `---' From time to time, you may find it's convenient or even ~meow-to-block~ necessary to rely on a block to bring your selection to a stop, that is, a block happens to be at the end of what you want to kill. Press ~O~ to mark the range for killing. #+BEGIN_QUOTE All software engineers want to be treated like your typical house cat. That mostly translates to, "Leave me alone! But wait, give me belly rubs too." -- Jonah Jolley #+END_QUOTE ** KEYPAD ฅ^•ﻌ•^ฅ ---------------------------------------------------------------- ฅ^•ﻌ•^ฅ *** 🐾 KEYPAD MODE With all the commands and keys described above, it could .---, happen that you still heavily rely on the modifier keys such │SPC│_. ~C-~ and ~M-~ in your daily routines within Emacs. You might `---' │`.---, be a long-time user of evil-mode or god-mode and just can't │ │ x │ live without your sweet leader keys. Inspired by god-mode, │ `---' Meow implements its own keypad mode. In this mode, any │`.---, single key pressed will be treated as if it is prefixed with │ │ c │ a modifier key. │ `---' │`.---, For example, you have a command whose keybinding is as crazy │ │ h │ as ~C-x C-x C-y C-y~. In Meow you just need ~SPC x x y y~. │ `---' It's 3 keys fewer and saves you from hurting your little │`.---, finger. Let's take a closer look at this key sequence. The │ │ m │ first 2, ~SPC x~ will invoke keypad mode and make Emacs │ `---' think you just hit ~C-x~. Then all the single keys, ~x y y~, `.---, will act as if they are prefixed with ~C-~, that is, they │ g │ are translated into ~C-x C-y C-y~. `---' The table below shows a map between keypad mode and the keys that invoked it: | Invoke Keypad Mode by | equal to | | ~SPC-x~ | ~C-x~ | | ~SPC-c~ | ~C-c~ | | ~SPC-h~ | ~C-h~ | | ~SPC-m~ | ~M-~ | | ~SPC-g~ | ~C-M-~ | ** BEACON