The plugin vsutil.vim contains utility functions used by several of my plugins. I do think, however, they are much more generic than the use they were designed for and put to in these plugins. I therefore have put together this documentation for the potential user.

At present, there are 10 public functions and one script local function, which is accessed by a command. There are also 2 other commands related to this one. I will address them here in no particular order other than the order in which they appear in the plugin, which is completely irrelevant.

IsVimNmr returns Boolean 0 or 1 based on whether or not its argument variable’s content is wholly numeric. Typically it is called in an if statement:

if IsVimNmr({numVar})

Do something with number

IsVimIdent returns Boolean 0 or 1 based on whether or not its argument variable’s content conforms to Vim identifier convention.

if IsVimIdent({identVar})

Use the identifier

IsVimVar returns Boolean –1 or 0 or 1 based on whether or not its argument variable is an identifier and if so, does it exist. The Boolean is –1 == valid, non-existent, 1 == valid, exist, and 0 == invalid.

let g:foo=1

function Foo(var)

echo IsVimVar(a:var)

endfunction

call Foo(‘g:foo’)

call Foo(‘foo’)

call Foo(‘0defects’)

-1

IsStrLit returns Boolean 0 or 1 based on whether or not its argument is enclosed in matching quotes. This is handy for removing quotes where they’re not wanted, adding them when they’re wanted, or telling whether or not you need to dereference.

IsArryDecl, which probably doesn’t belong here, but here it is for now at least, returns –1, 0, or 1.

RGBtoHex returns the hex of a 0-255 RGB value. This was written as part of a response to a posting and I’ve just kept it around for general purposes.

Next comes a fairly useful pair of utilities that are based on a variation of strtok. They are IsStrListTok and StrListTok. The former returns Boolean based on whether or not its argument is a token separated list defined by the current token delimiter. The latter parses a token separated list defined by the current token delimiter and returns the next token. Decision on the delimiter is as follows:

· Optional argument to the function

· Existence of a buffer variable (b:strListTokDelim)

· Existence of a script variable (s:strListTokDelim)

· Existence of a global variable (g:strListTokDelim)

· Default of comma or newline

if IsStrListTok(myList)

let myTok=StrListTok(myList,’b:myList’)

while myTok != ‘’

Use token

let myTok=StrListTok(‘’,’b:myList’)

endwhile

unlet b:myList

endif

The above would parse a comma/newline separated list of tokens, while the following would do the same with a colon separated list.

if IsStrListTok(myList,’:’)

let myTok=StrListTok(myList,’b:myList’,’:’)

while myTok != ‘’

Use token

let myTok=StrListTok(‘’,’b:myList’)

endwhile

unlet b:myList

endif

QualifiedPath decides if its argument is a fully qualified path file name using the contents of the variable b:QPATH as a pattern. The default is '^\(\~\|\h:\|\\\|/\)'.

FileParts is a lot like an MS/DOS C function I used once upon a time, but I can’t really remember the name of it. Anyway, it takes its first argument, a qualified path or file name that can be expanded into one, and breaks it down into its constituent parts. It puts results into any ‘referenced’ variables you pass to it, empty references indicating no interest in the part.

call FileParts(fname,’myFullName’,’myPathName’,’myName’,’myExt’)

The next group consists of 3 commands and one script-local function. It is for placing debug messages in code, which can be turned on and off. To start with, you need to execute the command SUDEBUGMSG to set up debugging with the name of a parent script. This is done by executing the command outside of any function in the script of your choice. Next, in any scripts that make up the functionality of the parent script and in the parent script itself you place debug commands of the form:

DEBUGMSG msg[,lvl]

Where msg is a string

lvl is 0 for normal

1 for warning

> 1 for error

if not specified, 0 for normal

echomsg format <parent-script>::<functions(s)>: <message>

displayed in black for normal

red for warning

reverse red for error

Display of the messages is toggled on and off by executing the command TGLDEBUGMSG.

Pause() is a function that allows echo-ing of messages/information and pausing to assure that they are seen.

Pause(msg)

The msg is displayed and the prompt ‘Press a key to continue’, giving the user an opportunity to view the information.

Sorting functions/commands from example by Robert Webb added. See :h eval-examples ‘Sorting lines (by Robert Webb)’ for details.

Uniq() is a function that compares adjacent lines in a file and if they are equal, deletes one.

Uniq(strtline,endline)

Substrmatch() is a function that compares 2 strings and finds the first longest occurrence of one in the other.

Substrmatch(str1,str2,offset,len,…)

Str2 is searched for in str1, if found, the offset and len of the match are placed in the passed variables. If optional arguments are specified they are the start of the search in str1 and str2.

The passed offset variable contains –1 if no match is found

let str1=”this matches, this matches, too. You see, it matches, too!”

let str2=”matches, too”

call Substrmatch(str1,str2,’b:offset’,’b:len’)

echo “offset=”.b:offset.” len=”.b:len

echo ”substr <”. strpart(str1,b:offset,b:len).”>”

call Substrmatch(str1,str2,’b:offset’,’b:len’,b:offset+1)

echo “offset=”.b:offset.” len=”.b:len

echo ”substr <”. strpart(str1,b:offset,b:len).”>”

let str1="this matches, and this matches. You see, it matches!"

let str2="matches, too"

call Substrmatch(str1,str2,'b:offset','b:len')

echo "offset=".b:offset." len=".b:len

echo "substr <".strpart(str1,b:offset,b:len).">"

call Substrmatch(str1,str2,'b:offset','b:len',b:offset+1)

echo "offset=".b:offset." len=".b:len

echo "substr <".strpart(str1,b:offset,b:len).">"

offset=19 len=12

substr <matches, too>

offset=46 len=12

substr <matches, too>

offset=5 len=9

substr <matches, >

offset=23 len=7

substr <matches>

RelativePath() is a function that finds the relative path of one file in the path of another.

RelativePath(path1,path2)

The longest common component of the 2 paths is found and the path of the second is defined relative to that common path. path1 may be specified as either ‘.’ or ‘%’ for ‘current dir’ and ‘current file dir’ respectively.

let path2='c:/Vim/vimfiles/plugin/vsutil.vim'

echo "Full-qualified file path <".path2.">"

let path1='%'

echo "Relative to <".path1."> [".expand('%:p')."]"

echo "Relative Path <".RelativePath(path1,path2).">"

let path1='.'

echo "Relative to <".path1."> [".getcwd()."]"

echo "Relative Path <".RelativePath(path1,path2).">"

let path1='/Vim/vimfiles/plugin/array.vim'

echo "Relative to <".path1.">"

echo "Relative Path <".RelativePath(path1,path2).">"

Full-qualified file path <c:/Vim/vimfiles/plugin/vsutil.vim>

Relative to <%> [C:\Vim\vimfiles\testing\test2.vim]

Relative Path <..\plugin\vsutil.vim>

Relative to <.> [C:\Vim\vimfiles\plugin\example]

Relative Path <..\vsutil.vim>

Relative to </Vim/vimfiles/plugin/array.vim>

Relative Path <.\vsutil.vim>