visincr.txt	The Visual Incrementing Tool		Nov 22, 2017

Author:  Charles E. Campbell  <NdrchipO@ScampbellPfamily.AbizM>
	  (remove NOSPAM from Campbell's email before using)
Copyright: (c) 2004-2015 by Charles E. Campbell	visincr-copyright
           The VIM LICENSE applies to visincr.vim and visincr.txt
           (see copyright) except use "visincr" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.

==============================================================================
1. Contents				visincr visincr-contents

	1. Contents .......................: visincr
	2. Quick Usage ....................: visincr-usage
	3. Increasing/Decreasing Lists.....: visincr-increase visincr-decrease
	   :I     [#] .....................: visincr-I
	   :II    [# [zfill]] .............: visincr-II
	   :IMOD  [# [modulus [modoffset]]]: visincr-IMOD
	   :IREP  [# [modulus [modoffset]]]: visincr-IREP
	   :IB    [#] .....................: visincr-IB
	   :IIB   [# [zfill]] .............: visincr-IIB
	   :IO    [#] .....................: visincr-IO
	   :IIO   [# [zfill]] .............: visincr-IIO
	   :IX    [#] .....................: visincr-IX
	   :IIX   [# [zfill]] .............: visincr-IIX
	   :IYMD  [# [zfill]] .............: visincr-IYMD
	   :IMDY  [# [zfill]] .............: visincr-IMDY
	   :IDMY  [# [zfill]] .............: visincr-IDMY
	   :IA    [#] .....................: visincr-IA
	   :ID    [#] .....................: visincr-ID
	   :IM    [#] .....................: visincr-IM
	   :IPOW  [#] .....................: visincr-IPOW
	   :IIPOW [#] .....................: visincr-IIPOW
	4. Examples........................: visincr-examples
	   :I .............................: ex-visincr-I
	   :II ............................: ex-visincr-II
	   :IMDY ..........................: ex-visincr-IMDY
	   :IYMD ..........................: ex-visincr-IYMD
	   :IDMY ..........................: ex-visincr-IDMY
	   :IA ............................: ex-visincr-IA
	   :ID ............................: ex-visincr-ID
	5. Options ........................: visincr-options
	6. History ........................: visincr-history

==============================================================================
2. Quick Usage				visincr-usage

	Use ctrl-v to visually select a column of numbers.  Then

QUICK DECIMAL INCREMENTING
	        :I [#]  will use the first line's number as a starting point
	                default increment (#) is 1
	                will justify left (pad right)
	                For more, see visincr-I

	        :II [# [zfill]]
	                will use the first line's number as a starting point
	                default increment (#) is 1
	                default zfill         is a blank (ex. :II 1 0)
	                will justify right (pad left)
	                For more, see visincr-II

	                   ORIG      I        II
	                   +---+   +----+   +----+
	                   | 8 |   | 8  |   |  8 |
	                   | 8 |   | 9  |   |  9 |
	                   | 8 |   | 10 |   | 10 |
	                   | 8 |   | 11 |   | 11 |
	                   +---+   +----+   +----+

		:IMOD [# [modulus [modoffset]]]
			Will use the first line's number as a starting
			point like :I; however, counts are displayed
			with
			  ((count - modoffset)%modulus ) + modoffset
			  default: increment is  1
			  default: modulus   is 10
			  default: modoffset is  0
	                For more, see visincr-IMOD

	                   ORIG     IMOD 1 3 1   IMOD 1 3
	                   +---+      +----+       +----+
	                   | 1 |      | 1  |       | 1  |
	                   | 1 |      | 2  |       | 2  |
	                   | 1 |      | 3  |       | 0  |
	                   | 1 |      | 1  |       | 1  |
	                   | 1 |      | 2  |       | 2  |
	                   | 1 |      | 3  |       | 0  |
	                   +---+      +----+       +----+

		:IREP [# [divisor [divoffset]]]
			Will use the first line's number as a starting
			point like :I; however, counts are displayed
			with
			  ((count - divoffset )/divisor + divoffset
			  default: increment is  1
			  default: divisor   is 10
			  default: divoffset is  0
	                For more, see visincr-IREP

	                   ORIG     IREP 1 2 1   IREP 1 2
	                   +---+      +----+       +----+
	                   | 1 |      | 1  |       | 0  |
	                   | 1 |      | 1  |       | 1  |
	                   | 1 |      | 2  |       | 1  |
	                   | 1 |      | 2  |       | 2  |
	                   | 1 |      | 3  |       | 2  |
	                   | 1 |      | 3  |       | 3  |
	                   +---+      +----+       +----+

QUICK OCTAL AND HEXADECIMAL INCREMENTING

	For octal and hexadecimal incrementing, use the variants
	(the increment is also octal or hexadecimal, respectively)

	        :IO [#]              :IX [#]
	        :IIO [# [zfil]]     :IIX [# [zfill]]

	                   ORIG      IO      IIO
	                   +---+   +----+   +----+
	                   | 6 |   | 6  |   |  6 |
	                   | 6 |   | 7  |   |  7 |
	                   | 6 |   | 10 |   | 10 |
	                   | 6 |   | 11 |   | 11 |
	                   +---+   +----+   +----+

	                   ORIG      IX      IIX
	                   +---+   +----+   +----+
	                   | 9 |   | 9  |   |  9 |
	                   | 9 |   | a  |   |  a |
	                   | 9 |   | b  |   |  b |
	                   | 9 |   | c  |   |  c |
	                   | 9 |   | d  |   |  d |
	                   | 9 |   | e  |   |  e |
	                   | 9 |   | f  |   |  f |
	                   | 9 |   | 10 |   | 10 |
	                   | 9 |   | 11 |   | 11 |
	                   +---+   +----+   +----+

QUICK DATE INCREMENTING

	        The following three commands need <calutil.vim> to do
	        their work:

	        :IYMD [#] Increment year/month/day dates (by optional # days)
	        :IMDY [#] Increment month/day/year dates (by optional # days)
	        :IDMY [#] Increment day/month/year dates (by optional # days)

	        For more: see visincr-IYMD, visincr-IMDY, and visincr-IDMY
	        (these calendar-based options require the calutil.vim plugin;
	        please see visincr-calutil on where to get it)

	        :ID  Increment days by name (Monday, Tuesday, etc).  If only
	             three or fewer letters are highlighted, then only
	             three-letter abbreviations will be used.
	             For more: see visincr-ID

	        :IA  Increment alphabetic lists
	             For more: see visincr-IA

	        :IM  Increment months by name (January, February, etc).
	             Like ID, if three or fewer letters are highlighted,
	             then only three-letter abbreviations will be used.
	             For more: see visincr-IM

QUICK RESTRICTED INCREMENTING

		:RI :RII :RIMDY :RIDMY :RID :RM visincr-restrict
	        :RI RII RIYMD RIMDY RIDMY RID RM
	             Restricted variants of the above commands - requires
	             that the visual block on the current line start with
	             an appropriate pattern (ie. a number for :I, a
	             dayname for :ID, a monthname for :IM, etc).
	             For more, see

	             Restricted left-justified incrementing......visincr-RI
	             Restricted right-justified incrementing.....visincr-RII
	             Restricted year/month/day incrementing......visincr-RIYMD
	             Restricted month/day/year incrementing......visincr-RIMDY
	             Restricted day/month/year incrementing......visincr-RIDMY
	             Restricted dayname incrementing.............visincr-RID
	             Restricted monthname incrementing...........visincr-RIM


==============================================================================
3. Increasing/Decreasing Lists		visincr-increase visincr-decrease
					visincr-increment visincr-decrement

The visincr plugin facilitates making a column of increasing or decreasing
numbers, dates, or daynames.

LEFT JUSTIFIED INCREMENTING			:I  visincr-I
	:I [#]  Will use the first line's number as a starting point to build
	        a column of increasing numbers (or decreasing numbers if the
	        increment is negative).

	            Default increment: 1
	            Justification    : left (will pad on the right)

	        The IX variant supports hexadecimal incrementing.

								visincr-RI
	        The restricted version (:RI) applies number incrementing only
	        to those lines in the visual block that begin with a number.

	        See visincr-raggedright for a discussion on ragged-right
	        handling.

	:IMOD [# [modulus [modoffset]]]		:IMOD visincr-IMOD
		Will use the first line's number as a starting point to
		build a column of increasing numbers using modulus
		arithmetic.  Each such number has an optional offset
		added to it.  Counts are displayed with

		    ((count - modoffset)%modulus ) + modoffset

		    Default modulus  : 10
		    Default modoffset: 0
	            Justification    : left (will pad on the right)

						:RIMOD visincr-RIMOD
	        The restricted version (:RIMOD) applies number incrementing
		using modulus arithmetic only to those lines in the visual
		block that begin with a number.

	:IREP [# [divisor [divoffset]]]		:IREP visincr-IREP
		Will use the first line's number as a starting point to
		build a column of increasing numbers using "repeating"
		arithmetic.  Each such number has an optional offset
		added to it.  Counts are displayed with

		    ((count - divoffset )/divisor + divoffset

		    Default divisor  : 10
		    Default divoffset: 0
	            Justification    : left (will pad on the right)

		The divisor essentially gives a count of the quantity
		of repeats that will be used.

						:RIREP visincr-RIREP
	        The restricted version (:RIREP) applies number incrementing
		using repeating arithmetic only to those lines in the visual
		block that begin with a number.

		:IB visincr-IB :IO visincr-IO :IX visincr-IX
	:IB [#] left justified binary incrementing
	:IO [#] left justified octal incrementing
	:IX [#] left justified hexadecimal incrementing
	        The commands above are variants of :I.  The increments are
	        in binary, octal, or hexadecimal for their respective commands.

			:IR visincr-IR :IIR visincr-IIR
	        These commands do left (IR) and right (IIR) justified
	        Roman numeral enumeration.  The increment for these
	        commands is in the usual arabic numerals (ie. decimal)
	        as Roman numerals don't support negative numbers.


RIGHT JUSTIFIED INCREMENTING			:II  visincr-II
	:II [# [zfill]]  Will use the first line's number as a starting point
	        to build a column of increasing numbers (or decreasing numbers
	        if the increment is negative).

	            Default increment: 1
	            Justification    : right (will pad on the left)
	            Zfill            : left padding will be done with the given
	                               character, typically a zero.


		:IIB visincr-IIB :IIO visincr-IIO :IIX visincr-IIX
	:IIB [# [zfill]] Does right-justified binary incrementing
	:IIO [# [zfill]] right justified octal incrementing
	:IIX [# [zfill]] right justified hexadecimal incrementing
	        These commands above are variants of :II.  Note that the
	        increments are specified in binary, octal, or hexadecimal,
	        respectively.

								visincr-RII
	        The restricted version (:RII) applies number incrementing only
	        to those lines in the visual block that begin with zero or more
	        spaces and end with a number.

RAGGED RIGHT HANDLING FOR I AND II		visincr-raggedright
	        For :I, :II, and variants:

	        If the visual block is ragged on the right-hand side (as can
	        easily happen when the "$" is used to select the
	        right-hand-side), the block will have spaces appended to
	        straighten it out.  If the string length of the count exceeds
	        the visual-block, then additional spaces will be inserted as
	        needed.  Leading tabs are handled by using virtual column
	        calculations.

DATE INCREMENTING
	:IYMD [# [zfill]]    year/month/day	IYMD	visincr-IYMD
	:IMDY [# [zfill]]    month/day/year	IMDY	visincr-IMDY
	:IDMY [# [zfill]]    day/month/year	IDMY	visincr-IDMY
	        Will use the starting line's date to construct an increasing
	        or decreasing list of dates, depending on the sign of the
	        number.  (these options need visincr-calutil)

	            Default increment: 1 (in days)

			visincr-RIYMD visincr-RIMDY visincr-RIDMY
	        Restricted versions (:RIYMD, :RIMDY, :RIDMY) applies number
	        incrementing only to those lines in the visual block that
	        begin with a date (#/#/#).

	        zfill: since dates include both single and double digits,
	        to line up the single digits must be padded.  By default,
	        visincr will pad the single-digits in dates with zeros.
	        However, one may get blank padding by using a backslash
	        and then a space:
			:IYMD 1 \
			         ^(space here)
	        Of course, one may use any charcter for such padding.

	        By default, English daynames and monthnames are used.
	        However, one may use whatever daynames and monthnames
	        one wishes by placing lines such as
			let g:visincr_dow  = "Mandag,Tirsdag,Onsdag,Torsdag,Fredag,Lørdag,Søndag"
			let g:visincr_month= "Janvier,Février,Mars,Avril,Mai,Juin,Juillet,Août,Septembre,Octobre,Novembre,Décembre"
	        in your <.vimrc> initialization file.  The two variables
	        (dow=day-of-week) should be set to a comma-delimited set of
	        words.
							g:visincr_datedivset
	        By default, the date dividers are: given by:
			let g:visincr_datedivset= '[-./_:~,+*^]\='
	        You may change the set in your <.vimrc>.  The separator actually
	        used is the first one found in your date column.  A date
	        divider is no longer strictly required (note that \= in the
	        date divider set).  For :IMDY and :IDMY and no date dividers,
	        the year may be 2 or 4 digits.  For :IYMD, the year must be
	        four digits if there are no date dividers.

SINGLE DIGIT DAYS OR MONTHS			visincr-leaddate

	        Single digit days or months are converted into two characters
	        by use of

			g:visincr_leaddate

	        which, by default, is '0'.  If you prefer blanks, simply put

			let g:visincr_leaddate= ' '

	        into your <.vimrc> file.

CALUTIL NEEDED FOR DATE INCREMENTING		visincr-calutil
	        For :IYMD, :IMDY, and IDMY:

	        These options utilize the <calutil.vim> plugin, available as
	        "Calendar Utilities" at the following url on the web:

	        http://www.drchip.org/astronaut/vim/index.html#VimFuncs

ALPHABETIC INCREMENTING				:IA visincr-IA
	:IA     Will produce an increasing/decreasing list of alphabetic
	        characters.

DAYNAME INCREMENTING			:ID visincr-ID visincr-RID
	:ID [#] Will produce an increasing/decreasing list of daynames.
	        Three-letter daynames will be used if the first day on the
	        first line is a three letter dayname; otherwise, full names
	        will be used.

	        Restricted version (:RID) applies number incrementing only
	        to those lines in the visual block that begin with a dayname
	        (mon tue wed thu fri sat).

MONTHNAME INCREMENTING			:IM visincr-IM visincr-RIM
	:IM [#] will produce an increasing/decreasing list of monthnames.
	        Monthnames may be three-letter versions (jan feb etc) or
	        fully-spelled out monthnames.

	        Restricted version (:RIM) applies number incrementing only
	        to those lines in the visual block that begin with a
	        monthname (jan feb mar etc).

POWER INCREMENTING	:IPOW  visincr-IPOW  visincr-IIPOW
	                :RIPOW visincr-RIPOW visincr-RIIPOW
	:IPOW [#] will produce an increasing/decreasing list of powers times
	        the starting point.  The multiplier(divisor)'s default value
	        is 2.

	        Restricted versions (:RIPOW and :RIIPOW) applies only
	        to those lines in the visual block that begin with
	        a number.


==============================================================================
4. Examples:						visincr-examples

LEFT JUSTIFIED INCREMENTING EXAMPLES
	:I                              :I 2            ex-visincr-I
	            Use ctrl-V to                   Use ctrl-V to
	Original    Select, :I          Original    Select, :I 2
	   8            8                  8            8
	   8            9                  8            10
	   8            10                 8            12
	   8            11                 8            14
	   8            12                 8            16

	:I -1                           :I -2
	            Use ctrl-V to                   Use ctrl-V to
	Original    Select, :I -1       Original    Select, :I -3
	   8            8                  8            8
	   8            7                  8            5
	   8            6                  8            2
	   8            5                  8            -1
	   8            4                  8            -4

RIGHT JUSTIFIED INCREMENTING EXAMPLES
	:II                             :II 2           ex-visincr-II
	            Use ctrl-V to                   Use ctrl-V to
	Original    Select, :II         Original    Select, :II 2
	   8             8                 8             8
	   8             9                 8            10
	   8            10                 8            12
	   8            11                 8            14
	   8            12                 8            16

	:II -1                          :II -2
	            Use ctrl-V to                   Use ctrl-V to
	Original    Select, :II -1      Original    Select, :II -3
	   8            8                  8             8
	   8            7                  8             5
	   8            6                  8             2
	   8            5                  8            -1
	   8            4                  8            -4

DATE INCREMENTING EXAMPLES
	:IMDY                                   ex-visincr-IMDY
	          Use ctrl-V to                   Use ctrl-V to
	Original  Select, :IMDY         Original  Select, :IMDY 7
	06/10/03     6/10/03            06/10/03     06/10/03
	06/10/03     6/11/03            06/10/03     06/17/03
	06/10/03     6/12/03            06/10/03     06/24/03
	06/10/03     6/13/03            06/10/03     07/01/03
	06/10/03     6/14/03            06/10/03     07/08/03


	:IYMD                                   ex-visincr-IYMD
	          Use ctrl-V to                   Use ctrl-V to
	Original  Select, :IYMD         Original  Select, :IYMD 7
	03/06/10    03/06/10            03/06/10    03/06/10
	03/06/10    03/06/11            03/06/10    03/06/17
	03/06/10    03/06/12            03/06/10    03/06/24
	03/06/10    03/06/13            03/06/10    03/07/ 1
	03/06/10    03/06/14            03/06/10    03/07/ 8


	:IDMY                                   ex-visincr-IDMY
	          Use ctrl-V to                   Use ctrl-V to
	Original  Select, :IDMY         Original  Select, :IDMY 7
	10/06/03    10/06/03            10/06/03    10/06/03
	10/06/03    11/06/03            10/06/03    17/06/03
	10/06/03    12/06/03            10/06/03    24/06/03
	10/06/03    13/06/03            10/06/03     1/07/03
	10/06/03    14/06/03            10/06/03     8/07/03


ALPHABETIC INCREMENTING EXAMPLES
	:IA                                     ex-visincr-IA
	          Use ctrl-V to                 Use ctrl-V to
	Original  Select, :IA         Original  Select, :IA 2
	   a)          a)                A)           A)
	   a)          b)                A)           C)
	   a)          c)                A)           E)
	   a)          d)                A)           G)

DAYNAME INCREMENTING EXAMPLES
	:ID                                     ex-visincr-ID
	          Use ctrl-V to                 Use ctrl-V to
	Original  Select, :ID         Original  Select, :ID 2
	  Sun       Sun                 Sun         Sun
	  Sun       Mon                 Sun         Tue
	  Sun       Tue                 Sun         Thu
	  Sun       Wed                 Sun         Sat
	  Sun       Thu                 Sun         Mon


	:ID
	          Use ctrl-V to                 Use ctrl-V to
	Original  Select, :ID         Original  Select, :ID 2
	 Sunday     Sunday             Sunday     Sunday
	 Sunday     Monday             Sunday     Monday
	 Sunday     Tuesday            Sunday     Tuesday
	 Sunday     Wednesday          Sunday     Wednesday
	 Sunday     Thursday           Sunday     Thursday

MONTHNAME INCREMENTING EXAMPLES
	:IM                                     ex-visincr-IM
	          Use ctrl-V to                 Use ctrl-V to
	Original  Select, :IM         Original  Select, :IM 2
	  Jan       Jan                 Jan       Jan
	  Jan       Feb                 Jan       Mar
	  Jan       Mar                 Jan       May
	  Jan       Apr                 Jan       Jul
	  Jan       May                 Jan       Sep

	:IM
	          Use ctrl-V to                 Use ctrl-V to
	Original  Select, :IM         Original  Select, :IM 2
	 January    January            January    January
	 January    February           January    March
	 January    March              January    May
	 January    April              January    July
	 January    May                January    September


==============================================================================
5. Options						visincr-options

    Default values are shown:

	let g:visincr_dow  ="Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday"
	let g:visincr_month="January,February,March,April,May,June,July,August,September,October,November,December"
	let g:visincr_datedivset= '[-./]'

    Respectively controls
      the day of week (ID),
      name of month   (IM), and
      dividers used by IMDY, IYMD, IDMY.

   g:visincr_longcmd
   If this variable exists, then "long" commands are provided rather than the
   normal ones; that is, all commands will be preceded with "VI_".
   In other words, VI_I, VI_II, VI_IMDY, etc., commands are provided.
   Put
	let g:visincr_longcmd= 1
  in your .vimrc (for it to take effect the variable must be set prior to
  loading visincrPlugin.vim).  Doing this reduces (does not eliminate) the
  possibility of command naming conflicts with other plugins.


==============================================================================
6. History:						visincr-history {{{1

	v20:	07/01/08	: Fixed :IIO and :IIX commands when they're given
				  two arguments (ex. :IIX 1 0).
		07//01/08	* Fixed a problem when 'selection' is
				  "exclusive" as happens with mswin.vim usage.
		06//18/09	* Included :IB and :IIB for binary incrementing
				* Included support for restricted incrementing:
				  :RIB, :RIIB, :RIO, :RIIO, :RIX, and :RIIX
		08//16/11	* g:visincr_longcmd provided to reduce command
				  naming conflicts amongst plugins.
		03/18/13	* (Gary Johnson) pointed out that changing
				  cedit to <Esc> caused problems with visincr;
				  the cedit setting is now bypassed
		01/09/14	* Included the :IMOD command.
		01/10/14	* Included the :IREP command.
		09/24/15	* Handles :behave mswin gracefully
		02/18/16	* Changed =~ matching to =~# or
				  =~?, as and when appropriate
		11/22/17	* :I and :II weren't picking up on an initial
				  negative number.  Fixed.
	v19:	12/19/07	: neglected to include calutil on the upload to
				  vim.sf.net, so a new version was made that
				  included it.
	v18:	02/13/07	: included :IPOW and variants
		02//15/07	* date dividers are no longer required
		10//17/07	* calutil.vim and calutil.txt included, and they
				  use vim 7's autoload feature
	v17:	07/26/06	: -complete=expression added to all visincr
				  commands
		07//27/06	* g:visincr_datedivset support included
	v16:	06/15/06	: :IX, :IIX, :IO, and :IIO now support negative
				   increments and negative counts
		07//13/06	* :IR :IIR (roman numeral) support included
	v14:	03/21/06	: :IX and :IIX implemented to support hexadecimal
				   incrementing
		03//25/06	* Visincr converted to use Vim 7.0's autoloading
		06//12/06	* Visincr will now direct users trying to do a
				  calendrical incrementing operation (:IMDY,:IYMD,
				  :IDMY) but missing calutil.vim to the help on
				  where to get it (visincr-calutil).
		06//12/06	* :IO and :IIO implemented to support octal
				  incrementing
	v13:	03/15/06	: a zfill of '' or "" now stands for an empty zfill
		03//16/06	* visincr now insures that the first character of
				  a month or day incrementing sequence (:IM, :ID)
				  is capitalized
				* (bugfix) names embedded in a line weren't being
				  incremented correctly; text to the right of the
				  daynames/monthnames went missing.  Fixed.
	v12:	04/20/05	: load-once variable changed to g:loaded_visincr
				  protected from users' cpo options
		05//06/05	* zfill capability provided to IDMY IMDY IYMD
		05//09/05	* g:visincr_dow and g:visincr_month now can be
				  set by the user to customize daynames and
				  monthnames.
		03//07/06	* passes my pluginkiller test (avoids more
				  problems causes by various options to vim)
	v11:	08/24/04	: g:visincr_leaddate implemented
	v10:	07/26/04	: :IM and :ID now handle varying length long-names
				  selected via linewise-visual mode
	v9 :	03//05/04	: included IA command
	v8 :	06//24/03	: added :IM command
				  added :RI .. :RM commands (restricted)
	v7 :	06//09/03	: bug fix -- years now retain leading zero
	v6 :	05//29/03	: bug fix -- pattern for IMDY IDMY IYMD didn't work
				  with text on the sides of dates; it now does
	v5 :	II		: implements 0-filling automatically if
				  the first number has the format	00/00...0#
		IYMD IMDY IDMY	: date incrementing, uses <calutil.vim>
		ID		: day-of-week incrementing
	v4			: gdefault option bypassed (saved/set nogd/restored)

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