1//////////////////////////////////////////////////////////////////////
2// LibFile: version.scad
3// File that provides functions to manage versioning.
4// Includes:
5// include <BOSL2/std.scad>
6// FileGroup: Data Management
7// FileSummary: Parse and compare semantic versions.
8// FileFootnotes: STD=Included in std.scad
9//////////////////////////////////////////////////////////////////////
10
11
12BOSL_VERSION = [2,0,652];
13
14
15// Section: BOSL Library Version Functions
16
17
18// Function: bosl_version()
19// Usage:
20// ver = bosl_version();
21// Topics: Versioning
22// Description:
23// Returns a list with three integer elements, [MAJOR,MINOR,REV],
24// representing the Major, Minor, and Build Revision numbers.
25// For example, version 2.1.43 will be returned as `[2,1,43]`.
26// See Also: bosl_version_num(), bosl_version_str()
27function bosl_version() = BOSL_VERSION;
28
29
30// Function: bosl_version_num()
31// Usage:
32// ver = bosl_version_num();
33// Topics: Versioning
34// Description:
35// Returns a floating point number of the version, formatted like M.mmrrrr where M is the major version number,
36// each m is a zero-padded digit of the minor version number, and each r is a zero-padded digit of the build
37// revision number. For example, version 2.1.43 will be returned as `2.010043`.
38// See Also: bosl_version(), bosl_version_str()
39function bosl_version_num() = version_to_num(BOSL_VERSION);
40
41
42// Function: bosl_version_str()
43// Usage:
44// ver = bosl_version_str();
45// Topics: Versioning
46// Description:
47// Returns a string of the version, formatted like "MAJOR.MINOR.REV".
48// For example, version 2.1.43 will be returned as `"2.1.43"`.
49// See Also: bosl_version(), bosl_version_num()
50function bosl_version_str() = version_to_str(BOSL_VERSION);
51
52
53// Module: bosl_required()
54// Usage:
55// bosl_required(version);
56// Topics: Versioning
57// Description:
58// Given a version as a list, number, or string, asserts that the currently installed BOSL library is at least the given version.
59// See Also: version_to_num(), version_to_str(), version_to_list(), version_cmp()
60// Arguments:
61// version = version required
62module bosl_required(version) {
63 no_children($children);
64 assert(
65 version_cmp(bosl_version(), version) >= 0,
66 str(
67 "BOSL ", bosl_version_str(), " is installed, but BOSL ",
68 version_to_str(version), " or better is required."
69 )
70 );
71}
72
73
74// Section: Generic Version Functions
75
76function _version_split_str(x, _i=0, _out=[], _num=0) =
77 _i>=len(x)? concat(_out,[_num]) :
78 let(
79 cval = ord(x[_i]) - ord("0"),
80 numend = cval<0 || cval>9,
81 _out = numend? concat(_out, [_num]) : _out,
82 _num = numend? 0 : (10*_num + cval)
83 )
84 _version_split_str(x, _i=_i+1, _out=_out, _num=_num);
85
86
87// Function: version_to_list()
88// Usage:
89// ver = version_to_list(x);
90// Topics: Versioning
91// Description:
92// Given a version string, number, or list, returns the list of version integers [MAJOR,MINOR,REVISION].
93// See Also: version_to_num(), version_to_str(), version_cmp(), bosl_required()
94// Arguments:
95// x = version to convert
96// Example:
97// v1 = version_to_list("2.1.43"); // Returns: [2,1,43]
98// v2 = version_to_list(2.120234); // Returns: [2,12,234]
99// v3 = version_to_list([2,3,4]); // Returns: [2,3,4]
100// v4 = version_to_list([2,3,4,5]); // Returns: [2,3,4]
101function version_to_list(version) =
102 is_list(version)? [default(version[0],0), default(version[1],0), default(version[2],0)] :
103 is_string(version)? _version_split_str(version) :
104 is_num(version)? [floor(version), floor(version*100%100), floor(version*1000000%10000+0.5)] :
105 assert(is_num(version) || is_vector(version) || is_string(version)) 0;
106
107
108// Function: version_to_str()
109// Usage:
110// str = version_to_str(version);
111// Topics: Versioning
112// Description:
113// Takes a version string, number, or list, and returns the properly formatter version string for it.
114// See Also: version_to_num(), version_to_list(), version_cmp(), bosl_required()
115// Arguments:
116// version = version to convert
117// Example:
118// v1 = version_to_str([2,1,43]); // Returns: "2.1.43"
119// v2 = version_to_str(2.010043); // Returns: "2.1.43"
120// v3 = version_to_str(2.340789); // Returns: "2.34.789"
121// v4 = version_to_str("2.3.89"); // Returns: "2.3.89"
122function version_to_str(version) =
123 let(version = version_to_list(version))
124 str(version[0],".",version[1],".",version[2]);
125
126
127// Function: version_to_num()
128// Usage:
129// str = version_to_num(version);
130// Topics: Versioning
131// Description:
132// Takes a version string, number, or list, and returns the properly formatter version number for it.
133// See Also: version_cmp(), version_to_str(), version_to_list(), bosl_required()
134// Arguments:
135// version = version to convert
136// Example:
137// v1 = version_to_num([2,1,43]); // Returns: 2.010043
138// v2 = version_to_num([2,34,567]); // Returns: 2.340567
139// v3 = version_to_num(2.120567); // Returns: 2.120567
140// v4 = version_to_num("2.6.79"); // Returns: 2.060079
141function version_to_num(version) =
142 let(version = version_to_list(version))
143 (version[0]*1000000 + version[1]*10000 + version[2])/1000000;
144
145
146// Function: version_cmp()
147// Usage:
148// cmp = version_cmp(a,b);
149// Topics: Versioning
150// Description:
151// Given a pair of versions, in any combination of string, integer, or list, compares them, and returns the relative value of them.
152// Returns an integer <0 if a<b. Returns 0 if a==b. Returns an integer >0 if a>b.
153// See Also: version_to_num(), version_to_str(), version_to_list(), bosl_required()
154// Example:
155// cmp1 = version_cmp(2.010034, "2.1.33"); // Returns: >0
156// cmp2 = version_cmp(2.010034, "2.1.34"); // Returns: 0
157// cmp3 = version_cmp(2.010034, "2.1.35"); // Returns: <0
158function version_cmp(a,b) =
159 let(
160 a = version_to_list(a),
161 b = version_to_list(b),
162 cmps = [for (i=[0:1:2]) if(a[i]!=b[i]) a[i]-b[i]]
163 ) cmps==[]? 0 : cmps[0];
164
165
166// vim: expandtab tabstop=4 shiftwidth=4 softtabstop=4 nowrap