You are looking at historical revision 39962 of this page. It may differ significantly from its current revision.

semantic-version

Documentation

A rather busy Semantic Versioning library.

Usage

 
(import semantic-version)

version-punctuation

[parameter] (version-punctuation [STR]) -> string

Returns the string (set) of punctuation characters. The first is always the default.

STR
string ; punctuation set, default is "._- +;:,".

version-tail-zero

[parameter] (version-tail-zero [IGN?]) -> boolean

Returns whether trailing 0's are ignored during comparision.

IGN?
boolean ; ignore flag, default is #f.

make-version

[procedure] (make-version CNT ELM [CHR]) --> semantic-version

Returns new version with CNT elements, ELM, and punctuation CHR.

CNT
integer ; element count.
ELM
(or number string symbol) ; version element.
CHR
char ; version punctuation, default is (string-ref (version-punctuation) 0).

version

[procedure] (version ELM...) --> semantic-version

Returns a new version with the specified elements, ELM..., and the default punctuation (see version-punctuation).

ELM
(or number string symbol) ; version element.

Note that the symbol printname is used internally.

check-version

error-version

[procedure] (check-version LOC OBJ [NAM]) -> semantic-version
[procedure] (error-version LOC OBJ [NAM])

Similar to check-errors procedures.

version-copy

[procedure] (version-copy VER) --> semantic-version

Return a copy of the version, sharing only atoms.

VER
semantic-version ; version to copy.

version?

[procedure] (version? OBJ) --> boolean
OBJ
* ; object to test.

version-depth

[procedure] (version-depth VER) --> integer

Return the number of elements in the version.

VER
semantic-version ; version to query.

version-elements

[procedure] (version-elements VER) --> (list-of (or number string))

Returns list of version elements.

VER
semantic-version ; version to query.

version-separators

[procedure] (version-separators VER) --> (list-of char)

Returns list of separator characters (punctuation).

VER
semantic-version ; version to query.

version->list

[procedure] (version->list VER) --> (list-of (or number string char))

Returns an "exploded" form, with version elements interleaved with punctuation characeters.

VER
semantic-version ; version to list.

list->version

[procedure] (list->version LIS) --> semantic-version

Returns a version from an "exploded" form, see version->list.

LIS
(list-of (or number string symbol char)) ; list of version components.

version-compare

[procedure] (version-compare VER1 VER2 [TAIL-ZERO?]) --> integer

Returns a negative, zero, or positive integer representing the relative order of VER1 and VER2. Compares number & string elements natively, but in a comparison between a number & a string element, the string always takes precedence. Thus "1.a.2" < "a.1.2".

VER1
semantic-version ; version 1 to compare.
VER2
semantic-version ; version 2 to compare.
TAIL-ZERO?
boolean ; ignore trailing 0's?

Orders versions in the same manner as the chicken-install tool.

version<?

version=?

version>?

version<=?

version>=?

[procedure] (version<? VER1 VER2 [TAIL-ZERO?]) --> boolean
[procedure] (version=? VER1 VER2 [TAIL-ZERO?]) --> boolean
[procedure] (version>? VER1 VER2 [TAIL-ZERO?]) --> boolean
[procedure] (version<=? VER1 VER2 [TAIL-ZERO?]) --> boolean
[procedure] (version>=? VER1 VER2 [TAIL-ZERO?]) --> boolean

See version-compare.

version-hash

[procedure] (version-hash VER [BND RND]) --> integer

A SRFI 69 compliant hash function for the semantic-version type.

VER
semantic-version ; version to hash.
BND
integer ; bounds (limit), see SRFI 69.
RND
integer ; randomization (salt), see SRFI 69.

version-comparator

[procedure] (version-comparator) --> comparator

Returns a SRFI 128 comparator for the semantic-version type.

comparator-hash-function
version-hash
comparator-type-test-predicate
version?
comparator-equality-predicate comparator
version=?
comparator-ordering-predicate comparator
version<?

string->version

[procedure] (string->version STR) --> semantic-version

Return the parsed form of the STR. The source separator (punctuation) is preserved, and restored by version->string.

STR
string ; string to convert.

version->string

[procedure] (version->string VER) --> string

Return the string form of the VER.

VER
semantic-version ; version to convert.

version-depth+!

[procedure] (version-depth+! VER CNT ELM [CHR]) -> semantic-version

Returns VER with more "depth", as ELM, interspersed with CHR.

