Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
versions
TOC »
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.
Example
(use versions) (define full-version (string->version "label1.2.4.5.6extra")) (define v1 (string->version "1.2.0")) (define v2 (string->version "2.0")) (printf "V1: ~A V2: ~A~%" (version->string v1) (version->string (version:bump v2))) (printf "Sorted: ~A~%" (map version->string (version-sort (list v2 v1 full-version))))
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. |
Version Records
- versionrecord
- make-version MAJOR MINOR #!key (label #f) (micro #f) (patch #f) (extra #f)procedure
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.
- version? OBJprocedure
Returns #t if OBJ is a version record.
- version:label VERSIONprocedure
- version:major VERSIONprocedure
- version:minor VERSIONprocedure
- version:micro VERSIONprocedure
- version:patch VERSIONprocedure
- version:extra VERSIONprocedure
Returns the specified field of the VERSION record.
Conversion Procedures
- string->version VERSION-STRINGprocedure
If VERSION-STRING is a string with valid version data, returns a version record with its parsed components. Otherwise, return #f.
- version->string VERSIONprocedure
Returns the string representation of the given VERSION record.
Conversion 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.
Comparison Procedures
In each of the following procedures, VER1 and VER2 may be either version records or version strings.
- version-compare VER1 VER2procedure
Returns -1 if VER1<VER2, 0 if VER1=VER2, and 1 if VER1>VER2.
- version=? VER1 VER2procedure
- version<? VER1 VER2procedure
- version<=? VER1 VER2procedure
- version>=? VER1 VER2procedure
- version>? VER1 VER2procedure
Comparison predicates for versions, according to the rules given above.
- version-exact? VER1 VER2procedure
Equivalent to (version=? VER1 VER2).
- version-older? VER1 VER2procedure
Equivalent to (version<? VER1 VER2).
- version-newer? VER1 VER2procedure
Equivalent to (version>? VER1 VER2).
Sorting Procedures
- (version-sort VERSION-LIST [ASCENDING? #t])procedure
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.
Bumping Procedures
Functional interface
All of the following procedures return a fresh version object.
- bump:major VERSION #!key (to #f)procedure
Returns a version with the major-part incremented or set to to if given.
- bump:minor VERSION #!key (to #f)procedure
Returns a version with the minor-part incremented or set to to if given.
- bump:micro VERSION #!key (to #f)procedure
Returns a version with the micro-part incremented or set to to if given.
- bump:patch VERSION #!key (to #f)procedure
Returns a version with the patch-part incremented or set to to if given.
- bump VERSIONprocedure
Returns a version with the lowest possible part incremented. This procedure tries to do the right thing, and should generaly really do.
Mutating interface
The following procedures mutate the version record in place.
- bump:major! VERSION #!key (to #f)procedure
Increase the major-part of the version by 1 or set to to if given.
- bump:minor! VERSION #!key (to #f)procedure
Increase the minor-part of the version by 1 or set to to if given.
- bump:micro! VERSION #!key (to #f)procedure
Increase the micro-part of the version by 1 or set to to if given.
- bump:patch! VERSION #!key (to #f)procedure
Increase the last number ofthe patch-part by 1 or set to to if given.
- bump! VERSIONprocedure
Increase the lowest possible part by 1. This procedure tries to do the right thing, and should generaly really do.
Licence
Copyright (C) 2008, Lenny Frank. All rights reserved. Copyright (C) 2011, David Krentzlin. 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.