add full dash functionality & documentation

README.md

@@ -2,9 +2,10 @@
 Semver (Semantic Version) parsing & utility script/function library in pure bash
 
 ## Overview
-`sver` is a self contained cli tool and function library implementing a [Semantic
-Versioning 2](https://semver.org) compliant parser and utilities. Written in
-optimized, portable, pure bash (v3+) for simplicity & speed.
+**sver** is a self contained cli tool and function library implementing a
+[Semantic Versioning 2](https://semver.org) compliant parser and utilities.
+Written in optimized, portable, pure Bash (v3+) for simplicity & speed, and
+can be even used as a function library in Busybox Dash.
 
 ### Features
 - bump or get version identifiers (major, minor, patch, prerelease, build_metadata)
@@ -25,7 +26,7 @@ It is a self contained bash script, so you can clone the repo and run directly.
 However, here are some other convenient ways to install it.
 
 #### asdf
-A [PR](https://github.com/asdf-vm/asdf-plugins/pull/965) has been opened to add `sver`
+A [PR](https://github.com/asdf-vm/asdf-plugins/pull/965) has been opened to add **sver**
 into the asdf plugin registry; until that happens, you can manually specify the asdf
 plugin repo.
 ```bash
@@ -50,7 +51,7 @@ If we can get enough momentum for this project on GitHub to meet Homebrew
 criteria for a core formula, it will be added! This requires more than 75 stars,
 30 forks or 30 watchers.
 
-### Command
+### Command line usage
 See `sver help` for documentation.
 ```text
 sver v1.0.0 (https://github.com/robzr/sver) self contained cli tool and function
@@ -103,19 +104,39 @@ Constraints:
 ```
 
 ### Bash function library
-To use sver as a bash function library, source it with the `SVER_RUN=false` variable
-set.
+To use **sver** as a Bash function library, source it with the `SVER_RUN=false`
+variable set.
 ```bash
 SVER_RUN=false . "$(command -v sver)"
 ```
-The same commands and syntax are available as the CLI, but written as
-functions, with the syntax `sver_<command>[_<subcommand>]`, ie: `sver_version`,
-`sver_bump_major`, etc. See source for details.
+As the CLI is simply a mapping to the function library, the commands and syntax
+are the same, with the functions naming pattern `sver_<command>[_<subcommand>]`,
+ie: `sver_version`, `sver_bump_major`, etc. To avoid the use of subshells and 
+redirection for returning string values, functions generally return values via
+the global `REPLY` variable. Note that this is a reuse of the default response
+variable used by Bash (and Dash) `read`.
+
+### Dash/Ash function library
+The command line completion and CLI command-to-function mapping depends on the
+Bash builtin `compgen`, which is not available in Dash (commonly used as the
+default shell in Alpine Linux and other compact distributions that use Busybox).
+Therefore, as the script is written, it will not function in Dash. However,
+all of the core **sver** functions can be used, although the `sort` function,
+differs from the bash implementation, by using a shell call to Busybox `sort`,
+and does not fully sort prereleases according to SemVer spec. Every other
+function is identical. To use **sver** in Dash, the Bash specific syntax needs
+to first be stripped out, which can be done with the following command (even
+with Busybox):
+```
+sed -n '/# bash-only-begin/,/# bash-only-end/!p' sver > sver.dash
+. sver.dash
+```
 
 # License
 Permissive [Creative Commons - CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
 license - same as Semantic Versioning itself.
 
 # TODO
-- constraint testing
-- asdf plugin
+- add unit testing for constraints
+- constraint sub-version may need work (ex: `v1.2.3 <= v1`)
+- finish dash functionality

sver

@@ -10,6 +10,12 @@ library implementing a Semantic Versioning 2 compliant parser and utilities.
 Written in optimized, portable, pure bash (v3)+ for simplicity & speed.
 "
 
+# Filter bash only segments out with: sed -n '/# bash-only-begin/,/# bash-only-end/!p'
+SVER_BASH_ONLY_EXCLUDED=true
+# bash-only-begin
+SVER_BASH_ONLY_EXCLUDED=false
+# bash-only-end
+
 # regex from https://semver.org with changes
 # - added ^v?
 # - removed PCRE named capture groups
@@ -52,7 +58,6 @@ _sver_compare_numeric() {
   return 0
 }
 
-# Filter bash only segments out with: sed -n '/# bash-only-begin/,/# bash-only-end/!p'
 # bash-only-begin
 _sver_complete_function() {
   if [ "$COMP_CWORD" = 1 ]; then
@@ -133,10 +138,10 @@ sver_constraint() { # $1=version $2=constraint(s); if matches returns 0 else 1
   version=$REPLY
   shift
   constraints="$*"
-  while [ -n "$constraints" ] ; do
+  while [ -n "$constraints" ]; do
     constraint=${constraints%%,*}
     constraint=${constraint#*,}
-    if [ "$constraint" = "$constraints" ] ; then
+    if [ "$constraint" = "$constraints" ]; then
       constraints=
     fi
     operator=${constraint//[^!=<>~]/}
@@ -237,7 +242,7 @@ sver_get_major() {
 
 sver_get_minor() {
   local version=${1#v}
-  if [[ "$version" =~ \.[0-9] ]] ; then
+  if [[ "$version" =~ \.[0-9] ]]; then
     version=${version#*\.}
     REPLY=${version%%\.*}
   else
@@ -247,7 +252,7 @@ sver_get_minor() {
 
 sver_get_patch() {
   local version=${1#v}
-  if [[ "$version" =~ \.[0-9]+\.[0-9] ]] ; then
+  if [[ "$version" =~ \.[0-9]+\.[0-9] ]]; then
     version=${version#*\.*\.}
     REPLY=${version%%[+-]*}
   else
@@ -434,7 +439,19 @@ sver_normalize() {
   REPLY=$version_return
 }
 
-sver_sort() { # no arg, input is list of semvers, output is via stdout
+# no arg, input is list of semvers, output is via stdout
+sver_sort() {
+  if [ "$SVER_BASH_ONLY_EXCLUDED" = true ]; then
+    # Warning: busybox compatible, but an approximation as it does not sort
+    # prereleases properly
+    sort -t. -nk1 -nk2 -nk3 -k4
+  else
+    sver_sort_bash
+  fi
+}
+
+# bash-only-begin
+sver_sort_bash() {
   local i j swapped tmp versions
   declare -a versions
 
@@ -463,6 +480,7 @@ sver_sort() { # no arg, input is list of semvers, output is via stdout
   IFS=$tmp
   REPLY=
 }
+# bash-only-end
 
 sver_validate() {
   REPLY=