1*pi_getscript.txt* For Vim version 7.2c. Last change: 2008 Jun 29 2> 3 GETSCRIPT REFERENCE MANUAL by Charles E. Campbell, Jr. 4< 5Authors: Charles E. Campbell, Jr. <[email protected]> 6 (remove NOSPAM from the email address) 7 *GetLatestVimScripts-copyright* 8Copyright: (c) 2004-2006 by Charles E. Campbell, Jr. *glvs-copyright* 9 The VIM LICENSE applies to getscript.vim and 10 pi_getscript.txt (see |copyright|) except use 11 "getscript" instead of "Vim". No warranty, express or implied. 12 Use At-Your-Own-Risk. 13 14Getscript is a plugin that simplifies retrieval of the latest versions of the 15scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will 16then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to 17get the latest versions of scripts listed therein from http://vim.sf.net/. 18 19============================================================================== 201. Contents *glvs-contents* *glvs* *getscript* 21 *GetLatestVimScripts* 22 23 1. Contents........................................: |glvs-contents| 24 2. GetLatestVimScripts -- Getting Started..........: |glvs-install| 25 3. GetLatestVimScripts Usage.......................: |glvs-usage| 26 4. GetLatestVimScripts Data File...................: |glvs-data| 27 5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins| 28 6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall| 29 7. GetLatestViMScripts Options.....................: |glvs-options| 30 8. GetLatestVimScripts Algorithm...................: |glvs-alg| 31 9. GetLatestVimScripts History.....................: |glvs-hist| 32 33 34============================================================================== 352. GetLatestVimScripts -- Getting Started *getscript-start* 36 *getlatestvimscripts-install* 37 38 VERSION FROM VIM DISTRIBUTION *glvs-dist-install* 39 40Vim 7.0 does not include the GetLatestVimScripts.dist file which 41serves as an example and a template. So, you'll need to create 42your own! See |GetLatestVimScripts_dat|. 43 44 VERSION FROM VIM SF NET *glvs-install* 45 46NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist 47file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for 48the first time. 49 50The GetLatestVimScripts.dist file serves as an example and a template for your 51own personal list. Feel free to remove all the scripts mentioned within it; 52the "important" part of it is the first two lines. 53 54Your computer needs to have wget for GetLatestVimScripts to do its work. 55 56 1. if compressed: gunzip getscript.vba.gz 57 2. Unix: 58 vim getscript.vba 59 :so % 60 :q 61 cd ~/.vim/GetLatest 62 mv GetLatestVimScripts.dist GetLatestVimScripts.dat 63 (edit GetLatestVimScripts.dat to install your own personal 64 list of desired plugins -- see |GetLatestVimScripts_dat|) 65 66 3. Windows: 67 vim getscript.vba 68 :so % 69 :q 70 cd **path-to-vimfiles**/GetLatest 71 mv GetLatestVimScripts.dist GetLatestVimScripts.dat 72 (edit GetLatestVimScripts.dat to install your own personal 73 list of desired plugins -- see |GetLatestVimScripts_dat|) 74 75 76============================================================================== 773. GetLatestVimScripts Usage *glvs-usage* *:GLVS* 78 79Unless its been defined elsewhere, > 80 :GLVS 81will invoke GetLatestVimScripts(). If some other plugin has defined that 82command, then you may type 83> 84 :GetLatestVimScripts 85< 86The script will attempt to update and, if permitted, will automatically 87install scripts from http://vim.sourceforge.net/. To do so it will peruse a 88file, 89> 90 .vim/GetLatest/GetLatestVimScripts.dat (unix) 91< 92or > 93 ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows) 94(see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin 95directory (see |glvs-plugins|). 96 97Scripts which have been downloaded will appear in the 98~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows) 99subdirectory. GetLatestVimScripts will attempt to automatically 100install them if you have the following line in your <.vimrc>: > 101 102 let g:GetLatestVimScripts_allowautoinstall=1 103 104The <GetLatestVimScripts.dat> file will be automatically be updated to 105reflect the latest version of script(s) so downloaded. 106(also see |glvs-options|) 107 108 109============================================================================== 1104. GetLatestVimScripts Data File *getscript-data* *glvs-data* 111 *:GetLatestVimScripts_dat* 112The data file <GetLatestVimScripts.dat> must have for its first two lines 113the following text: 114> 115 ScriptID SourceID Filename 116 -------------------------- 117< 118Following those two lines are three columns; the first two are numeric 119followed by a text column. The GetLatest/GetLatestVimScripts.dist file 120contains an example of such a data file. Anything following a #... is 121ignored, so you may embed comments in the file. 122 123The first number on each line gives the script's ScriptID. When you're about 124to use a web browser to look at scripts on http://vim.sf.net/, just before you 125click on the script's link, you'll see a line resembling 126 127 http://vim.sourceforge.net/scripts/script.php?script_id=40 128 129The "40" happens to be a ScriptID that GetLatestVimScripts needs to 130download the associated page. 131 132The second number on each line gives the script's SourceID. The SourceID 133records the count of uploaded scripts as determined by vim.sf.net; hence it 134serves to indicate "when" a script was uploaded. Setting the SourceID to 1 135insures that GetLatestVimScripts will assume that the script it has is 136out-of-date. 137 138The SourceID is extracted by GetLatestVimScripts from the script's page on 139vim.sf.net; whenever its greater than the one stored in the 140GetLatestVimScripts.dat file, the script will be downloaded 141(see |GetLatestVimScripts_dat|). 142 143If your script's author has included a special comment line in his/her plugin, 144the plugin itself will be used by GetLatestVimScripts to build your 145<GetLatestVimScripts.dat> file, including any dependencies on other scripts it 146may have. As an example, consider: > 147 148 " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim 149 150This comment line tells getscript.vim to check vimscript #884 and that the 151script is automatically installable. Getscript will also use this line to 152help build the GetLatestVimScripts.dat file, by including a line such as: > 153 154 884 1 AutoAlign.vim 155< 156in it an AutoAlign.vim line isn't already in GetLatestVimScripts.dat file. 157See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a 158comprehensive ability to keep your plugins up-to-date! 159 160 *GetLatestVimScripts_dat* 161As an example of a <GetLatestVimScripts.dat> file: 162> 163 ScriptID SourceID Filename 164 -------------------------- 165 294 1 Align.vim 166 120 2 decho.vim 167 40 3 DrawIt.tar.gz 168 451 4 EasyAccents.vim 169 195 5 engspchk.vim 170 642 6 GetLatestVimScripts.vim 171 489 7 Manpageview.vim 172< 173Note: the first two lines are required, but essentially act as comments. 174 175 176============================================================================== 1775. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins* 178 179If a plugin author includes the following comment anywhere in their plugin, 180GetLatestVimScripts will find it and use it to automatically build the user's 181GetLatestVimScripts.dat files: 182> 183 src_id 184 v 185 " GetLatestVimScripts: ### ### yourscriptname 186 ^ 187 scriptid 188< 189As an author, you should include such a line in to refer to your own script 190plus any additional lines describing any plugin dependencies it may have. 191Same format, of course! 192 193If your command is auto-installable (see |glvs-autoinstall|), and most scripts 194are, then you may include :AutoInstall: at the start of "yourscriptname". 195 196GetLatestVimScripts commands for those scripts are then appended, if not 197already present, to the user's GetLatest/GetLatestVimScripts.dat file. Its a 198relatively painless way to automate the acquisition of any scripts your 199plugins depend upon. 200 201Now, as an author, you probably don't want GetLatestVimScripts to download 202your own scripts for you yourself, thereby overwriting your not-yet-released 203hard work. GetLatestVimScripts provides a solution for this: put 204> 205 0 0 yourscriptname 206< 207into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip 208examining the "yourscriptname" scripts for those GetLatestVimScripts comment 209lines. As a result, those lines won't be inadvertently installed into your 210<GetLatestVimScripts.dat> file and subsequently used to download your own 211scripts. This is especially important to do if you've included the 212:AutoInstall: option. 213 214Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line 215as you've used in your GetLatestVimScripts comment! 216 217 218============================================================================== 2196. GetLatestVimScripts AutoInstall *getscript-autoinstall* 220 *glvs-autoinstall* 221 222GetLatestVimScripts now supports "AutoInstall". Not all scripts are 223supportive of auto-install, as they may have special things you need to do to 224install them (please refer to the script's "install" directions). On the 225other hand, most scripts will be auto-installable. 226 227To let GetLatestVimScripts do an autoinstall, the data file's comment field 228should begin with (surrounding blanks are ignored): > 229 230 :AutoInstall: 231< 232Both colons are needed, and it should begin the comment (yourscriptname) 233field. 234 235One may prevent any autoinstalling by putting the following line in your 236<.vimrc>: > 237 238 let g:GetLatestVimScripts_allowautoinstall= 0 239< 240With :AutoInstall: enabled, as it is by default, files which end with 241 242 ---.tar.bz2 : decompressed & untarred in .vim/ directory 243 ---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it 244 ---.vim.bz2 : decompressed & moved into .vim/plugin directory 245 ---.tar.gz : decompressed & untarred in .vim/ directory 246 ---.vba.gz : decompressed in .vim/ directory, then vimball handles it 247 ---.vim.gz : decompressed & moved into .vim/plugin directory 248 ---.vba : unzipped in .vim/ directory 249 ---.vim : moved to .vim/plugin directory 250 ---.zip : unzipped in .vim/ directory 251 252and which merely need to have their components placed by the untar/gunzip or 253move-to-plugin-directory process should be auto-installable. Vimballs, of 254course, should always be auto-installable. 255 256When is a script not auto-installable? Let me give an example: 257 258 .vim/after/syntax/blockhl.vim 259 260The <blockhl.vim> script provides block highlighting for C/C++ programs; it is 261available at: 262 263 http://vim.sourceforge.net/scripts/script.php?script_id=104 264 265Currently, vim's after/syntax only supports by-filetype scripts (in 266blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install would 267possibly overwrite the current user's after/syntax/c.vim file. 268 269In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to 270allow a after/syntax/c/ directory: 271 272 http://vim.sourceforge.net/scripts/script.php?script_id=1023 273 274The script allows multiple syntax files to exist separately in the 275after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and build an 276appropriate tarball for auto-install because of the potential for the 277after/syntax/c.vim contained in it to overwrite a user's c.vim. 278 279 280============================================================================== 2817. GetLatestVimScripts Options *glvs-options* 282> 283 g:GetLatestVimScripts_wget 284< default= "wget" 285 This variable holds the name of the command for obtaining 286 scripts. 287> 288 g:GetLatestVimScripts_options 289< default= "-q -O" 290 This variable holds the options to be used with the 291 g:GetLatestVimScripts_wget command. 292> 293 g:getLatestVimScripts_allowautoinstall 294< default= 1 295 This variable indicates whether GetLatestVimScripts is allowed 296 to attempt to automatically install scripts. Note that it 297 doesn't understand vimballs (yet). Furthermore, the plugin 298 author has to have explicitly indicated that his/her plugin 299 is automatically installable. 300 301 302============================================================================== 3038. GetLatestVimScripts Algorithm *glvs-algorithm* *glvs-alg* 304 305The Vim sourceforge page dynamically creates a page by keying off of the 306so-called script-id. Within the webpage of 307 308 http://vim.sourceforge.net/scripts/script.php?script_id=40 309 310is a line specifying the latest source-id (src_id). The source identifier 311numbers are always increasing, hence if the src_id is greater than the one 312recorded for the script in GetLatestVimScripts then it's time to download a 313newer copy of that script. 314 315GetLatestVimScripts will then download the script and update its internal 316database of script ids, source ids, and scriptnames. 317 318The AutoInstall process will: 319 320 Move the file from GetLatest/ to the following directory 321 Unix : $HOME/.vim 322 Windows: $HOME\vimfiles 323 if the downloaded file ends with ".bz2" 324 bunzip2 it 325 else if the downloaded file ends with ".gz" 326 gunzip it 327 if the resulting file ends with ".zip" 328 unzip it 329 else if the resulting file ends with ".tar" 330 tar -oxvf it 331 else if the resulting file ends with ".vim" 332 move it to the plugin subdirectory 333 334 335============================================================================== 3369. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1 337 338v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript 339v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will 340 issue an error message if its not supported 341v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that 342 getscriptPlugin.vim was setting it but not restoring it. 343v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin 344 interface, register-a bypass 345 Oct 29, 2007 * Bill McCarthy suggested a change to getscript that avoids 346 creating pop-up windows 347v24 Apr 16, 2007 : * removed save&restore of the fo option during script 348 loading 349v23 Nov 03, 2006 : * ignores comments (#...) 350 * handles vimballs 351v22 Oct 13, 2006 : * supports automatic use of curl if wget is not 352 available 353v21 May 01, 2006 : * now takes advantage of autoloading. 354v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use; 355 unzip needs the -o flag to overwrite. 356v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong 357 script! Fixed. 358v18 Mar 21, 2005 : * bugfix to automatic database construction 359 * bugfix - nowrapscan caused an error 360 (tnx to David Green for the fix) 361 Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in 362 :AutoInstall:s, even though its o/s is windows 363 Apr 01, 2005 * when downloading errors occurred, GLVS was 364 terminating early. It now just goes on to trying 365 the next script (after trying three times to 366 download a script description page) 367 Apr 20, 2005 * bugfix - when a failure to download occurred, 368 GetLatestVimScripts would stop early and claim that 369 everything was current. Fixed. 370v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which 371 defaults to 1, can be used to prevent all 372 :AutoInstall: 373v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent 374 * fixed bug with :AutoInstall: use of helptags 375v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't 376 always preventing downloads (just usually). Fixed. 377v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than 378 s:dotvim. Fixed. 379v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid 380 is zero. Useful for script authors; that way their 381 own GetLatestVimScripts activity won't overwrite 382 their scripts. 383v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that 384 was intended only for testing. Removed, now works. 385 * :AutoInstall: implemented 386v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin: 387 * :GetLatestVimScripts command 388 * (runtimepath)/GetLatest/GetLatestVimScripts.dat 389 now holds scripts that need updating 390v10 Apr 19, 2004 : * moved history from script to doc 391v9 Jan 23, 2004 : windows (win32/win16/win95) will use 392 double quotes ("") whereas other systems will use 393 single quotes ('') around the urls in calls via wget 394v8 Dec 01, 2003 : makes three tries at downloading 395v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id=" 396 not found in downloaded webpage 397 Uses t_ti, t_te, and rs to make progress visible 398v6 Aug 06, 2003 : final status messages now display summary of work 399 ( "Downloaded someqty scripts" or 400 "Everything was current") 401 Now GetLatestVimScripts is careful about downloading 402 GetLatestVimScripts.vim itself! 403 (goes to <NEW_GetLatestVimScripts.vim>) 404v5 Aug 04, 2003 : missing an endif near bottom 405v4 Jun 17, 2003 : redraw! just before each "considering" message 406v3 May 27, 2003 : Protects downloaded files from errant shell 407 expansions with single quotes: '...' 408v2 May 14, 2003 : extracts name of item to be obtained from the 409 script file. Uses it instead of comment field 410 for output filename; comment is used in the 411 "considering..." line and is now just a comment! 412 * Fixed a bug: a string-of-numbers is not the 413 same as a number, so I added zero to them 414 and they became numbers. Fixes comparison. 415 416============================================================================== 417vim:tw=78:ts=8:ft=help:fdm=marker 418