refactor(api)!: one way to ask what a file is

CHANGELOG.md

@@ -16,6 +16,10 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
+- **Breaking**: `DecodedFile::list_file_types`/`::mimetype` and
+  `DocumentFile::type`/`::meta` are gone, in every binding. Use the free
+  `odr::list_file_types`/`odr::mimetype`, or `odr::open(...).file_type()`.
+
 - **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.

apple/src/ODRFile.mm

@@ -384,21 +384,20 @@ + (nullable instancetype)decodeFile:(ODRFile *)file
                                                logger:(ODRLogger *)logger
                                                 error:(NSError **)error {
   return guarded(error, [&]() -> NSArray<NSNumber *> * {
-    return to_nsarray(
-        odr::DecodedFile::list_file_types(to_string(path), logger.handle));
+    return to_nsarray(odr::list_file_types(to_string(path), logger.handle));
   });
 }
 
 + (nullable NSArray<NSNumber *> *)listFileTypesAtPath:(NSString *)path
                                                 error:(NSError **)error {
   return guarded(error, [&]() -> NSArray<NSNumber *> * {
-    return to_nsarray(odr::DecodedFile::list_file_types(to_string(path)));
+    return to_nsarray(odr::list_file_types(to_string(path)));
   });
 }
 
 + (nullable NSString *)mimetypeAtPath:(NSString *)path error:(NSError **)error {
   return guarded(error, [&]() -> NSString * {
-    return to_nsstring(odr::DecodedFile::mimetype(to_string(path)));
+    return to_nsstring(odr::mimetype(to_string(path)));
   });
 }
 

jni/java/app/opendocument/core/DocumentFile.java

@@ -10,14 +10,6 @@ public DocumentFile(String path) {
     this(create(path));
   }
 
-  public static FileType typeByPath(String path) {
-    return FileType.fromNative(typeByPathNative(path));
-  }
-
-  public static FileMeta metaByPath(String path) {
-    return metaByPathNative(path);
-  }
-
   public DocumentType documentType() {
     return DocumentType.fromNative(documentTypeNative(handle()));
   }
@@ -43,10 +35,6 @@ public Document document() {
 
   private static native long create(String path);
 
-  private static native int typeByPathNative(String path);
-
-  private static native FileMeta metaByPathNative(String path);
-
   private native int documentTypeNative(long handle);
 
   private native long decryptDocumentFileNative(long handle, String password);

jni/src/jni_file.cpp

@@ -347,23 +347,6 @@ Java_app_opendocument_core_DocumentFile_create(JNIEnv *env, jclass,
   });
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_app_opendocument_core_DocumentFile_typeByPathNative(JNIEnv *env, jclass,
-                                                         jstring path) {
-  return guarded(env, [&] {
-    return static_cast<jint>(odr::DocumentFile::type(to_string(env, path)));
-  });
-}
-
-extern "C" JNIEXPORT jobject JNICALL
-Java_app_opendocument_core_DocumentFile_metaByPathNative(JNIEnv *env, jclass,
-                                                         jstring path) {
-  return guarded(env, [&] {
-    return odr_jni::make_file_meta(
-        env, odr::DocumentFile::meta(to_string(env, path)));
-  });
-}
-
 extern "C" JNIEXPORT jint JNICALL
 Java_app_opendocument_core_DocumentFile_documentTypeNative(JNIEnv *env, jobject,
                                                            jlong handle) {

jni/tests/app/opendocument/core/FileTest.java

@@ -127,8 +127,8 @@ void listFileTypes() throws IOException {
   @Test
   void documentFileByPath() throws IOException {
     Path odt = TestFiles.odtFile(tempDir);
-    assertEquals(FileType.OPENDOCUMENT_TEXT, DocumentFile.typeByPath(odt.toString()));
-    FileMeta meta = DocumentFile.metaByPath(odt.toString());
-    assertEquals(FileType.OPENDOCUMENT_TEXT, meta.type);
+    DecodedFile file = Odr.open(odt.toString());
+    assertEquals(FileType.OPENDOCUMENT_TEXT, file.fileType());
+    assertEquals(FileType.OPENDOCUMENT_TEXT, file.fileMeta().type);
   }
 }

python/src/bind_file.cpp

@@ -265,24 +265,6 @@ void odr_python::bind_file(py::module_ &m) {
           },
           py::arg("data"), py::arg("logger") = odr::Logger::null(),
           "Decode a document file held in memory; `data` is its bytes.")
