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::VersionA package for handling version information.
Functions
ToStringConverts a VersionInt to a string.
FromStringConverts a version string to a VersionInt.
ToTextFileWrites a VersionInt to a text file.
ToBinaryFileWrites a VersionInt to a binary file.
FromBinaryFileRetrieves a VersionInt from a binary file.
ToValuesConverts a VersionInt to the array ( major, minor, month, day, year ).
FromValuesReturns a VersionInt created from the passed values.
CheckFileFormatChecks if a file’s format is compatible with the current release.
IsDevelopmentReleaseReturns whether the passed VersionInt is for a development release.
Implementation
String FormatFull releases are in the common major.minor format.
Integer FormatVersionInts are 32-bit values with the bit distribution below.
Binary File FormatFive 8-bit unsigned values, appearing major, minor, month, day, year.
Text File FormatIn 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

fileHandleThe handle of the file to write it to.  It should be at the correct location.
versionThe VersionInt to write.

ToBinaryFile

sub ToBinaryFile #(handle fileHandle,
VersionInt version)

Writes a VersionInt to a binary file.

Parameters

fileHandleThe handle of the file to write it to.  It should be at the correct location.
versionThe VersionInt to write.

FromBinaryFile

sub FromBinaryFile #(handle fileHandle) => VersionInt

Retrieves a VersionInt from a binary file.

Parameters

fileHandleThe 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

majorThe major version number.  For development releases, it should be the stable version it’s based off of.
minorThe 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.
monthThe numeric month of the development release.  For stable releases it should be zero.
dayThe day of the development release.  For stable releases it should be zero.
yearThe 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

fileVersionThe VersionInt of the file format.
minimumVersionThe 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]
sThe sign bit.  Always zero, so it’s always interpreted as positive.
yThe year bits if it’s a development release, zero otherwise.  2000 is added to the value, so the range is from 2000 to 2255.
mThe month bits if it’s a development release, zero otherwise.
dThe day bits if it’s a development release, zero otherwise.
vThe major version bits.  For development releases, it’s the last stable version it was based off of.
xThe 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.

sub ToString #(VersionInt version) => string
Converts a VersionInt to a string.
A comparable integer representing a version number.
sub FromString #(string string) => VersionInt
Converts a version string to a VersionInt.
sub ToTextFile #(handle fileHandle,
VersionInt version)
Writes a VersionInt to a text file.
sub ToBinaryFile #(handle fileHandle,
VersionInt version)
Writes a VersionInt to a binary file.
sub FromBinaryFile #(handle fileHandle) => VersionInt
Retrieves a VersionInt from a binary file.
sub ToValues #(VersionInt version) => ( int, int, int, int, int )
Converts a VersionInt to the array ( major, minor, month, day, year ).
sub FromValues #(int major,
int minor,
int month,
int day,
int year) => VersionInt
Returns a VersionInt created from the passed values.
sub CheckFileFormat #(VersionInt fileVersion,
optional VersionInt minimumVersion) => bool
Checks if a file’s format is compatible with the current release.
sub IsDevelopmentRelease #(VersionInt version) => bool
Returns whether the passed VersionInt is for a development release.
Full releases are in the common major.minor format.
Close