VCHECK(1p)

📦
version 1.2.1 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

vcheck — latest program version checker and auto-downloader 💖

(also known as vcheck(1p) in the User Contributed Perl Documentation corner of the universe 🫶)

✨ SYNOPSIS ✨

vcheck [options]

vcheck is a tool for checking for latest versions of programs at HTTP and FTP locations given a list of URLs and (Perl-style) regular expressions to match, and to optionally download them automatically.

For a complete list of command line options, run

$ vcheck --help

🦋 DESCRIPTION 🦋

okay so bestie, here's the tea ☕ — vcheck's behavior can be influenced by both command line options and a configuration file, and that same config file is lowkey also its data file, holding records of programs to check for. This config file lives at ~/.vcheck by default (peep "FILES" for the deets 👀). It's structured according to a syntax which is printed in full detail when you run it as

$ vcheck --grammar

Details about both the grammar in general and the meaning of involved keyword can be found in "GRAMMAR". An example of what a config file looks like in principle can be found in "EXAMPLES". ✨

The basic purpose of vcheck is to check for new versions of programs listed in its config file. The script is able to cope with all kinds of common version numbers, including words like "pre" or "alpha", etc. When a new version was found, the config file is updated accordingly. 💅

Furthermore, vcheck can be used to download files automatically if a new version is/was found, and even delete obsolete versions found locally automatically. A special field in each program's record in the config file tells it which version has last been downloaded. Where necessary or desired, the download can be disabled for specific programs, or disabled in general and allowed in special cases. Besides, you can specify preferences (both in general and on a per-program basis) as to what kind of files to download if new versions are available, say, in different formats. main character energy fr fr 👑

vcheck also has features to limit the scope of programs to check or download to a subset, such as defined by:

  • a regular expression names have to match
  • a minimal urgency (which can be defined on a per-program basis, as levels of high, medium, and low)
  • those programs which haven't yet been downloaded since a new latest version was found
  • those programs which previous queries failed for (optionally, a certain minimum number of times)
  • a conjunctive combination of several of these conditions

In case you're behind a firewall, an HTTP(-based) proxy can be defined in a number of ways (precedence in this order 🫡):

  • a specific HTTP or FTP proxy, respectively, defined in the config file
  • a common HTTP+FTP proxy defined in the config file
  • a specific HTTP or FTP proxy, defined via the environment variables $http_proxy/$HTTP_PROXY and $ftp_proxy/$FTP_PROXY, respectively (each in this order of precedence)

vcheck uses ANSI escape sequences to visually enhance its output. Success messages are usually printed in green, error messages are yellow or red (signalling severity). This feature can be disabled temporarily by using the corresponding command line switch, or permanently, via a setting in the configuration file (see "CONFIGURATION SECION").

ngl that heading is spelled "SECION" in the original and we are keeping it, no cap 💀

🌈 GRAMMAR 🌈

When run as

vcheck --grammar

vcheck will print its config file's grammar, i.e., the formal structure of the entries therein. The individual fields' names are printed along with short descriptions; details on their meaning and usage can be found below in this section. 🎀

