Skip to content

Indentation and Tabulation

ygrek edited this page Oct 5, 2024 · 32 revisions

Tabs versus Spaces (Silicon Valley)

Basic Settings

Kakoune has two relevant settings you might want to check: tabstop sets the width of each tab character (inserted with the <tab> key), and indentwidth sets the number of spaces inserted or removed by the > and < commands.

If you're the kind of person who hates tabs for indentation and only wants to use spaces, you'll probably want to map <tab> to something else, and control the amount of indenting by setting indentwidth.

If you're the kind of person who hates spaces for indentation and only wants to use tabs, you'll probably want to set indentwidth to 0 (which means "indent with a tab, not spaces") and control the amount of indenting by setting tabstop.

Paste some text from the clipboard without triggering indentation

Use \ before entering insert mode to prevent hooks from being executed in this insert session (\ i for example, then use your terminal pasting capability like Shift Insert or mouse middle click).

Indentation and Tab handling — Through a mapping

# except for Makefile
hook global WinSetOption filetype=(?!makefile).* %{
  map global insert <tab> '<a-;><a-gt>'
  map global insert <s-tab> '<a-;><a-lt>'
}

Indentation and Tab handling — Through hooks

hook global InsertChar \t %{ try %{
  execute-keys -draft "h<a-h><a-k>\A\h+\z<ret><a-;>;%opt{indentwidth}@"
}}
hook global InsertDelete ' ' %{ try %{
  execute-keys -draft 'h<a-h><a-k>\A\h+\z<ret>i<space><esc><lt>'
}}

Use Tab for both indenting and completion

When the completion menu is visible in insert mode, Tab and Shift Tab will cycle through the available options. When the completion menu is not shown, or when the character before the cursor is whitespace, Tab and Shift Tab are just handled normally, so the previous tab-expansion example still works.

hook global InsertCompletionShow .* %{
    try %{
        # this command temporarily removes cursors preceded by whitespace;
        # if there are no cursors left, it raises an error, does not
        # continue to execute the mapping commands, and the error is eaten
        # by the `try` command so no warning appears.
        execute-keys -draft 'h<a-K>\h<ret>'
        map window insert <tab> <c-n>
        map window insert <s-tab> <c-p>
        hook -once -always window InsertCompletionHide .* %{
            unmap window insert <tab> <c-n>
            unmap window insert <s-tab> <c-p>
        }
    }
}

Smarttab, expandtab and noexpandtab

You can use smarttab.kak plugin. It provides these commands to toggle different policy when using Tab and > keys:

  • noexpandtab - use tab for everything.
    Tab will insert \t character, and > will use \t character when indenting. Aligning cursors with & uses \t character.
  • expandtab - use space for everything.
    Tab will insert %opt{indentwidth} amount of spaces, and > will indent with spaces.
  • smarttab - indent with tab, align with space.
    Tab will insert \t character if your cursor is inside indentation area, e.g. before any non-whitespace character, and insert spaces if cursor is after any non-whitespace character. Aligning cursors with & uses space.

If you are looking for a more faithful implementation of vim's expandtab and softtabstop options, try this gist: vimtab.kak. Just copy and paste it into your kakrc file and set the options as you wish. It also respects the usage of \ to disable hooks for insert mode, thus allowing you to insert a <tab> even when expandtab is enabled.

See also

Clone this wiki locally