diff options
Diffstat (limited to 'docs/doctool/Modules/NaturalDocs/Version.pm')
| -rw-r--r-- | docs/doctool/Modules/NaturalDocs/Version.pm | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/docs/doctool/Modules/NaturalDocs/Version.pm b/docs/doctool/Modules/NaturalDocs/Version.pm new file mode 100644 index 00000000..67f1a331 --- /dev/null +++ b/docs/doctool/Modules/NaturalDocs/Version.pm @@ -0,0 +1,201 @@ +############################################################################### +# +# Package: 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. +# +############################################################################### + +# This file is part of Natural Docs, which is Copyright (C) 2003-2005 Greg Valure +# Natural Docs is licensed under the GPL + +use strict; +use integer; + +package NaturalDocs::Version; + +# +# About: 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. +# + +# Group: Functions + + +# +# Function: FromString +# +# Converts a version string to a <VersionInt>. +# +sub FromString #(string) + { + my ($self, $string) = @_; + + if ($string eq '1') + { + return 91; # 0.91 + } + else + { + $string =~ /^(\d+)\.(\d+)$/; + my ($major, $minor) = ($1, $2); + + if (length $minor == 1) + { $minor *= 10; }; + + return ($major << 8) | $minor; + }; + }; + +# +# Function: FromBinaryFile +# +# 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>. +# +sub FromBinaryFile #(fileHandle) + { + my ($self, $fileHandle) = @_; + + my $version; + read($fileHandle, $version, 2); + + # A big-endian UInt16 as a shortcut to the integer format. + return unpack('n', $version); + }; + +# +# Function: FromTextFile +# +# 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>. +# +sub FromTextFile #(fileHandle) + { + my ($self, $fileHandle) = @_; + + my $version = <$fileHandle>; + ::XChomp(\$version); + + return $self->FromString($version); + }; + + +# +# Function: ToString +# +# Converts a <VersionInt> to a string. +# +sub ToString #(integer) + { + my ($self, $integer) = @_; + + my $major = $integer >> 8; + my $minor = $integer & 0x00FF; + + if ($minor % 10 == 0) + { $minor /= 10; } + elsif ($minor < 10) + { $minor = '0' . $minor; }; + + return $major . '.' . $minor; + }; + + +# +# Function: ToTextFile +# +# 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. +# +sub ToTextFile #(fileHandle, version) + { + my ($self, $fileHandle, $version) = @_; + + print $fileHandle $self->ToString($version) . "\n"; + }; + + +# +# Function: ToBinaryFile +# +# 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. +# +sub ToBinaryFile #(fileHandle, version) + { + my ($self, $fileHandle, $version) = @_; + + # Big-endian UInt16 as a shortcut to the binary format. + print $fileHandle pack('n', $version); + }; + + + +############################################################################### +# Group: Implementation + +# +# About: 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. +# + +# +# About: Integer Format +# +# <VersionInts> 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. +# + +# +# About: 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. +# + +# +# About: Text File Format +# +# In text files, versions are the <String Format> followed by a native line break. +# + + +1; |