1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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;
|