vissort.txt	Visual-Mode Based Sorting		Sep 21, 2012

Author:  Charles E. Campbell  <NdrOchip@ScampbellPfamilyA.Mbiz>
Copyright: (c) 2004-2012 by Charles E. Campbell		vissort-copyright
           The VIM LICENSE applies to vissort.vim and vissort.txt
           (see copyright) except use "vissort" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.

	  (remove NOSPAM from Campbell's email first)

==============================================================================
1. Contents						vissort-contents

	1. Contents.......................................: vissort-contents
	2. Sorting a Column...............................: vissort
	3. Sorting Lines Based Upon a Column..............: vissort-lines
	4. BlockSort......................................: vissort-blocksort
	5. Options........................................: vissort-options
	6. History........................................: vissort-history

==============================================================================
2. Sorting a Column				vissort vissort-column

   Sorting a column independently of the surrounding lines

   vissort provides the ability to sort lines based on a column; the
   technique described here allows one to sort columns independently of any
   line contents surrounding the column.

   This topic is also covered on vim's wiki

	http://vim.wikia.com/wiki/index.php?search=vissort&fulltext=0

   Select the column using blockwise-visual mode (use ctrl-v, move).  Then,
   assuming <vis.vim> has been installed as a plugin, type

	:B sort

   or you may often use an external sorting program; in such a case, the
   typical command is:

	:B !sort

  Since these methods use blockwise-visual selection, the command will appear
  as

	:'<,'>B sort

   Examples:

	Original Text:

	one      two      three   four
	five     six      seven   eight
	nine     ten      eleven  twelve
	thirteen fourteen fifteen sixteen

	Use <vis.vim>'s B command with sort - sorts the column only:

	    ctrl-v to select column
	    :'<,'>B Bisort
	one      fourteen three   four
	five     six      seven   eight
	nine     ten      eleven  twelve
	thirteen two      fifteen sixteen

	Note how only the column (two, six, ten, fourteen) is affected;
	the rest of the lines are left as they were.

==============================================================================
3. Sorting Lines Based Upon a Column			 vissort-lines

	sorting lines based on selected column

   :[range]Vissort   actually same as Bisort
   :'<,'>Vissort     apply sort to visual-block only

   Select a block of text with visual-block mode; use the Vissort command to
   sort the block.  This function sorts the lines *based on the selected
   column*.

   Example:

	Original Text:

	one      two      three   four
	five     six      seven   eight
	nine     ten      eleven  twelve
	thirteen fourteen fifteen sixteen

	Use ctrl-v (Visual-Block) to select two..fourteen column,
	then Vissort:

	thirteen fourteen fifteen sixteen
	five     six      seven   eight
	nine     ten      eleven  twelve
	one      two      three   four

==============================================================================
4. BlockSort					vissort-blocksort

   :'<,'>BS
   :'< '>BS nextblock endblock findtag tagpat tagsub
   :[range]call BlockSort(nextblock,endblock,findtag,tagpat,tagsub)
   :[range]call BlockSort(...)

              If any arguments are missing, BlockSort()
                    will query the user for them.

    This function's purpose is to sort blocks of text based on tags
    contained within the blocks.

    WARNING: this function can move lots of text around, so using it
    is use-at-your-own-risk!  Please check and verify that things
    have worked as you expected.  Backing up your file before
    modifying it would be advisable before doing such things as
    sorting C functions.

    nextblock:
      Blocks are assumed to begin on a line containing the nextblock pattern.

      If the nextblock pattern is "" (the empty string), then the next block is
      assumed to begin with the line following the line matching the endblock
      pattern.

    endblock:
      Blocks are assumed to end with a line containing the endblock pattern.

      If the endblock pattern is "" (the empty string), then the end of the
      block will be assumed to be the line preceding the line matching
      the nextblock pattern.

    findtag:
      Blocks are assumed to contain a tag findable by the findtag pattern.

      If the findtag pattern is "", then nextblock line will be assumed
      to contain the tag.

    tagpat, tagsub:
      The tagpat and tagsub are used by a substitute(); the tag is extracted
      by applying the tagpat to the line containing the tag and substitution
      is made with the tagsub pattern.

      If the tagpat is "", then it will default to '^.*$'.

      If the tagsub is "", then if the tagpat was "", then tagsub will
      take on the default value of "&".

      If the tagsub is "" but the tagpat wasn't "", then the tagsub will
      take on the default value of '\1'.

   Examples:

    1. :[range]call BlockSort('^[a-z]','---$','\u','^.*\(\u\).*$','\1')

     Original Text:
     	one
             	some
             	junk
             	B
             	appears
             	---
     	two
             	some more
             	junk
             	A
             	appears here.
             	---

     After BlockSort('^[a-z]','---$','\u','^.*\(\u\).*$','\1')
     	two
             	some more
             	junk
             	A
             	appears here.
             	---
     	one
             	some
             	junk
             	B
             	appears
             	---

     Explanation of Arguments for Example#1:
     [range]call BlockSort(
     '^[a-z]',       | blocks begin lines with a character in the range [a-z]
     '---$',         | blocks end with three dashes and end-of-line
     '\u',           | blocks have at least one upper case character ([A-Z]) in them
     '^.*\(\u\).*$', | lines  that have an upper case character (ie. are a tag) are
     '\1')           |        transformed to contain only that upper case character

    2. Sorting C functions (see warning above!)			CFuncSort
			    [USE AT YOUR OWN RISK]

	:[range]CFuncSort
	:[range]call BlockSort('','^}','^[^/*]\&^[^ ][^*]\&^.*\h\w*\s*(','^.\{-}\(\h\w*\)\s*(.*$','')

	CFuncSort is a command that does exactly the same thing as the
	BlockSort shown above; its just easier to type.

	Each function is a block; the nextblock is implied by being the endblock + 1.

	The endblock assumes that C functions end with a pattern matching '^}'.  This
	assumption is not required by the language, but it is typical use.

	The findtag pattern attempts to avoid comments; its not perfect:
	                 1         2
	        12345678901234567890  <--column
		/* something()
		 * somethingelse()
		 */
       		// something()
	Its looking for a C-word ('\h\w*') followed by possible white space
	and an open parenthesis.  It undoubtedly can be confused by prototypes,
	stuff that looks like functions but is inside comments, etc.

	Once such a line is found, the tagpat operates to identify the function name.
	Since tagsub is '', its default value of '\1' is used.

     Explanation of Arguments for Example#2:
     [range]call BlockSort(
     '',                                | blocks begin after the next pattern
     '^}',                              | blocks end with a closing curly
                                        |     brace which begins the line
     '^[^/*]\&^[^ ][^*]\&^.*\h\w*\s*(', | the block is tagged by an identifier
                                        |     followed by optional spaces and
					|     opening "(".  Some care is taken
					|     to avoid comment lines.
     '^.\{-}\(\h\w*\)\s*(.*$',          | the tag is extracted by using this
                                        |     pattern
     '')                                | the default value of '\1' is used to
                                        |     extract only the tag

==============================================================================
5. Options					vissort-options

	g:vissort_sort
		Default Value: "sort"
		This string holds the command used to invoke sorting.
		(see :sort)

	g:vissort_option
		Default Value: ""
		This string holds any options desired; ie. "n".
		(see :sort)
		One may set this option with the
			:VSO x
		command, where "x" is an option (such as n or i).
		One may remove options with
			:VSO

==============================================================================
6. History						 vissort-history
	v4	Dec 19, 2011	* removed BISort function (which provided
				  internal sorting for vim v6)
				* updated document and text
	v1-3	2005		* sorry, earlier versions didn't have history


==============================================================================
vim:tw=78:ts=8:ft=help