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

Author:  Charles E. Campbell  <drNchipO@ScampbellPfamilyA.bizM>
	  (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

		:MakeANtags
		:MkAsNeeded

	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
	bypassed.

	MAKING ANMENU				ANmenu

	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"
	      endif
	    endif


==============================================================================
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
			      ANtags.

			      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
				  executed.
		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
				  things.
		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
				  backslash).
		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.
				  Fixed.
				* 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
				  silently
		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
				  execution)
	v2	Apr 05, 2004	* bugfix: an error message showed up when the
				  ../.vim/AsNeeded directory was empty of *.vim
				  files
				* improved warning message when no matching
				  command/function/map is found
	v1	Feb 19, 2004	* AsNeeded first released

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