Description

versioning procedures

Author

elf

Version

Usage

(require-extension versions)

Download

versions.egg

Documentation

Introduction

This extension provides procedures for handling versioning of arbitrary packages. It should simplify determining when new packages are available based on some string containing version data. This should, hopefully, make life easier for maintainers.

Version Strings

Version strings have the following format:

[LABEL][MAJOR][MINOR][MICRO][PATCH][EXTRA]

MAJOR, MINOR, MICRO (if given), and all segments of PATCH (if given) must be separated by dots (.). The version strings have the following semantics:

Segment Required? Format Description
LABEL
no
[any chars]
Any characters, including digits, are allowed. If the LABEL ends with a digit character, some separator character BESIDES . is required; otherwise, the end of LABEL will be parsed as the MAJOR value. The LABEL segment usually corresponds to the name of the package.
MAJOR
yes
[integer]
Major release version.
MINOR
yes
.[integer]
Minor release version.
MICRO
no
.[integer]
Micro release version.
PATCH
no
(.[integer])...
Patch version. This may be composed of any number of segments; there is no limit. (This is to allow parsing of version control tree versions.)
EXTRA
no
[any chars]
Extra version suffix, usually for local or maintainer versions. It must be separated from the final element by a non-digit, non-dot character.

The following table gives some examples of valid version strings along with their breakdowns:

String LABEL MAJOR MINOR MICRO PATCH EXTRA
1.2 #f 1 2 #f #f #f
1.2.3 #f 1 2 3 #f #f
1.2.3.4 #f 1 2 3 (4) #f
1.2.3.4.5.6 #f 1 2 3 (4 5 6) #f
1.2-extra #f 1 2 #f #f -extra
1.2a3 #f 1 2 #f #f a3
1.2.3-extra #f 1 2 3 #f -extra
1.2.3a3 #f 1 2 3 #f a3
1.2.3-4extra #f 1 2 3 #f -4extra
1.2.3.4.5-extra #f 1 2 3 (4 5) -extra
foo-1.2.3 foo- 1 2 3 #f #f
foo_1.2.3 foo_ 1 2 3 #f #f
foo1.2.3 foo 1 2 3 #f #f
foo1-2.3.4 foo1- 2 3 4 #f #f

The following examples are NOT valid version strings:

String Reason
foo-1-2-3
Version number components must be separated by . (dot).
foo-1.a3
Minor release number is required.
1a3
Minor release is required.

Version Records

procedure: (make-version MAJOR MINOR #!key (label #f) (micro #f) (patch #f) (extra #f))

Creates a new version record with the given components. MAJOR, MINOR, and MICRO (if given) must be exact non-negative integers. LABEL and EXTRA, if given, must be non-null strings. PATCH (if given) must be either a non-negative exact integer or a list/vector composed of non-negative exact integers.

procedure: (version? OBJ)

Returns #t if OBJ is a version record.

procedure: (version:label VERSION)
procedure: (version:major VERSION)
procedure: (version:minor VERSION)
procedure: (version:micro VERSION)
procedure: (version:patch VERSION)
procedure: (version:extra VERSION)

Returns the specified field of the VERSION record.

Conversion Procedures

procedure: (string->version VERSION-STRING)

If VERSION-STRING is a string with valid version data, returns a version record with its parsed components. Otherwise, return #f.

procedure: (version->string VERSION)

Returns the string representation of the given VERSION record.

Version Comparison

Comparison Rules

Two version objects, v1 and v2 are ordered via the rules below. (The version: prefix is ommitted for conciseness.) All string fields are compared with the string=?, string<?, and string>? procedures. All numeric fields or numeric field components are compared with the fx=, fx<, and fx> procedures. The patch field, below, is first checked against the entire field for existence, then each element (if it exists) is compared in order, with an implicit last element of #f.

Field v1 Field Value v2 Field Value Comparison Result
label exists exists =
continue to major
<
v1 < v2
>
v1 > v2
exists #f
v1 > v2
#f exists
v1 < v2
#f #f
continue to major
major exists exists =
continue to minor
<
v1 < v2
>
v2 > v2
minor exists exists =
continue to micro
<
v1 < v2
>
v1 > v2
micro exists exists =
continue to patch
<
v1 < v2
>
v1 > v2
exists #f
v1 > v2
#f exists
v1 < v2
#f #f
continue to patch
patch exists exists =
continue
<
v1 < v2
>
v1 > v2
exists #f
v1 > v2
#f exists
v1 < v2
#f #f
continue to extra
extra exists exists =
v1 = v2
<
v1 < v2
>
v1 > v2
exists #f
v1 > v2
#f exists
v1 < v2
#f #f
v1 = v2

Some examples:

1.0 < foo-1.0

1.0 < 1.0.0

1.0-squid < 1.0.0

1.0.0 < 1.0.0-squid

1.0.1.0 < 1.0.1.0.1

Comparison Procedures

In each of the following procedures, VER1 and VER2 may be either version records or version strings.

procedure: (version-compare VER1 VER2)

Returns -1 if VER1<VER2, 0 if VER1=VER2, and 1 if VER1>VER2.

procedure: (version=? VER1 VER2)
procedure: (version<? VER1 VER2)
procedure: (version<=? VER1 VER2)
procedure: (version>=? VER1 VER2)
procedure: (version>? VER1 VER2)

Comparison predicates for versions, according to the rules given above.

procedure: (version-exact? VER1 VER2)

Equivalent to (version=? VER1 VER2).

procedure: (version-older? VER1 VER2)

Equivalent to (version<? VER1 VER2).

procedure: (version-newer? VER1 VER2)

Equivalent to (version>? VER1 VER2).

Sorting Procedures

procedure: (version-sort VERSION-LIST [ASCENDING? #t])

Sorts VERSION-LIST (a list of version strings and/or records). If ASCENDING? is given and #f, VERSION-LIST is sorted in descending order. ASCENDING? defaults to #t.

Bugs

None known.

Licence

Copyright (C) 2008, Lenny Frank.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation 
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the 
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED AS-IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.