.. rst3: filename: html/vimBindings.html

###################
Using Vim with Leo
###################

This chapter discusses these topics:

- How to enable and use Leo's new vim-emulation mode.
- How to import and export vim's .otl files.
- How to install and use stand-alone vim-like bindings.

.. contents:: Contents
    :depth: 3
    :local:

Using Leo's native vim mode
+++++++++++++++++++++++++++

In general, vim-mode in Leo works much as in the real vim. There are three modes, insert, normal and visual.

Supported commands
******************

- Cursor motions: ^,$,0,b,e,f,F,gg,gG,j,h,k,l,t,T,w.
- The gb,ge,gh commands are synonyms for 0,$,^.
- The h,j,k,l commands work on outlines when entered in the outline pane.
- 0 in outline pane: goto-first-visible-node
- e in outline pane: goto-last-visible-node.
- Deleting text: d{motion},{motion}d,v{motion}d,diw,x.
- Insert commands: a,A,i,o,O and switch to insert mode if entered in the outline pane.
- Yank & paste commands: y,p. These act on outlines if entered in the outline pane.
- Search commands: /,?,n,*,#.  These commands are node-only searches.
- The dot command '.' works for motions, but not yet for inserts or searches.
- v: start/end visual mode.

Notes:

- Except as noted above, all vim-mode commands must be entered in the body pane.
- <Return> in headlines switches to the outline pane.
- <Return> in the outline pane switches to the body pane.

Differences from the real vim
*****************************

- The gb,ge,gh commands are synonyms for 0,$,^.
- The h,j,k,l commands work on outlines when entered in the outline pane.
- The a,A,i,o,O commands switch to insert mode if entered in the outline pane.
- The y,p commands act on outlines if entered in the outline pane.
- Ending visual mode with 'v' retains the selection range.
- Ctrl-H puts the headline in insert mode.
- Mouse clicks never change vim's state.

Abbreviations
*************

- The ``jj`` abbreviation switches to normal mode, preserving the changed
  status of the .leo file.
- Return in visual/normal mode enters insert mode.

..  - ``,,`` in normal mode now moves to insert mode.
..  ``,,`` in insert mode does nothing, unless there is an abbreviation template available.

Colon commands
**************

The ':' command enters Leo's minibuffer, with ':' pre-inserted. You may
backspace over the ':'. Here are the commands::

    :! Execute a shell command.
    :e! Revert all changes to a .leo file, prompting if there have been changes.
    :gt cycle-focus
    :q Quit, prompting for saves.
    :qa Quit only if there are no unsaved changes.
    :r Prompt for a file name.  Insert it at the cursor.
    :tabnew Prompt for a file name, and open a new tab.
    :w Save the .leo file.
    :wa Save all changed  .leo files.
    :wq Save all open files and exit.
    :xa ave all open files and exit.

The following colon commands are unique to Leo::

    :print-vim-dot
    :toggle-vim-mode
    :toggle-vim-trainer-mode

Settings
********

**@bool vim-mode = False**: Enables Leo's vim mode when True.

**@bool vim-crosses-lines = True**: When True the f,F,h,l,t,T,x
commands may cross line boundaries.

Using vimoutline (.otl) files in Leo
++++++++++++++++++++++++++++++++++++

Leo can automatically import and export vimoutline (.otl) files. Nodes like::

    @auto-otl <path to .otl file>

or equivalently::

    @auto-vimoutline <path to .otl file>

import the .otl as a Leo outline.

These nodes work like other @auto nodes: when Leo loads an outline, Leo reads the .otl file into the @auto-otl tree. When Leo writes an outline, Leo writes any @auto-otl tree back to the .otl file.

After creating an @auto-otl node by hand, be sure to use Leo's refresh-from-disk command to populate the node. Do this *before* saving the .leo file. If you try to save an empty @auto-otl node Leo will warn you that you are about to overwrite the file.

The refresh-from-disk command creates an @auto-otl node whose **children** represent the contents of the external .otl file. Leo does *not* write the @auto-otl node itself. This allows you to put Leo directives in the node.

Using stand-alone vim bindings
++++++++++++++++++++++++++++++

Installing vim bindings
***********************