-      // `type`/`meta` are overloaded on `File` and path, so the address of
-      // either is ambiguous; name the signature.
-      .def_static(
-          "type_by_file",
-          py::overload_cast<const odr::File &>(&odr::DocumentFile::type),
-          py::arg("file"))
-      .def_static(
-          "type_by_path",
-          py::overload_cast<const std::string &>(&odr::DocumentFile::type),
-          py::arg("path"))
-      .def_static(
-          "meta_by_file",
-          py::overload_cast<const odr::File &>(&odr::DocumentFile::meta),
-          py::arg("file"))
-      .def_static(
-          "meta_by_path",
-          py::overload_cast<const std::string &>(&odr::DocumentFile::meta),
-          py::arg("path"))
       .def("document_type", &odr::DocumentFile::document_type)
       .def("decrypt", &odr::DocumentFile::decrypt, py::arg("password"),
            py::call_guard<py::gil_scoped_release>())

python/tests/test_file.py

@@ -163,12 +163,10 @@ def test_decoded_file_from_file(odt_path):
 def test_document_file_from_file(odt_path):
     file = pyodr.File.from_memory(odt_path.read_bytes())
 
-    assert pyodr.DocumentFile.type_by_file(file) == pyodr.FileType.opendocument_text
-    assert (
-        pyodr.DocumentFile.meta_by_file(file).type == pyodr.FileType.opendocument_text
-    )
-
     document_file = pyodr.DocumentFile(file)
+    assert document_file.file_type() == pyodr.FileType.opendocument_text
+    assert document_file.file_meta().type == pyodr.FileType.opendocument_text
+
     assert document_file.document_type() == pyodr.DocumentType.text
 
 
@@ -213,10 +211,4 @@ def test_file_and_path_entry_points_agree(odt_path):
     assert pyodr.mimetype(file) == pyodr.mimetype(path)
     assert pyodr.list_file_types(file) == pyodr.list_file_types(path)
     assert pyodr.open(file).file_type() == pyodr.open(path).file_type()
-    assert pyodr.DocumentFile.type_by_file(file) == pyodr.DocumentFile.type_by_path(
-        path
-    )
-    assert (
-        pyodr.DocumentFile.meta_by_file(file).type
-        == pyodr.DocumentFile.meta_by_path(path).type
-    )
+    assert pyodr.DocumentFile(file).file_type() == pyodr.DocumentFile(path).file_type()

src/odr/file.cpp

