You are looking at historical revision 41388 of this page. It may differ significantly from its current revision.
semantic-version
Documentation
A rather busy Semantic Versioning library.
Usage
(import semantic-version)
Core
Usage
(import (semantic-version core))
version-punctuation
[parameter] (version-punctuation [STR]) -> stringReturns 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-versionReturns new version with CNT elements, ELM, and punctuation CHR.
- CNT
- integer ; element count.
- ELM
- (or number string symbol) ; version element, default 0.
- CHR
- char ; version punctuation, default is (string-ref (version-punctuation) 0).
check-version
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-versionReturns 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-versionReturn 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) --> stringReturn the string form of the VER.
- VER
- semantic-version ; version to convert.
Element
Usage
(import (semantic-version element))
version
[procedure] (version ELM...) --> semantic-versionReturns 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-versionReturn a copy of the version, sharing only atoms.
- VER
- semantic-version ; version to copy.
version-depth
[procedure] (version-depth VER) --> integerReturn 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.
Compare
Usage
(import (semantic-version compare))
version-tail-zero
[parameter] (version-tail-zero [IGN?]) -> booleanReturns whether trailing 0's are ignored during comparision.
- IGN?
- boolean ; ignore flag, default is #f.
version-compare
[procedure] (version-compare VER1 VER2 [TAIL-ZERO?]) --> integerReturns 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?]) --> booleanStrictly equal, where VER1 & VER2 compare equal and have the same punctuation.
version-hash
[procedure] (version-hash VER [BND RND]) --> integerA 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.
Operation
Usage
(import (semantic-version operation))
version-depth+!
[procedure] (version-depth+! VER CNT [ELM CHR]) -> semantic-versionReturns 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-versionReturns 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-versionReturns 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-versionReturns 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-extend!
[procedure] (version-extend! VER COMP...) -> semantic-versionReturns 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-versionReturns 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-versionReturn VER with target element at or before IDXth element incremented by AMT.
- VER
- semantic-version ; version to adjust.
- IDX
- fixnum ; 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-versionReturn VER with target element at or before IDXth element decremented by AMT.
- VER
- semantic-version ; version to adjust.
- IDX
- fixnum ; 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-versionReturn copy of VER with target element at or before IDXth element incremented by AMT.
- VER
- semantic-version ; version to adjust.
- IDX
- fixnum ; 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-versionReturn copy of VER with target element at or before IDXth element decremented by AMT.
- VER
- semantic-version ; version to adjust.
- IDX
- fixnum ; 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 (pathname->version pn) (string->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"> (version-inc! ver1) ;=> #<version "a.1.b.3.extra"> ;see Bugs (version-dec! ver1 1) ;=> #<version "a.0.b.3.extra">
Bugs & Limitations
- Poor version-inc!/dec!/inc/{{dec)), or adjustment, semantics. The index should be on the list of targets, not all elements. And targets are only number.
Requirements
Author
Version history
- 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
Copyright (C) 2021-2022 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.