[[tags: egg]]

== semantic-version

[[toc:]]


== Documentation

A rather busy Semantic Versioning library.

== Usage

<enscript highlight="scheme">
(import semantic-version)
</enscript>

=== version-punctuation

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

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</parameter>

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</procedure>

Returns 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)}}.

=== version

<procedure>(version ELM...) --> semantic-version</procedure>

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>
<procedure>(error-version LOC OBJ [NAM])</procedure>

Similar to ''check-errors'' procedures.

=== version-copy

<procedure>(version-copy VER) --> semantic-version</procedure>

Return a copy of the version, sharing only atoms.

; VER : {{semantic-version}} ; version to copy.

=== version?

<procedure>(version? OBJ) --> boolean</procedure>

; OBJ : {{*}} ; object to test.

=== version-depth

<procedure>(version-depth VER) --> integer</procedure>

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))</procedure>

Returns list of version elements.

; VER : {{semantic-version}} ; version to query.

=== version-separators

<procedure>(version-separators VER) --> (list-of char)</procedure>

Returns list of separator characters (punctuation).

; VER : {{semantic-version}} ; version to query.

=== version->list

<procedure>(version->list VER) --> (list-of (or number string char))</procedure>

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</procedure>

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</procedure>

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>
<procedure>(version=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
<procedure>(version>? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
<procedure>(version<=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
<procedure>(version>=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>

See {{version-compare}}.

=== version-hash

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

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</procedure>

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</procedure>

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</procedure>

Return the string form of the VER.

; VER : {{semantic-version}} ; version to convert.

=== version-depth+!

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

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, default {{0}}.
; CHR : {{char}} ; version punctuation, default is {{(string-ref (version-punctuation) 0)}}.

=== version-depth-!

<procedure>(version-depth-! VER CNT) -> semantic-version</procedure>

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</procedure>

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, default {{0}}.
; CHR : {{char}} ; version punctuation, default is {{(string-ref (version-punctuation) 0)}}.

=== version-depth-

<procedure>(version-depth- VER CNT) --> semantic-version</procedure>

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</procedure>

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</procedure>

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</procedure>

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</procedure>

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</procedure>

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</procedure>

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
<enscript highlight="scheme">
(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">
</enscript>


== Requirements

[[srfi-1]]
[[srfi-69]]
[[srfi-128]]
[[utf8]]

[[test]]


== Author

[[/users/kon-lovett|Kon Lovett]]


== 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.