NaturalDocs::Version

A package for handling version information. What? That’s right. Although it should be easy and obvious, version numbers need to be dealt with in a variety of formats, plus there’s compatibility with older releases which handled it differently. I wanted to centralize the code after it started getting complicated. So there ya go.

Summary

NaturalDocs::Version	A package for handling version information.
Functions
ToString	Converts a VersionInt to a string.
FromString	Converts a version string to a VersionInt.
ToTextFile	Writes a VersionInt to a text file.
FromTextFile	Retrieves a VersionInt from a text file.
ToBinaryFile	Writes a VersionInt to a binary file.
FromBinaryFile	Retrieves a VersionInt from a binary file.
ToValues	Converts a VersionInt to the array ( major, minor, month, day, year ).
FromValues	Returns a VersionInt created from the passed values.
CheckFileFormat	Checks if a file’s format is compatible with the current release.
IsDevelopmentRelease	Returns whether the passed VersionInt is for a development release.
Implementation
String Format	Full releases are in the common major.minor format.
Integer Format	VersionInts are 32-bit values with the bit distribution below.
Binary File Format	Five 8-bit unsigned values, appearing major, minor, month, day, year.
Text File Format	In text files, versions are the String Format followed by a native line break.

Functions

ToString

sub ToString #( VersionInt version ) => string

Converts a VersionInt to a string.

FromString

sub FromString #( string string ) => VersionInt

Converts a version string to a VersionInt.

ToTextFile

sub ToTextFile #( handle fileHandle,
VersionInt version )

Writes a VersionInt to a text file.

Parameters

fileHandle	The handle of the file to write it to. It should be at the correct location.
version	The VersionInt to write.

FromTextFile

sub FromTextFile #( handle fileHandle ) => VersionInt

Retrieves a VersionInt from a text file.

Parameters

fileHandle

The handle of the file to read it from. It should be at the correct location.

Returns

The VersionInt.

ToBinaryFile

sub ToBinaryFile #( handle fileHandle,
VersionInt version )

Writes a VersionInt to a binary file.

Parameters

fileHandle	The handle of the file to write it to. It should be at the correct location.
version	The VersionInt to write.

FromBinaryFile

sub FromBinaryFile #( handle fileHandle ) => VersionInt

Retrieves a VersionInt from a binary file.

Parameters

fileHandle

The handle of the file to read it from. It should be at the correct location.

Returns

The VersionInt.

ToValues

sub ToValues #( VersionInt version ) => ( int, int, int, int, int )

Converts a VersionInt to the array ( major, minor, month, day, year ). The minor version will be in two digit form, so x.2 will return 20. The date fields will be zero for stable releases.

FromValues

sub FromValues #( int major,
int minor,
int month,
int day,
int year ) => VersionInt

Returns a VersionInt created from the passed values.

Parameters

major	The major version number. For development releases, it should be the stable version it’s based off of.
minor	The minor version number. It should always be two digits, so x.2 should pass 20. For development releases, it should be the stable version it’s based off of.
month	The numeric month of the development release. For stable releases it should be zero.
day	The day of the development release. For stable releases it should be zero.
year	The year of the development release. For stable releases it should be zero.

Returns

The VersionInt.

CheckFileFormat

sub CheckFileFormat #( VersionInt fileVersion,
optional VersionInt minimumVersion ) => bool

Checks if a file’s format is compatible with the current release.

If the application is a development release or the file is from one, this only returns true if they are from the exact same development release.
If neither of them are development releases, this only returns true if the file is from a release between the minimum specified and the current version. If there’s no minimum it just checks that it’s below the current version.

Parameters

fileVersion	The VersionInt of the file format.
minimumVersion	The minimum VersionInt required of the file format. May be undef.

Returns

Whether the file’s format is compatible per the above rules.

IsDevelopmentRelease

sub IsDevelopmentRelease #( VersionInt version ) => bool

Returns whether the passed VersionInt is for a development release.

Implementation

String Format

Full Releases

Full releases are in the common major.minor format. Either part can be up to two digits. The minor version is interpreted as decimal places, so 1.3 > 1.22. There are no leading or trailing zeroes.

Development Releases

Development releases are in the format “Development Release mm-dd-yyyy (vv.vv base)” where vv.vv is the version number of the full release it’s based off of. The month and day will have leading zeroes where applicable. Example: “Development Release 07-09-2006 (1.35 base)”.

0.91 and Earlier

Text files from releases prior to 0.95 had a separate file format version number that was used instead of the application version. These were never changed between 0.85 and 0.91, so they are simply “1”. Text version numbers that are “1” instead of “1.0” will be interpreted as 0.91.

Integer Format

VersionInts are 32-bit values with the bit distribution below.

s yyyyyyyy mmmm ddddd vvvvvvv xxxxxxx
[syyy|yyyy] [ymmm|mddd] [ddvv|vvvv] [vxxx|xxxx]

s	The sign bit. Always zero, so it’s always interpreted as positive.
y	The year bits if it’s a development release, zero otherwise. 2000 is added to the value, so the range is from 2000 to 2255.
m	The month bits if it’s a development release, zero otherwise.
d	The day bits if it’s a development release, zero otherwise.
v	The major version bits. For development releases, it’s the last stable version it was based off of.
x	The minor version bits. It’s always stored as two decimals, so x.2 would store 20 here. For development releases, it’s the last stable version it was based off of.

It’s stored with the development release date at a higher significance than the version because we want a stable release to always treat a development release as higher than itself, and thus not attempt to read any of the data files. I’m not tracking data file formats at the development release level.

Binary File Format

Current

Five 8-bit unsigned values, appearing major, minor, month, day, year. Minor is always stored with two digits, so x.2 would store 20. Year is stored minus 2000, so 2006 is stored 6. Stable releases store zero for all the date fields.

1.35 Development Releases

1.35-based development releases are stored the same as current releases, but with 1.36 as the version number. This is done so previous versions of Natural Docs that didn’t include the date fields would still know it’s a higher version. There is no actual 1.36 release.

1.35 and Earlier

Two 8-bit unsigned values, appearing major then minor. Minor is always stored with two digits, so x.2 would store 20.

Text File Format

In text files, versions are the String Format followed by a native line break.