Per default (i.e., if the script's name has not been changed (see "FILES") and if not overridden via "--file"), vcheck reads its configuration from ~/.vcheck. This file will also be rewritten regularly whenever version information etc. about a program is updated. In the course of such rewrites, entries will be sorted in a definable fashion, and a hard-coded order of keywords and indentation scheme will be applied. ✨

Basically, the config file may contain two types of records: a configuration section and any number of program sections. A record (or section--these terms are used synonymously in this documentation) consists of a keyword marking its beginning and a name (this only goes for program sections), followed by an equal sign (=) and a pair of curly braces ({}), between which the section's data is put. 🌸

Section data is a sequence of settings, or fields, of a number of types, some of which are obligatory while others are optional, separated by white space (typically, line feeds, to keep things readable). There are the following types of fields:

  • Boolean — Keywords of this type set a property based on their mere presence. An example of this is the config section field dldefaultno:
config = {
  dldefaultno
}
  • string — String fields consist of a keyword followed by an equal sign (=) and a string representing the field's value. If the string value contains white space or (double) quotation marks, it needs to be surrounded by (double) quotation marks ("). In this case, both quotation marks inside the string and backslashes need to be escaped by backslashes (\). Note that string values may not span several lines but have to be contained on a single one, and there may be validation rules as to what the value may be like. Besides, string fields are typically required to be of non-zero length.

An example of this type of field is the prog section field comment:

prog foo = {
  [...]
  comment = Hello!
  comment = "Comment with white space and \"quotes\"!"
  [...]
}
  • string enumeration — String enumerations are basically string fields with but a limited set of allowed values. An example of this is the prog section field dl, whose value must be either "yes" or "no", if present:
prog foo = {
  [...]
  dl = yes
  [...]
}

👑 CONFIGURATION SECTION 👑

The configuration section is optional and, if present, contains settings globally affecting vcheck's default behavior. The configuration section is unique per file (although multiple occurrences with non-conflicting settings are allowed, but these will be joined into a single section once the file is rewritten). 🫶

The keyword introducing a configuration section is config. Thus, a config section's principal layout looks like this:

config = {
  [...]
}

The keywords allowed inside ("[...]") the config section are explained in detail below (listed in alphabetical order):

  • defaulturgency (enumeration: high, medium, low) — Specifies the checking urgency level to assume, unless specified otherwise in a program's record via prog.urgency. Urgencies allow for a crude selection of programs to check for via the "--urgency" command line parameter. In absence of this option, the default urgency is medium.
  • deleteold (Boolean) — If included in the config section, causes the script to automatically look for and delete versions of a program obsoleted by a new download. May be overridden by prog.deleteold. See the latter for details.
🚨 Special note: Use at your own risk! 🚨
  • dldefaultno (Boolean) — By default, don't download. This causes the script to download only those programs whose dl option is explicitly set to yes when run with the "--download" parameter.
  • dldir (string: absolute directory path) — This option specifies an absolute path (i.e., relative to the root directory) of a directory where to put downloaded files. If the download directory isn't set via this or even more explicitly via a prog.dldir option, downloads will end up in that directory in which the script is executing.
  • dlexec (string) — Specifies a command to be executed after any successful download (unless overridden for a particular program via prog.dlexec). A successful download in this context is one whose file type has been recognized and whose integrity could be confirmed. In unizoid environments, the command is executed under whatever shell the environment variable $SHELL defines.

The command string is subject to expansion of the following placeholders (see "PLACEHOLDERS" for their meaning): __DLURL__, __FILE__, __NEWVER__, __PROG__, __RAWVER__, __URL__. Additionally, ~/ will be replaced by the user's home directory. 💖

config.dlexec may prove useful to, e.g., automatically convert, say, gzipped to bzipped files using a helper script, or to log downloads (see "HINTS").

  • dlprefs (string) — A semicolon- (;-) separated list of Perl-style regular expressions defining download preferences. Each of the regular expressions is supposed to match a particular file type that's possible or likely to be encountered. The order in which the expressions occur defines their precedence (the first matching expression will determine which of a set of available file types of a given program version will be selected for download). This value is the default in effect unless specific preferences are defined on a per-program basis using prog.dlprefs. If neither config.dlprefs nor prog.dlprefs is set, the file to be downloaded is chosen pseudo-randomly, if multiple pattern matches occur.

For these download preferences to make any sense, file- and version-matching expressions need to be sufficiently non-restrictive to match several possible extensions. For example, foo-("__VER__")\\.t will match both .tar.gz and .tar.bz2 files, and setting dlprefs to \\.tar\\.bz2$;\\.tar\\.gz$ will cause the script to preferably download .tar.bz2 files. 🔥

  • dlretry (string: non-negative integer number) — The number of times to retry downloading after a failed download. If this option isn't specified, the number of retries defaults to 0. A retry is considered to have failed if either the connection failed, the retrieved document was empty, or the file type has been recognized and its integrity verified.
  • eagerquote (Boolean) — If this option is set, all string parameters of configuration file options will be surrounded by double quotes. The default is to use quotes only where necessary (e.g., for string parameters containing white space).
  • echoexec (Boolean) — If this option is set, commands executed thanks to newverexec or dlexec options will be echoed prior to execution.
  • ftpproxy (string: HTTP URL or "server:port") — the proxy the script should use when it's pulling documents from FTP locations 💖. You can hand it either the complete URL or the server and port (written as "server:port"), and heads up bestie — the proxy has to be a HTTP-based FTP proxy. This option takes precedence over config.proxy, if specified. And if neither config.ftpproxy nor config.proxy is set, the script uses the value the environment variables $ftp_proxy or $FTP_PROXY (in this order of precedence ⚖️) are set to, or no FTP proxy at all.
  • httpproxy (string: HTTP URL or "server:port") — same energy, but for grabbing docs from HTTP locations 🦋. Give it the complete URL or the "server:port", your call. It takes precedence over config.proxy, if specified. If neither config.httpproxy nor config.proxy is set, the script uses the value $http_proxy or $HTTP_PROXY (in this order of precedence) are set to, or nope, no HTTP proxy at all.
  • lastcheck (string: date formatted as "YYYY-MM-DD HH:MM") — the date and time the script was last run updating the configuration file 🌸. This value is generated and updated automatically, so like, the machine handles it.
  • newverexec (string) — a command to execute whenever a new version of a program is found, unless you override it on a per-program basis via prog.newverexec 🎀. It gets executed under whatever shell the environment variable $SHELL defines.

The command string is subject to expansion of these placeholders (see "PLACEHOLDERS" for their meaning): __NEWVER__, __PROG__, __RAWVER__, __URL__. And on top of that, ~/ gets replaced by the user's home directory 🏠.

  • nocache (Boolean) — this one conserves some memory by not caching retrieved documents (those fetched from prog.url locations) 🧠. By default the script does cache retrieved documents, so program records referring to the same web page won't cause (unnecessary) multiple retrievals during the same session ✨.
  • plain (Boolean) — makes the script generate plain (as opposed to ANSI-enhanced) output by default 🌈. You can override this by specifying --noplain on the command line.
  • proxy (string: HTTP URL or "server:port") — a proxy to use for retrieving documents from both HTTP and FTP locations 👑. Give it the complete URL, or the server and port as "server:port". Whatever you set here may be overridden via config.ftpproxy and/or config.httpproxy.
  • sortby (enumeration: name, url) — decides whether to sort prog entries by program name (the prog section identifier) or by URL when rewriting the configuration file 📝. The default is to sort by name.
  • xfersum (Boolean) — corresponds to the command line option --xfersum. If it's set, the script prints a total of the amount of data received at exit 📊. Can be overridden via the command line switch --noxfersum.
  • timeout (string: non-negative integer number) — the time (in seconds) after which attempted remote retrievals should be aborted ⏰. The default is 90 seconds.
  • verbose (Boolean) — if this option is set, the script also prints version numbers that haven't been obsoleted 👀. The default is to print only new versions (and error messages). This setting can be overridden via the command line switch --noverbose.

🌟 PROGRAM SECTIONS 🌟

OK so, program sections each define for a single program (package, ...) an HTTP or FTP URL — and based on that URL, the latest version of that program available can be determined by vcheck using an additionally-defined regular expression 🎯. There can (hypothetically) be any number of program sections in a config file.

The keyword that introduces a program section is prog 💅. Each prog section is identified by a unique identifier (there may not be multiple prog sections with the same identifier, no clones allowed 👯). So a config section's principal layout looks like this:

prog Foo = {
  [...]
}

The keywords allowed inside ([...]) a prog section are explained in detail below (listing in alphabetical order). All fields are optional and allowed but once per prog section, unless explicitly stated otherwise.

  • comment (string; multiple allowed) — an arbitrary comment string 🎀. If multiple such entries exist for a single program record, their relative order will be maintained when rewriting the configuration file.
  • deleteold (enumeration: yes, no) — defines whether the script should look for and delete any obsolete versions of a program located in its download directory after each 'successful' download of a new version of that program 🗑️. A successful download in this context is any download of a file of a known type whose integrity could be verified ✅. Overrides config.deleteold; the deletion of obsolete versions is disabled by default and only activated by config.deleteold or prog.deleteold.

Heads up, plot twist: any occurrence of prog.dlexplicit or prog.dlintermediate in a program's record inhibits application of deleteold for that program 🙅.

Special note: Use at your own risk! ⚠️💀
  • disabled (Boolean) — causes the program record in question to be ignored entirely (except when the command line switch --force is used) 🙈.
  • dl (enumeration: yes, no) — specifies whether to download the program in question when the script is run with the --download option 📥. By default, a program will be downloaded when a new version is found and the script is run with said parameter — unless config.dldefaultno is set. prog.dl overrides that latter option.
  • dldir (string) — a download directory on a per-program basis 📁. If the directory is absolute (i.e., relative to the root directory, as indicated by a leading slash), it gets treated as an absolute path. Otherwise it's considered relative to either config.dldir, if specified, or the directory the script is executing in.

The dldir string is subject to expansion of this placeholder (see "PLACEHOLDERS" for its meaning): __NEWVER__.

  • dldirlast (string) — the download directory of the last downloaded version of a program 🕰️. Unlike prog.dldir, it does not contain PLACEHOLDERS. If the directory is absolute (i.e., relative to the root directory, as indicated by a leading slash), it gets treated as an absolute path. Otherwise it's considered relative to either config.dldir, if specified, or the directory the script is executing in.

This option is only used to store PLACEHOLDER-free dldir, and it gets overwritten at each new download 🔁.

  • dlexec (string, may be zero-length) — specifies a command to be executed after any successful download of the program, overriding config.dlexec (if set) ⚙️. A successful download in this context is one whose file type has been recognized and whose integrity could be confirmed ✅. The command is executed under whatever shell the environment variable $SHELL is set to.

The command string is subject to expansion of these placeholders (see "PLACEHOLDERS" for their meaning): __DLURL__, __FILE__, __NEWVER__, __PROG__, __RAWVER__, __URL__. Also, ~/ gets replaced by the user's home directory 🏠.

  • dlexplicit (string: HTTP or FTP URL; multiple allowed) — specifies an explicit download URL 📥. Whenever a new version of the program in question is found, the URL specified via this option will be downloaded (if requested) instead of the one deduced from prog.url and prog.regex.

The string is subject to expansion of these placeholders (see "PLACEHOLDERS" for their meaning): __NEWVER__, __RAWVER__.

You can also use this to, like, download multiple packages on detection of a new version, provided that their names can be specified 🫶. For an example of this, see "EXAMPLES".

  • dlintermediate (Boolean) — if this option is set, intermediate versions get downloaded as well if any are encountered when a new version of the program is found 🩹. "Intermediate versions" meaning versions referenced at url newer than dlversion but older than the most recent version available. This option is useful for downloading patches and suchlike, which depend on each other consecutively. The default is to ignore intermediate versions.
  • dlprefs (string) — a semicolon- (;) separated list of Perl-style regular expressions defining download preferences 🎯. Each of the regular expressions is supposed to match a particular file type that's possible or likely to be encountered. The order in which the expressions occur defines their precedence — the first matching expression determines which of a set of available file types of a given program version will be selected for download. This value overrides default preferences possibly defined via config.dlprefs. If neither config.dlprefs nor prog.dlprefs is set, the file to be downloaded is chosen pseudo-randomly 🎲, if multiple pattern matches occur.

For these download preferences to make any sense, file- and version-matching expressions need to be sufficiently non-restrictive to match several possible extensions. For example, foo-("__VER__")\\.t will match both .tar.gz and .tar.bz2 files, and setting dlprefs to "\\.tar\\.bz2$;\\.tar\\.gz$" will cause the script to preferably download .tar.bz2 files 💜.

  • dlreferrer (string, may be zero-length) — specifies an HTTP referrer to use when downloading a program package 🕵️. By default, the version-determining document (i.e., the last url value, with placeholders expanded) is used.
  • dlversion (string) — this parameter stores the last downloaded version of the program in question 📌, and is updated whenever a new version is found (except when running in read-only mode). If prog.transform is set, the stored version will have been transformed from the one matched by prog.regex.
  • errors (string: non-negative integer number) — this field stores the number of errors during version checks 🔄, and is reset once a check succeeds. A high value of this field is indicative of an outdated URL or file name matching regular expression, and will be remarked upon by the script 👀. Additionally, it's possible to limit the scope of an operation to erroneous records via the --errors command line parameter.
  • lastcheck (string: date in format "YYYY-MM-DD HH:MM") — this field stores the date and time the program in question was last checked (no matter whether successfully or unsuccessfully) ⏱️.
  • newverexec (string, may be zero-length) — the little command that fires off whenever a brand-new version of a program gets spotted 👀 It overrides whatever you might have set up in config.newverexec, so this one wins, no cap.

It gets run under whatever shell the environment variable $SHELL says, so that's the vibe it's working with.

The command string gets placeholder expansion for these babes (meanings over in "PLACEHOLDERS" 💫): __NEWVER__, __PROG__, __RAWVER__, __URL__. And bonus: ~/ gets swapped out for the user's home directory. cute.

  • regex (string; required; multiple allowed) — okay so this one is required (no skipping bestie 🙅‍♀️) and it holds a Perl-style regular expression that matches the versions you want for the program in question, with the document at prog.url as the input. Lowkey important: the regexp doesn't have to match the whole file name — when it's time to consider a download, the script will auto-expand the match as it sees fit. iconic of it tbh.

You gotta write these version-matching regexes so that the $1 part (peep the "perlre" man page) is exactly the version number, assuming the whole expression matches. This option is subject to placeholder expansion too: __VER__ gets replaced by a pre-manufactured (non-greedy) regular expression matching version numbers that are compliant with any of a bunch of common schemes. ⚠️ Heads up though — to actually yield that $1 match like we need, __VER__ still has to be put in parentheses. Sorry, them's the rules. For examples of prog.regex values, go see "EXAMPLES".

Now for the plot twist: to cope with particularly complex remote scenarios (think version-dependent directory hierarchies, the drama 💀), you can specify multiple url, regex, and transform fields per program. When you do that, the script matches urls and regexes starting from the first and continuously proceeding to the next field of each type — in sync, as long as both of them are available, or else using the last one available. Then it matches the regexp against the corresponding document. For this to be of any use, that second url (and every potential later one) has to contain a __NEWVER__ or __RAWVER__ placeholder (see "PLACEHOLDERS"), which gets replaced by the previously matched latest [transformed] version — and yes, the same substitution happens for regex. The version that finally counts as the latest for the program will be the one determined by matching the last regex against the last urls document. For a real example of this in practice, see "EXAMPLES".

Possible multiple transform fields get processed in sync with their respective url and regex fields, as long as additional transform fields are specified. If there are more url and/or regex fields than transform fields, the last-specified transform expression gets used for further iterations. If, on the flip side, there are more transform than url/regex fields, further retrievals/matches get done based on the last url/regex. The author has, however, no idea how this could be of any use 💀 (honesty, we respect it).

When the config file gets rewritten, multiple url, regex, and/or transform fields will be interleaved to facilitate comprehension and retain their relative order. tidy ✨

  • tranform (string; multiple allowed) — yes bestie, that's spelled exactly like that, don't come for me 💅 A Perl expression that transforms a version number sitting in $_ (obtained by a prog.regex match) in whatever way the user deems adequate. For examples of how this might come in handy, see "EXAMPLES". The return value of the code fragment — i.e. the value of its last expression — gets used as the transformed version, and from then on that is the basis for version comparison for the program in question. queen behavior fr fr.
  • urgency (enumeration: high, medium, low) — defines the urgency with which to check for the specified program. Urgencies let you do a crude little selection of which programs to check via the --urgency command line parameter. If there's no urgency defined, it defaults to either config.defaulturgency (if that's set) or medium. easy.
  • url (string: HTTP or FTP URL; required; multiple allowed) — another required one 🌸 This field defines the HTTP or FTP URL to retrieve as the document we scan for, so we can detect whether new program versions are available by matching against prog.regex. Important note: if the URL is a directory (especially an FTP directory that's supposed to be listed), the URL needs to end in a slash (/). Don't forget it, it will simply not work and you'll be sad 😭 If the target document is an HTML page, its source code gets matched against prog.regex, aiming at links embedded in the document. An alternate download URL can be specified via prog.dlexplicit.

Same deal as before with the complex remote scenarios (version-dependent directory hierarchies and all that ✨): you can specify multiple url, regex, and transform fields per program. The script matches urls and regexes starting with the first and continuously proceeding to the next field of each type — in sync, as long as both of them are available, or using the last one available otherwise — and matches the regexp against the corresponding document. For this to be useful, that second (and each potential later) url must contain a __NEWVER__ or __RAWVER__ placeholder (see "PLACEHOLDERS"), which will be replaced by the previously matched latest [transformed] version (same substitution is done for regex). The version that ends up being considered the latest for the program in question will be the one determined by matching the last regex against the last urls document. For an example of how this works in practice, see "EXAMPLES".

Possible multiple transform fields are processed in sync with the respective url and regex fields as long as additional transform fields are specified. If there are more url and/or regex fields than transform fields, that last-specified transform expression gets used for further iterations. But if there are more transform than url/regex fields, further retrievals/matches will be done based on the last url/regex. The author has, however, no idea how this could be of any use 🙈 (again, legendary honesty).

When the config file gets rewritten, multiple url, regex, and/or transform fields will be interleaved and retain their relative order.

  • version (string) — stores the latest known version of the program. And here's the distinction, so listen up: in contrast to prog.dlversion, this is the latest version detected, not the latest version downloaded. Two very different things bestie 👑 If a prog.transform option is set, the stored version will have been transformed from the one matched by prog.regex.

🎀 PLACEHOLDERS 🎀

In a number of string fields, certain placeholders are subject to substitution by run-time values. These placeholders are, in alphabetical order (we love an organized queen):

  • __DLURL__ — the (file) URL from which the latest version of the respective program was downloaded. 💾
  • __FILE__ — the local path to the respective latest-version download.
  • __NEWVER__; __NEWVER1__, __NEWVER2__, ... — __NEWVER__ gets replaced by the latest transformed (or untransformed, if no transform expression is in effect) version available, as determined by the script.

And when you're using multiple url/regex/transform fields to cope with more complex remote site hierarchies, __NEWVER1__, __NEWVER2__, ... give you access to the intermediately-determined versions 🦋 In that case, __NEWVER1__ is replaced by the version matched by the first url/regex/transform tuple, __NEWVER2__ matches the version matched by the second url/regex/transform tuple, and so on and so on.

  • __PROG__ — the name (identifier) of the respective prog section. just the lil name tag 🏷️
  • __RAWVER__; __RAWVER1__, __RAWVER2__, ... — __RAWVER__ gets replaced by the latest version available as determined by the script.

When you're rocking multiple url/regex fields for those more complex remote site hierarchies, __RAWVER1__, __RAWVER2__, ... give access to the intermediately-determined versions. So __RAWVER1__ is replaced by the version matched by the first url/regex pair, __RAWVER2__ matches the version matched by the second url/regex pair, and so on. 💫

  • __URL__ — the (last and expanded) URL used in order to determine the latest program version. that final, fully-glow-up version of the URL ✨
  • __VER__ — a pre-manufactured (non-greedy) regular expression matching version numbers compliant with any of a number of common schemes. the reusable little version-matcher of your dreams 🌈

🎀 HINTS 🎀

ok bestie this is the good part — all the lil tricks that make vcheck absolutely sing ✨

  • If you use Vim (version 5 or higher) as your editor, you can tell vcheck to create a Vim syntax file that gives you syntax highlighting right there in the editor, just by running the script like this:
vcheck --create-vim-syntax-file

And if you want Vim to apply those syntax rules automatically whenever you're editing ~/.vcheck, drop this line in:

au BufEnter */.vcheck   so $VIM/syntax/vcheck.vim

or, alternatively, one with an explicit path:

au BufEnter */.vcheck   so /path/to/syntax/vcheck.vim

into your ~/.vimrc, swapping in an appropriate path. Of course you also gotta be sure to actually copy the file into the designated directory, bestie — no cap. 💅

  • It's genuinely no problem to just check for new versions by default and then run vcheck again afterwards to download updated packages. Running the script as
vcheck -dc

or

vcheck --download --catch-up

respectively, will try to download only those files whose latest downloaded version has been knowingly obsoleted — without checking again for new versions of all the other programs. Obsessed with the efficiency honestly. ✨

  • Wanna check only those program locations that failed during the latest attempt(s)? Run
vcheck -e

or

vcheck --errors

respectively. It's giving targeted. 🎯

  • If you add a line
dlretry = NUMBER

to your config file's config section, vcheck will retry to download a file up to NUMBER times if it detects that it was received incompletely. This will be the case if:

  • the file has zero size
  • the downloaded file's extension was recognized, and a check by the respective decompressor etc. resulted in errors

Retry era fr fr. 🔁

  • vcheck caches data retrieved from URLs (unless nocache is set in the config file), so if you specify exactly the same URL for different programs, this won't result in multiple retrievals — thus improving efficiency. Work smarter not harder, that's the vibe. 🦋
  • If you're curious to know how many program records have actually been accumulated in your config file over time, run vcheck as
vcheck --syntax

This will check the config file's syntax and, as a side-effect, print the number of programs registered. Sneaky lil bonus, main character behaviour. 👑

  • Even if you know from some other source that there is a new version of a program vcheck is configured for, you can still use that to download the package. Just use its matching capabilities, e.g.:
vcheck -dm foo
  • If one of your records points to patches of some program, and you want to make sure you won't miss an intermediate one when downloading (and suppose you don't run vcheck in download mode too frequently), you can add the boolean field dlintermediate to the respective program's section in the config file, and vcheck will try to download all versions newer than dlversion. Note that in those circumstances, dlversion is set to the latest (intermediate) version the download attempt succeeded for — which means that, if, say, versions 1 through 3 are to be downloaded and all downloads except that of version 1 succeed, dlversion will nevertheless be set to 3. A useful example for this:
