feat(file): Expose API to inspect iKv file format and storage kind

include/ikvxx/ikvxx.hpp

@@ -25,6 +25,19 @@ enum ValueType {
 /// On-disk iKv format versions supported for explicit writes.
 enum class Version : unsigned { v1 = 1, v2 = 2 };
 
+/// Serialized storage kind of an iKv document.
+enum class StorageKind : unsigned {
+    unknown = 0,
+    text,
+    binary
+};
+
+/// File format information reported by the library.
+struct FileFormat {
+    StorageKind storage = StorageKind::unknown;
+    Version version = Version::v2;
+};
+
 /// Error raised for invalid types, unsupported operations, parse failures,
 /// and I/O failures.
 class Error : public std::runtime_error {
@@ -145,4 +158,8 @@ private:
     bool read_only_ = false;
 };
 
+/// Inspects an iKv file and reports whether it is text or binary plus its version.
+/// Throws Error when the file cannot be identified.
+FileFormat inspectFile(const std::string& path);
+
 } // namespace ikv

src/value.cpp

@@ -39,6 +39,10 @@ ValueType publicType(ikv_type_t type) noexcept {
     }
 }
 
+Version publicVersion(ikv_version_t version) {
+    return version == IKV_VERSION_1 ? Version::v1 : Version::v2;
+}
+
 } // namespace
 
 void Value::Deleter::operator()(ikv_node_t* node) const noexcept { ikv_free(node); }
@@ -251,4 +255,18 @@ void Value::refresh(const std::string& path) {
     if (!ikv_refresh_from_path(node_, path.c_str())) throw Error("failed to refresh iKv root from: " + path);
 }
 
+FileFormat inspectFile(const std::string& path) {
+    if (ikv_version_t version = ikv_detect_file_version(path.c_str(), true);
+        version != IKV_VERSION_UNKNOWN) {
+        return {StorageKind::binary, publicVersion(version)};
+    }
+
+    if (ikv_version_t version = ikv_detect_file_version(path.c_str(), false);
+        version != IKV_VERSION_UNKNOWN) {
+        return {StorageKind::text, publicVersion(version)};
+    }
+
+    throw Error("failed to identify iKv file format: " + path);
+}
+
 } // namespace ikv