Place a copy of the "@keys Vim bindings" node and its sub-nodes, located in the leoSettings.leo file, under the "@settings" node in the myLeoSettings.leo file

The same procedure is performed to update to a new version.

Note: Place any local customized key bindings in a separate "@keys My Vi" node in the myLeoSettings.leo file to prevent them from being overwritten when updating to a new version.

General commands
****************

The following commands are always available.

State change commands::

    i           Change state to insert from command state
    Esc         Change state to command from insert state
    Ctrl-[      Same as ESC

Save/Exit/Quite commands::

    :e          Revert
    :w<return>  Save '.leo' file
    :wq<return> Save '.leo' file and quit Leo
    :q<return>  Quit Leo   (Leo will prompt if file not saved)
    ZZ          Save leo file and exit

Undo/Redo commands::

    u           Undo previous command
    Ctrl-r      Redo previous command


Search options::

    Ctrl-/      Prompt for option to change
                Options:
                    a   Search all nodes (also <cr> key)
                    h   Toggle headline search
                    b   Toggle body search
                    m   Toggle marking of nodes (specify sub-option)
                        f   Toggle marking of nodes with found text
                        c   Toggle marking of nodes with changed text
                            (only supported with 'Alt-/', 'Alt-p')
                    r   Toggle regex matches
                        ('/' key turns off regex. 'n' key uses regex if turned on)

    Note: Whether a search is limited to node's body or the node's sub-outline
          is determined by which pane has focus when search text specified.
          (See "Find text commands:" sub-sections in Outline/Body Pane sections)

Miscellaneous commands::

    Tab         Toggle focus between Outline and Body pane
    =           Simulate double-click on current node's icon box
    Alt-G       Go to specified line number (relative to external file)
    Ctrl-:      Enter Leo's command line

Body pane commands
******************

Move cursor commands::

    h           Go back 1 character
       LtArrow  Mapped to "h" for convenience
    j           Go down 1 line
       DnArrow  Mapped to "j" for convenience
    k           Go up 1 line
       UpArrow  Mapped to "k" for convenience
    l           Go forward 1 character
       RtArrow  Mapped to "l" for convenience

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Goto beginning of current line
    ^           Go to 1st non-blank character on current line
    $           Goto end of current line

    %           Go to matching bracket

    (           Go to beginning of current sentence
    )           Go to beginning of next sentence
    {           Go to beginning of current paragraph
    }           Go to beginning of next paragraph

    gg          Go to the first line (Cursor at column 1)
    G           Go to the last line  (Cursor at column 1)

Mark commands::

    m<label>    Assign cursor location to a single character label
    `<label>    Go to location associated with label

      Note: Only character count is tracked. Any inserts or deletes will change mark.
          Mark's are not node specific; `<label> will go to location in current node.

Select commands::

    Ctrl-v      Toggle text select mode (Vim's "visual" mode)
       V        Mapped to 'Ctrl-v' for convenience (Should toggle line select)

Insert/substitute commands::

    a           Insert at cursor
    i           Mapped to "a" until "cursor on a character" supported
    A           Insert at end of line
    I           Insert at first non-space
    o           Open new line below current line
    O           Open new line above current line
    R           Overwrite text
    s           Substitute character (Delete character, enter insert state)
    S           Substitute line (Delete line, enter insert state)

Change commands::

    C           Change to end of line
    cc          Change all of current line
    cw          Change to end of word
    cb          Change to beginning of word
    c)          Delete to end of sentence
    c(          Delete to beginning of sentence
    c}          Delete to end of paragraph
    c{          Delete to beginning of paragraph
    c%          Change from current bracket type its matching bracket type
    ct<char>    Selects forward to <char> (follow with 'i' to change selection)
    cT<char>    Selects backward to <char> (follow with 'i' to change selection)
    c<cr>       Change selected text

Delete commands::

    x           Delete next character
    delete      Delete next character
    D           Delete to the end of the current line
    dd          Delete current line
    dw          Delete to end of word
    db          Delete to beginning of word
    d)          Delete to end of sentence
    d(          Delete to beginning of sentence
    d}          Delete to end of paragraph
    d{          Delete to start of paragraph
    d%          Delete from current bracket type to its apposing bracket
    dt<ch>      Delete to character (not limited to current line)
    d<cr>       Delete selected text

    J           Join next line to end of current line (deletes carriage return)

Yank text commands::

    Y           Yank to end of line
    yy          Yank line
    yw          Yank to beginning of next word
    yb          Yank to beginning of current word
    y)          Yank to end of sentence
    y(          Yank to beginning of sentence
    y}          Yank to end of paragraph
    y{          Yank to beginning of paragraph
    y%          Yank from current bracket type to its opposing bracket
    yt<char>    Select forward to <char>  (use 'y<cr>' to yank selection)
    yT<char>    Select backward to <char> (use 'y<cr>' to yank selection)
    y<cr>       Yank selected text (Vim uses 'y' in visual mode)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node's body text
    ?           Search backward within current node's body text
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" in General Commands section to change options.

Replace [and find next] commands::

    Commands using Paste buffer (clipboard)
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.
    Ctrl-p      Paste then find next match
                Note: Use 'pn' instead of 'Ctrl-p' in headlines (Leo limitation)
                      Command will continue to paste when match no longer found.

    Commands prompting for replace string
    Note: Scope and direction taken from last use of '/','?' or 'Ctrl-/'(scope only)
    Alt-/       Prompt for search & replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Indent/Unindent line commands::

    >>          Indent the current line
    >)          Indent to the end of sentence
    >(          Indent to the beginning of sentence
    >}          Indent to the end of paragraph
    >{          Indent to the beginning of paragraph
    >g          Indent to the start of buffer
    >G          Indent to the end of buffer

    <>          Unindent the current line
    <)          Unindent to the end of sentence
    <(          Unindent to the beginning of sentence
    <}          Unindent to the end of paragraph
    <{          Unindent to the beginning of paragraph
    <g          Unindent to the start of buffer
    <G          Unindent to the end of buffer

Format commands::

    gqap        Split long line into separate lines
    gwap        Split long line into separate lines
    gqq         Split long line into separate lines
    gww         Split long line into separate lines

    Note: 'gwap' and 'gww' should not move cursor but do.

Scroll commands::

    Ctrl-b      Scroll text up by pane's height
    Ctrl-f      Scroll text down by pane's height
       Ctrl-y   Mapped to Ctrl-b until scroll up one line is supported
       Ctrl-e   Mapped to Ctrl-f until scroll down one line is supported
       Ctrl-u   Mapped to Ctrl-b until scroll up half a pane height is supported
       Ctrl-d   Mapped to Ctrl-f until scroll down half a pane height is supported

Window commands::

    Ctrl-w s    Open another view into current node's body (Vim: Split window)
       Ctrl-w n Mapped to "Ctrl-w s" (Vim: New buffer in split window)
    Ctrl-w w    Switch to next view (Vim: Go to up/left window w/wrapping)
       Ctrl-w p Mapped to "Ctrl-w w" (Vim: Cycle through windows)
       Ctrl-w k Mapped to "Ctrl-w w" (Vim: Go to window above current window)
       Ctrl-w j Mapped to "Ctrl-w w" (Vim: Go to window below current window)
    Ctrl-w c    Close current view in body pane (Vim: Close current window)
       Ctrl-w q Mapped to "Ctrl-w c" (Vim: Quit current window)

Node commands::

    Go to another node while focus remains in the body pane.
    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level
       Ctrl-DnArrow    Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow    Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow    Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow    Mapped to "Ctrl-l" for convenience

Outline commands
****************

The following commands are supported when in a headline's command mode.

State change commands::

    Ctrl-i      Change state to command from grayed state
    return      Change state to command from insert state
    Ctrl-]      Change state to grayed from command state

Cursor movement commands::

    h           Go to previous character
       LtArrow  Mapped to 'h' for convenience
    l           Go to next character
       RtArrow  Mapped to "l" for convenience

    Note: 'j' and 'k' will scroll the buffer contents up and down;
          leaving the focus in the outline pane.

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Go to beginning of line
    ^           Go to beginning of line
    $           Go to end of line

    %           Go to matching bracket

Edit commands::

    x           Delete next character
    delete      Delete next character
    dd          kill-line

    s           Select current character

    v           Toggle text select mode (issue cursor movement commands)
    y<return>   Yank selected text

    C           Select to end of line (follow with 'i' to change text)
    cc          Delete line (follow with 'i' to change text)

    D           Select to end of line (follow with 'x' to delete text)
    dd          Delete line

    Y           Select to end of line (follow with 'y<return>' to yank text)
    yy          Select line (follow with 'y<return>' to yank text)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node and its subnodes
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" section above to change options using 'Ctrl-/'

Replace [and find next] commands::

    Commands that use Paste buffer (clipboard)
    Note: Paste-then-search command not possible in headlines (Use 'pn')
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.

    Commands that prompt for the replace string
    Alt-/       Prompt for search & replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Node edit commands::

    o           Insert node after current node

    Ctrl-x      Delete current node
    Ctrl-c      Yank current node
    Ctrl-v      Paste current node

Node goto commands::

    G           Go to the outline's last node
    gg          Go to the outline's first node

    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level

       DnArrow  Mapped to "Ctrl-j" for convenience
       UpArrow  Mapped to "Ctrl-k" for convenience

       Ctrl-DnArrow Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow Mapped to "Ctrl-l" for convenience

Node move commands::

    Ctrl-Shift-k    Move node down
    Ctrl-Shift-h    Move node left
    Ctrl-Shift-l    Move node right
    Ctrl-Shift-j    Move node up

       Ctrl-Shift-DnArrow    Mapped to "Ctrl-Shift-k" for convenience
       Ctrl-Shift-LtArrow    Mapped to "Ctrl-Shift-h" for convenience
       Ctrl-Shift-RtArrow    Mapped to "Ctrl-Shift-l" for convenience
       Ctrl-Shift-UpArrow    Mapped to "Ctrl-Shift-j" for convenience

Node mark commands::

    m           Toggle node mark
    Ctrl-m      Go to next marked node
    Alt-m       Clear all marked nodes

Outline scroll commands::

   Ctrl-y       Scroll outline up one line
   Ctrl-e       scroll outline down one line
   Ctrl-u       Scroll outline up one half page
   Ctrl-d       scroll outline down one half page
   Ctrl-b       Scroll outline up one page
   Ctrl-f       scroll outline down one page

Commands not supported
**********************

Notable missing editing commands::

    t<char>     Move cursor to character before specified character
    r           Replace a single character with a single character
    0           Go to 1st column in current line (Use '|' instead)
    bksp        Move one character to the left
    ~           Toggle character's case
    .           Repeat last editing command
    ;           Repeat last cursor movement command
    <n><cmd>    Perform command 'n' number of times
    <cmd><n><object>    Perform the command on the n'th or up to the n'th object

Notable missing body pane commands::

    <num>G      Go to specified line number
    z<movement> Slide buffer to put current line at top/middle/bottom of pane
    '<command>  Go to line of last edit, jump, ...
    `<command>  Go to character of last edit, jump, ...

Avoiding changes to 'tag' files
*******************************

If you use the open-with command to open a node text in Vim and your Vim's "tag" file refers to external files then there is a risk that a external file that is initially displayed via the "tag" command" in Vim is accidentally edited and saved from the external Vim editor while your Leo session still contains the external file's original text that may later recreate the original external file during a Leo save operation (overwriting the changes saved from the Vim editor).

To prevent this problem, modifications to external files can be avoided by using Vim's "modeline" feature to disable editing of external files.

Vim's "modeline" feature scans each loaded buffer for text at the top or bottom of the file containing " vim:" followed by a series of Vim options. The text is usually embedded within a comment. The following example prevents modifications to a buffer in a Python file::

    # vim:noma (A space is required between the '#' and "vim:noma")

If this line is placed in a separate Leo node at the top or bottom of the list of nodes under a external file node (ex: @file) then any external file saved and then later loaded into Vim will, by default, not be modifiable. If a derived file does need to be edited then modifications can be re-enabled on a file-by-file basis by issuing Vim's ":ma" command while viewing the derived file.

The number of lines that Vim checks at the top and bottom of the buffer is configurable. The following Vim command must be placed in the vimrc file to allow for Leo's trailing sentinel lines::

    set modelines=8

Issue the ":help modeline" command within Vim for the more information about modelines.