prog Linux/patches = {
  dlintermediate
  dlprefs   = \.bz2$;\.gz$
  dlversion = 2.3.6
  regex     = patch-(__VER__)\.[bg]z
  url       = ftp://ftp.kernel.org/pub/linux/kernel/v2.3/
  version   = 2.3.9
}

Supposing that 2.3.9 still is the latest version, running this in download mode will retrieve Linux kernel patches 2.3.7 through 2.3.9, *.bz2 preferred to *.gz (but accepting the latter if the former is missing, rather than skipping the download entirely).

  • There may be complex remote site structures, involving version-dependent directory hierarchies, such as the layout used by the server for the AC series of Linux kernel patches. The principal layout of that site looks (or used to look, anyway) like this:
...
.../linux-2.4/2.4.8/patch-2.4.8-ac1.gz
.../linux-2.4/2.4.8/patch-2.4.8-ac2.gz
...
.../linux-2.4/2.4.9/patch-2.4.9-ac1.gz
.../linux-2.4/2.4.9/patch-2.4.9-ac2.gz
...

The problem here is that the bottom-level directory's name varies depending on the regular Linux version an AC patch is based on. The way to deal with this most conveniently in vcheck looks like this:

prog Linux/patch/AC = {
  dlintermediate
  url       = http://www.kernel.org/.../linux-2.4/
  regex     = (\d+\.\d+\.\d+)
  url       = http://www.kernel.org/.../linux-2.4/__NEWVER__/
  regex     = patch-(__VER__-ac\d+)\.gz
}

