Adopt new versions module functions

- add xqdoc
- ensure find endpoint can use all version attributes for finding packages

Author: joewiz

modules/app.xqm

@@ -216,7 +216,7 @@ declare function app:view-package($node as node(), $model as map(*), $mode as xs
             (: view current package info :)
             else
                 let $packages := $package-group//package
-                let $compatible-packages := versions:find-compatible-packages($packages, $procVersion)
+                let $compatible-packages := versions:get-packages-satisfying-exist-version($packages, $procVersion)
                 let $incompatible-packages := $packages except $compatible-packages
                 let $show-details := true()
                 return

modules/find.xq

@@ -1,9 +1,18 @@
 xquery version "3.1";
 
 (:~
- : Respond to eXist build requests for packages using various identifier and version number criteria
+ : Respond to eXist build requests for packages by their package descriptor's abbrev or name 
+ : attribute, matching either (1) a minimum eXist version expressed as a SemVer version, or 
+ : (2) an EXPath Package version attributes (`version`, `semver`, `semver-min`, and `semver-max`).
  :
- : The info parameter can be used for troubleshooting
+ : The parameter name `version` is retained for backward compatibility, even though it's 
+ : `versions` in the EXPath Package spec.
+ :
+ : The `info` parameter can be used for troubleshooting.
+ :
+ : The `zip` parameter forces the EXPath Package to be returned with a .xar.zip file extension.
+ :
+ : @see http://expath.org/spec/pkg
  :)
 
 import module namespace app="http://exist-db.org/xquery/app" at "app.xqm";
@@ -16,33 +25,37 @@ declare namespace response="http://exist-db.org/xquery/response";
 let $abbrev := request:get-parameter("abbrev", ())
 let $name := request:get-parameter("name", ())
 let $exist-version-semver := request:get-parameter("processor", $config:default-exist-version)
-let $version := request:get-parameter("version", ())
+let $versions := request:get-parameter("version", ())
 let $semver := request:get-parameter("semver", ())
 let $semver-min := request:get-parameter("semver-min", ())
 let $semver-max := request:get-parameter("semver-max", ())
 let $zip := request:get-parameter("zip", ())
 let $info := request:get-parameter("info", ())
 let $app-root-absolute-url := request:get-parameter("app-root-absolute-url", ())
 
-let $package-group :=
+let $packages :=
     if ($name) then
-        doc($config:package-groups-doc)//package-group[name eq $name]
+        doc($config:package-groups-doc)//package-group[name eq $name]//package
     else
-        doc($config:package-groups-doc)//package-group[abbrev eq $abbrev]
+        doc($config:package-groups-doc)//package-group[abbrev eq $abbrev]//package
 
-let $newest-compatible-package := versions:find-newest-compatible-package($package-group//package, $exist-version-semver, $version, $semver, $semver-min, $semver-max)
+let $package := 
+    if (exists($versions) or exists($semver) or exists($semver-min) or exists($semver-max)) then
+        versions:get-newest-package-satisfying-version-attributes($packages, $versions, $semver, $semver-min, $semver-max)
+    else
+        versions:get-newest-package-satisfying-exist-version($packages, $exist-version-semver)
 
 return
-    if ($newest-compatible-package) then
+    if ($package) then
         (: TODO shouldn't we get $abs-public from $config? - joewiz :)
         let $abs-public := $app-root-absolute-url || "/public/"
-        let $xar-filename := $newest-compatible-package/@path
+        let $xar-filename := $package/@path
         return
             if ($info) then
                 element found {
-                    $newest-compatible-package/@sha256, 
-                    $newest-compatible-package/version ! attribute version {.},
-                    $newest-compatible-package/@path
+                    $package/@sha256, 
+                    $package/version ! attribute version {.},
+                    $package/@path
                 }
             else if ($zip) then
                 app:redirect-to($abs-public || $xar-filename || ".zip")

modules/list.xq

@@ -20,16 +20,12 @@ declare option output:method "xml";
 declare option output:media-type "application/xml";
 
 let $exist-version := request:get-parameter("version", $config:default-exist-version)
-let $exist-version-semver := 
-    if (semver:validate($exist-version)) then
-        $exist-version
-    else
-        $config:default-exist-version
+let $exist-version-semver := semver:parse($exist-version, true()) => semver:serialize-parsed()
 return
     element apps { 
         attribute version { $exist-version-semver },
         for $package-group in doc($config:package-groups-doc)//package-group
-        let $compatible-packages := versions:find-compatible-packages($package-group//package, $exist-version-semver)
+        let $compatible-packages := versions:get-packages-satisfying-exist-version($package-group//package, $exist-version-semver)
         return
             if (exists($compatible-packages)) then
                 let $newest-package := head($compatible-packages)