Skip to content

Latest commit

 

History

History
181 lines (124 loc) · 8.07 KB

TUTORIAL.org

File metadata and controls

181 lines (124 loc) · 8.07 KB
Raw

TUTORIAL

Read before start

Meow will find underlying commands based on keybindings. You may find abnormal behaviour if you changed some default keybindings. For example: forward-char on C-f is used by meow-right. If you changed this keybinding, you have to change variable meow--kbd-forward-char to the correct value.

Keybindings Cheat Sheet

We have created some recommended configs for specific keyboard layouts that you can re-use for a quick setup.

QWERTY - DVORAK - PROGRAMMER DVORAK - COLEMAK

You can very easily change any of these when you setup Meow.

Tutor inside Emacs

There is a tutor inside Emacs after installing Meow. Open it with M-x meow-tutor.

States

Meow’s modal editing has 5 states: NORMAL, INSERT, MOTION, KEYPAD and BEACON. In this tutorial, we will walk through these states and basic operations.

╔═══════════╗    ╔════════════╗
║  MOTION   ║    ║   KEYPAD   ║
╚═══════════╝    ╚═══════╤════╝
      ▲              ▲   │
      │         <SPC>│   │after one command
   special           │   ▼
   ┏━━┷━━┓       ╔═══╧════════╗
   ┃START┠─text─▶║   NORMAL   ╟───────────╮
   ┗━━━━━┛       ╚═══════╤════╝  enter secondary selection
                     ▲   │                │
                <ESC>│   │i/a/c           │
                     │   ▼                ▼
                 ╔═══╧════════╗i/a/c╔════════════╗
                 ║   INSERT   ║◀────╢   BEACON   ║
                 ╚════════════╝     ╚════════════╝

INSERT

You can switch to INSERT state with meow-insert/append/change/open-below/open-above.

There’s nothing special in INSERT state, except ESC is bound to meow-insert-exit. Use it to go back to NORMAL state.

NOTE:

If you enter INSERT state by meow-change, the inserted content will be selected when you exit.

NORMAL

NORMAL state is the default state for text editing.

For commands in NORMAL state is defined via meow-normal-define-key.

Check here for command documents

MOTION

MOTION state is the default state for special modes, like dired, proced, etc.

By default, MOTION state has no keybindings, except SPC is used as the leader key. The original command on SPC can be access via SPC SPC.

Users may want a consistent keybindings for movement globally, for example: k/j to move up/down. Usually, you can bind k/j in MOTION state, however the original command on k/j is not accessible. To solve the problem, Meow introduce a simple solution.

For any keybinding you defined with meow-motion-overwrite-define-key, the overwritten command will be bound to the key with hyper modifier.

Here’s an example: you want use j as next-line globally.

(meow-motion-overwrite-define-key '("j" . next-line))
(meow-leader-define-key '("j" . "H-j"))

Now j will act as next-line, the original command on j (e.g. dired-goto-file in dired) will be bound to H-j. Since we use j in the leader for H-j, now we can call it via SPC j.

It is also possible to route the original command(e.g. j) to original motion key(e.g. n).

(meow-motion-overwrite-define-key '("j" . next-line))
(meow-motion-overwrite-define-key '("n" . "H-j"))

Now you have swapped j and n.

The settings we made has nothing to do with the name of a command. Thus, it works in all special modes.

KEYPAD

KEYPAD is the state used for executing commands without modifier keys.

Entering KEYPAD state by pressing SPC in NORMAL or MOTION state.

In KEYPAD state, single keys will be translated, and the first key will decide how it starts:

  • Start with x / h / c / m / g will begin with C-x / C-h / C-c / M- / C-M- respectively.
  • Any other key will start with itself, and temporarily activate the leader keymap.

The following keys will act according to following rules:

  • m will be translated to M-.
  • g will be translated to C-M-.
  • Any key following a prefix like m or g is interpreted as C-<key>.
  • SPC stands for literal prefix, means that the key will not be modified with C-.
  • If the translation results in an undefined binding, the last key will fallback to an unmodified version. (e.g. If C-c C-a is undefined, fallback to C-c a)

Some examples(assuming in NORMAL state):

InputTranslationExplanation
SPC aa in leader keymapleader map default is mode-specific-map, C-c
SPC c t tC-c C-t C-tstart with c as C-c
SPC x m tC-x M-tm as meta prefix
SPC g xC-M-xg as control + meta prefix
SPC x SPC pC-x pSPC as literal prefix

The leader keymap

By default, the mode-specific-map will be used as the leader keymap. In practice, this means that your leader keybinds get stored under C-c and can be accessed as such. Therefore, for instance, C-c x and SPC x are identical.

This can be changed by setting meow-keypad-leader-dispatch.

;; Some examples
(setq meow-keypad-leader-dispatch "C-x") ; Dispatch to the keymap at C-x
(setq meow-keypad-leader-dispatch ctl-x-map) ; Dispatch to the ctl-x-map

Tips

After command execution, no matter succeed or failed, KEYPAD state will be disabled, the previous state will be activated.

To revoke input, use BACKSPACE, to cancel all input and exit KEYPAD, use ESC or C-g.

If which-key-mode is enabled, it will be used to display the key binding help, otherwise a builtin implementation will be used.

BEACON

BEACON - Batch KMacro

BEACON is the state used for applying kmacro to multiple places quickly. It’s kinda like multiple-cursors, but it works differently.

BEACON state will be enabled automatically when cursor moves into the secondary selection. BEACON state will be disabled automatically when cursor moves out or secondary selection is disabled.

Once BEACON state is enabled, you can create fake cursors/regions with movement commands.

  • meow-left/right will create cursors in current column.
  • meow-next/back-word/symbol will create cursors at words’/symbols’ beginning or end.
  • meow-mark-word/symbol will create regions for every same words/symbols.
  • meow-visit/search will create regions for every same regexp.
  • meow-find/till will create cursors for every same characters.
  • meow-line will create regions for every N lines. (N is the number of selected lines).
  • meow-join will create cursors for each indentation beginning.

Once you have fake cursors/regions, you have two options:

  • quickly & simple Switch to INSERT state and start recording kmacro with meow-insert/append/change, finish recording and apply this kmacro to all cursors/regions when exit INSERT state.
  • generally Start recording with F3 (kmacro-start-macro-or-insert-counter or kmacro-start-macro), finish recording and apply this kmacro to all cursors/regions with F4 (kmacro-end-or-call-macro or kmacro-end-macro).

NOTE:

  • Your recorded kmacro can be used later.
  • Your can use your recorded kmacro with F4 directly.
  • Once you start recording kmacro with F3, you will be in NORMAL state.