VER
semantic-version ; version to extend.
CNT
integer ; element count.
ELM
(or number string symbol) ; version element.
CHR
char ; version punctuation, default is (string-ref (version-punctuation) 0).

version-depth-!

[procedure] (version-depth-! VER CNT) -> semantic-version

Returns VER with less "depth", as CNT elements are dropped, along with the corresponding punctuation.

VER
semantic-version ; version to extend.
CNT
integer ; element count.

version-depth+

[procedure] (version-depth+ VER CNT ELM [CHR]) --> semantic-version

Returns a copy of VER with more "depth", as ELM, interspersed with CHR.

VER
semantic-version ; version to extend.
CNT
integer ; element count.
ELM
(or number string symbol) ; version element.
CHR
char ; version punctuation, default is (string-ref (version-punctuation) 0).

version-depth-

[procedure] (version-depth- VER CNT) --> semantic-version

Returns a copy of VER with less "depth", as CNT elements are dropped, along with the corresponding punctuation.

VER
semantic-version ; version to extend.
CNT
integer ; element count.

version-extend!

[procedure] (version-extend! VER COMP...) -> semantic-version

Returns VER with added "depth", in the form of a new "tail", in "exploded" form.

VER
semantic-version ; version to extend.
COMP
(list-of (or number string symbol char)) ; version components.

version-extend

[procedure] (version-extend VER COMP...) --> semantic-version

Returns copy of VER with added "depth", in the form of a new "tail", in "exploded" form.

VER
semantic-version ; version to extend.
COMP
(list-of (or number string symbol char)) ; version components.

version-inc!

[procedure] (version-inc! VER [IDX AMT]) -> semantic-version

Return VER with IDX element incremented by AMT.

VER
semantic-version ; version to adjust.
IDX
integer ; which element to adjust, default is (sub1 (version-depth VER)).
AMT
number ; amount to adjust, default is 1.

Currently only number elements may be targets.

version-dec!

[procedure] (version-dec! VER [IDX AMT]) -> semantic-version

Return VER with IDX element decremented by AMT.

VER
semantic-version ; version to adjust.
IDX
integer ; which element to adjust, default is (sub1 (version-depth VER)).
AMT
number ; amount to adjust, default is 1.

Currently only number elements may be targets.

version-inc

[procedure] (version-inc VER [IDX AMT]) --> semantic-version

Return copy of VER with IDX element incremented by AMT.

VER
semantic-version ; version to adjust.
IDX
integer ; which element to adjust, default is (sub1 (version-depth VER)).
AMT
number ; amount to adjust, default is 1.

Currently only number elements may be targets.

version-dec

[procedure] (version-dec VER [IDX AMT]) --> semantic-version

Return copy of VER with IDX element decremented by AMT.

VER
semantic-version ; version to adjust.
IDX
integer ; which element to adjust, default is (sub1 (version-depth VER)).
AMT
number ; amount to adjust, default is 1.

Currently only number elements may be targets.

Example

 
(import (chicken base) (chicken file) (chicken pathname) (chicken sort)
        (srfi 1)
        semantic-version)

(define (egg-repo-versions repo egg)
  (map! (o string->version pathname-strip-directory)
        (glob (make-pathname `(,repo ,egg "tags") "*"))) )

(for-each (o print version->string) (sort (egg-repo-versions REPO "apropos") version<?))
;=> prints release versions in ascending order

(string=? "a.1,b" ((o version->string string->version) "a.1,b"))
;=> #t
; but, assuming baseline `version-punctuation'
(string=? "a.1.b" (version->string (version 'a 1 'b)))
;=> #t

(define ver1 (version 'a 1 'b 2))

ver1
;=> #<version "a.1.b.2">
(version-inc! ver1)
;=> #<version "a.1.b.3">
(version-dec! ver1 1)
;=> #<version "a.0.b.3">

Requirements

srfi-1 srfi-69 srfi-128 utf8

test

Author

Kon Lovett

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/semantic-version

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history
0.0.2
Use record, make-version & semantic-version follow convention, rename accessors.
0.0.1
Release.

License

Copyright (C) 2021 Kon Lovett. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

 Redistributions of source code must retain the above copyright notice, this list of conditions and the following
   disclaimer.
 Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided with the distribution.
 Neither the name of the author nor the names of its contributors may be used to endorse or promote
   products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICESLOSS OF USE, DATA, OR PROFITSOR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.