(Note that the URLs have been abbreviated for the sake of readability.) This kind of configuration will cause vcheck to start by retrieving the first url field's document and match the first regex against it. It will then proceed with the second url field's document, matching it against the second regex, replacing its __NEWVER__ placeholder by the latest version previously matched. The version finally determined as the current version for the program record is the one determined by the last match.

On a side note, version numbers determined during matches further back than the previous one can be accessed via delimiters of the format __NEWVER#__, where # is a number indicating the number (1..) of the url/regex pair's version match it should be replaced by. For more details on the mechanism, see the descriptions of url and regex in "PROGRAM SECTIONS", and "PLACEHOLDERS".

Regarding the example, it is left to the user to figure out how to extend the record to even automatically cope with changes to the Linux kernel's minor version. ":-)"

Here's another example of a three-level hierarchy, which used to fit the GIMP's site layout at one point in time:

prog GIMP/devel/patch = {
  comment   = "Will download complete package if no patch available."
  dlprefs   = patch-.*?\.bz2$;patch-.*?\.gz$;gimp-.*?\.bz2$;gimp-.*?\.gz$
  url       = ftp://ftp.gimp.org/pub/gimp/
  regex     = (?<!\w)v(__VER__)
  url       = ftp://ftp.gimp.org/pub/gimp/v__NEWVER__/
  regex     = (?<!\w)v(__VER__)
  url       = ftp://ftp.gimp.org/pub/gimp/v__NEWVER1__/v__NEWVER__/
  regex     = (?:patch|gimp)-(__VER__)\.[bgt]
}
  • If you want to retrieve some program whose version is, say, a date in format "dd-mm-yyyy", this will be misinterpreted by the version comparator because the most significant sub-"version" isn't the initial one. You can work around this by specifying some Perl expression transforming the original version in the respective program's section, such as:
