forked from aniani/vim
483 lines
21 KiB
Plaintext
483 lines
21 KiB
Plaintext
*pi_getscript.txt* For Vim version 9.0. Last change: 2017 Aug 01
|
|
>
|
|
GETSCRIPT REFERENCE MANUAL by Charles E. Campbell
|
|
<
|
|
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
|
|
(remove NOSPAM from the email address)
|
|
*GetLatestVimScripts-copyright*
|
|
Copyright: (c) 2004-2012 by Charles E. Campbell *glvs-copyright*
|
|
The VIM LICENSE (see |copyright|) applies to the files in this
|
|
package, including getscriptPlugin.vim, getscript.vim,
|
|
GetLatestVimScripts.dist, and pi_getscript.txt, except use "getscript"
|
|
instead of "Vim". Like anything else that's free, getscript and its
|
|
associated files are provided *as is* and comes with no warranty of
|
|
any kind, either expressed or implied. No guarantees of
|
|
merchantability. No guarantees of suitability for any purpose. By
|
|
using this plugin, you agree that in no event will the copyright
|
|
holder be liable for any damages resulting from the use of this
|
|
software. Use at your own risk!
|
|
|
|
Getscript is a plugin that simplifies retrieval of the latest versions of the
|
|
scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will
|
|
then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to
|
|
get the latest versions of scripts listed therein from http://vim.sf.net/.
|
|
|
|
==============================================================================
|
|
1. Contents *glvs-contents* *glvs* *getscript*
|
|
*GetLatestVimScripts*
|
|
|
|
1. Contents........................................: |glvs-contents|
|
|
2. GetLatestVimScripts -- Getting Started..........: |glvs-install|
|
|
3. GetLatestVimScripts Usage.......................: |glvs-usage|
|
|
4. GetLatestVimScripts Data File...................: |glvs-data|
|
|
5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins|
|
|
6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall|
|
|
7. GetLatestViMScripts Options.....................: |glvs-options|
|
|
8. GetLatestVimScripts Algorithm...................: |glvs-alg|
|
|
9. GetLatestVimScripts History.....................: |glvs-hist|
|
|
|
|
|
|
==============================================================================
|
|
2. GetLatestVimScripts -- Getting Started *getscript-start*
|
|
*getlatestvimscripts-install*
|
|
|
|
VERSION FROM VIM DISTRIBUTION *glvs-dist-install*
|
|
|
|
Vim 7.0 does not include the GetLatestVimScripts.dist file which
|
|
serves as an example and a template. So, you'll need to create
|
|
your own! See |GetLatestVimScripts_dat|.
|
|
|
|
VERSION FROM VIM SF NET *glvs-install*
|
|
|
|
NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist
|
|
file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for
|
|
the first time.
|
|
|
|
The GetLatestVimScripts.dist file serves as an example and a template for your
|
|
own personal list. Feel free to remove all the scripts mentioned within it;
|
|
the "important" part of it is the first two lines.
|
|
|
|
Your computer needs to have wget or curl for GetLatestVimScripts to do its work.
|
|
|
|
1. if compressed: gunzip getscript.vba.gz
|
|
2. Unix:
|
|
vim getscript.vba
|
|
:so %
|
|
:q
|
|
cd ~/.vim/GetLatest
|
|
mv GetLatestVimScripts.dist GetLatestVimScripts.dat
|
|
(edit GetLatestVimScripts.dat to install your own personal
|
|
list of desired plugins -- see |GetLatestVimScripts_dat|)
|
|
|
|
3. Windows:
|
|
vim getscript.vba
|
|
:so %
|
|
:q
|
|
cd **path-to-vimfiles**/GetLatest
|
|
mv GetLatestVimScripts.dist GetLatestVimScripts.dat
|
|
(edit GetLatestVimScripts.dat to install your own personal
|
|
list of desired plugins -- see |GetLatestVimScripts_dat|)
|
|
|
|
|
|
==============================================================================
|
|
3. GetLatestVimScripts Usage *glvs-usage* *:GLVS*
|
|
|
|
Unless it has been defined elsewhere, >
|
|
|
|
:GLVS
|
|
|
|
will invoke GetLatestVimScripts(). If some other plugin has defined that
|
|
command, then you may type
|
|
>
|
|
:GetLatestVimScripts
|
|
<
|
|
The script will attempt to update and, if permitted, will automatically
|
|
install scripts from http://vim.sourceforge.net/. To do so it will peruse a
|
|
file,
|
|
>
|
|
.vim/GetLatest/GetLatestVimScripts.dat (unix)
|
|
<
|
|
or >
|
|
..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows)
|
|
(see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin
|
|
directory (see |glvs-plugins|).
|
|
|
|
Scripts which have been downloaded will appear in the
|
|
~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows)
|
|
subdirectory. GetLatestVimScripts will attempt to automatically
|
|
install them if you have the following line in your <.vimrc>: >
|
|
|
|
let g:GetLatestVimScripts_allowautoinstall=1
|
|
|
|
The <GetLatestVimScripts.dat> file will be automatically be updated to
|
|
reflect the latest version of script(s) so downloaded.
|
|
(also see |glvs-options|)
|
|
|
|
|
|
==============================================================================
|
|
4. GetLatestVimScripts Data File *getscript-data* *glvs-data*
|
|
*:GetLatestVimScripts_dat*
|
|
The data file <GetLatestVimScripts.dat> must have for its first two lines
|
|
the following text:
|
|
>
|
|
ScriptID SourceID Filename
|
|
--------------------------
|
|
<
|
|
Following those two lines are three columns; the first two are numeric
|
|
followed by a text column. The GetLatest/GetLatestVimScripts.dist file
|
|
contains an example of such a data file. Anything following a #... is
|
|
ignored, so you may embed comments in the file.
|
|
|
|
The first number on each line gives the script's ScriptID. When you're about
|
|
to use a web browser to look at scripts on http://vim.sf.net/, just before you
|
|
click on the script's link, you'll see a line resembling
|
|
|
|
http://vim.sourceforge.net/scripts/script.php?script_id=40
|
|
|
|
The "40" happens to be a ScriptID that GetLatestVimScripts needs to
|
|
download the associated page, and is assigned by vim.sf.net itself
|
|
during initial uploading of the plugin.
|
|
|
|
The second number on each line gives the script's SourceID. The SourceID
|
|
records the count of uploaded scripts as determined by vim.sf.net; hence it
|
|
serves to indicate "when" a script was uploaded. Setting the SourceID to 1
|
|
insures that GetLatestVimScripts will assume that the script it has is
|
|
out-of-date.
|
|
|
|
The SourceID is extracted by GetLatestVimScripts from the script's page on
|
|
vim.sf.net; whenever it is greater than the one stored in the
|
|
GetLatestVimScripts.dat file, the script will be downloaded
|
|
(see |GetLatestVimScripts_dat|).
|
|
|
|
If your script's author has included a special comment line in his/her plugin,
|
|
the plugin itself will be used by GetLatestVimScripts to build your
|
|
<GetLatestVimScripts.dat> file, including any dependencies on other scripts it
|
|
may have. As an example, consider: >
|
|
|
|
" GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim
|
|
|
|
This comment line tells getscript.vim to check vimscript #884 and that the
|
|
script is automatically installable. Getscript will also use this line to
|
|
help build the GetLatestVimScripts.dat file, by including a line such as: >
|
|
|
|
884 1 :AutoInstall: AutoAlign.vim
|
|
<
|
|
assuming that such a line isn't already in GetLatestVimScripts.dat file.
|
|
See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a
|
|
comprehensive ability to keep your plugins up-to-date!
|
|
|
|
In summary:
|
|
|
|
* Optionally tell getscript that it is allowed to build/append a
|
|
GetLatestVimScripts.dat file based upon already installed plugins: >
|
|
let g:GetLatestVimScripts_allowautoinstall=1
|
|
<
|
|
* A line such as >
|
|
" GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim
|
|
< in an already-downloaded plugin constitutes the concurrence of the
|
|
plugin author that getscript may do AutoInstall. Not all plugins
|
|
may be AutoInstall-able, and the plugin's author is best situated
|
|
to know whether or not his/her plugin will AutoInstall properly.
|
|
|
|
* A line such as >
|
|
884 1 :AutoInstall: AutoAlign.vim
|
|
< in your GetLatestVimScripts.dat file constitutes your permission
|
|
to getscript to do AutoInstall. AutoInstall requires both your
|
|
and the plugin author's permission. See |GetLatestVimScripts_dat|.
|
|
|
|
|
|
*GetLatestVimScripts_dat*
|
|
As an example of a <GetLatestVimScripts.dat> file:
|
|
>
|
|
ScriptID SourceID Filename
|
|
--------------------------
|
|
294 1 :AutoInstall: Align.vim
|
|
120 2 Decho.vim
|
|
40 3 DrawIt.tar.gz
|
|
451 4 EasyAccents.vim
|
|
195 5 engspchk.vim
|
|
642 6 GetLatestVimScripts.vim
|
|
489 7 Manpageview.vim
|
|
<
|
|
Note: the first two lines are required, but essentially act as comments.
|
|
|
|
|
|
==============================================================================
|
|
5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins*
|
|
|
|
(this section is for plugin authors)~
|
|
|
|
If a plugin author includes the following comment anywhere in their plugin,
|
|
GetLatestVimScripts will find it and use it to automatically build the user's
|
|
GetLatestVimScripts.dat files:
|
|
>
|
|
src_id
|
|
v
|
|
" GetLatestVimScripts: ### ### yourscriptname
|
|
^
|
|
scriptid
|
|
<
|
|
As an author, you should include such a line in to refer to your own script
|
|
plus any additional lines describing any plugin dependencies it may have.
|
|
Same format, of course!
|
|
|
|
If your command is auto-installable (see |glvs-autoinstall|), and most scripts
|
|
are, then you may include :AutoInstall: just before "yourscriptname":
|
|
>
|
|
src_id
|
|
v
|
|
" GetLatestVimScripts: ### ### :AutoInstall: yourscriptname
|
|
^
|
|
scriptid
|
|
<
|
|
NOTE: The :AutoInstall: feature requires both the plugin author's and~
|
|
the user's permission to operate!~
|
|
|
|
GetLatestVimScripts commands for those scripts are then appended, if not
|
|
already present, to the user's GetLatest/GetLatestVimScripts.dat file. It is
|
|
a relatively painless way to automate the acquisition of any scripts your
|
|
plugins depend upon.
|
|
|
|
Now, as an author, you probably don't want GetLatestVimScripts to download
|
|
your own scripts atop your own copy, thereby overwriting your not-yet-released
|
|
hard work. GetLatestVimScripts provides a solution for this: put
|
|
>
|
|
0 0 yourscriptname
|
|
<
|
|
into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip
|
|
examining the "yourscriptname" scripts for those GetLatestVimScripts comment
|
|
lines. As a result, those lines won't be inadvertently installed into your
|
|
<GetLatestVimScripts.dat> file and subsequently used to download your own
|
|
scripts. This is especially important to do if you've included the
|
|
:AutoInstall: option.
|
|
|
|
Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line
|
|
as you've used in your GetLatestVimScripts comment!
|
|
|
|
|
|
==============================================================================
|
|
6. GetLatestVimScripts AutoInstall *getscript-autoinstall*
|
|
*glvs-autoinstall*
|
|
|
|
GetLatestVimScripts now supports "AutoInstall". Not all scripts are
|
|
supportive of auto-install, as they may have special things you need to do to
|
|
install them (please refer to the script's "install" directions). On the
|
|
other hand, most scripts will be auto-installable.
|
|
|
|
To let GetLatestVimScripts do an autoinstall, the data file's comment field
|
|
should begin with (surrounding blanks are ignored): >
|
|
|
|
:AutoInstall:
|
|
<
|
|
Both colons are needed, and it should begin the comment (yourscriptname)
|
|
field.
|
|
|
|
One may prevent any autoinstalling by putting the following line in your
|
|
<.vimrc>: >
|
|
|
|
let g:GetLatestVimScripts_allowautoinstall= 0
|
|
<
|
|
With :AutoInstall: enabled, as it is by default, files which end with
|
|
|
|
---.tar.bz2 : decompressed & untarred in .vim/ directory
|
|
---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it
|
|
---.vim.bz2 : decompressed & moved into .vim/plugin directory
|
|
---.tar.gz : decompressed & untarred in .vim/ directory
|
|
---.vba.gz : decompressed in .vim/ directory, then vimball handles it
|
|
---.vim.gz : decompressed & moved into .vim/plugin directory
|
|
---.vba : unzipped in .vim/ directory
|
|
---.vim : moved to .vim/plugin directory
|
|
---.zip : unzipped in .vim/ directory
|
|
|
|
and which merely need to have their components placed by the untar/gunzip or
|
|
move-to-plugin-directory process should be auto-installable. Vimballs, of
|
|
course, should always be auto-installable.
|
|
|
|
When is a script not auto-installable? Let me give an example:
|
|
|
|
.vim/after/syntax/blockhl.vim
|
|
|
|
The <blockhl.vim> script provides block highlighting for C/C++ programs; it is
|
|
available at:
|
|
|
|
http://vim.sourceforge.net/scripts/script.php?script_id=104
|
|
|
|
Currently, vim's after/syntax only supports by-filetype scripts (in
|
|
blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install would
|
|
possibly overwrite the current user's after/syntax/c.vim file.
|
|
|
|
In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to
|
|
allow a after/syntax/c/ directory:
|
|
|
|
http://vim.sourceforge.net/scripts/script.php?script_id=1023
|
|
|
|
The script allows multiple syntax files to exist separately in the
|
|
after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and build an
|
|
appropriate tarball for auto-install because of the potential for the
|
|
after/syntax/c.vim contained in it to overwrite a user's c.vim.
|
|
|
|
|
|
==============================================================================
|
|
7. GetLatestVimScripts Options *glvs-options*
|
|
>
|
|
g:GetLatestVimScripts_wget
|
|
< default= "wget"
|
|
This variable holds the name of the command for obtaining
|
|
scripts.
|
|
>
|
|
g:GetLatestVimScripts_options
|
|
< default= "-q -O"
|
|
This variable holds the options to be used with the
|
|
g:GetLatestVimScripts_wget command.
|
|
>
|
|
g:GetLatestVimScripts_allowautoinstall
|
|
< default= 1
|
|
This variable indicates whether GetLatestVimScripts is allowed
|
|
to attempt to automatically install scripts. Furthermore, the
|
|
plugin author has to have explicitly indicated that his/her
|
|
plugin is automatically installable (via the :AutoInstall:
|
|
keyword in the GetLatestVimScripts comment line).
|
|
>
|
|
g:GetLatestVimScripts_autoinstalldir
|
|
< default= $HOME/.vim (linux)
|
|
default= $HOME/vimfiles (windows)
|
|
Override where :AutoInstall: scripts will be installed.
|
|
Doesn't override vimball installation.
|
|
>
|
|
g:GetLatestVimScripts_scriptaddr
|
|
< default='http://vim.sourceforge.net/script.php?script_id='
|
|
Override this if your system needs
|
|
... ='http://vim.sourceforge.net/script/script.php?script_id='
|
|
|
|
==============================================================================
|
|
8. GetLatestVimScripts Algorithm *glvs-algorithm* *glvs-alg*
|
|
|
|
The Vim sourceforge page dynamically creates a page by keying off of the
|
|
so-called script-id. Within the webpage of
|
|
|
|
http://vim.sourceforge.net/scripts/script.php?script_id=40
|
|
|
|
is a line specifying the latest source-id (src_id). The source identifier
|
|
numbers are always increasing, hence if the src_id is greater than the one
|
|
recorded for the script in GetLatestVimScripts then it's time to download a
|
|
newer copy of that script.
|
|
|
|
GetLatestVimScripts will then download the script and update its internal
|
|
database of script ids, source ids, and scriptnames.
|
|
|
|
The AutoInstall process will:
|
|
|
|
Move the file from GetLatest/ to the following directory
|
|
Unix : $HOME/.vim
|
|
Windows: $HOME\vimfiles
|
|
if the downloaded file ends with ".bz2"
|
|
bunzip2 it
|
|
else if the downloaded file ends with ".gz"
|
|
gunzip it
|
|
if the resulting file ends with ".zip"
|
|
unzip it
|
|
else if the resulting file ends with ".tar"
|
|
tar -oxvf it
|
|
else if the resulting file ends with ".vim"
|
|
move it to the plugin subdirectory
|
|
|
|
|
|
==============================================================================
|
|
9. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1
|
|
|
|
v36 Apr 22, 2013 : * (glts) suggested use of plugin/**/*.vim instead of
|
|
plugin/*.vim in globpath() call.
|
|
* (Andy Wokula) got warning message when setting
|
|
g:loaded_getscriptPlugin
|
|
v35 Apr 07, 2012 : * (MengHuan Yu) pointed out that the script URL has
|
|
changed (somewhat). However, it doesn't work, and
|
|
the original one does (under Linux). I'll make it
|
|
yet-another-option.
|
|
v34 Jun 23, 2011 : * handles additional decompression options for tarballs
|
|
(tgz taz tbz txz)
|
|
v33 May 31, 2011 : * using fnameescape() instead of escape()
|
|
* *.xz support
|
|
v32 Jun 19, 2010 : * (Jan Steffens) added support for xz compression
|
|
v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
|
|
* (David Schaefer) the acd option interferes with vimballs
|
|
Solution: bypass the acd option
|
|
v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
|
|
issue an error message if it is not supported
|
|
v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that
|
|
getscriptPlugin.vim was setting it but not restoring it.
|
|
v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin
|
|
interface, register-a bypass
|
|
Oct 29, 2007 * Bill McCarthy suggested a change to getscript that avoids
|
|
creating pop-up windows
|
|
v24 Apr 16, 2007 : * removed save&restore of the fo option during script
|
|
loading
|
|
v23 Nov 03, 2006 : * ignores comments (#...)
|
|
* handles vimballs
|
|
v22 Oct 13, 2006 : * supports automatic use of curl if wget is not
|
|
available
|
|
v21 May 01, 2006 : * now takes advantage of autoloading.
|
|
v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
|
|
unzip needs the -o flag to overwrite.
|
|
v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
|
|
script! Fixed.
|
|
v18 Mar 21, 2005 : * bugfix to automatic database construction
|
|
* bugfix - nowrapscan caused an error
|
|
(tnx to David Green for the fix)
|
|
Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in
|
|
:AutoInstall:s, even though its o/s is windows
|
|
Apr 01, 2005 * when downloading errors occurred, GLVS was
|
|
terminating early. It now just goes on to trying
|
|
the next script (after trying three times to
|
|
download a script description page)
|
|
Apr 20, 2005 * bugfix - when a failure to download occurred,
|
|
GetLatestVimScripts would stop early and claim that
|
|
everything was current. Fixed.
|
|
v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
|
|
defaults to 1, can be used to prevent all
|
|
:AutoInstall:
|
|
v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
|
|
* fixed bug with :AutoInstall: use of helptags
|
|
v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
|
|
always preventing downloads (just usually). Fixed.
|
|
v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
|
|
s:dotvim. Fixed.
|
|
v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
|
|
is zero. Useful for script authors; that way their
|
|
own GetLatestVimScripts activity won't overwrite
|
|
their scripts.
|
|
v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
|
|
was intended only for testing. Removed, now works.
|
|
* :AutoInstall: implemented
|
|
v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
|
|
* :GetLatestVimScripts command
|
|
* (runtimepath)/GetLatest/GetLatestVimScripts.dat
|
|
now holds scripts that need updating
|
|
v10 Apr 19, 2004 : * moved history from script to doc
|
|
v9 Jan 23, 2004 : windows (win32/win16/win95) will use
|
|
double quotes ("") whereas other systems will use
|
|
single quotes ('') around the urls in calls via wget
|
|
v8 Dec 01, 2003 : makes three tries at downloading
|
|
v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id="
|
|
not found in downloaded webpage
|
|
Uses t_ti, t_te, and rs to make progress visible
|
|
v6 Aug 06, 2003 : final status messages now display summary of work
|
|
( "Downloaded someqty scripts" or
|
|
"Everything was current")
|
|
Now GetLatestVimScripts is careful about downloading
|
|
GetLatestVimScripts.vim itself!
|
|
(goes to <NEW_GetLatestVimScripts.vim>)
|
|
v5 Aug 04, 2003 : missing an endif near bottom
|
|
v4 Jun 17, 2003 : redraw! just before each "considering" message
|
|
v3 May 27, 2003 : Protects downloaded files from errant shell
|
|
expansions with single quotes: '...'
|
|
v2 May 14, 2003 : extracts name of item to be obtained from the
|
|
script file. Uses it instead of comment field
|
|
for output filename; comment is used in the
|
|
"considering..." line and is now just a comment!
|
|
* Fixed a bug: a string-of-numbers is not the
|
|
same as a number, so I added zero to them
|
|
and they became numbers. Fixes comparison.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:fdm=marker
|