Pretty Fold

Pretty Fold is a lua plugin for Neovim which has two separate features:

Framework for easy foldtext customization. Filetype specific and foldmethod specific configuration is supported.
Folded region preview (like in QtCreator).

simplescreenrecorder-2022-01-05_20.24.21.mp4

Instalation and quickstart

Instalation and setup expample with packer:

use{ 'anuvyklack/pretty-fold.nvim',
   config = function()
      require('pretty-fold').setup{}
      require('pretty-fold.preview').setup_keybinding()
   end
}

Foldtext configuration

pretty-fold.nvim comes with the following defaults:

{
   fill_char = '•',
   sections = {
      left = {
         'content',
      },
      right = {
         ' ', 'number_of_folded_lines', ': ', 'percentage', ' ',
         function(config) return config.fill_char:rep(3) end
      }
   },

   remove_fold_markers = true,

   -- Keep the indentation of the content of the fold string.
   keep_indentation = true,

   -- Possible values:
   -- "delete" : Delete all comment signs from the fold string.
   -- "spaces" : Replace all comment signs with equal number of spaces.
   -- false    : Do nothing with comment signs.
   comment_signs = 'spaces',

   -- List of patterns that will be removed from content foldtext section.
   stop_words = {
      '@brief%s*', -- (for cpp) Remove '@brief' and all spaces after.
   },

   add_close_pattern = true,
   matchup_patterns = {
      { '{', '}' },
      { '%(', ')' }, -- % to escape lua pattern char
      { '%[', ']' }, -- % to escape lua pattern char
      { 'if%s', 'end' },
      { 'do%s', 'end' },
      { 'for%s', 'end' },
   },
}

`sections`

The main part. Contains two tables: config.sections.left and config.sections.right which content will be left and right aligned respectively. Each of them can contains service sections, strings and functions that return string. All functions accept config table as an argument.

Service sections

The strings from the table below will be expanded according to the table.

Item	Expansion
`'content'`	The content of the first non-blank line of the folded region, somehow modified according to other options.
`'number_of_folded_lines'`	The number of folded lines.
`'percentage'`	The percentage of the folded lines out of the whole buffer.

`fill_char`

Character used to fill the space between the left and right sections.

`remove_fold_markers`

Remove foldmarkers from the content section.

`keep_indentation`

Keep the indentation of the content of the fold string.

`comment_signs`

What to do with commnet signs.

Option	Description
`'delete'`	delete all comment signs from the foldstring
`'spaces'`	replace all comment signs with equal number of spaces
`false`	do nothing with comment signs

`stop_words`

Patterns that will be removed from the content section.

`matchup_patterns`

The list with patterns where each item is a list with two items: open and close patterns.

If config.add_close_pattern option is set to true, and the opening pattern is found in first non-blank line of the folded region the close pattern will be added after ellipsis (...). Like this:

The comment substring in foldtext is correctly handled on close pattern adding.

If comment_signs = 'spaces' is set, the output will be

Examples

require('pretty-fold').setup{
   keep_indentation = false,
   fill_char = '•',
   sections = {
      left = {
         '+', function() return string.rep('-', vim.v.foldlevel) end,
         ' ', 'number_of_folded_lines', ':', 'content',
      },
      right = nil
   }
}

require('pretty-fold').setup{
   keep_indentation = false,
   fill_char = '━',
   sections = {
      left = {
         '━ ', function() return string.rep('*', vim.v.foldlevel) end, ' ━┫', 'content', '┣'
      },
      right = {
         '┫ ', 'number_of_folded_lines', ': ', 'percentage', ' ┣━━',
      }
   }
}

Setup for particular filetype

This plugin provides to setup functions.

The first one

require('pretty-fold').setup(config: table)

sets global foldtext option.

But if you want to setup filetype specific foldext use the secons one

require('pretty-fold').ft_setup(filtype: string, config: table)

This function should be called for every buffer of the desired filtype, but this plugin doesn't provides any autocommands to do this because Neovim (and Vim) has much more convinient mechanist to do this: after/ftplugin directory. To setup foldext with pretty-fold.nvim plugin only for, for expample, C++ files add to the file (on Linux)

$HOME/.config/nvim/after/ftplugin/cpp.lua

the next content:

require('pretty-fold').ft_setup('cpp', {
   stop_words = {
      '@brief%s*', -- remove '@brief' and all spaces after from foldtext
   },
   -- your other settings
})

Foldmethod specific configuration

The pretty-fold.nvim plugin supports different configuration for different foldmethods. For this pass the configuration table for a particular foldmethod as a value to the key named after foldmethod.

It is allowed to have one unlabeled global config table for all foldmethods and tune only desired options in foldmethod specific config table. All options that doesn't have value in foldmethod config table will be taken from global config table.

Example:

require('pretty-fold').setup({
    {...}, -- global config table for all Foldmethods
    marker = { comment_signs = 'spaces' },
    expr   = { comment_signs = false },
})

Preview

I personally don't want to learn a new key combination to open fold preview. So I tried to create something that would feel natural.

The preview open can be mapped to h or l key. This key will be work as usual until you move cursor somewhere inside folded region. Then on first press on this key, the preview floating window will be opened. On second press fold will be opened and preview will be closed.

A preview window also will be closed on any cursor move, changing mode, or buffer leaving.

To enable this feature call

require('pretty-fold.preview').setup_keybinding('h') --  choose'h' or 'l' key

Warning: Only h or l keys can be passed to this function, any other will cause an error.

Custom preview mapping

If you would like to create your custom preview mapping check lua/pretty-fold/preview.lua file. The main function is show_preview() which creates preview floating window and setup autocommands to close it and change its size on scrolling and vim resizing.

Additional information

Check 'fillchars' option. From lua it can be set the next way:

vim.opt.fillchars:append('fold:•')

Nauticus / pretty-fold.nvim