foldstaff-vim

      🍔🍙

This document has been prepared baded on automatic translation.
Please forgive me if there are some strange sentences...

This plugin is utilities for Folding at Vim editor.
The settings for each utility, can be switched for each filetype.

foldstaff-vim provides the bellow utilities:

• foldstaff-header
  For foldtext. Generates the display Text of closed Folding.
  You can freely edit the content to be displayed using formatting-text as like the statusline.
  And you can set the formatting-text for each filetype and each foldlevel.
  You can also specify the length of the display Text.

• foldstaff-marker
  Set the fold-marker, with right-side aligned.
  That is almot all there is to it.

• foldstaff-fold
  Folding method for foldexpr, when the fold-expr.
  This has some folding types:
  

  • type = "code"
    This is for Code or Script buffer.
    This is similar to fold-indent, but folding into the previous paret level line. (like as VS-Code)
    And, fold-marker, etc. can also uses.
  • type = "text"
    This is mainly for Vim-help.
    Folding buffer individually, after separating them with horizontal line and blank line.
    The result looks like an outline or table of contents.
  • type = "match"
    Judges and folds each line using a pre-defined matching-patterns.

• foldstaff-option
  This is a function for option setting, for above utilities.
  Although it is possible to set global-variableg: as in general plugins, this function allows you to check and reflect the values immediately.

---

Screenshot

Default:

Modify:

Funcky:

Vim-Help at foldstaff-fold type="text":

---

Installation

Install using your favorite package manager.

• Vundle:

  Plugin 'hongkong3/foldstaff-vim'

• NeoBundle:

  NeoBundle 'hongkong3/foldstaff-vim'

• VimPlug:

  Plug 'hongkong3/foldstaff-vim'

• Pathgon:

  cd ~/.view/bundle
  git clone https://github.com/hongkong3/foldstaff-vim

---

Usage

For more information on how to use it, please see the help in Vim.
:h foldstaff

Quick start:

Place this in your .vimrc:

let g:enable_foldstaff = 1

This will allow you to use all the utilities.
(also, add foldstaff["help"] settings)

The following is an introduction of how to use and set up each of them individually.

[Vim9-version]

If you write the following in vimrc, it will run in the Vim9-script version.

let g:foldstaff_enable_vim9 = 1

Note: Some functions may not work due to changes in Vim9-script specifications.
(Confirmed to work: gVim 8.2.4324)

---

foldstaff-header:

Setup:

:set foldtext=foldstaff#header()

This is used as a callback function for foldtext from Vim.
In usage, it is more important to edit the formatting-text.

caution: not realtime update

When changes to the base-text, will not realtime reflected in the folded-text.
It will be updated by...

• number of buffer-lines changed
• window resized (window-columns changed)
• execute :FoldstaffOption on current buffer

The text on the line with first non-symbolic character from foldstart, will be used as the base-text.
(This means, that lines with only symbols as separators will be ignored)

about: base-text

As an example, here is the case of folding with fold-marker.

• before fold

    # define _______________________________________________{{{2  #A
    X_RANGE = 10 #(+-)x_range.
  
    # ______________________________________________________{{{2  #B
    rgb_val = []
    data_range = np.linspace(-(X_RANGE),X_RANGE,(X_RANGE*4)+1)

• after folded

    # define _____________________________________________~+[ 3]  #A
    rgb_val = []                                           +[ 6]  #B

In the case of #A the text of the foldstart line will be used as is.
In case #B, foldstart line is only a symbol and a marker, so it is ignored and the text of the next line is used.

By the way, there is no need to place the marker on a separate line to avoid displaying symbols like #B.

• Removing symbols uses :FoldstaffOption python.modify, etc.
• Use other folding methods

etc. Please use the way that best suits your writing style.

foldstaff-header-format

The formatting-text is used for generated the folded-text.
You can set for each filetype and each foldlevel.

Specify the formatting-text for each foldlevel as a string in a LIST variable.
If the number of formatting-text is less than the foldlevel, the last item will be used.

" I'm leaving a lot out.
header.format = [
  '# %t %<=%> %p%%(%l)',                    " #Lv1
  '## %t %<-%> %p%%(%l)',                   " #Lv2
  '%{repeat("#", %v)%} %t %<.%>%p%%(%l)',   " #Lv3, ...
]

Even if there is only one formatting-text, as in the default, the foldlevel can be represented by including an expression.

header.format = ['%i%t %<%>%{repeat("+", %v)%}[%L]']

Items that can be used within the formatting-text include the following:

item	contents
%%	a single percent sign %
%t	base-text It will also be modified by header.modify
%< ... %>	fill the margin by repeat string, from between this
%{ ... %}	evalute expression between this, and replace to result
%s , %S	line number of foldstart, and with padding
%e , %E	line number of foldend, and with padding
%l , %L	number of line in folded, and with padding
%p %P	percentage of foldstart line in buffer [0 .. 100] percentage of foldstart line in buffer ["  0.0" .. "100.0"]
%v	current closed foldlevel (start 1)
%V	max foldlevel
%i	indent of foldstart line [space]
%I	indent-level (indent() / shiftwidth())
%T	line number where the base-text
%d	folddashes ["-"]
%D	&diff [0 / 1]

You can also call user-functions as evaluation expressions, so I think you can do most things.

---

foldstaff-marker:

This is set the fold-marker. This function is designed to be used setting to key-mapping.

Setup:

:map zf <Plug>(foldstaff-marker)
:map zF <Plug>(foldstaff-endmarker)

zf and zF are just examples. Feel free to set the actual keys as you wish.
Two key-mappings are provided, for the {{{start-marker and }}}end-marker.

At runtime, it works as follows:

• When executed in Normal-Mode, fold-marker will be placed by the behind of cursor line.
  • if fold-marker already been placed, then remove it.

  " - - - - - - - - - - - - - - - - - - - - - - - - - - -{{{

• When executed with <count>¹, place fold-marker for it foldlevel.
  • if fold-marker already been placed, then replace marker of new foldlevel.

  " ===================================================={{{2

• When execute in Visual-Mode(multiline selected), will be placed start-marker on first-line, and end-marker on last-line.

  for i in range(10) " - - - - - - - - - - - - - - - - - {{{
    echo i
  endfor " - - - - - - - - - - - - - - - - - - - - - - - }}}

Also, you can possible to set the character of fill at margin, for each foldlevel.
There is unlimit characters, so you can do something like this.

  " ( T T)/(^ ^ )`( - -)c(>_< )9_( T T)/(^ ^ )`( - -)c(>_{{{

---

foldstaff-fold:

This function is for foldexpr.
This function performs folding according to the contents of the buffers.

Setup:

:set foldmethod=expr foldexpr=foldstaff#fold()

This completes the configuration, but the settings will often be overwritten...
It may be more constructive to execute the following Ex-Command as needed.

Command:

:FoldstaffFold
:FoldstaffFold {type}

{type} cna be code, text, match, or auto.
If {type} is omitted, then auto will be used.
When auto is used, it will switch to code or text depending on the buffer contents.

If match is specified, it cannot be executed unless :FoldstaffOption fold.match = [...] is set beforehand.

---

foldstaff-option:

This is a dedicated function for setting options for this plugin.
A function version is also available, but I think it is easier to use the command.

Command:

:FoldstaffOption
:FoldstaffOption {filetype}.{method}.{key} = {value}
:FoldstaffOption {filetype}.{method}.{key}[index] = {value}

When executed with no argument, if g:foldstaff exists, it will read the setting.

If arguments are specified, it will change the setting to that value.
The only part of the argument that is required is the {key} = {value} part.
Arguments {filetype} and {method} can be omitted.

For the about to be specified for {filetype}, {method} and {key}, please check Option described below.

After execution, it will display the changed option-vriable, and update foldstaff-header and foldstaff-fold.
It also acquires the changed option-variable in register h as a string. (type "hp to paste it)

---

Option

The option values in this plugin are managed by a DICT variable.
The contents of this variable are as follows:

    " #line-continuation '\' omitted.
    [g:]foldstaff = {
        "_" = #{                            " filetype [basic]
            header = #{                     " @ foldstaff-header
                format = [                  "   formatting text(s)
                    '%i%t %<%>%{repeat("[", %v)%}%L]',
                ],
                width = '+0',               "   max-length of folded text
                min = 8,                    "   min-length of base-text
                ellipsis = '~',             "   symbols when base-text omitted
                modify = [],                "   substitution-list to base-text
            },
            marker = #{                     " @ foldstaff-marker
                fill = [                    "   padding strings list
                    '- ',                   "     for non-level
                    '=', '_', '.',          "     for each foldlevel
                ],
                width = 0,                  "   length of fold marker
            },
            fold = #{                       " @ foldstaff-fold
                type = 'auto',              "   fold-type: [code/text/match/auto]
                keyswitch = -1,             "   za zo zc key-maps switch flag
                match = [],                 "   for fold-type:'match' (default is empty)
            },
        },
    " # The same settings as above can be added for each filetypes.
        "vim" = {
            ...
        },
        "help" = {
            ...
        }, ...
    }

See :h foldstaff-option-detail for details of each setting value.

---

This "foldstaff" is no relationship with any real person, organization, or name.

Footnotes

1. for example, an input like "1zf" or "2zF". ↩