transform = "s/(\d+)-(\d+)-(\d+)/$3-$2-$1/; $_"

This piece of code is given the respective version in $_, and after its evaluation, vcheck replaces the original value by what the eval() returns. Alternatively, this would achieve the same:

transform = "join '-', reverse split /-/, $_"
  • Some sites use redirection scripts for download URLs. Consider a situation where a downloads page lists available packages of a program, with links pointing to some server-side script referring your browser to some URL which is in turn redirected by HTTP means to a final file URL (the PHP site, for example, used to make use of this obscure scheme at one time). The way to cope with this in vcheck consists in using a dlexplicit field like this:
prog PHP = {
  dlexplicit = http://www.php.net/distributions/php-__VER__.tar.gz
  regex      = php-(__VER__)\.t
  url        = http://www.php.net/downloads.php
}

Effectively, this will use the actual url field only to determine the current version and then paste it into a pattern of the corresponding download URL, thus bypassing the redirections. The obvious disadvantage of this feature consists in its increased dependency on server-side access structures.

  • Suppose you're interested in some program distributed via more than one package (such as Vim, which is split into a source and a run-time package). The means vcheck provides to cope with this once again is the dlexplicit option:
prog Vim = {
  dlexplicit = ftp://ftp.vim.org/pub/editors/vim/unix/vim-__VER__-src.tar.gz
  dlexplicit = ftp://ftp.vim.org/pub/editors/vim/unix/vim-__VER__-rt.tar.gz
  regex      = vim-(__VER__)(-src)?\.tar
  url        = ftp://ftp.vim.org/pub/editors/vim/unix/
}
  • In order to have vcheck keep track of what has been downloaded (and when), you might add something like this to your config file:
