vim-flexagon

KO | EN

gitlite — search

#python #hacktoberfest #ai #llm #android #machine-learning #docker #windows #cli #kubernetes #vue #pytorch #openai #open-source

(★ 14)

Flexible and useful vim folding switcher

vim-flexagon Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Flexagon, A Vim fold method method manager

A wrapper around vims folding to easily switch between various folding schemes 
and some useful pre-packaged schemes, all designed to be easily discovered and 
easily switched.

Flexagon also provides some custom fold presentation and a "bubble" Plug 
mapping to walk through folds.

# Overview

Vim offers several folding methods, each with trade-offs, none to my mind fully 
satisfying. Further, I've found folds useful for code visualization, a purpose 
that's not a primary aim of vim's folding method.

Rather then striving to find the perfect fold method, I decided to embrace the 
diversity and make it easy to add and change folding methods

# Inspiration

An interesting and short comment thread on Reddit, in particular user 
``/u/]interiot`` preference for using mediawiki syntax over vim's native 
folding
https://www.reddit.com/r/vim/comments/1hnh8v/question_what_foldmethod_are_you_guys_using_and/

Wiki header syntax is intuitive, natural and clean.
It also has a natural and unobtrusive way to signal levels.

Some other natural schemes along this line:

* Markdown

* Javadoc/Doxygen

* "Flower pot" header bars

# Visualization

Folding offers a way for a text based editor to visualize "shape". Selectively
hiding code offers a way to emphasize other code. Flexagon offers two several
folds that help visualize code structure:

* Hide comments ( ``:Fold: code`` )

* Hide non-comments ( ``:Fold: comments`` )

* Blank and or all whitespace lines ( ``:Fold: space`` )

Each offers a different emphasis on the code, which I've found surprisingly
revealing and useful.

# Levels

One level of folding offers most of the benefit of folding, as folding
visibility is binary (visible or not). There is benefit in several levels, but
each additional level offers less. In particular each higher level fold
requires working through more mental details Many of the packaged folds in
Flexagon are conceived and implemented with only one fold level in mind.

As in vim's native marker folds, multiple levels are likely better when
deliberate, as the higher levels are more likely to be related with each other.
For example, a layer 4 indent in one block may have no relationship to a layer
4 indent in another block, but the intent of a ``{{`` marker in one block most
likely is highly related to a ``{{`` in another block.

# Commands

There is one command **''Fold:''** (shadowing vim's native ``:fold`` commeand). 
It offers tab completion of the various folding methods.

## Custom Folds

Currently supported folding arguments:

* ***wiki*** Use embedded wiki ``=`` heading markers. Given this code:

#!/usr/bin/perl
         # = this is a first level header
         some_code_here();
         # == this is a second level header
         some_more_code_here();
         # === this is a third level header
         even_more_code();

``:Fold wiki`` will create nested folds as indicated.

Leading comments are expected.
     
* ***markdown*** similar to wiki, but use hash header. Also works on regular
  markdown

* ***doxygen*** Not a true/full javadoc/doxygen fold, but a useful approximation.
  Fold when an extra comment character is present, i.e.:
  * ``/**`` in ``c``
  * ``##`` in shell, perl etc.
  * ``///`` ( or ``##``) in ``php``
Most of these expect ``commentstring`` to be set.

* ***space*** space separated sections (i.e. "paragraphs")
    Since spaces often separate "ideas" this Fold provides an overview of the 
    ideas in the code.

* ***comment*** hide code and show comments. This approximates "literate" code 
  (Donald Knuth's interesting idea).

* ***code*** This is the inverse of comment above, showing only code. This is 
  useful in code with excess comments (yes this exists :-) )

* ***braces*** Fold on brace characters. I found this in Steve Losh's .vimrc 
  and immediately wondered why this wasn't a standard. It's a very good fit for 
  any C language family code, roughly the equivalent of ``indent`` as a python
  fold.

* **header** "Flower Pot" headers (not particularly sophisticated)

* ***ini*** fold on DOS INI section headers with second folds on breaks and 
  comments

* ***html*** A not entirely successful attempt to fold HTML

## Vim Native Folds
Since I've shadowed vim's native fold command it's only polite to allow 
switching to those native methods
* ***manual***
* ***indent***

# Discussion

Folding with more then one level deep is complicated, not only in 
implementation, but in conception. Syntax folding offers fine control, in a way 
the seems logical, but in practice this has not worked well for me. Let alone 
resource drag, my practical experience changing the fold level expects more 
knowledge of which folding level I want to see. One level is easy to 
understand, and two levels provides most of the utility.

vim-flexagon

vim-flexagon Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vim-flexagon

vim-flexagon Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README