lib: cli/ui/web: clarify version string code

version -> packageversion
versiondescription -> versionStringFor

hledger-ui/Hledger/UI/UIOptions.hs

@@ -9,17 +9,23 @@ import Data.Default
 import Data.List (intercalate)
 import System.Environment
 
-import Hledger.Cli hiding (progname,version,prognameandversion)
+import Hledger.Cli hiding (packageversion, progname, prognameandversion)
 import Hledger.UI.Theme (themeNames)
 
-progname, version, prognameandversion :: String
+-- cf Hledger.Cli.Version
-progname = "hledger-ui"
+
+packageversion :: String
 #ifdef VERSION
-version = VERSION
+packageversion = VERSION
 #else
-version = ""
+packageversion = ""
 #endif
-prognameandversion = versiondescription progname
+
+progname :: String
+progname = "hledger-ui"
+
+prognameandversion :: String
+prognameandversion = versionStringFor progname
 
 uiflags = [
   -- flagNone ["debug-ui"] (setboolopt "rules-file") "run with no terminal output, showing console"

hledger-web/Hledger/Web/Handler/MiscR.hs

@@ -27,7 +27,7 @@ import Yesod.Default.Handlers (getFaviconR, getRobotsR)
 
 import Hledger
 import Hledger.Web.Import
-import Hledger.Web.WebOptions (version)
+import Hledger.Web.WebOptions (packageversion)
 import Hledger.Web.Widget.Common (journalFile404)
 
 getRootR :: Handler Html
@@ -60,7 +60,7 @@ getVersionR = do
   VD{caps} <- getViewData
   when (CapView `notElem` caps) (permissionDenied "Missing the 'view' capability")
   selectRep $ do
-    provideJson $ version
+    provideJson $ packageversion
 
 getAccountnamesR :: Handler TypedContent
 getAccountnamesR = do

hledger-web/Hledger/Web/WebOptions.hs

@@ -16,18 +16,24 @@ import System.Environment (getArgs)
 import Network.Wai as WAI
 import Network.Wai.Middleware.Cors
 
-import Hledger.Cli hiding (progname, version)
+import Hledger.Cli hiding (packageversion, progname, prognameandversion)
 import Hledger.Web.Settings (defhost, defport, defbaseurl)
 
-progname, version :: String
+-- cf Hledger.Cli.Version
-progname = "hledger-web"
+
+packageversion :: String
 #ifdef VERSION
-version = VERSION
+packageversion = VERSION
 #else
-version = ""
+packageversion = ""
 #endif
+
+progname :: String
+progname = "hledger-web"
+
 prognameandversion :: String
-prognameandversion = versiondescription progname
+prognameandversion = versionStringFor  progname
+
 
 webflags :: [Flag RawOpts]
 webflags =

hledger/Hledger/Cli/Version.hs

@@ -5,11 +5,10 @@ Version number-related utilities. See also the Makefile.
 -}
 
 module Hledger.Cli.Version (
+  packageversion,
   progname,
-  version,
   prognameandversion,
-  versiondescription,
+  versionStringFor,
-  -- binaryfilename,
 )
 where
 
@@ -17,23 +16,17 @@ import GitHash (giDescribe, tGitInfoCwdTry)
 import System.Info (os, arch)
 import Hledger.Utils
 
-
+-- | This package's version, passed in as VERSION build variable, or a generic description.
--- package name and version from the cabal file
+packageversion :: String
-progname :: String
-progname = "hledger"
-
-version :: String
 #ifdef VERSION
-version = VERSION
+packageversion = VERSION
 #else
-version = "dev build"
+packageversion = "dev build"
 #endif
 
-prognameandversion :: String
+-- | A period and the patch level (number of patches added since the package version), 
-prognameandversion = versiondescription progname
+-- passed in as PATCHLEVEL build variable, or the empty string. 
-
+-- If PATCHLEVEL is defined it must be a number, or this will fail.
--- developer build version strings include PATCHLEVEL (number of
--- patches since the last tag). If defined, it must be a number.
 patchlevel :: String
 #ifdef PATCHLEVEL
 patchlevel = "." ++ show (PATCHLEVEL :: Int)
@@ -41,9 +34,12 @@ patchlevel = "." ++ show (PATCHLEVEL :: Int)
 patchlevel = ""
 #endif
 
--- the package version plus patchlevel if specified
+-- | The version and patchlevel passed in as build variables, combined and prettified.
+-- This will raise an error if VERSION is has <1 or >3 components,
+-- or if PATCHLEVEL is defined but not a number.
+-- Used as a fallback if git describe is unavailable.
 buildversion :: String
-buildversion = prettify . splitAtElement '.' $ version ++ patchlevel
+buildversion = prettify . splitAtElement '.' $ packageversion ++ patchlevel
   where
     prettify (major:minor:bugfix:patches:[]) =
         major ++ "." ++ minor ++ bugfix' ++ patches'
@@ -56,19 +52,35 @@ buildversion = prettify . splitAtElement '.' $ version ++ patchlevel
     prettify []                      = error' "VERSION is empty, please fix"  -- PARTIAL:
     prettify _                       = error' "VERSION has too many components, please fix"
 
--- | A string representing the version description of the current package
+-- | The name of this package's main executable.
-versiondescription :: String -> String
+progname :: String
-versiondescription progname = concat [
+progname = "hledger"
+
+-- | The program name and the best version information we can obtain 
+-- from git describe or build variables.
+prognameandversion :: String
+prognameandversion = versionStringFor progname
+
+-- | Given a program name, make a version string consisting of: 
+--
+-- * the program name
+-- * the output of "git describe" in the current repo at build time 
+--   (last tag, commit count since then, HEAD's git hash);
+--   or if that fails, buildversion
+-- * the platform (OS) name
+-- * the processor architecture name.
+--
+versionStringFor :: String -> String
+versionStringFor progname = concat [
     progname
   , " "
-  , either (const buildversion) giDescribe gi
+  , either (const buildversion) giDescribe $$tGitInfoCwdTry
   , ", "
   , os'
   , "-"
   , arch
   ]
   where
-    gi = $$tGitInfoCwdTry
     os' | os == "darwin"  = "mac"
         | os == "mingw32" = "windows"
         | otherwise       = os