refactor(html)!: cut translate to its four inputs

CHANGELOG.md

@@ -16,6 +16,10 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
+- **Breaking**: `html::translate` takes only a `DecodedFile`, `Document`,
+  `Filesystem` or `Archive` now; drop the cache path, in every binding. Open a
+  file as `FileType::text_file` to render it as a numbered line list.
+
 - **Breaking**: the inert `HtmlConfig` fields `background_image_format`,
   `background_image_dpi`, `no_drm` and `embed_outline` are gone, with their
   java, python, objc and wasm mirrors. Drop them; nothing replaces them.

android/src/androidTest/java/app/opendocument/core/DocumentTest.kt

@@ -85,11 +85,10 @@ class DocumentTest {
 
     @Test
     fun translateToHtml() {
-        val cache = Files.createDirectories(tempDir.resolve("cache"))
         val output = Files.createDirectories(tempDir.resolve("output"))
 
         val file = Odr.open(TestFiles.odtFile(tempDir).toString())
-        val service = Html.translate(file, cache.toString(), HtmlConfig())
+        val service = Html.translate(file, HtmlConfig())
         val html = service.bringOffline(output.toString())
 
         val pages = html.pages()
@@ -112,9 +111,8 @@ class DocumentTest {
 
     @Test
     fun translateCsv() {
-        val cache = Files.createDirectories(tempDir.resolve("csv-cache"))
         val file = Odr.open(TestFiles.csvFile(tempDir).toString())
-        val service = Html.translate(file, cache.toString(), HtmlConfig())
+        val service = Html.translate(file, HtmlConfig())
 
         // a spreadsheet: a document view plus one per sheet
         val views = service.listViews()

android/src/androidTest/java/app/opendocument/core/HttpServerTest.kt

@@ -4,7 +4,6 @@ import androidx.test.ext.junit.runners.AndroidJUnit4
 import java.io.IOException
 import java.net.HttpURLConnection
 import java.net.URL
-import java.nio.file.Files
 import java.nio.file.Path
 import java.util.concurrent.atomic.AtomicReference
 import org.junit.Assert.assertEquals
@@ -60,12 +59,11 @@ class HttpServerTest {
 
         val server = HttpServer()
 
-        val cachePath = Files.createDirectories(tempDir.resolve("doc-cache")).toString()
         val file = Odr.open(TestFiles.odtFile(tempDir).toString())
         val htmlConfig = HtmlConfig()
         htmlConfig.embedImages = false
         htmlConfig.relativeResourcePaths = false
-        val service = Html.translate(file, cachePath, htmlConfig)
+        val service = Html.translate(file, htmlConfig)
         server.connectService(service, "doc")
         val views = service.listViews()
         assertEquals(1, views.size)

apple/README.md

@@ -24,7 +24,7 @@ Requires iOS 15 or macOS 12.
 let file = try DecodedFile.decode(path: path)
 let config = HtmlConfig()
 let service = try HtmlTranslator.translate(
-  file: file, cachePath: cacheDirectory, config: config)
+  file: file, config: config)
 
 for view in service.views {
   var resources: NSArray?
@@ -50,7 +50,7 @@ it beats writing every page to disk up front.
 
 ```swift
 let service = try HtmlTranslator.translate(
-  file: file, cachePath: cacheDirectory, config: HtmlConfig())
+  file: file, config: HtmlConfig())
 
 let server = HttpServer()
 try server.connect(service, prefix: "doc")

apple/include/OdrCoreObjC/ODRHtml.h

@@ -257,39 +257,34 @@ NS_SWIFT_NAME(HtmlService)
 NS_SWIFT_NAME(HtmlTranslator)
 @interface ODRHtmlTranslator : NSObject
 
-/// Translates a decoded file. `cachePath` is a directory for temporary output.
+/// Translates a decoded file, dispatching on what it decoded to.
 + (nullable ODRHtmlService *)translateFile:(ODRDecodedFile *)file
-                                 cachePath:(NSString *)cachePath
                                     config:(ODRHtmlConfig *)config
                                      error:(NSError **)error
-    NS_SWIFT_NAME(translate(file:cachePath:config:));
+    NS_SWIFT_NAME(translate(file:config:));
 + (nullable ODRHtmlService *)translateFile:(ODRDecodedFile *)file
-                                 cachePath:(NSString *)cachePath
                                     config:(ODRHtmlConfig *)config
                                     logger:(ODRLogger *)logger
                                      error:(NSError **)error
-    NS_SWIFT_NAME(translate(file:cachePath:config:logger:));
+    NS_SWIFT_NAME(translate(file:config:logger:));
 
 /// Translates an already-decoded document.
 + (nullable ODRHtmlService *)translateDocument:(ODRDocument *)document
-                                     cachePath:(NSString *)cachePath
                                         config:(ODRHtmlConfig *)config
                                          error:(NSError **)error
-    NS_SWIFT_NAME(translate(document:cachePath:config:));
+    NS_SWIFT_NAME(translate(document:config:));
 
 /// Translates a filesystem — a document's parts, or an archive's contents.
 + (nullable ODRHtmlService *)translateFilesystem:(ODRFilesystem *)filesystem
-                                       cachePath:(NSString *)cachePath
                                           config:(ODRHtmlConfig *)config
                                            error:(NSError **)error
-    NS_SWIFT_NAME(translate(filesystem:cachePath:config:));
+    NS_SWIFT_NAME(translate(filesystem:config:));
 
 /// Translates an archive.
 + (nullable ODRHtmlService *)translateArchive:(ODRArchive *)archive
-                                    cachePath:(NSString *)cachePath
                                        config:(ODRHtmlConfig *)config
                                         error:(NSError **)error
-    NS_SWIFT_NAME(translate(archive:cachePath:config:));
+    NS_SWIFT_NAME(translate(archive:config:));
 
 /// Applies a diff produced by the browser-side JavaScript back to `document`.
 + (BOOL)editDocument:(ODRDocument *)document

apple/src/ODRHtml.mm

@@ -504,61 +504,51 @@ - (nullable ODRHtml *)bringOfflineTo:(NSString *)outputPath
 @implementation ODRHtmlTranslator
 
 + (nullable ODRHtmlService *)translateFile:(ODRDecodedFile *)file
-                                 cachePath:(NSString *)cachePath
                                     config:(ODRHtmlConfig *)config
                                      error:(NSError **)error {
   return [ODRHtmlTranslator translateFile:file
-                                cachePath:cachePath
                                    config:config
                                    logger:ODRLogger.null
                                     error:error];
 }
 
 + (nullable ODRHtmlService *)translateFile:(ODRDecodedFile *)file
-                                 cachePath:(NSString *)cachePath
                                     config:(ODRHtmlConfig *)config
                                     logger:(ODRLogger *)logger
                                      error:(NSError **)error {
   return guarded(error, [&]() -> ODRHtmlService * {
     return [ODRHtmlService
-        serviceWithHandle:odr::html::translate(
-                              file.handle, to_string(cachePath),
-                              config.nativeConfig, logger.handle)];
+        serviceWithHandle:odr::html::translate(file.handle, config.nativeConfig,
+                                               logger.handle)];
   });
 }
 
 + (nullable ODRHtmlService *)translateDocument:(ODRDocument *)document
-                                     cachePath:(NSString *)cachePath
                                         config:(ODRHtmlConfig *)config
                                          error:(NSError **)error {
   return guarded(error, [&]() -> ODRHtmlService * {
     return [ODRHtmlService
         serviceWithHandle:odr::html::translate(document.handle,
-                                               to_string(cachePath),
                                                config.nativeConfig)];
   });
 }
 
 + (nullable ODRHtmlService *)translateFilesystem:(ODRFilesystem *)filesystem
-                                       cachePath:(NSString *)cachePath
                                           config:(ODRHtmlConfig *)config
                                            error:(NSError **)error {
   return guarded(error, [&]() -> ODRHtmlService * {
     return [ODRHtmlService
         serviceWithHandle:odr::html::translate(filesystem.handle,
-                                               to_string(cachePath),
                                                config.nativeConfig)];
   });
 }
 
 + (nullable ODRHtmlService *)translateArchive:(ODRArchive *)archive
-                                    cachePath:(NSString *)cachePath
                                        config:(ODRHtmlConfig *)config
                                         error:(NSError **)error {
   return guarded(error, [&]() -> ODRHtmlService * {
     return [ODRHtmlService
         serviceWithHandle:odr::html::translate(archive.handle,
-                                               to_string(cachePath),
                                                config.nativeConfig)];
   });
 }

apple/tests/OdrCoreTests.swift

@@ -121,7 +121,7 @@ final class HtmlTests: XCTestCase {
   private func service() throws -> HtmlService {
     let file = try DecodedFile.decode(path: try Fixture.odt())
     return try HtmlTranslator.translate(
-      file: file, cachePath: try temporaryDirectory(), config: HtmlConfig())
+      file: file, config: HtmlConfig())
   }
 
   func testRendersHtml() throws {
@@ -152,7 +152,7 @@ final class HtmlTests: XCTestCase {
 
     let file = try DecodedFile.decode(path: try Fixture.odt())
     let service = try HtmlTranslator.translate(
-      file: file, cachePath: try temporaryDirectory(), config: config)
+      file: file, config: config)
     var resources: NSArray?
     let html = try XCTUnwrap(service.views.first).writeHtml(resources: &resources)
 
@@ -188,7 +188,7 @@ final class HtmlTests: XCTestCase {
       "alpha,beta\ngamma,delta\nepsilon,zeta\n", as: "table.csv")
     let file = try DecodedFile.decode(path: path)
     let service = try HtmlTranslator.translate(
-      file: file, cachePath: try temporaryDirectory(), config: config)
+      file: file, config: config)
     var resources: NSArray?
     let html = try XCTUnwrap(service.views.first).writeHtml(resources: &resources)
 
@@ -242,8 +242,7 @@ final class HttpServerTests: XCTestCase {
     let config = HtmlConfig()
     config.relativeResourcePaths = false
     let service = try HtmlTranslator.translate(
-      file: try DecodedFile.decode(path: try Fixture.odt()),
-      cachePath: try temporaryDirectory(), config: config)
+      file: try DecodedFile.decode(path: try Fixture.odt()), config: config)
 
     let server = HttpServer()
     try server.connect(service, prefix: "doc")

cli/src/server.cpp

@@ -6,7 +6,6 @@
 #include <odr/http_server.hpp>
 
 #include <cstdint>
-#include <filesystem>
 #include <iostream>
 #include <string>
 
@@ -48,12 +47,6 @@ int main(const int argc, char **argv) {
 
     const HttpServer server{{}, logger};
 
-    // the server does not own a cache any more, so the translation goes
-    // somewhere of our choosing
-    const std::filesystem::path cache_path =
-        std::filesystem::temp_directory_path() / "odr-server";
-    std::filesystem::remove_all(cache_path);
-
     // bind before anything is printed: the port is only known once the socket
     // is, and it is not necessarily the one that was asked for
     const std::uint32_t port = server.bind("localhost", 8080);
@@ -66,11 +59,9 @@ int main(const int argc, char **argv) {
 
     {
       const std::string prefix = "file";
-      const std::string prefix_cache_path = (cache_path / prefix).string();
-      std::filesystem::create_directories(prefix_cache_path);
 
       const HtmlService service =
-          html::translate(decoded_file, prefix_cache_path, html_config, logger);
+          html::translate(decoded_file, html_config, logger);
       server.connect_service(service, prefix);
       const HtmlViews views = service.list_views();
       ODR_INFO(logger, "hosted decoded file with id: " << prefix);
@@ -86,11 +77,9 @@ int main(const int argc, char **argv) {
               : decoded_file.as_archive_file().archive().as_filesystem();
 
       const std::string prefix = "filesystem";
-      const std::string prefix_cache_path = (cache_path / prefix).string();
-      std::filesystem::create_directories(prefix_cache_path);
 
       const HtmlService filesystem_service =
-          html::translate(filesystem, prefix_cache_path, html_config, logger);
+          html::translate(filesystem, html_config, logger);
       server.connect_service(filesystem_service, prefix);
       ODR_INFO(logger, "hosted filesystem with id: " << prefix);
       for (const auto &view : filesystem_service.list_views()) {

cli/src/translate.cpp

@@ -46,7 +46,7 @@ int main(const int argc, char **argv) {
     config.format_html = true;
 
     std::filesystem::create_directories(output);
-    const HtmlService service = html::translate(decoded_file, output, config);
+    const HtmlService service = html::translate(decoded_file, config);
     const Html html = service.bring_offline(output);
 
     return 0;

jni/README.md

@@ -11,7 +11,7 @@ import app.opendocument.core.HtmlService;
 import app.opendocument.core.Odr;
 
 DecodedFile file = Odr.open("document.odt");
-HtmlService service = Html.translate(file, "cache-dir", new HtmlConfig());
+HtmlService service = Html.translate(file, new HtmlConfig());
 app.opendocument.core.Html html = service.bringOffline("output-dir");
 for (var page : html.pages()) {
     System.out.println(page.name + " " + page.path);

jni/java/app/opendocument/core/Html.java

@@ -55,28 +55,27 @@ public static final class LocatedResource {
   // the wrapper for the duration - keepAlive() does.
 
   /** Translates a decoded file to HTML. */
-  public static HtmlService translate(DecodedFile file, String cachePath, HtmlConfig config) {
+  public static HtmlService translate(DecodedFile file, HtmlConfig config) {
     try {
-      return new HtmlService(translateFile(file.handle(), cachePath, config), file);
+      return new HtmlService(translateFile(file.handle(), config), file);
     } finally {
       file.keepAlive();
     }
   }
 
   /** Translates a document to HTML. */
-  public static HtmlService translate(Document document, String cachePath, HtmlConfig config) {
+  public static HtmlService translate(Document document, HtmlConfig config) {
     try {
-      return new HtmlService(translateDocument(document.handle(), cachePath, config), document);
+      return new HtmlService(translateDocument(document.handle(), config), document);
     } finally {
       document.keepAlive();
     }
   }
 
   /** Translates a filesystem to HTML. */
-  public static HtmlService translate(Filesystem filesystem, String cachePath, HtmlConfig config) {
+  public static HtmlService translate(Filesystem filesystem, HtmlConfig config) {
     try {
-      return new HtmlService(
-          translateFilesystem(filesystem.handle(), cachePath, config), filesystem);
+      return new HtmlService(translateFilesystem(filesystem.handle(), config), filesystem);
     } finally {
       filesystem.keepAlive();
     }
@@ -87,11 +86,9 @@ public static void edit(Document document, String diff) {
     document.edit(diff);
   }
 
-  private static native long translateFile(long fileHandle, String cachePath, HtmlConfig config);
+  private static native long translateFile(long fileHandle, HtmlConfig config);
 
-  private static native long translateDocument(
-      long documentHandle, String cachePath, HtmlConfig config);
+  private static native long translateDocument(long documentHandle, HtmlConfig config);
 
-  private static native long translateFilesystem(
-      long filesystemHandle, String cachePath, HtmlConfig config);
+  private static native long translateFilesystem(long filesystemHandle, HtmlConfig config);
 }

jni/src/jni_html.cpp

@@ -177,37 +177,32 @@ odr::HtmlResource &resource(jlong handle) {
 extern "C" JNIEXPORT jlong JNICALL
 Java_app_opendocument_core_Html_translateFile(JNIEnv *env, jclass,
                                               jlong file_handle,
-                                              jstring cache_path,
                                               jobject config) {
   return guarded(env, [&] {
-    return make_handle(odr::html::translate(
-        *from_handle<odr::DecodedFile>(file_handle), to_string(env, cache_path),
-        odr_jni::html_config_from_java(env, config)));
+    return make_handle(
+        odr::html::translate(*from_handle<odr::DecodedFile>(file_handle),
+                             odr_jni::html_config_from_java(env, config)));
   });
 }
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_app_opendocument_core_Html_translateDocument(JNIEnv *env, jclass,
                                                   jlong document_handle,
-                                                  jstring cache_path,
                                                   jobject config) {
   return guarded(env, [&] {
     return make_handle(
         odr::html::translate(*from_handle<odr::Document>(document_handle),
-                             to_string(env, cache_path),
                              odr_jni::html_config_from_java(env, config)));
   });
 }
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_app_opendocument_core_Html_translateFilesystem(JNIEnv *env, jclass,
                                                     jlong filesystem_handle,
-                                                    jstring cache_path,
                                                     jobject config) {
   return guarded(env, [&] {
     return make_handle(
         odr::html::translate(*from_handle<odr::Filesystem>(filesystem_handle),
-                             to_string(env, cache_path),
                              odr_jni::html_config_from_java(env, config)));
   });
 }