vim-scripts / advancedsorters Goto Github PK

This is a mirror of http://www.vim.org/scripts/script.php?script_id=4958

DESCRIPTION
The built-in :sort command is powerful, but it still is line-based. It
doesn't take into account folded lines, nor can it sort entire blocks like
function definitions, paragraphs, etc. But often, one needs to sort exactly
such areas as single entities, i.e. without changing the line order within
them. A workaround in Vim is condensing each block into a single line,
performing the sorting, and then expanding again. (External, more powerful
sort commands could be used, too.)

This plugin implements this workaround and encapsulates the three separate
steps in one handy command.

While :sort has several flags for sorting on various numbers, and a
/{pattern}/ can be specified to skip or sort on, it doesn't allow arbitrary
(Vimscript) expressions.

This plugin offers extension commands that evaluate an expression per line,
put that number in front of the line, do a numerical sort, and then remove the
temporary number again. Specializations handle the common sort by number of
characters and by the line's display width.

SOURCE
- :SortUnfolded inspired by
  http://stackoverflow.com/questions/13554191/sorting-vim-folds
- :SortRangesByRange inspired by
  http://superuser.com/questions/752032/how-do-i-sort-multiple-blocks-of-text-by-the-first-line-in-each-block-in-vim
- :SortByExpr inspired by
  http://stackoverflow.com/questions/11531073/how-do-you-sort-a-range-of-lines-by-length
- :SortWORDs inspired by
  http://stackoverflow.com/questions/26739697/sort-line-horizontally-in-vim
  http://stackoverflow.com/questions/1327978/sorting-words-not-lines-in-vim

SEE ALSO
- The LineJuggler.vim plugin (vimscript #4140) offers many quick mappings to
  move around (blocks of) lines. For small data sets, manual shifting may be
  quicker than coming up with a correct sort command.

USAGE
:[range]SortUnfolded[!] [i][u][r][n][x][o] [/{pattern}/]
                        Sort visible lines in the buffer / [range]. Lines
                        inside closed folds are kept intact; sorting is done
                        on all lines of the fold as one unit; i.e. the order
                        of the other lines inside the fold does _not_ change!

:[range]SortRangesByHeader[!] /{expr}/ [i][u][r][n][x][o] [/{pattern}/]
                        Each match of {expr} (in the buffer / [range]) starts
                        a new area that sorts as one unit; i.e. the order of
                        the other lines inside the area does _not_ change!

:[range]SortRangesByMatch[!] /{expr}/ [i][u][r][n][x][o] [/{pattern}/]
                        Each (multi-line) match of {expr} (in the buffer /
                        [range]) defines an area that sorts as one unit.
                        Non-matching lines are sorted individually.

:[range]SortRangesByRange[!] {range} [i][u][r][n][x][o] [/{pattern}/]
                        Each {range} (in the buffer / [range]) defines an area
                        that sorts as one unit.
                        Note: For this command, /{pattern}/ must be separated
                        from the {range} by a [i][u][r][n][x][o] flag or a
                        space; you cannot directly concatenate them.

                        Note: The text must not contain embedded <Nul>
                        characters (^@) for the above commands!

:[range]SortByExpr[!] {expr}
                        Sort lines in [range] by the {expr}, which should take
                        the current line as input via v:val and return a
                        number. With [!] the order is reversed.

:[range]SortByExprUnique[!] {expr}
                        Sort lines in [range] by the {expr}; only the first
                        line that gets a certain number from {expr} is kept.
                        With [!] the order is reversed.

:[range]SortByCharLength[!]
                        Sort lines in [range] by the number of characters.

:[range]SortByWidth[!]
                        Sort lines in [range] by the display width.

:[range]SortWORDs[!] [i][u][r][n][x][o] [/{pattern}/]
                        Sort individual (whitespace-delimited) WORDs in the
                        current line / [range].

:[range]Uniq[!] [i][r] [/{pattern}/]
                        Remove lines in [range] that have already been
                        encountered earlier (not necessarily adjacent).
                        With [i] case is ignored.
                        When /{pattern}/ is specified and there is no [r] flag
                        the text matched with {pattern} is ignored.
                        With [r] only the matching {pattern} is considered;
                        the rest is ignored.
                        If a {pattern} is used, any lines which don't have a
                        match for {pattern} are kept.

EXAMPLE
We're taking any Vimscript file with multiple function definitions as an
example, and show how to sort whole functions according to function name (and
arguments).

To use folding, we first have to define the folds, then trigger the sorting:
    :g/^function/,/^endfunction/fold
    :SortUnfolded

If we don't care about including any lines after the "endfunction", we can
just base the areas on the function start:
    :SortRangesByHeader /^function/
But we'll get better results with an explicit end. One way is to define a
multi-line pattern that covers the entire function:
    :SortRangesByMatch /^function\_.\{-}\nendfunction$/
Another way spans up a range, similar to what we've done above to define the
folds:
    :SortRangesByRange /^function/,/^endfunction$/