pi_getscript.txt (22783B)
1 *pi_getscript.txt* For Vim version 9.2. Last change: 2026 Aug 17 2 > 3 GETSCRIPT REFERENCE MANUAL by Charles E. Campbell 4 < 5 Original Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> 6 (remove NOSPAM from the email address) 7 *GetLatestVimScripts-copyright* 8 Copyright: (c) 2004-2012 by Charles E. Campbell *glvs-copyright* 9 The VIM LICENSE (see |copyright|) applies to the files in this 10 package, including getscriptPlugin.vim, getscript.vim, 11 GetLatestVimScripts.dist, and pi_getscript.txt, except use "getscript" 12 instead of "Vim". Like anything else that's free, getscript and its 13 associated files are provided *as is* and comes with no warranty of 14 any kind, either expressed or implied. No guarantees of 15 merchantability. No guarantees of suitability for any purpose. By 16 using this plugin, you agree that in no event will the copyright 17 holder be liable for any damages resulting from the use of this 18 software. Use at your own risk! 19 20 Getscript is a plugin that simplifies retrieval of the latest versions of the 21 scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will 22 then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to 23 get the latest versions of scripts listed therein from https://www.vim.org/. 24 25 ============================================================================== 26 1. Contents *glvs-contents* *glvs* *getscript* 27 *GetLatestVimScripts* 28 29 1. Contents........................................: |glvs-contents| 30 2. GetLatestVimScripts -- Getting Started..........: |glvs-install| 31 3. GetLatestVimScripts Usage.......................: |glvs-usage| 32 4. GetLatestVimScripts Data File...................: |glvs-data| 33 5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins| 34 6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall| 35 7. GetLatestViMScripts Options.....................: |glvs-options| 36 8. GetLatestVimScripts Algorithm...................: |glvs-alg| 37 9. GetLatestVimScripts History.....................: |glvs-hist| 38 39 40 ============================================================================== 41 2. GetLatestVimScripts -- Getting Started *getscript-start* 42 *getlatestvimscripts-install* 43 44 VERSION FROM VIM DISTRIBUTION *glvs-dist-install* 45 46 Vim 7.0 does not include the GetLatestVimScripts.dist file which 47 serves as an example and a template. So, you'll need to create 48 your own! See |GetLatestVimScripts_dat|. 49 50 VERSION FROM VIM SF NET *glvs-install* 51 52 NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist 53 file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for 54 the first time. 55 56 The GetLatestVimScripts.dist file serves as an example and a template for your 57 own personal list. Feel free to remove all the scripts mentioned within it; 58 the "important" part of it is the first two lines. 59 60 Your computer needs to have wget or curl for GetLatestVimScripts to do its 61 work. 62 63 1. if compressed: gunzip getscript.vmb.gz 64 2. Unix: 65 vim getscript.vmb 66 :so % 67 :q 68 cd ~/.vim/GetLatest 69 mv GetLatestVimScripts.dist GetLatestVimScripts.dat 70 (edit GetLatestVimScripts.dat to install your own personal 71 list of desired plugins -- see |GetLatestVimScripts_dat|) 72 73 3. Windows: 74 vim getscript.vmb 75 :so % 76 :q 77 cd **path-to-vimfiles**/GetLatest 78 mv GetLatestVimScripts.dist GetLatestVimScripts.dat 79 (edit GetLatestVimScripts.dat to install your own personal 80 list of desired plugins -- see |GetLatestVimScripts_dat|) 81 82 PREVENT LOADING 83 84 If you want to use plugins, but for some reason don't wish to use getscript, 85 then you can avoid loading the getscript plugin by adding the following to 86 your |vimrc|: > 87 88 :let g:loaded_getscriptPlugin = 1 89 < 90 91 ============================================================================== 92 3. GetLatestVimScripts Usage *glvs-usage* *:GLVS* 93 94 Unless it has been defined elsewhere, > 95 96 :GLVS 97 98 will invoke GetLatestVimScripts(). If some other plugin has defined that 99 command, then you may type 100 > 101 :GetLatestVimScripts 102 < 103 The script will attempt to update and, if permitted, will automatically 104 install scripts from http://vim.sourceforge.net/. To do so it will peruse a 105 file, 106 > 107 .vim/GetLatest/GetLatestVimScripts.dat (unix) 108 < 109 or > 110 ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows) 111 (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin 112 directory (see |glvs-plugins|). 113 114 Scripts which have been downloaded will appear in the 115 ~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows) 116 subdirectory. GetLatestVimScripts will attempt to automatically 117 install them if you have the following line in your <.vimrc>: > 118 119 let g:GetLatestVimScripts_allowautoinstall=1 120 121 The <GetLatestVimScripts.dat> file will be automatically be updated to 122 reflect the latest version of script(s) so downloaded. 123 (also see |glvs-options|) 124 125 126 ============================================================================== 127 4. GetLatestVimScripts Data File *getscript-data* *glvs-data* 128 *:GetLatestVimScripts_dat* 129 The data file <GetLatestVimScripts.dat> must have for its first two lines 130 the following text: 131 > 132 ScriptID SourceID Filename 133 -------------------------- 134 < 135 Following those two lines are three columns; the first two are numeric 136 followed by a text column. The GetLatest/GetLatestVimScripts.dist file 137 contains an example of such a data file. Anything following a #... is 138 ignored, so you may embed comments in the file. 139 140 The first number on each line gives the script's ScriptID. When you're about 141 to use a web browser to look at scripts on http://vim.sf.net/, just before you 142 click on the script's link, you'll see a line resembling 143 144 http://vim.sourceforge.net/scripts/script.php?script_id=40 145 146 The "40" happens to be a ScriptID that GetLatestVimScripts needs to 147 download the associated page, and is assigned by vim.sf.net itself 148 during initial uploading of the plugin. 149 150 The second number on each line gives the script's SourceID. The SourceID 151 records the count of uploaded scripts as determined by vim.sf.net; hence it 152 serves to indicate "when" a script was uploaded. Setting the SourceID to 1 153 insures that GetLatestVimScripts will assume that the script it has is 154 out-of-date. 155 156 The SourceID is extracted by GetLatestVimScripts from the script's page on 157 vim.sf.net; whenever it is greater than the one stored in the 158 GetLatestVimScripts.dat file, the script will be downloaded 159 (see |GetLatestVimScripts_dat|). 160 161 If your script's author has included a special comment line in his/her plugin, 162 the plugin itself will be used by GetLatestVimScripts to build your 163 <GetLatestVimScripts.dat> file, including any dependencies on other scripts it 164 may have. As an example, consider: > 165 166 " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim 167 168 This comment line tells getscript.vim to check Vim script #884 and that the 169 script is automatically installable. Getscript will also use this line to 170 help build the GetLatestVimScripts.dat file, by including a line such as: > 171 172 884 1 :AutoInstall: AutoAlign.vim 173 < 174 assuming that such a line isn't already in GetLatestVimScripts.dat file. 175 See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a 176 comprehensive ability to keep your plugins up-to-date! 177 178 In summary: 179 180 * Optionally tell getscript that it is allowed to build/append a 181 GetLatestVimScripts.dat file based upon already installed plugins: > 182 let g:GetLatestVimScripts_allowautoinstall=1 183 < 184 * A line such as > 185 " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim 186 < in an already-downloaded plugin constitutes the concurrence of the 187 plugin author that getscript may do AutoInstall. Not all plugins 188 may be AutoInstall-able, and the plugin's author is best situated 189 to know whether or not his/her plugin will AutoInstall properly. 190 191 * A line such as > 192 884 1 :AutoInstall: AutoAlign.vim 193 < in your GetLatestVimScripts.dat file constitutes your permission 194 to getscript to do AutoInstall. AutoInstall requires both your 195 and the plugin author's permission. See |GetLatestVimScripts_dat|. 196 197 198 *GetLatestVimScripts_dat* 199 As an example of a <GetLatestVimScripts.dat> file: 200 > 201 ScriptID SourceID Filename 202 -------------------------- 203 294 1 :AutoInstall: Align.vim 204 120 2 Decho.vim 205 40 3 DrawIt.tar.gz 206 451 4 EasyAccents.vim 207 195 5 engspchk.vim 208 642 6 GetLatestVimScripts.vim 209 489 7 Manpageview.vim 210 < 211 Note: the first two lines are required, but essentially act as comments. 212 213 214 ============================================================================== 215 5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins* 216 217 (this section is for plugin authors)~ 218 219 If a plugin author includes the following comment anywhere in their plugin, 220 GetLatestVimScripts will find it and use it to automatically build the user's 221 GetLatestVimScripts.dat files: 222 > 223 src_id 224 v 225 " GetLatestVimScripts: ### ### yourscriptname 226 ^ 227 scriptid 228 < 229 As an author, you should include such a line in to refer to your own script 230 plus any additional lines describing any plugin dependencies it may have. 231 Same format, of course! 232 233 If your command is auto-installable (see |glvs-autoinstall|), and most scripts 234 are, then you may include :AutoInstall: just before "yourscriptname": 235 > 236 src_id 237 v 238 " GetLatestVimScripts: ### ### :AutoInstall: yourscriptname 239 ^ 240 scriptid 241 < 242 NOTE: The :AutoInstall: feature requires both the plugin author's and~ 243 the user's permission to operate!~ 244 245 GetLatestVimScripts commands for those scripts are then appended, if not 246 already present, to the user's GetLatest/GetLatestVimScripts.dat file. It is 247 a relatively painless way to automate the acquisition of any scripts your 248 plugins depend upon. 249 250 Now, as an author, you probably don't want GetLatestVimScripts to download 251 your own scripts atop your own copy, thereby overwriting your not-yet-released 252 hard work. GetLatestVimScripts provides a solution for this: put 253 > 254 0 0 yourscriptname 255 < 256 into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip 257 examining the "yourscriptname" scripts for those GetLatestVimScripts comment 258 lines. As a result, those lines won't be inadvertently installed into your 259 <GetLatestVimScripts.dat> file and subsequently used to download your own 260 scripts. This is especially important to do if you've included the 261 :AutoInstall: option. 262 263 Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line 264 as you've used in your GetLatestVimScripts comment! 265 266 267 ============================================================================== 268 6. GetLatestVimScripts AutoInstall *getscript-autoinstall* 269 *glvs-autoinstall* 270 271 GetLatestVimScripts now supports "AutoInstall". Not all scripts are 272 supportive of auto-install, as they may have special things you need to do to 273 install them (please refer to the script's "install" directions). On the 274 other hand, most scripts will be auto-installable. 275 276 To let GetLatestVimScripts do an autoinstall, the data file's comment field 277 should begin with (surrounding blanks are ignored): > 278 279 :AutoInstall: 280 < 281 Both colons are needed, and it should begin the comment (yourscriptname) 282 field. 283 284 One may prevent any autoinstalling by putting the following line in your 285 <.vimrc>: > 286 287 let g:GetLatestVimScripts_allowautoinstall= 0 288 < 289 With :AutoInstall: enabled, as it is by default, files which end with 290 291 ---.tar.bz2 : decompressed & untarred in .vim/ directory 292 ---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it 293 ---.vmb.bz2 : idem 294 ---.vim.bz2 : decompressed & moved into .vim/plugin directory 295 ---.tar.gz : decompressed & untarred in .vim/ directory 296 ---.vba.gz : decompressed in .vim/ directory, then vimball handles it 297 ---.vmb.gz : idem 298 ---.vim.gz : decompressed & moved into .vim/plugin directory 299 ---.vba : moved to .vim/ directory, then vimball handles it 300 ---.vmb : idem 301 ---.vim : moved to .vim/plugin directory 302 ---.zip : unzipped in .vim/ directory 303 304 and which merely need to have their components placed by the untar/gunzip or 305 move-to-plugin-directory process should be auto-installable. Vimballs, of 306 course, should always be auto-installable. 307 308 When is a script not auto-installable? Let me give an example: 309 310 .vim/after/syntax/blockhl.vim 311 312 The <blockhl.vim> script provides block highlighting for C/C++ programs; it is 313 available at: 314 315 https://www.vim.org/scripts/script.php?script_id=104 316 317 Currently, vim's after/syntax only supports by-filetype scripts (in 318 blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install would 319 possibly overwrite the current user's after/syntax/c.vim file. 320 321 In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to 322 allow a after/syntax/c/ directory: 323 324 https://www.vim.org/scripts/script.php?script_id=1023 325 326 The script allows multiple syntax files to exist separately in the 327 after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and build an 328 appropriate tarball for auto-install because of the potential for the 329 after/syntax/c.vim contained in it to overwrite a user's c.vim. 330 331 332 ============================================================================== 333 7. GetLatestVimScripts Options *glvs-options* 334 > 335 g:GetLatestVimScripts_wget 336 < default= "wget" 337 This variable holds the name of the command for obtaining 338 scripts. 339 > 340 g:GetLatestVimScripts_options 341 < default= "-q -O" 342 This variable holds the options to be used with the 343 g:GetLatestVimScripts_wget command. 344 > 345 g:GetLatestVimScripts_allowautoinstall 346 < default= 1 347 This variable indicates whether GetLatestVimScripts is allowed 348 to attempt to automatically install scripts. Furthermore, the 349 plugin author has to have explicitly indicated that his/her 350 plugin is automatically installable (via the :AutoInstall: 351 keyword in the GetLatestVimScripts comment line). 352 > 353 g:GetLatestVimScripts_autoinstalldir 354 < default= $HOME/.vim (linux) 355 default= $HOME/vimfiles (windows) 356 Override where :AutoInstall: scripts will be installed. 357 Doesn't override vimball installation. 358 > 359 g:GetLatestVimScripts_scriptaddr 360 < default='https://www.vim.org/scripts/script.php?script_id=' 361 > 362 g:GetLatestVimScripts_downloadaddr 363 < default='https://www.vim.org/scripts/download_script.php?src_id=' 364 > 365 g:GetLatestVimScripts_bunzip2 366 < default= bunzip2 367 This variable holds the name of the command to decompress .bz2 368 files 369 > 370 g:GetLatestVimScripts_bunzip3 371 < default= bunzip3 372 This variable holds the name of the command to decompress .bz3 373 files 374 > 375 g:GetLatestVimScripts_gunzip 376 < default= gunzip 377 This variable holds the name of the command to decompress .gz 378 files 379 > 380 g:GetLatestVimScripts_unxz 381 < default= unxz 382 This variable holds the name of the command to decompress .xz 383 files 384 > 385 g:GetLatestVimScripts_unzip 386 < default= unzip 387 This variable holds the name of the command to decompress .zip 388 files 389 390 Note: The variables associated with decompression commands help workaround 391 crossplatform issues. For example, on Windows is possible to delegate 392 this calls into `wsl` by doing: > 393 394 let g:GetLatestVimScripts_bunzip2= "wsl -e bunzip2" 395 let g:GetLatestVimScripts_gunzip= "wsl -e gunzip" 396 let g:GetLatestVimScripts_unxz= "wsl -e unxz" 397 let g:GetLatestVimScripts_unzip= "wsl -e unzip" 398 < 399 ============================================================================== 400 8. GetLatestVimScripts Algorithm *glvs-algorithm* *glvs-alg* 401 402 The Vim sourceforge page dynamically creates a page by keying off of the 403 so-called script-id. Within the webpage of 404 405 https://www.vim.org/scripts/script.php?script_id=40 406 407 is a line specifying the latest source-id (src_id). The source identifier 408 numbers are always increasing, hence if the src_id is greater than the one 409 recorded for the script in GetLatestVimScripts then it's time to download a 410 newer copy of that script. 411 412 GetLatestVimScripts will then download the script and update its internal 413 database of script ids, source ids, and scriptnames. 414 415 The AutoInstall process will: 416 417 Move the file from GetLatest/ to the following directory 418 Unix : $HOME/.vim 419 Windows: $HOME\vimfiles 420 if the downloaded file ends with ".bz2" 421 bunzip2 it 422 else if the downloaded file ends with ".bz3" 423 bunzip3 it 424 else if the downloaded file ends with ".gz" 425 gunzip it 426 if the resulting file ends with ".zip" 427 unzip it 428 else if the resulting file ends with ".tar" 429 tar -oxvf it 430 else if the resulting file ends with ".vim" 431 move it to the plugin subdirectory 432 433 434 ============================================================================== 435 9. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1 436 437 v38 Feb 25, 2025 : * handles additional decompression option for .bzip3 files. 438 v37 Sep 23, 2024 : * Support for the new vimball's .vmb extension (old .vba 439 extension conflicted with visual basic). 440 * Support for |glvs-autoinstall| in ftplugins and packages. 441 * Allow platform driven customization of decompressing 442 commands. 443 v36 Apr 22, 2013 : * (glts) suggested use of plugin/**/*.vim instead of 444 plugin/*.vim in globpath() call. 445 * (Andy Wokula) got warning message when setting 446 g:loaded_getscriptPlugin 447 v35 Apr 07, 2012 : * (MengHuan Yu) pointed out that the script URL has 448 changed (somewhat). However, it doesn't work, and 449 the original one does (under Linux). I'll make it 450 yet-another-option. 451 v34 Jun 23, 2011 : * handles additional decompression options for tarballs 452 (tgz taz tbz txz) 453 v33 May 31, 2011 : * using fnameescape() instead of escape() 454 * *.xz support 455 v32 Jun 19, 2010 : * (Jan Steffens) added support for xz compression 456 v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript 457 * (David Schaefer) the acd option interferes with vimballs 458 Solution: bypass the acd option 459 v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will 460 issue an error message if it is not supported 461 v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that 462 getscriptPlugin.vim was setting it but not restoring it. 463 v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin 464 interface, register-a bypass 465 Oct 29, 2007 * Bill McCarthy suggested a change to getscript that avoids 466 creating pop-up windows 467 v24 Apr 16, 2007 : * removed save&restore of the fo option during script 468 loading 469 v23 Nov 03, 2006 : * ignores comments (#...) 470 * handles vimballs 471 v22 Oct 13, 2006 : * supports automatic use of curl if wget is not 472 available 473 v21 May 01, 2006 : * now takes advantage of autoloading. 474 v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use; 475 unzip needs the -o flag to overwrite. 476 v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong 477 script! Fixed. 478 v18 Mar 21, 2005 : * bugfix to automatic database construction 479 * bugfix - nowrapscan caused an error 480 (tnx to David Green for the fix) 481 Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in 482 :AutoInstall:s, even though its o/s is windows 483 Apr 01, 2005 * when downloading errors occurred, GLVS was 484 terminating early. It now just goes on to trying 485 the next script (after trying three times to 486 download a script description page) 487 Apr 20, 2005 * bugfix - when a failure to download occurred, 488 GetLatestVimScripts would stop early and claim that 489 everything was current. Fixed. 490 v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which 491 defaults to 1, can be used to prevent all 492 :AutoInstall: 493 v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent 494 * fixed bug with :AutoInstall: use of helptags 495 v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't 496 always preventing downloads (just usually). Fixed. 497 v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than 498 s:dotvim. Fixed. 499 v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid 500 is zero. Useful for script authors; that way their 501 own GetLatestVimScripts activity won't overwrite 502 their scripts. 503 v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that 504 was intended only for testing. Removed, now works. 505 * :AutoInstall: implemented 506 v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin: 507 * :GetLatestVimScripts command 508 * (runtimepath)/GetLatest/GetLatestVimScripts.dat 509 now holds scripts that need updating 510 v10 Apr 19, 2004 : * moved history from script to doc 511 v9 Jan 23, 2004 : windows (win32/win16/win95) will use 512 double quotes ("") whereas other systems will use 513 single quotes ('') around the urls in calls via wget 514 v8 Dec 01, 2003 : makes three tries at downloading 515 v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id=" 516 not found in downloaded webpage 517 Uses t_ti, t_te, and rs to make progress visible 518 v6 Aug 06, 2003 : final status messages now display summary of work 519 ( "Downloaded someqty scripts" or 520 "Everything was current") 521 Now GetLatestVimScripts is careful about downloading 522 GetLatestVimScripts.vim itself! 523 (goes to <NEW_GetLatestVimScripts.vim>) 524 v5 Aug 04, 2003 : missing an endif near bottom 525 v4 Jun 17, 2003 : redraw! just before each "considering" message 526 v3 May 27, 2003 : Protects downloaded files from errant shell 527 expansions with single quotes: '...' 528 v2 May 14, 2003 : extracts name of item to be obtained from the 529 script file. Uses it instead of comment field 530 for output filename; comment is used in the 531 "considering..." line and is now just a comment! 532 * Fixed a bug: a string-of-numbers is not the 533 same as a number, so I added zero to them 534 and they became numbers. Fixes comparison. 535 536 ============================================================================== 537 vim:tw=78:ts=8:noet:ft=help:fdm=marker