Respect SAW_IMPORT_PATH

Due to an oversight, the `SAW_IMPORT_PATH` environment variable (or,
equivalently, the `-i`/`--import-path` command-line options) were being
blatantly ignored by SAW. This fixes that oversight by restricting the API in
`SAWScript.Import` to a single exported function (`findAndLoadFile`), which
always consults `SAW_IMPORT_PATH` before attempting to load a file.

Fixes #2756.

Author: RyanGlScott

CHANGES.md

@@ -197,6 +197,9 @@ This release supports [version
 * Fix a bug that would cause SAW to crash when loading an instantiation of a
   parameterized Cryptol module that contains newtypes or enums (#2673).
 
+* Fix a bug that would cause SAW to completely ignore the paths specified in
+  the `SAW_IMPORT_PATH`/`--import-path` options.
+
 # Version 1.4 -- date still TBD
 
 This release supports [version

doc/pdfs/saw-user-manual.pdf

@@ -21,7 +21,8 @@ command-line options:
 : Specify a colon-delimited list of paths to search for Java classes.
 
 `-i path, --import-path=path`
-: Specify a colon-delimited list of paths to search for imports.
+: Specify a colon-delimited list of paths to search for imports. Note that
+  paths can also be specified using the `SAW_IMPORT_PATH` environment variable.
 
 `-t, --extra-type-checking`
 : Perform extra type checking of intermediate values.
@@ -70,7 +71,9 @@ SAW also uses several environment variables for configuration:
   searched to find a Java executable.
 
 `SAW_IMPORT_PATH`
-: Specify a colon-delimited list of directory paths to search for imports.
+: Specify a colon-delimited list of directory paths to search for imports. Note
+  that paths can also be specified using the `-i`/`--import-path` command-line
+  options.
 
 `SAW_JDK_JAR`
 : Specify the path of the `.jar` file containing the core Java

doc/saw-user-manual/appendices/repl-reference.md

@@ -24,6 +24,6 @@
 #    - the devel version can then be bumped to the current day if needed
 #
 
-# BSD/Linux: date +%s -d "09/29/2025 00:00:00 GMT"
-# OSX: date -j -f "%m/%d/%Y %H:%M:%S %Z" "9/29/2025 00:00:00 GMT" +%s
-SOURCE_DATE_EPOCH=1759104000
+# BSD/Linux: date +%s -d "10/30/2025 00:00:00 GMT"
+# OSX: date -j -f "%m/%d/%Y %H:%M:%S %Z" "10/30/2025 00:00:00 GMT" +%s
+SOURCE_DATE_EPOCH=1761782400

doc/scripts/epoch.mk

@@ -0,0 +1 @@
+let a = 1;

intTests/test2756/a.saw

@@ -0,0 +1 @@
+let b = 2;

intTests/test2756/b_dir/b.saw

@@ -0,0 +1 @@
+let c = 3;

intTests/test2756/c_dir1/c_dir2/c.saw

@@ -0,0 +1,7 @@
+include "a.saw";
+include "b.saw";
+include "c.saw";
+
+print a;
+print b;
+print c;

intTests/test2756/test.saw

@@ -0,0 +1,8 @@
+set -e
+
+# All of the following are equivalent, and they should all succeed.
+SAW_IMPORT_PATH=b_dir:c_dir1/c_dir2 $SAW test.saw
+$SAW --import-path b_dir:c_dir1/c_dir2 test.saw
+$SAW -i b_dir:c_dir1/c_dir2 test.saw
+$SAW --import-path b_dir --import-path c_dir1/c_dir2 test.saw
+$SAW -i b_dir -i c_dir1/c_dir2 test.saw

intTests/test2756/test.sh

@@ -8,8 +8,7 @@ Stability   : provisional
 {-# LANGUAGE CPP #-}
 
 module SAWScript.Import
-  ( loadFile
-  , findAndLoadFile
+  ( findAndLoadFile
   ) where
 
 import qualified Data.Text.IO as TextIO (readFile)
@@ -24,6 +23,7 @@ import SAWCentral.Options
 import SAWScript.Parser
 import SAWScript.Token (Token)
 
+-- | Load the 'Stmt's in a @.saw@ file.
 loadFile :: Options -> FilePath -> IO [Stmt]
 loadFile opts fname = do
   printOutLn opts Info $ "Loading file " ++ show fname
@@ -53,6 +53,10 @@ parseFile tokens = do
     Left err -> Left err
     Right stmts -> Right stmts
 
+-- | Find a file, potentially looking in a list of multiple search paths (as
+-- specified via the @SAW_IMPORT_PATH@ environment variable or
+-- @-i@/@--import-path@ command-line options). If the file was successfully
+-- found, load it. If not, raise an error.
 findAndLoadFile :: Options -> FilePath -> IO [Stmt]
 findAndLoadFile opts fp = do
   let paths = importPath opts