Natural Docs
Version 1.2
Natural Docs
Packages
Objects
Languages
Output Formats
Extensions
Documentation
Indexes
Web Site

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.
Format
Version numbers are represented as major.minor.
Functions
FromString
Converts a version string to a comparable integer.
FromBinaryFile
Retrieves a version number from a binary file.
FromTextFile
Retrieves a version number from a text file.
ToString
Converts a version integer to a string.
ToTextFile
Writes a version string to a text file.
ToBinaryFile
Writes a version string to a binary file.
Implementation
String Format
String versions are normally in the common major.minor format, with the exception of “1”.
Integer Format
Version integers are 16-bit unsigned values.
Binary File Format
In binary files, versions are two 8-bit unsigned values, appearing major then minor.
Text File Format
In text files, versions are the String Format followed by a native line break.

Format

Version numbers are represented as major.minor.  Major is from 0 to 255, and minor can have one or two digits.  Minor is interpreted as a decimal, so 1.25 is less than 1.3.

Functions

FromString

sub FromString #(string)

Converts a version string to a comparable integer.

FromBinaryFile

sub FromBinaryFile #(fileHandle)

Retrieves a version number from a binary file.

Parameters

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

Returns

The version as a comparable integer.

FromTextFile

sub FromTextFile #(fileHandle)

Retrieves a version number from a text file.

Parameters

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

Returns

The version as a comparable integer.

ToString

sub ToString #(integer)

Converts a version integer to a string.

ToTextFile

sub ToTextFile #(fileHandle,
version)

Writes a version string to a text file.

Parameters

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

ToBinaryFile

sub ToBinaryFile #(fileHandle,
version)

Writes a version string to a binary file.

Parameters

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

Implementation

String Format

String versions are normally in the common major.minor format, with the exception of “1”.

If the string is “1” and not “1.0”, it’s represents releases 0.85 through 0.91, since those had a separate version number for data files.  We switched to using the app version number in 0.95.  This issue does not apply to binary data files since they came after 0.95.

Text files with “1” as the version will be interpreted as 0.91, since this should not cause compatibility problems.  The only file format changes between 0.85 and 0.91 were to PreviousMenuState.nd, which didn’t exist in 0.85 and didn’t change between 0.9 and 0.91, and Menu.txt, which only changed in 0.9 to add index entries.

Integer Format

Version integers are 16-bit unsigned values.  The major version is the high-order byte, and the minor the low-order byte.  The minor is always stored with two decimals, so 0.9 would be stored as 0 and 90.

Binary File Format

In binary files, versions are two 8-bit unsigned values, appearing major then minor.  The minor is always stored with two decimals, so 0.9 would be stored as 0 and 90.  It’s in the Integer Format if interpreted as a big-endian 16-bit value.

Text File Format

In text files, versions are the String Format followed by a native line break.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
sub FromString #(string)
Converts a version string to a comparable integer.
sub FromBinaryFile #(fileHandle)
Retrieves a version number from a binary file.
sub FromTextFile #(fileHandle)
Retrieves a version number from a text file.
sub ToString #(integer)
Converts a version integer to a string.
sub ToTextFile #(fileHandle,
version)
Writes a version string to a text file.
sub ToBinaryFile #(fileHandle,
version)
Writes a version string to a binary file.
String versions are normally in the common major.minor format, with the exception of “1”.
The file used to store the previous state of the menu so as to detect changes.
The file used to generate the menu.
Version integers are 16-bit unsigned values.