semantic-version - The CHICKEN Scheme wiki

Documentation

A rather busy Semantic Versioning library.

Usage

(import semantic-version)

Core

Usage

(import (semantic-version core))

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 "._- +;:,".

make-version

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

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

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

error-version

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

Similar to check-errors procedures.

version?

[procedure] (version? OBJ) --> boolean

OBJ: * ; object to test.

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.

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.

Elements

Usage

(import (semantic-version element))

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.

version-copy

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

Return a copy of the version, sharing only atoms.

VER: semantic-version ; version to copy.

version-depth

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

Return the number of elements in the version.

VER: semantic-version ; version to query.

version-parts

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

Returns list of version elements.

VER: semantic-version ; version to query.

version-puncs

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

Returns list of punctuation characters.

VER: semantic-version ; version to query.

Comparisons

Usage

(import (semantic-version compare))

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.

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-strict=?

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

Strictly equal, where VER1 & VER2 compare equal and have the same punctuation.

version-hash

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

A CHICKEN SRFI 69 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.

Operations

Usage

(import (semantic-version operation))

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: fixnum ; element count.
ELM: (or number string symbol) ; version element, default 0.
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: fixnum ; element count.

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: fixnum ; element count.
ELM: (or number string symbol) ; version element, default 0.
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: fixnum ; element count.

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-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-succ

[procedure] (version-succ VER [AMT [IDX [SEARCH?]]]) --> semantic-version

Return copy of VER with the target element at, or before with SEARCH?, IDX replaced by the AMT successor.

VER: semantic-version ; version to adjust.
AMT: fixnum ; amount to adjust, default is 1.
IDX: fixnum ; which element to adjust, default is (sub1 (version-depth VER)).
SEARCH?: boolean ; search backwards for a successful operation from IDX, default is #f.

Only integer elements may be targets. See Notes.

Underflow of a zero predecessor is an error. Overflow of a most-positive-fixnum successor is an error.

version-pred

[procedure] (version-pred VER [AMT [IDX [SEARCH?]]]) --> semantic-version

Return copy of VER with the target element at, or before with SEARCH?, IDX replaced by the AMT predecessor.

VER: semantic-version ; version to adjust.
AMT: fixnum ; amount to adjust, default is 1.
IDX: fixnum ; which element to adjust, default is (sub1 (version-depth VER)).
SEARCH?: boolean ; search backwards for a successful operation from IDX, default is #f.

Only integer elements may be targets. See Notes.

Underflow of a zero predecessor is an error. Overflow of a most-positive-fixnum successor is an error.

version-succ!

[procedure] (version-succ! VER [AMT [IDX [SEARCH?]]]) -> semantic-version

Return VER with the target element at, or before with SEARCH?, IDX replaced by the AMT successor.

VER: semantic-version ; version to adjust.
AMT: fixnum ; amount to adjust, default is 1.
IDX: fixnum ; which element to adjust, default is (sub1 (version-depth VER)).
SEARCH?: boolean ; search backwards for a successful operation from IDX, default is #f.

Only integer elements may be targets. See Notes.

Underflow of a zero predecessor is an error. Overflow of a most-positive-fixnum successor is an error.

version-pred!

[procedure] (version-pred! VER [AMT [IDX [SEARCH?]]]) -> semantic-version

Return VER with the target element at, or before with SEARCH?, IDX replaced by the AMT predecessor.

VER: semantic-version ; version to adjust.
AMT: fixnum ; amount to adjust, default is 1.
IDX: fixnum ; which element to adjust, default is (sub1 (version-depth VER)).
SEARCH?: boolean ; search backwards for a successful operation from IDX, default is #f.

Only integer elements may be targets. See Notes.

Underflow of a zero predecessor is an error. Overflow of a most-positive-fixnum successor is an error.

Example

(import scheme utf8
  (chicken base)
  (chicken file)
  (chicken pathname)
  (chicken sort)
  semantic-version)

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

(for-each print (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 "extra"))
ver1
;=> #<version "a.1.b.2.extra">
;See above for last element index as the default
(version-succ! ver1)
;=> #<version "a.1.b.3.extra">
;See Notes on indexing & element search
(version-pred! ver1 1 2)
;=> #<version "a.0.b.3.extra">

Notes

Odd successor & predecessor, or adjustment, semantics. The index could be on the list of targets, not all elements.
Targets are only integer. Enumerations could be accommodated. Strings treatment can be overridden, but not recommended.
Predecessor of a zero is an Underflow Error. Successor of a most-positive-fixnum is an Overflow Error.

Requirements

utf8 srfi-1 srfi-69 srfi-128 vector-lib record-variants

test

Author

Kon Lovett

Version history

0.0.16: Successor & Predecessor search is optional.
0.0.15: Swap successor & predecessor index and amount arguments. Error on underflow/overflow of targets.
0.0.14: .
0.0.13: .
0.0.12: .
0.0.11: Better UTF-8 support.
0.0.10: Add version-succ!/pred!/succ/pred. Remove version-inc!/dec!/inc/dec.
0.0.9: Better, better but not good, version-inc!/dec!/inc/dec semantics.
0.0.8: .
0.0.7: .
0.0.6: Rename version-elements => version-parts & version-separators => version-puncs.
0.0.5: Add version-strict=?.
0.0.4: Remove version-comparator; see tests.
0.0.3: Separate modules.
0.0.2: Use record, make-version & semantic-version follow convention, rename accessors.
0.0.1: Release.

License

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.