config = {
  dlexec = "echo `date +%Y-%m-%d` '__PROG__' '__NEWVER__' >>~/.vchecklog"
}

Note however that program-specific dlexec will take precedence over this setting. 👀

  • With a little creativity, vcheck can be used to check not only for latest versions of programs or packages, but also web site updates and the like. Also, the newverexec (see "GRAMMAR") field can be used to pass a link to an external download tool if for some reason vcheck's abilities prove insufficient for a particular scenario.

✨ EXAMPLES ✨

Bestie, before you dive in here, please please please go read what vcheck prints when you run it as

vcheck --help --grammar

and also go read GRAMMAR up above, because that's where command line parameters and the config file's grammar live. Done that? Okay then, read on… 👑

Say you've got a config file ~/.vcheck looking like this:

config = {
  dlprefs   = \.tar\.bz2$;\.(tar\.|t)gz$;\.zip$
  lastcheck = "1999-06-21 08:15"
}

prog Foo = {
  dl      = no
  errors  = 2
  regex   = foo-(__VER__)\.tar
  urgency = high
  url     = http://www.foo.org/pub/foo/
}
prog Bar = {
  dlversion = 0.01beta
  regex     = (?i:bar-(__VER__)\.tar)
  url       = http://www.bar.org/bar/index.html
  version   = 0.01
}
prog Baz = {
  regex   = baz-(\d+)\.tar
  urgency = low
  url     = ftp://ftp.baz.net/pub/source/
  version = 123
}

