help which_version

Title

which_version -- Return location and programmer's
version of ado-files

Syntax

which_version
fname[.ftype]
[ , options ]

firstversion
extract only the first programmer's version number

assertversion([relop] #.#[.#[.#]])
assert programmer's version number

Description

which_version looks for fname.ftype along the
ado-path and, if it finds the file, displays the full
path and filename, along with all lines in the file that begin with
*!. If fname.ftype is not found, the command
exits with error and sets the return code to 111.

which_version returns the full path and filename of
fname.ftype in s(fn). Additionally,
which_version searches all lines in fname.ftype
that begin with *! for the programmer's version number and, if
it finds the version number, returns it in s(version); see
Remarks.

Options

firstversion extracts from fname.ftype only the
first programmer's version number. Default is to extract the largest
version number. See Remarks.

assertversion([relop]
#.#[.#[.#]]) verifies that
the programmer's version number equals the specified version number and,
if it does not, exits with error and sets the return code to 9. If there
is no programmer's version number in fname.ftype, the
return code is set to 6. relop is one of the relational
operators >, <, >= or <=, and verifies that the
programmer's version number is larger (or equal) or lower (or equal) to the
specified version number.

Remarks

which_version extracts from fname.ftype the
programmer's version number if it follows the pattern typically used
by StataCorp.

*! version #.#.# DayMonthYear

Many community-contributed commands mimic this pattern to indicate the
programmer's version number; many do not. which_version recognizes
any of the following variations

*! version 2.1.0 11nov2019 daniel klein

*! 1.0.4 NJC 24 March 2014

*! NJC 1.3.0 28 Feb 2014

*! version 3.23 31may2019 Ben Jann

*! v.2.1.1 Confirmatory factor analysis, by Stas Kolenikov ...

*! v 14.3 2Feb2019 by Joao Pedro Azevedo ...

and extracts the programmer's version numbers 2.1.0, 1.0.4,
1.3.0, 3.23, 2.1.1, and 14.3.

Technically, which_version looks, in lines of
fname.ftype that begin with *!, for the first
occurrence of the pattern

[v[.]]#.#[.#[.#]]

and interprets it as the programmer's version number. The pattern is
expected to be one word; white spaces are not allowed. The pattern may
optionally begin with the letter v, followed by a dot. The
pattern must contain at least two and at most four numbers, separated
by dots. Although it is not shown, the pattern may be terminated by a
white space, a comma (,), a colon (:), or a semi-colon (;).

Some community-contributed commands include as comments a version-history
and, thus, multiple programmer's version numbers. which_version
extracts the latest, i.e., largest programmer's version number. For example,
from

*! 1.1.15 MLB 22Mar2012

*! 1.1.13 MLB 03Aug2010

...

*! 1.1.9 MLB 28Apr2010

...

*! 1.0.1 MLB 15May2007

which_version extracts the programmer's version number
1.1.15. Likewise, from

*! version 1.0.0 2008.04.26

*! version 1.0.1 2009.01.20

...

*! version 2.0.1 2010.08.27 Version submitted to SSC

*!

*! by David C. Elliott

*! Text file chunking algorithm

...

which_version extracts the programmer's version number
2.0.1.

Note that from

*! Version 2.3.4.1: Changes made June 15, 2019: option label ...

*! Version 2.3.40 : Changes made June 6, 2019: eform() ...

*! Version 2.3.3.9: command replay added. This is used ...

...

*! Version 2.1.0 , Attaullah Shah, attaullah.shah@imsciences.edu.pk,Aug1, 2018

*! Version 1.0 , Attaullah Shah, attaullah.shah@imsciences.edu.pk,7Jan2018

...

which_version extracts, perhaps unexpectedly, the programmer's
version number 2.3.40. Changing from two numbers (Version 1.0)
to four numbers (Version 2.3.4.1) that indicate the programmer's
version is not a problem. However, which_version insists that
2.3.40 != 2.3.4.0 and that 2.3.40[.0] > 2.3.4.1.

Sometimes, which_version extracts a wrong programmer's version
number. For example, from

*! version 1.1.2 30may2015 Robert Picard, Picard@netbox.com & NJC

*! cloned from egen version 3.4.1 05jun2013; modified to accept tsvarlists

which_version extracts the (wrong) programmer's version number
3.4.1. The firstversion option fixes this problem.

If which_version cannot find a programmer's version number, it
displays "unknown version" and returns nothing in s(version).

Examples

. which_version recode

. sreturn list

. which_version which_version , assertversion(> 1.0.0)

. sreturn list

Saved results

which_version saves the following in s():

Macros

s(fn) full path and filename

s(version) programmer's version number

Author

Daniel Klein, INCHER-Kassel, University of Kassel, klein.daniel.81@gmail.com

Also see

Online: which, findfile, regexm()