# What good will FastFold do?

Automatic folds (that is, folds generated by a fold method different
from `manual`), bog down VIM noticeably in insert mode. They are also often
recomputed too early (for example, when inserting an opening fold marker
whose closing counterpart is yet missing to complete the fold.)

See http://vim.wikia.com/wiki/Keep_folds_closed_while_inserting_text
for a discussion.

With this plug-in, the folds in the currently edited buffer are updated by an
automatic fold method only

- when saving the buffer
- when closing or opening folds (zo, za, zc, etc...)
- when moving or operating fold-wise (zj,zk,[z,]z)
- when typing `zuz` in normal mode

and are kept as is otherwise (by keeping the fold method set to `manual`).

# Example Setup

Each of these triggers for updating folds can be modified or disabled by adding
the lines

```vim
nmap zuz <Plug>(FastFoldUpdate)
let g:fastfold_savehook = 1
let g:fastfold_fold_command_suffixes =  ['x','X','a','A','o','O','c','C']
let g:fastfold_fold_movement_commands = [']z', '[z', 'zj', 'zk']
```

to the file `~/.vimrc` (respectively `%USERPROFILE%/_vimrc` on Microsoft Windows).

For example, by adding

```vim
let g:tex_fold_enabled=1
let g:vimsyn_folding='af'
let g:xml_syntax_folding = 1
let g:php_folding = 1
let g:perl_fold = 1
```

to the `.vimrc` file and installing this plug-in, the folds in a TeX, Vim, XML,
PHP or Perl file are updated by the `syntax` fold method when saving the
buffer, opening, closing, moving or operating on folds, or typing `zuz` in
normal mode and are kept as is otherwise.

*Set fold methods for every file type only*! Setting it globally risks that FastFold assumes the wrong, global, fold method instead of that intended by the file type plug-in, for example TagList.

# Configuration

- If you prefer that folds are only updated manually but not when saving the buffer,
  then add `let g:fastfold_savehook = 0` to your `.vimrc`.

-   If you prefer that folds are updated whenever you close or open folds by a
    standard keystroke such as `zx`,`zo` or `zc`, then add `let
    g:fastfold_fold_command_suffixes = []` to your `.vimrc`.

    The exact list of these standard keystrokes is `zx,zX,za,zA,zo,zO,zc,zC` and
    it can be customized by changing the global variable
    `g:fastfold_mapsuffixes`. If you wanted to intercept all possible fold
    commands (such as zr,zm,...), change this to:

    ```vim
    let g:fastfold_fold_command_suffixes =
    ['x','X','a','A','o','O','c','C','r','R','m','M','i','n','N']
    ```

- If you prefer that this plug-in does not add a normal mode mapping that updates
  folds (that defaults to `zuz`), then add
  `nmap <SID>(DisableFastFoldUpdate) <Plug>(FastFoldUpdate) ` to your `.vimrc`.

  You can remap `zuz` to your favorite keystroke, say `<F5>`, by adding
  `nmap <F5> <Plug>(FastFoldUpdate)` to your `.Vimrc`.

  There is also a command `FastFoldUpdate` that updates all folds and its
  variant `FastFoldUpdate!` that updates all folds and echos by which fold
  method the folds were updated.

# Addons

## Vim-Stay

`FastFold` integrates with the plug-in
[vim-stay](https://github.com/kopischke/vim-stay/issues) that restores the
folds of a file buffer by `:mkview` and `:loadview`.

## Custom Fold Text

A `CustomFoldText()` function that displays the percentage of the number of buffer lines that the folded text takes up and indents folds according to their nesting level, similar to [that](http://www.gregsexton.org/2011/03/improving-the-text-displayed-in-a-fold/) by Greg Sexton, is available at

http://www.github.com/Konfekt/FoldText

## Fold Text-Object

Create a fold text object, mapped to `iz` and `az`, by adding the lines

```vim
xnoremap iz :<c-u>FastFoldUpdate<cr><esc>:<c-u>normal! ]zv[z<cr>
xnoremap az :<c-u>FastFoldUpdate<cr><esc>:<c-u>normal! ]zV[z<cr>
```

to the file `~/.vimrc` (respectively `%USERPROFILE%/_vimrc` on Microsoft Windows).