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 preferrably 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")

This option specifies a proxy to use for retrieving documents from FTP locations. It specifies either the complete URL or the server and port (as "server:port") of the proxy, and the proxy has to be a HTTP-based FTP proxy. This option takes precedence over config.proxy, if specified. 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")

This option specifies a proxy to use for retrieving documents from HTTP locations. It specifies either the complete URL or the server and port (as "server:port") of the proxy. This option takes precedence over config.proxy, if specified. If neither config.httpproxy nor config.proxy is set, the script uses the value the environment variables $http_proxy or $HTTP_PROXY (in this order of precedence) are set to, or 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.

newverexec (string)

A command to be executed whenever a new version of a program is found, unless overridden on a per-program basis via prog.newverexec. 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): "__NEWVER__", "__PROG__", "__RAWVER__", "__URL__". Additionally, `~/' will be replaced by the user's home directory.

nocache (Boolean)

This option conserves some memory by not caching retrieved documents (those fetched from prog.url locations). By default, the script caches retrieved document so that program records referring to the same web page won't result in (unnecessary) multiple retrievals during the same session.

plain (Boolean)

This option causes the script to generate plain (as opposed to ANSI-enhanced) output by default. The option may be overridden by specifying "--noplain" on the command line.

proxy (string: HTTP URL or "server:port")

This option specifies a proxy to use for retrieving documents from both HTTP and FTP locations. It specifies either the complete URL or the server and port (as "server:port") of the proxy. The proxy set via this option may be overridden via config.ftpproxy and/or config.httpproxy.

sortby (enumeration: name, url)

This option specifies whether to sort prog entries by program name (prog section identifier) or URL when rewriting the configuration file. The default is to sort by name.

xfersum (Boolean)

Corresponds to the command line option "--xfersum". If set, the script will print a total of the amount of data that has been 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 will also print 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

Program sections each define for a single program (package, ...) an HTTP or FTP URL based on which 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 introducing 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). Thus, 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)

This option defines whether the script should look for and delete any obsolete versions of a program located in its download directory after each 'Usuccessful' 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.

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)

This option causes the program record in question to be ignored (except when the command line switch "--force" is used).

dl (enumeration: yes, no)

This option 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 the latter option.

dldir (string)

This option specifies 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 will be treated as an absolute path, otherwise it will be considered relative to either config.dldir, if specified, or the directory the script is executing in.

The dldir string is subject to expansion of the following placeholders (see "PLACEHOLDERS" for their meaning): "__NEWVER__".

dldirlast (string)

This option specifies the download directory of the last downloaded version of a program. It does not contains "PLACEHOLDERS" unlike "prog.dldir". If the directory is absolute (i.e., relative to the root directory, as indicated by a leading slash), it will be treated as an absolute path, otherwise it will be 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, it is overwriten 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 the following placeholders (see "PLACEHOLDERS" for their meaning): "__DLURL__", "__FILE__", "__NEWVER__", "__PROG__", "__RAWVER__", "__URL__". Additionally, `~/' will be 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 command string is subject to expansion of the following placeholders (see "PLACEHOLDERS" for their meaning): "__NEWVER__", "__RAWVER__".

This option can also be used to, e.g., 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 (i.e., version referenced at url newer than dlversion but older than the most recent version available) will be downloaded as well if any are encountered when a new version of the program is found. 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 will determine 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 preferrably 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 is 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)

A command to be executed whenever a new version of a program is found, overriding a possible definition via config.newverexec. 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): "__NEWVER__", "__PROG__", "__RAWVER__", "__URL__". Additionally, `~/' will be replaced by the user's home directory.

regex (string; required; multiple allowed)

This required field is supposed to contain a Perl-style regular expression matching desired versions of the program in question given the document at prog.url as input. Note that the regexp needn't match the complete file name--when considering a download, the script will auto-expand the match as seen fit.

Regular expressions for matching programs' version numbers have to be written in such a way that the $1 part (see the "perlre" man page), if the entire expression matches, is exactly the version number. The option is subject to placeholder expansion: "__VER__" will be replaced by a pre-manufactured (non-greedy) regular expression matching version numbers compliant with any of a number of common schemes. Note that in order to yield a $1 match as required, "__VER__" still needs to be put in parentheses. For examples of prog.regex values, see "EXAMPLES".

In order to cope with particularly complex remote scenarios (such as version-dependent directory hierarchies), multiple url, regex, and transform fields may be specified per program. In this case, the script will match 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 match the regexp against the corresponding document. In order for this to be of any use, the second (and each potential later) url will have to contain a "__NEWVER__" or "__RAWVER__" placeholder (see "PLACEHOLDERS") which will be replaced by the previously matched latest [transformed] version (the same substitution is done for regex). The version that will finally be 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 can be used in practice, see "EXAMPLES".

Possible multiple transform fields will be 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, the last-specified transform expression will be used for further iterations. If, on the other hand, 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.

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

tranform (string; multiple allowed)

A Perl expression transforming a version number in $_ (obtained by a prog.regex match) in some 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, is used as the transformed version and will henceforth be the basis for version comparison for the program in question.

urgency (enumeration: high, medium, low)

Defines the urgency with which to check for the specified program. Urgencies allow for a crude selection of programs to check for via the "--urgency" command line parameter. If there is no urgency defined, it defaults to either config.defaulturgency (if set) or medium.

url (string: HTTP or FTP URL; required; multiple allowed)

This required field defines the HTTP or FTP URL to retrieve as the document to scan for in order to detect the availability of new program versions by matching against prog.regex. Note that if the URL is a directory (especially, an FTP directory which is supposed to be listed), the URL needs to end in a slash (`/'). If the target document is an HTML page, its source code will be matched against prog.regex, aiming at links embedded in the document. An alternate download URL can be specified via prog.dlexplicit.

In order to cope with particularly complex remote scenarios (such as version-dependent directory hierarchies), multiple url, regex, and transform fields may be specified per program. In this case, the script will match 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 match the regexp against the corresponding document. In order for this to be of any use, the second (and each potential later) url will have to contain a "__NEWVER__" or "__RAWVER__" placeholder (see "PLACEHOLDERS") which will be replaced by the previously matched latest [transformed] version (the same substitution is done for regex). The version that will finally be 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 can be used in practice, see "EXAMPLES".

Possible multiple transform fields will be 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, the last-specified transform expression will be used for further iterations. If, on the other hand, 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.

When the config file is 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. In contrast to prog.dlversion, this is the latest version detected, not the latest version downloaded. 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):

"__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__" is replaced by the latest transformed (or untransformed, if no transform expression is in effect) version available as determined by the script.

When using multiple url/regex/transform fields in order to cope with more complex remote site hierarchies, "__NEWVER1__", "__NEWVER2__", ... give access to intermediately-determined versions. In this 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.

"__PROG__"

The name (identifier) of the respective prog section.

"__RAWVER__"; "__RAWVER1__", "__RAWVER2__", ...

"__RAWVER__" is replaced by the latest version available as determined by the script.

When using multiple url/regex fields in order to cope with more complex remote site hierarchies, "__RAWVER1__", "__RAWVER2__", ... give access to intermediately-determined versions. In this case, "__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.

"__VER__"

A pre-manufactured (non-greedy) regular expression matching version numbers compliant with any of a number of common schemes.