#+title: 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.

Example:

#+BEGIN_SRC emacs-lisp
  (setq meow--kbd-forward-char "<right>")

  ;; or bind it to the function directly
  (setq meow--kbd-forward-char #'forward-char)
#+END_SRC

* Keybindings Cheat Sheet

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

[[https://github.com/meow-edit/meow/blob/master/KEYBINDING_QWERTY.org][QWERTY]] - [[https://github.com/meow-edit/meow/blob/master/KEYBINDING_DVORAK.org][DVORAK]] - [[https://github.com/meow-edit/meow/blob/master/KEYBINDING_DVP.org][PROGRAMMER DVORAK]] - [[https://github.com/meow-edit/meow/blob/master/KEYBINDING_COLEMAK.org][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.

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

** 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~.

[[file:COMMANDS.org][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 then the original command on k/j is not accessible. To access the original command on k/j, use ~SPC k/j~.

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

#+begin_src emacs-lisp
  (meow-motion-define-key '("j" . next-line))
#+end_src

The settings we made 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):

| Input         | Translation          | Explanation                                      |
|---------------+----------------------+--------------------------------------------------|
| ~SPC a~       | ~a~ in leader keymap | leader map default is ~mode-specific-map~, ~C-c~ |
| ~SPC c t t~   | ~C-c C-t C-t~        | start with ~c~ as ~C-c~                          |
| ~SPC x m t~   | ~C-x M-t~            | ~m~ as meta prefix                               |
| ~SPC g x~     | ~C-M-x~              | ~g~ as control + meta prefix                     |
| ~SPC x SPC p~ | ~C-x p~              | ~SPC~ 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~.

#+begin_src emacs-lisp
  ;; 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
#+end_src

*** 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

#+begin_quote
BEACON - Batch KMacro
#+end_quote

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.