@@ -87,25 +87,6 @@ void File::copy(const std::string &path) const {
 
 std::shared_ptr<internal::abstract::File> File::impl() const { return m_impl; }
 
-std::vector<FileType> DecodedFile::list_file_types(const File &file,
-                                                   const Logger &logger) {
-  return internal::open_strategy::list_file_types(file.impl(), logger);
-}
-
-std::vector<FileType> DecodedFile::list_file_types(const std::string &path,
-                                                   const Logger &logger) {
-  return list_file_types(File::from_disk(path), logger);
-}
-
-std::string_view DecodedFile::mimetype(const File &file, const Logger &logger) {
-  return internal::magic::mimetype(file.impl(), logger);
-}
-
-std::string_view DecodedFile::mimetype(const std::string &path,
-                                       const Logger &logger) {
-  return mimetype(File::from_disk(path), logger);
-}
-
 DecodedFile::DecodedFile(std::shared_ptr<internal::abstract::DecodedFile> impl)
     : m_impl{std::move(impl)} {
   if (m_impl == nullptr) {
@@ -373,22 +354,6 @@ DocumentFile DocumentFile::from_memory(std::string data, const Logger &logger) {
   return DocumentFile(File::from_memory(std::move(data)), logger);
 }
 
-FileType DocumentFile::type(const File &file) {
-  return DocumentFile(file).file_type();
-}
-
-FileType DocumentFile::type(const std::string &path) {
-  return type(File::from_disk(path));
-}
-
-FileMeta DocumentFile::meta(const File &file) {
-  return DocumentFile(file).file_meta();
-}
-
-FileMeta DocumentFile::meta(const std::string &path) {
-  return meta(File::from_disk(path));
-}
-
 DocumentFile::DocumentFile(
     std::shared_ptr<internal::abstract::DocumentFile> impl)
     : DecodedFile(impl), m_impl{std::move(impl)} {}

src/odr/file.hpp

@@ -352,16 +352,6 @@ class File final {
 /// @brief Represents a decoded file.
 class DecodedFile {
 public:
-  [[nodiscard]] static std::vector<FileType>
-  list_file_types(const File &file, const Logger &logger = Logger::null());
-  [[nodiscard]] static std::vector<FileType>
-  list_file_types(const std::string &path,
-                  const Logger &logger = Logger::null());
-  [[nodiscard]] static std::string_view
-  mimetype(const File &file, const Logger &logger = Logger::null());
-  [[nodiscard]] static std::string_view
-  mimetype(const std::string &path, const Logger &logger = Logger::null());
-
   explicit DecodedFile(std::shared_ptr<internal::abstract::DecodedFile> impl);
   explicit DecodedFile(const File &file, const Logger &logger = Logger::null());
   DecodedFile(const File &file, FileType as,
@@ -525,11 +515,6 @@ class DocumentFile final : public DecodedFile {
   [[nodiscard]] static DocumentFile
   from_memory(std::string data, const Logger &logger = Logger::null());
 
-  static FileType type(const File &file);
-  static FileType type(const std::string &path);
-  static FileMeta meta(const File &file);
-  static FileMeta meta(const std::string &path);
-
   explicit DocumentFile(std::shared_ptr<internal::abstract::DocumentFile>);
   explicit DocumentFile(const File &file,
                         const Logger &logger = Logger::null());

src/odr/odr.cpp

@@ -6,6 +6,8 @@
 #include <odr/internal/encoding/text_encoding_table.hpp>
 #include <odr/internal/file_type_table.hpp>
 #include <odr/internal/git_info.hpp>
+#include <odr/internal/magic.hpp>
+#include <odr/internal/open_strategy.hpp>
 #include <odr/internal/project_info.hpp>
 
 #include <algorithm>
@@ -184,20 +186,20 @@ bool odr::text_encoding_is_decodable(const TextEncoding encoding) noexcept {
 
 std::vector<odr::FileType> odr::list_file_types(const File &file,
                                                 const Logger &logger) {
-  return DecodedFile::list_file_types(file, logger);
+  return internal::open_strategy::list_file_types(file.impl(), logger);
 }
 
 std::vector<odr::FileType> odr::list_file_types(const std::string &path,
                                                 const Logger &logger) {
-  return DecodedFile::list_file_types(path, logger);
+  return list_file_types(File::from_disk(path), logger);
 }
 
 std::string_view odr::mimetype(const File &file, const Logger &logger) {
-  return DecodedFile::mimetype(file, logger);
+  return internal::magic::mimetype(file.impl(), logger);
 }
 
 std::string_view odr::mimetype(const std::string &path, const Logger &logger) {
-  return DecodedFile::mimetype(path, logger);
+  return mimetype(File::from_disk(path), logger);
 }
 
 odr::DecodedFile odr::open(const File &file, const Logger &logger) {

test/src/file_test.cpp

@@ -3,6 +3,7 @@
 #include <odr/exceptions.hpp>
 #include <odr/file.hpp>
 #include <odr/filesystem.hpp>
+#include <odr/odr.hpp>
 
 #include <odr/internal/common/file.hpp>
 #include <odr/internal/util/file_util.hpp>
@@ -162,12 +163,11 @@ TEST(File, from_memory_decodes_the_same_as_from_disk) {
   EXPECT_EQ(from_memory.file_meta().document_type,
             from_disk.file_meta().document_type);
 
-  EXPECT_EQ(DecodedFile::list_file_types(
-                File::from_memory(internal::util::file::read(path))),
-            DecodedFile::list_file_types(path));
-  EXPECT_EQ(DecodedFile::mimetype(
-                File::from_memory(internal::util::file::read(path))),
-            DecodedFile::mimetype(path));
+  EXPECT_EQ(
+      list_file_types(File::from_memory(internal::util::file::read(path))),
+      list_file_types(path));
+  EXPECT_EQ(mimetype(File::from_memory(internal::util::file::read(path))),
+            mimetype(path));
 }
 
 /// `MemoryFile` used to report itself as `disk`, and `memory_data()` handed

test/src/internal/csv/csv_file_test.cpp

@@ -4,6 +4,7 @@
 #include <odr/exceptions.hpp>
 #include <odr/file.hpp>
 #include <odr/html.hpp>
+#include <odr/odr.hpp>
 #include <odr/table_dimension.hpp>
 
 #include <test_util.hpp>
@@ -66,7 +67,7 @@ TEST(CsvFile, csv) {
       std::make_shared<internal::text::TextFile>(file.impl())));
 
   // and the probe in `open_strategy` reaches the same conclusion
-  EXPECT_THAT(DecodedFile::list_file_types(file),
+  EXPECT_THAT(list_file_types(file),
               testing::Contains(FileType::comma_separated_values));
 }
 

test/src/internal/markdown/markdown_file_test.cpp

@@ -120,7 +120,7 @@ TEST(MarkdownFile, translating_the_decoded_file_yields_the_document) {
 TEST(MarkdownFile, it_is_not_detected_by_content) {
   const File file = File::from_memory("# hello\n\nsome *markdown*\n");
 
-  EXPECT_THAT(DecodedFile::list_file_types(file),
+  EXPECT_THAT(list_file_types(file),
               testing::Not(testing::Contains(FileType::markdown)));
   EXPECT_EQ(DecodedFile(file).file_type(), FileType::text_file);
 }

test/src/internal/odf/odf_flat_file_test.cpp

@@ -394,8 +394,8 @@ TEST(FlatOpenDocumentFile, the_statistics_give_the_entry_count) {
 
 /// A flat document is well formed xml too, so both readings are reported.
 TEST(FlatOpenDocumentFile, it_is_listed_next_to_the_source_view) {
-  const std::vector<FileType> types = DecodedFile::list_file_types(
-      File::from_memory(flat_text("<text:p>Hello</text:p>")));
+  const std::vector<FileType> types =
+      list_file_types(File::from_memory(flat_text("<text:p>Hello</text:p>")));
 
   EXPECT_NE(std::ranges::find(types, FileType::xml), std::end(types));
   EXPECT_NE(std::ranges::find(types, FileType::opendocument_text),

test/src/internal/xml/xml_file_test.cpp

@@ -53,7 +53,7 @@ TEST(XmlFile, an_xml_file_opens_as_xml) {
   EXPECT_FALSE(file.is_document_file());
   EXPECT_TRUE(file.capabilities().translate_html);
 
-  EXPECT_THAT(DecodedFile::list_file_types(File::from_memory("<a><b/></a>")),
+  EXPECT_THAT(list_file_types(File::from_memory("<a><b/></a>")),
               testing::Contains(FileType::xml));
 }
 

wasm/src/wasm_file.cpp

@@ -37,13 +37,13 @@ emscripten::val detect(const std::string &bytes, std::string name) {
     const Logger &logger = default_logger();
 
     emscripten::val types = emscripten::val::array();
-    for (const FileType type : DecodedFile::list_file_types(file, logger)) {
+    for (const FileType type : odr::list_file_types(file, logger)) {
       types.call<void>("push", static_cast<int>(type));
     }
 
     emscripten::val result = emscripten::val::object();
     result.set("fileTypes", types);
-    result.set("mimeType", std::string(DecodedFile::mimetype(file, logger)));
+    result.set("mimeType", std::string(odr::mimetype(file, logger)));
     return ok(result);
   });
 }