New function: compile-update-file.

The new function only compiles a file if the output file doesn't exist
or is out of date.

In addition, both compile-file now deletes the output file if
compilation fails, and has a documented return value.

* lisplib.c (compiler_set_entries): Add autoload entry fro
compile-update-file.
(open-compile-streams): Accepts a third argument: a function to test the
input stream against the output path. The output file is opened, and the
streams are returned, only if that test function returns true.
Also, a third element is returned: the output path. This lets the
caller to know what to delete, if the output file must be deleted.
(compile-file-conditionally): New internal function, formed from
compile-file. Takes an extra argument, the test function to pass to
open-compile-streams. Compilation is skipped if open-compile-streams
returns nil. Internals reshuffled a bit. If compilation doesn't set the
success flag, then the with-resources logic now removes the output file
in addition to closing the output stream. Prior to setting the success
flag, we flush the output stream.

* txr.1: Documented new function, all return values, and deletion of
output file on unsuccessful compilation.

1 files changed, 32 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index 4487cbf6..61801b87 100644
--- a/txr.1
+++ b/txr.1
@@ -69426,9 +69426,10 @@ In all cases, the return value of
 .code compile
 is the compiled function.
 
-.coNP Function @ compile-file
+.coNP Functions @ compile-file and @ compile-update-file
 .synb
 .mets (compile-file < input-path <> [ output-path ])
+.mets (compile-update-file < input-path <> [ output-path ])
 .syne
 .desc
 The
@@ -69521,6 +69522,36 @@ after the compilation completes.
 
 Compilation proceeds according to the File Compilation Model.
 
+If the compilation process fails to produce a successful translation
+for each form in the input file, the output file is removed.
+
+The
+.code compile-update-file
+function differs from
+.code compile-file
+in the following regard: compilation is performed only if the input
+file is newer than the output file, or else if the output file doesn't
+exist.
+
+The
+.code compile-file
+always returns
+.code t
+if it terminates normally, which occurs if it successfully translates
+every form in the input file, depositing the translation into the output
+file. If compilation fails,
+.code compile-file
+terminates by throwing an exception.
+
+The
+.code compile-update-file
+function returns
+.code t
+if it successfully compiles, similarly to
+.codn compile-file .
+If compilation is skipped, the function returns
+.codn nil .
+
 .coNP Macro @ with-compilation-unit
 .synb
 .mets (with-compilation-unit << form *)