ENH Add min-ngless-version to external modules

This way, if a module does require some specific bit of functionality,
it can be specified explicit for better error messages

closes #143

Author: luispedro

ChangeLog

@@ -1,4 +1,5 @@
 Version 1.2.0+
+	* Add min-ngless-version field for modules
 	* Add early check that block assignments are always to block variables
 	* Use ZStd compression for temporary files from preprocess()
 	* Correctly handle subpaths in samples for collect (fixes #141)

Execs/Main.hs

@@ -1,5 +1,5 @@
 {-# LANGUAGE PackageImports #-}
-{- Copyright 2013-2020 NGLess Authors
+{- Copyright 2013-2021 NGLess Authors
  - License: MIT
  -}
 module Main
@@ -214,26 +214,6 @@ loadScript (CmdArgs.ScriptFilePath fname) =
             Left err -> Left (show err)
 
 
-parseVersion :: Maybe T.Text -> NGLess NGLVersion
-parseVersion Nothing = return $ NGLVersion 1 2
-parseVersion (Just "1.2") = return $ NGLVersion 1 2
-parseVersion (Just "1.1") = return $ NGLVersion 1 1
-parseVersion (Just "1.0") = return $ NGLVersion 1 0
-parseVersion (Just "0.0") = return $ NGLVersion 0 0
-parseVersion (Just "0.5") = return $ NGLVersion 0 5
-parseVersion (Just "0.6") = return $ NGLVersion 0 6
-parseVersion (Just "0.7") = return $ NGLVersion 0 7
-parseVersion (Just "0.8") = return $ NGLVersion 0 8
-parseVersion (Just "0.9") = return $ NGLVersion 0 9
-parseVersion (Just "0.10") = return $ NGLVersion 0 10
-parseVersion (Just "0.11") = return $ NGLVersion 0 11
-parseVersion (Just v) = case T.splitOn "." v of
-                            [majV,minV,_] ->
-                                throwScriptError $ concat ["The NGLess version string at the top of the file should only\ncontain a major and a minor version, separated by a dot.\n\n"
-                                                        ,"You probably meant to write:\n\n"
-                                                        ,"ngless \"" , T.unpack majV, ".", T.unpack minV, "\"\n"]
-                            [_, _] -> throwScriptError $ concat ["Version ", T.unpack v, " is not supported (only versions 1.[0-2] and 0.0/0.5-12 are available in this release)."]
-                            _ -> throwScriptError $ concat ["Version ", T.unpack v, " could not be understood. The version string should look like \"1.0\" or similar"]
 
 modeExec :: CmdArgs.NGLessMode -> IO ()
 modeExec opts@CmdArgs.DefaultMode{} = do

Modules/example-cmd.ngm/0.0/module.yaml

@@ -1,5 +1,8 @@
 version: '0.0.0'
 name: 'Test tool'
+min-ngless-version:
+    min-version: "1.3"
+    reason: "The min-ngless-version field is only supported since NGLess 1.3"
 functions:
     -
         nglName: "testing"

NGLess/ExternalModules.hs

@@ -1,4 +1,4 @@
-{- Copyright 2015-2019 NGLess Authors
+{- Copyright 2015-2021 NGLess Authors
  - License: MIT
  -}
 
@@ -178,9 +178,27 @@ instance Aeson.FromJSON Command where
             <*> o .:? "additional" .!= []
             <*> o .:? "return" .!=  CommandReturn NGLVoid "" ""
 
+data ModuleNGLessMinVersion = ModuleNGLessMinVersion
+                        { nglessMinVersion :: NGLVersion
+                        , nglessMinVersionReason :: T.Text
+                        }
+    deriving (Eq, Show)
+
+instance Aeson.FromJSON ModuleNGLessMinVersion where
+    parseJSON = Aeson.withObject "min-ngless-version" $ \o -> do
+            vtText <- o .: "min-version"
+            reason <- o .: "reason"
+            vt <- (Aeson.withText "minimal NGLess version" $ \vt ->
+                        case parseVersion (Just vt) of
+                            Left err -> fail (show err)
+                            Right val -> return val) vtText
+            return $ ModuleNGLessMinVersion vt reason
+
+
 data ExternalModule = ExternalModule
     { emInfo :: ModInfo -- ^ module information
     , modulePath :: FilePath -- ^ directory where module files are located
+    , modNGLessMinVersion :: Maybe ModuleNGLessMinVersion -- ^ minimal NGLess version for this module
     , initCmd :: Maybe FilePath
     , initArgs :: [String]
     , emFunctions :: [Command]
@@ -197,6 +215,7 @@ instance Aeson.FromJSON ExternalModule where
                 init_cmd <- initO' .: "init_cmd"
                 init_args <- initO' .:? "init_args" .!= []
                 return (init_cmd, init_args)
+        modNGLessMinVersion <- o .:? "min-ngless-version"
         references <- o .:? "references" .!= []
         emFunctions <- o .:? "functions" .!= []
         singleCitation <- o .:? "citation"
@@ -406,6 +425,14 @@ asInternalModule em@ExternalModule{..} = do
 validateModule :: ExternalModule -> NGLessIO ()
 validateModule  em@ExternalModule{..} = do
     checkSyntax em
+    whenJust modNGLessMinVersion $ \(ModuleNGLessMinVersion minV reason) -> do
+        curV <- ngleVersion <$> nglEnvironment
+        when (minV > curV) $
+            throwScriptError $ concat
+                [ "Current NGLess version is too old for loading module '"
+                , show emInfo, ".\n"
+                , "Version ", show minV, " is required.\n"
+                , "Reason: ", T.unpack reason]
     whenJust initCmd $ \initCmd' -> do
         outputListLno' DebugOutput ("Running initialization for module ":show emInfo:" ":initCmd':" ":initArgs)
         env <- nglessEnv modulePath
@@ -533,7 +560,10 @@ checkCompatible modname version mi = do
 loadModule :: ModInfo -> NGLessIO Module
 loadModule mi
         | isGlobalImport mi && name `notElem` knownModules =
-            throwScriptError ("Module '" ++ T.unpack name ++ "' is not known.\n\t" ++ T.unpack (suggestionMessage name knownModules) ++ "\n\tTo import local modules, use \"local import\"")
+            throwScriptError (
+                    "Module '" ++ T.unpack name ++ "' is not known.\n\t"
+                    ++ T.unpack (suggestionMessage name knownModules)
+                    ++ "\n\tTo import local modules, use \"local import\"")
         | otherwise = asInternalModule =<< findLoad name version
     where
         isGlobalImport LocalModInfo{} = False

NGLess/NGLess/NGLEnvironment.hs

@@ -1,8 +1,9 @@
-{- Copyright 2016-2019 NGLess Authors
+{- Copyright 2016-2021 NGLess Authors
  - License: MIT
  -}
 module NGLess.NGLEnvironment
     ( NGLVersion(..)
+    , parseVersion
     , NGLEnvironment(..)
     , nglEnvironment
     , nglConfiguration
@@ -39,6 +40,27 @@ data NGLEnvironment = NGLEnvironment
                     , ngleConfiguration :: NGLessConfiguration
                     } deriving (Show, Eq)
 
+parseVersion :: Maybe T.Text -> NGLess NGLVersion
+parseVersion Nothing = return $ NGLVersion 1 2
+parseVersion (Just "1.3") = return $ NGLVersion 1 3
+parseVersion (Just "1.2") = return $ NGLVersion 1 2
+parseVersion (Just "1.1") = return $ NGLVersion 1 1
+parseVersion (Just "1.0") = return $ NGLVersion 1 0
+parseVersion (Just "0.0") = return $ NGLVersion 0 0
+parseVersion (Just "0.5") = return $ NGLVersion 0 5
+parseVersion (Just "0.6") = return $ NGLVersion 0 6
+parseVersion (Just "0.7") = return $ NGLVersion 0 7
+parseVersion (Just "0.8") = return $ NGLVersion 0 8
+parseVersion (Just "0.9") = return $ NGLVersion 0 9
+parseVersion (Just "0.10") = return $ NGLVersion 0 10
+parseVersion (Just "0.11") = return $ NGLVersion 0 11
+parseVersion (Just v) = case T.splitOn "." v of
+                            [majV,minV,_] ->
+                                throwScriptError $ concat ["The NGLess version string at the top of the file should only\ncontain a major and a minor version, separated by a dot.\n\n"
+                                                        ,"You probably meant to write:\n\n"
+                                                        ,"ngless \"" , T.unpack majV, ".", T.unpack minV, "\"\n"]
+                            [_, _] -> throwScriptError $ concat ["Version ", T.unpack v, " is not supported (only versions 1.[0-2] and 0.0/0.5-12 are available in this release)."]
+                            _ -> throwScriptError $ concat ["Version ", T.unpack v, " could not be understood. The version string should look like \"1.0\" or similar"]
 ngle :: IORef NGLEnvironment
 {-# NOINLINE ngle #-}
 ngle = unsafePerformIO (newIORef $ NGLEnvironment (NGLVersion 0 0) Nothing "" ["bwa"] [] (error "Configuration not set"))

docs/sources/modules.md

@@ -231,6 +231,17 @@ provide a list:
         - "Paper 1"
         - "Paper 2"
 
+## Minimal NGLess Version
+
+External modules can specify a minimal NGLess version that they need to run.
+This is optional, but if it is used, you need to additionally supply a reason
+for the requirement (using the aptly-named `reason` field):
+
+    min-ngless-version:
+        min-version: "1.3"
+        reason: "The min-ngless-version field is only supported since NGLess 1.3"
+
+
 ## Internal Modules
 
 This is very advanced as it requires writing Haskell code which can then

tests/exampleExternalModule/example-cmd.ngl

@@ -1,4 +1,4 @@
-ngless '1.1'
+ngless '1.3'
 import "example-cmd" version "0.0"
 import "mocat" version "0.6"