picolisp-semver/README.md

PicoLisp SemVer

SemVer 2.0.0 library for PicoLisp

• Validates and compares Major.Minor.Patch versions (ex: "1.0.0")
• Drops pre-release extensions (ex: 1.1.0-alpha.1 -> 1.1.0)
• Drops build metadata extensions (ex: 2.2.0+buildmetadata -> 2.0.0)
• Drops versions prefixed with v or v. (ex: v3.3.0 -> 3.3.0)
• Invalidates incorrectly formatted versions (ex: "1.invalid.0" -> NIL)

Requirements

• PicoLisp 32-bit or 64-bit v16.6+, or pil21
• Tested up to PicoLisp vv20.6.29, see test runs

Stability

This library is now declared stable and should be suitable for use in production environments.

Usage

Note: Namespaces can be disabled by setting the environment variable PIL_NAMESPACES=false

• Include semver.l in your application: (load "semver.l")
• Use one of the 5 public functions listed below

Function	Description	Returns	Example
semver-format	Formats a version string into a list of integers	List of integers	(1 4 2)
semver-cmp	Compares two lists of integers using the spaceship <=>	List containing NIL, 0 or T	(NIL 0 T)
semver-compare	Compares two version strings	NIL, 0, or T	T
semver-sort	Sorts a list of version strings	List of integers or strings	((1 3 0) (1 4 0) (1 6 0)) or ("1.3.0" "1.4.0" "1.6.0")
semver-satisfies	Returns whether a version is satisfied by a range	NIL or T	NIL or T

Invalid versions are returned as NIL.

Version comparison is always from left to right.

A brief explanation of the result obtained from semver-compare:

if left < right then return NIL # left is older
if left = right then return  0 # left and right are the same
if left > right then return  T # left is newer

Examples

1. Compare two version strings

(load "semver.l")

(semver-compare "1.4.0" "1.5.0")
-> NIL
(semver-compare "1.5.0" "1.5.0")
-> 0
(semver-compare "1.6.0" "1.5.0")
-> T

2. Format a version string into a list of integers

(load "semver.l")

(semver-format "1.4.0")
-> (1 4 0)

3. Compare two lists of integers

• The (car) corresponds to the major
• The (cadr) corresponds to the minor
• The (caddr) corresponds to the patch

(load "semver.l")

(semver-cmp (2 3 2) (1 4 2))
-> (T NIL 0)
(semver-cmp (1 5 0) (1 4 2))
-> (0 T NIL)
(semver-cmp (2 3 2) (1 4 2))
-> (T NIL 0)

4. Sort a list of version strings

(load "semver.l")

(semver-sort '("1.4.0" "1.6.0" "1.3.0" "1.4.0-alpha"))
-> ((1 3 0) (1 4 0) (1 4 0) (1 6 0))
(semver-sort '("1.4.0" "1.6.0" "1.3.0" "1.4.0-alpha") T)
-> ("1.3.0" "1.4.0" "1.4.0" "1.6.0")

5. Satisfies a range

Arguments:

• The first argument is the version
• The second argument is the minimum version: must be >= (greater than or equal)
• The third argument is the maximum version: must be < (less than)

Notes:

• If no argument is supplied, NIL is returned
• If the first argument is NIL, NIL is returned
• If only the first argument is supplied, T is returned
• If the third argument is NIL, only the minimum >= is compared
• If the second argument is NIL, but the third is supplied, only the maximum < is compared

(load "semver.l")

(semver-satisfies)
-> NIL
(semver-satisfies NIL NIL "3.0.0")
-> NIL
(semver-satisfies "2.0.0")
-> T
(semver-satisfies "2.0.0" "1.0.0")
-> T
(semver-satisfies "2.0.0" NIL "1.0.0")
-> NIL
(semver-satisfies "2.0.0" NIL "3.0.0")
-> T

(semver-satisfies "1.0.0" "1.0.0" "2.0.0")
-> T
(semver-satisfies "1.6.0" "1.0.0" "2.0.0")
-> T
(semver-satisfies "3.0.0" "1.0.0" "2.0.0")
-> NIL
(semver-satisfies "0.9.0" "1.0.0" "2.0.0")
-> NIL
(semver-satisfies "2.0.0" "1.0.0" "2.0.0")
-> NIL

Testing

This library now comes with full unit tests. To run the tests, type:

make check

Contributing

If you find any bugs or issues, please create an issue.

If you want to improve this library, please make a pull-request.

License

MIT License

Copyright (c) 2017-2020 Alexander Williams, Unscramble license@unscramble.jp