*AsNeeded.txt*	Loading Functions, Maps, and Commands AsNeeded	Jul 02, 2015

Author:  Charles E. Campbell  <NcampObell@SdrPchip.AorgM-NOSPAM>
	  (remove NOSPAM from Campbell's email to use)
Copyright: (c) 2004-2011 by Charles E. Campbell		*asneeded-copyright*
           The VIM LICENSE applies to AsNeeded.vim and AsNeeded.txt
           (see |copyright|) except use "AsNeeded" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.

1. Contents						*asneeded-contents*

	1. Contents......................: |asneeded-contents|
	2. AsNeeded Manual...............: |asneeded|
	3. AsNeeded Global Variables.....: |asneeded-var|
	4. AsNeeded History..............: |asneeded-history|

2. AsNeeded Manual			*asneeded*  *:AN*  *:ANX* *:AsNeeded*

	The AsNeeded plugin transforms plugin use to either automatically
	loading or assisting in loading plugins when they're needed. >

		:AN command     :ANX command
		:AN map         :ANX map
	or >

		:AsNeeded command
		:AsNeeded map
	Functions are automatically loaded when called using the FuncUndefined
	event that Vim provides.  :AN or :AsNeeded assists with loading
	commands or maps by searching through plugin files placed in >

		.vim/AsNeeded/       (Unix)
		vimfiles\AsNeeded\   (Windows)
	for one containing the desired map or command; once found, AsNeeded
	then loads it.

	The ANX command follows successful searches with an attempt to execute
	the requested command or map.

	MAKING ANTAGS				*MakeANtags* *MkAsNeeded*
	For those who have large numbers of scripts in their AsNeeded directory,
	using either >

	will create an ANtags file in the AsNeeded directory.  This file will
	then be used to quickly look up the requested map, command, or
	function; the usual search of all scripts in the directory will then be


	Creating ANtags as shown in |MkAsNeeded| will also create ANmenu in
	the AsNeeded/ directory.  If sourced, say by the following code in
	your .vimrc, and if you're running gvim and have menus available, a
	DrChip.AsNeeded menu full of AsNeeded-loadable items is made
	available. >

	    let vimhome= substitute(&rtp,',.*$','','')
	    if filereadable(vimhome."/AsNeeded/ANmenu")
	      if has("menu") && has("gui_running") && &go =~ 'm'
	       exe "so ".vimhome."/AsNeeded/ANmenu"

3. AsNeeded Global Variables				*asneeded-var*

   	*g:AsNeededSuccess* : if this variable exists, then AsNeeded
	                      will inform the user of successful loading
			      of AsNeeded functions/commands/mappings.

	*g:AsNeededAutoMake*  : Set this variable to something like "ls -1t"
			      (Linux/Unix) and AsNeeded will automatically
			      invoke |MkAsNeeded| when necessary.  The
			      variable needs to hold a shell command which
			      will generate a time-sorted list of files, most
			      recent first.  If a *.vim file is present in
			      that list before the ANtags file, then AsNeeded
			      will automatically call MakeANtags().  If a
			      file has been removed w/o regenerating ANtags,
			      AsNeeded will (when that function/map/cmd is
			      invoked) detect the problem and re-generate

			      Typical settings:
			      	Linux/Unix: /bin/ls -1t
				Windows   : dir /b/a-d/o-d

4. AsNeeded History					*asneeded-history* {{{1

	v17	May 20, 2009	* when a help page was the only page, as may be
				  obtained with
				    gvim -c "exec \"he TOPIC\"|silent! only"
				  and a :AN (or :ANX) command was issued to load
				  a plugin, the help page was quit.  The problem
				  was that "q!" was applied to a temporary one-line
				  buffer and, although normally that works just
				  fine, with help pages it caused vim to quit.  A
				  bufwipe is now taken instead.
		Feb 22, 2011	* for menus, &go =~# used to insure correct case
		Jul 12, 2011	* commands with "!" forms may now be used with
				  :ANX.  Thus a :CMD! not previously loaded will
				  be loaded by AsNeeded and the :CMD! form is then
		Sep 21, 2011	* using histget() instead of a:cmdmap to do
				  commands; this means that ranges, arguments,
				  etc are now used after AsNeeded has loaded a
				  command's source.
		Sep 29, 2011	* MkAsNeeded made incorrect ANmenu entries when
				  dealing with single-letter commands.  Fixed.
		Oct 23, 2012 	* |:bwipe|-ing the AsNeeded/ANtags buffer after
				  use so as not to have it appear in the |:ls|! list
		Jul 02, 2015	* Changed %d to %d _ to use black hole register
	v16	Mar 14, 2007	* ANtags had full paths; it now generates AsNeeded/
				  relative paths and the AsNeeded() function
				  compensates by prepending path information.
				  Reduces file size and allows ANtags to be moved
				  from machine to machine without changes.
		Apr 11, 2007	* A try-catch-endtry handles problems with rvim
				  with g:AsNeededAutoMake (avoids problems with
				  shell invocation not being allowed).
		Oct 10, 2007	* Saves/restores magic setting
		Feb 06, 2008	* :MkAsNeeded now creates ANmenu; this is a vim
				  script which, if sourced, will create a
				  DrChip.AsNeeded menu full of AsNeeded-loadable
		Jun 10, 2008	* Executing a command that AsNeeded loads now shows
				  that command's output if you have |'cmdheight'|
				  greater than or equal to 2.
		Aug 01, 2008	* improved cmdsrch to skip -complete=... and other
				  command options.
	v15	Sep 21, 2006	* if AsNeeded/ANtags exists, but a file therein was
				  removed w/o re-generating ANtags, AsNeeded will,
				  if |g:AsNeededAutoMake| exists, re-make the
				  ANtags file.  A message will be issued
				  irregardless and settings restored.
				* As Bill McCarthy pointed out, I intended for
				  g:AsNeededAutoMake to also source the resulting
				  ANtags file; unfortunately, it was still sourcing
				  the previous one.  Fixed!
		Sep 25, 2006	* fnamemodify() used instead of a substitute to
				  get the directory name holding ANtags.
				  (Bill McCarthy)
				* AsNeeded now handles silent[!] before commands
				  during :MkAsNeeded
		Feb 22, 2007	* v15h addressed having no mapleader with a map
				  defined as \abc (ie.the map itself has that leading
		Feb 23, 2007	* v15i handles having no mapleader but the maps are
				  <Leader>abc style. (done at prodding of B McCarthy!)
	v14	Jul 31, 2006	* Taglist does a quick-loading trick that involved
				  using FuncUndefined autocmds.  AsNeeded now defers
				  to taglist instead of issuing a warning.
				* ei=all was inadvertently being left on; thus no
				  autocmds were operational after AsNeeded
				  successfully loaded a function.  Fixed!
				* included |'patchmode'| in the SaveSettings() and
				  RestoreSettings() bypass functions
				* |g:AsNeededAutoMake| support implemented
				  (Z Sekera's suggestion)
	v13	Mar 23, 2006	* The search for a map wasn't looking for
				  <Leader>amap when asked for :ANX \amap ; instead,
				  AsNeeded was incorrectly looking for <Leader>\amap.
				* AsNeeded's successful loading message managed to
				  disappear from view (again).  I've deferred
				  showing it until the end of the function.
				* Used Thomas's idea for ANcmds.vim plugin
				  generation, which sets up skeleton commands.
	v12	Mar 07, 2006	* AsNeeded now saves and restores settings in such
				  a way that if a command/map/script-sourcing
				  changes vim settings it will be retained, instead
				  of whatever settings were in effect when AsNeeded
				  was first invoked
	v11	Jan 03, 2006	* Bugfix -- AsNeeded's success message sometimes
				  caused an error because srchstring didn't exist
		Jan 25, 2006	* internally used temporary buffers now wiped out
		Feb 10, 2006	* keeps/restores lz option
	v10	Aug 08, 2005	* Bugfix -- maps with backslashes are escaped
		Aug 17, 2005	* report option workaround
	v9	Mar 15, 2005	* MakeANtags command search pattern improved
				* MakeANtags' function search pattern improved
		Apr 22, 2005	* maps beginning with a backslash needed one extra
				  leading backslash in their search pattern for ANtags
	v8	Feb 16, 2005	* With MakeANtags, AsNeeded's search pattern needed
				  to use \\| instead of \|
	v7	Feb 16, 2005	* MakeANtags now warns the user when no tags were
				  found in some vim-script file
				* MakeANtags would occasionally miss certain maps
				  when making ANtags
				* MakeANtags was omitting the backslashes in
				  Windows paths
	v6	Sep 20, 2004	* bug left in debugging code fixed
		Dec 29, 2004	* wipes out temporarily used buffers
		Feb 09, 2005	* MakeANtags and ANtags support included
	v5	Aug 06, 2004	* ANX cmd [args] now accepted.
				* improved command vs map detection: uses maparg()
				* ANX bugfix, now detects maps vs commands and
				  attempts to execute them appropriately
	v4	Jul 12, 2004	* bugfix: somewhen the AsNeeded loading of commands
				  got dropped.
	v3	May 19, 2004	* bugfix: now works correctly when mapleader
				  wasn't set by user explicitly
				* ANX command/map (an AsNeeded find coupled with
	v2	Apr 05, 2004	* bugfix: an error message showed up when the
				  ../.vim/AsNeeded directory was empty of *.vim
				* improved warning message when no matching
				  command/function/map is found
	v1	Feb 19, 2004	* AsNeeded first released