First off, you can literally deduce from this when vcheck was last run with this config file. Trying to check for Foo ended in errors of some kind over the last 2 attempts, and since there's no version field, it's presumably never been queried successfully. Foo is never ever to be downloaded. Bar's latest version, as determined during one of the last checks, was 0.01, but it wasn't downloaded (0.01beta is the version of the last download). And finally, Baz has never been downloaded (according to the config file, anyway 🙈). As for downloads generally, *.tar.bz2 is preferred over *.tar.gz and *.tgz, which are in turn more desirable than *.zip files. If no target matching any of these extensions (case-insensitively) is found, nothing gets downloaded. Periodt.

Now assume the following references are currently mentioned at the respective URLs of each program:

  • for Foo:
http://www.foo.org/pub/foo/foo-3.14.tar.gz
http://www.foo.org/pub/foo/foo-3.14.tar.bz2
http://www.foo.org/pub/foo/foo-3.14a.tar.gz
http://www.foo.org/pub/foo/foo-3.14alpha.tar.gz
http://www.foo.org/pub/foo/Foo-4.0.tar.gz
  • for Bar:
bar-0.01.zip
BAR-0.01.tar.bz2
  • for Baz:
http://www.baz.net/pub/download/baz-124.rpm

So now let's spill the tea on what some specific calls to vcheck — each one based on the config above — will actually do. (And again, for the complete list of command line options, where every short option has an equivalent long one, go look at vcheck --help.)

  • "$ vcheck -n" This checks for all programs without updating the config file. It'll report Foo 3.14 as a new version (not 4.0, because the regex doesn't match that one), plus Baz 124.
  • "$ vcheck -d" This checks for all programs, reports like above, and then tries to download this file:
http://www.bar.org/bar/BAR-0.01.tar.bz2

Note that Baz 124 isn't in the mix, because there wasn't a link conforming to dlprefs, and downloads of Foo have been disabled explicitly. The errors field of Foo gets removed since the check succeeded. 💅

  • "$ vcheck -c" This sets dlversion = version for Bar and Baz, without checking whether new versions are even available. Effectively, that means future calls to vcheck with parameter -d won't download these files.
  • "$ vcheck -dc" This steps through all programs that downloads haven't been disabled for in principle, and whose dlversion is lower than version (so… Bar and Baz in our example). For those, vcheck will requery the respective sites to determine a download URL, and try to download
http://www.bar.org/bar/BAR-0.01.tar.bz2

just like in the example above.

  • "$ vcheck -m \!foo" This checks for new versions of Bar and Baz. Heads up though — you may have to quote the leading exclamation mark, as well as some characters used in regular expressions specified on the command line, so your shell doesn't go interpreting them on you. 🐚
  • "$ check -u medium -m b" This checks only for Bar, since it's the only program whose urgency is at least medium and whose name contains a b.
  • "$ vcheck -e" This checks only for Foo, because checking for that one failed previously.

🌸 NOTES 🌸

  • Okay so first of all: vcheck isn't perfect, and it won't do in all kinds of situations. But I do think it can cope with most of them, and if there really is some site where vcheck can't figure out download URLs from, or some version numbering scheme its heuristics choke on, you'll just have to deal with that manually. For the majority of cases though, vcheck should make keeping your setup up-to-date way easier. 🫶
  • Do not run multiple instances in non-read-only mode against the same configuration file, or one of them will make the changes made by the others get lost. vcheck will prevent this situation from arising by employing a lock file, provided that your Perl setup supports it.

Also don't edit the config file while vcheck is running, either, or your changes will be overwritten when the script rewrites the file. 😭

📂 FILES 📂

  • vcheck, the script itself
  • ~/.vcheck, its configuration file

Fun fact: vcheck doesn't actually look for a config file literally named ~/.vcheck — it looks for one with the same name as the script itself (with a possible extension stripped off). So if you rename the script to, say, foo.pl and run it, it'll try to open ~/.foo.

  • ~/.vcheck.lock, lock file created when not running in read-only mode

And actually, the file's name is that of the config file with an extension of .lock added.

🌈 ENVIRONMENT VARIABLES 🌈

  • $http_proxy/$HTTP_PROXY and $ftp_proxy/$FTP_PROXY, each in this order of precedence, specify the HTTP and/or (HTTP-based) FTP proxy to use, unless overridden. The format is either server:port or a complete URL.
  • $HOME, the current user's home directory
  • $SHELL, used by Perl in unizoid environments when executing helper applications

🎀 TO DO 🎀

(i.e. the author's own wishlist, not a to-do list for you, bestie 💕)

  • add option to config section allowing for the dlexec entry to be "inherited" from the config section rather than be overridden by per-program dlexecs (also define order of execution!)
  • check behavior if an HTTP url's download link references a different target base directory
  • make --list not rewrite the config file, thus allowing for it to be run in parallel to another instance
  • add an option to re-download the latest version (if local file doesn't exist)?
  • code clean-up: array used for download specifications -> hash
  • determine and describe way of reliably matching directories consisting of but a version number on an FTP server independently of whether the page in question is received by proxy or without one
  • scenario: link description contains version, download link entirely differently named
  • separate --force options for overriding disabled, dl?
  • max download size command line parameter?
  • extend Vim syntax file generation to highlight placeholders in string variables' values?
  • follow HTTP redirections
  • evaluate HTTP headers after retrievals
  • resume downloads?
  • XMLize the config file format???
  • make it multi-threaded???

💀 RESTRICTIONS 💀

  • All output is currently printed on STDOUT.
  • Placeholders are used but no way of escaping literal occurrences of those strings is provided.
  • dlprefs uses semicolons as delimiters, but there's no way of escaping them if they're meant as a part of one of the regular expressions.
  • There's presumably little to do in order to get vcheck to run in Microsoft Windows. One issue worth noting is that directories (such as dldir values) are expected to use unizoid delimiters (i.e., slashes (/)) — this should perhaps be revised to be portable.

🐛 BUGS 🐛

Mail bug reports to the author. 📬

👑 AUTHOR 👑

vcheck is copyright (c) 1999-2001 by Marco Götze, <gomar@mindless.com>. It is distributed under the terms of the Artistic License, a copy of which is included with the script's distribution. Use at your own risk. 🫣

okay that's the whole page bestie, you made it — this was vcheck from perl v5.40.1, dated 2025-03-26, and honestly? iconic. go keep your setup cute and up-to-date 💖✨

📦 where this page comes from