archive_r_ruby 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5c817b1729dcccb9268c75be4c2ce7fe8ca6a41e38421190d0028faa6223eaa
-  data.tar.gz: f6257d3a247d2abd5f88d149e09cd0d16a78623403b430c78f1e613db99f9b4d
+  metadata.gz: 648064959d139565d2e122215cb49ae178b9d5e735a99176b8d785238b753800
+  data.tar.gz: d9f05748fbcca7aa76bb615b53480c9133423905c1137005d1c6df895a8b09c3
 SHA512:
-  metadata.gz: b9076f2e8c632e23374174921c5862814348f8d64ca20405e3851101f798c15eaf56afef46339227b50b9a5da70ea40833ace51d3894435dc488a20cbe86cdb4
-  data.tar.gz: 9236f13270d0a46db84e592b0603817fc1b255c50d3ec80e7659d6c3eba02d7f6bcc457c303800a3c03d374e6209f4cf33a6c3e4857d0257989d9768e8bbf9b5
+  metadata.gz: dd1b45fd72e08536d0b95b261b8ca071d68fa0a1840c984c9d5aae4d9449b394a11ad6e7f8a4ca8df53b68ee7aef68791468e98404fd6a4ec098a34d831affd6
+  data.tar.gz: ebf2a08b3ff59ba317b48cd175d87bf0624e2d4c67d2c95c90b1c8fb32cd9c1afa6ff48f0d24cb467401d3b9b2364cf368946cf4af01e8bdb744431ee9cd961f

data/LICENSE.txt

@@ -1,5 +1,5 @@
 archive_r License
-Version: 0.1.6 (2025-12-10)
+Version: 0.1.7 (2025-12-16)
 
 ----------------------------------------
 Primary License
@@ -75,7 +75,7 @@ The following components are redistributed only because libarchive (bundled with
    - License: GNU LGPLv3+ or GNU GPLv2+ (https://gmplib.org/)
 
 10. OpenSSL 3
-    - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r binaries.
+   - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r Windows wheels.
     - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
 
 11. lz4

data/README.md

@@ -1,5 +1,8 @@
 # archive_r Ruby Binding
 
+Ruby bindings for archive_r, a libarchive-based library for processing many archive formats.
+It streams entry data directly from the source to recursively read nested archives without extracting to temporary files or loading large in-memory buffers.
+
 Ruby bindings expose the archive_r traverser API with a natural, block-friendly interface. This document consolidates the Ruby-specific instructions that previously lived in the repository root README.
 
 ## Requirements

data/ext/archive_r/archive_r_ext.cc

@@ -72,11 +72,7 @@ static VALUE path_entry_to_rb(const PathEntry &entry) {
     }
     return array;
   }
-  VALUE array = rb_ary_new_capa(entry.nested_nodes().size());
-  for (const auto &child : entry.nested_nodes()) {
-    rb_ary_push(array, path_entry_to_rb(child));
-  }
-  return array;
+  return Qnil;
 }
 
 static VALUE path_hierarchy_to_rb(const PathHierarchy &hierarchy) {
@@ -509,12 +505,7 @@ static PathEntry rb_value_to_path_entry(VALUE value) {
     return PathEntry::multi_volume(std::move(parts));
   }
 
-  PathEntry::NodeList nodes;
-  nodes.reserve(static_cast<size_t>(length));
-  for (long i = 0; i < length; ++i) {
-    nodes.emplace_back(rb_value_to_path_entry(rb_ary_entry(array, i)));
-  }
-  return PathEntry::nested(std::move(nodes));
+  rb_raise(rb_eTypeError, "PathEntry array must contain only Strings");
 }
 
 // Helper: Convert Ruby path argument into vector of PathHierarchy

data/ext/archive_r/vendor/archive_r/LICENSE.txt

@@ -1,5 +1,5 @@
 archive_r License
-Version: 0.1.6 (2025-12-10)
+Version: 0.1.7 (2025-12-16)
 
 ----------------------------------------
 Primary License
@@ -75,7 +75,7 @@ The following components are redistributed only because libarchive (bundled with
    - License: GNU LGPLv3+ or GNU GPLv2+ (https://gmplib.org/)
 
 10. OpenSSL 3
-    - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r binaries.
+   - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r Windows wheels.
     - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
 
 11. lz4

data/ext/archive_r/vendor/archive_r/include/archive_r/data_stream.h

@@ -3,23 +3,13 @@
 
 #pragma once
 
+#include "archive_r/platform_compat.h"
 #include "archive_r/path_hierarchy.h"
 
 #include <functional>
 #include <memory>
-#include <sys/types.h>
 #include <cstdint>
 
-#ifdef _WIN32
-#include <basetsd.h>
-using ssize_t = SSIZE_T;
-#endif
-
-// Avoid conflict with potential 'read' macro on Windows
-#ifdef read
-#undef read
-#endif
-
 namespace archive_r {
 
 /**

data/ext/archive_r/vendor/archive_r/include/archive_r/entry.h

@@ -7,17 +7,12 @@
 #include <filesystem>
 #include <memory>
 #include <string>
-#include <sys/types.h>
 #include <vector>
 
-#ifdef _MSC_VER
-#include <BaseTsd.h>
-typedef SSIZE_T ssize_t;
-#endif
-
 #include "archive_r/entry_fault.h"
 #include "archive_r/entry_metadata.h"
 #include "archive_r/path_hierarchy.h"
+#include "archive_r/platform_compat.h"
 
 namespace archive_r {
 
@@ -36,8 +31,21 @@ struct MultiVolumeGroupOptions {
  * - Content access (read operations)
  * - Multi-volume archive grouping support
  *
- * Entry objects are typically obtained from ArchiveTraverser::Iterator and
- * remain valid until the iterator advances.
+ * \par Lifetime and Copying
+ * - An Entry& obtained while iterating a Traverser is typically valid until the
+ *   iterator advances.
+ * - Entry is copyable. Copies retain metadata (name/path/metadata/etc), but do not
+ *   retain traverser-managed traversal control state. Calling set_descent() or
+ *   set_multi_volume_group() on such copies will report a fault and has no effect.
+ *   Prefer calling these control methods on the Entry& inside the iteration loop,
+ *   before advancing.
+ *
+ * \par Reading
+ * - read() returns >0 for bytes read, 0 for EOF, -1 for error.
+ * - On error, read() dispatches an EntryFault via the registered fault callback
+ *   (if any).
+ * - After any successful read() (including EOF), descent is disabled until
+ *   explicitly re-enabled via set_descent(true).
  */
 class Entry {
 public:
@@ -89,8 +97,8 @@ public:
   /**
    * @brief Read data from the entry
    *
-  * Each call uses an internal ArchiveStackOrchestrator so reads remain valid even
-  * if the owning iterator advances or other traversal work continues in parallel.
+    * Each call uses an internal ArchiveStackOrchestrator so reads remain valid even
+    * if the owning iterator advances.
    *
    * @param buffer Buffer to read data into
    * @param length Maximum number of bytes to read
@@ -101,6 +109,9 @@ public:
   /**
    * @brief Enable or disable automatic descent into this entry
    * @param enabled true to descend (default), false to keep traversal at current level
+    *
+    * This control is only available for entries that are managed by a Traverser.
+    * Calling this on an Entry that is not traverser-managed reports a fault.
    */
   void set_descent(bool enabled);
 
@@ -128,6 +139,9 @@ public:
    *     }
    * }
    * @endcode
+  *
+  * This control is only available for entries that are managed by a Traverser.
+  * Calling this on an Entry that is not traverser-managed reports a fault.
    */
   void set_multi_volume_group(const std::string &base_name, const MultiVolumeGroupOptions &options = {});
 

data/ext/archive_r/vendor/archive_r/include/archive_r/path_hierarchy.h

@@ -18,7 +18,6 @@ namespace archive_r {
  * A component can be one of three shapes:
  * - single string value (most common)
  * - multi-volume part list (split archives that share a common base name)
- * - nested list of child entries (used for synthetic grouping)
  */
 class PathEntry {
 public:
@@ -27,8 +26,6 @@ public:
     enum class Ordering { Natural, Given } ordering = Ordering::Natural;
   };
 
-  using NodeList = std::vector<PathEntry>;
-
   PathEntry() = default;
 
   explicit PathEntry(std::string value)
@@ -37,9 +34,6 @@ public:
   explicit PathEntry(Parts parts)
       : _value(std::move(parts)) {}
 
-  explicit PathEntry(NodeList nodes)
-      : _value(std::move(nodes)) {}
-
   static PathEntry single(std::string entry) { return PathEntry(std::move(entry)); }
 
   static PathEntry multi_volume(std::vector<std::string> entries, Parts::Ordering ordering = Parts::Ordering::Natural) {
@@ -50,24 +44,14 @@ public:
     return PathEntry(std::move(parts));
   }
 
-  static PathEntry nested(NodeList hierarchies) {
-    if (hierarchies.empty()) {
-      throw std::invalid_argument("nested hierarchies cannot be empty");
-    }
-    return PathEntry(std::move(hierarchies));
-  }
-
   bool is_single() const { return std::holds_alternative<std::string>(_value); }
   bool is_multi_volume() const { return std::holds_alternative<Parts>(_value); }
-  bool is_nested() const { return std::holds_alternative<NodeList>(_value); }
   const std::string &single_value() const { return std::get<std::string>(_value); }
   const Parts &multi_volume_parts() const { return std::get<Parts>(_value); }
   Parts &multi_volume_parts_mut() { return std::get<Parts>(_value); }
-  const NodeList &nested_nodes() const { return std::get<NodeList>(_value); }
-  NodeList &nested_nodes_mut() { return std::get<NodeList>(_value); }
 
 private:
-  std::variant<std::string, Parts, NodeList> _value;
+  std::variant<std::string, Parts> _value;
 };
 
 using PathHierarchy = std::vector<PathEntry>;
@@ -76,11 +60,10 @@ using PathHierarchy = std::vector<PathEntry>;
  * Compare two entries using the ordering enforced throughout archive_r.
  *
  * Ordering rules:
- * 1. Entry categories are ordered single < multi-volume < nested node-list.
+ * 1. Entry categories are ordered single < multi-volume.
  * 2. Single entries compare by string value.
  * 3. Multi-volume entries first compare their ordering flag (Natural < Given),
  *    then compare corresponding part names lexicographically, finally by list length.
- * 4. Nested node-lists compare child entries pairwise using the same rules.
  */
 int compare_entries(const PathEntry &lhs, const PathEntry &rhs);
 

data/ext/archive_r/vendor/archive_r/include/archive_r/platform_compat.h

@@ -7,8 +7,8 @@
 
 #if defined(_WIN32)
 #  include <sys/stat.h>
+#  include <BaseTsd.h>
 #  if !defined(_SSIZE_T_DEFINED)
-#    include <BaseTsd.h>
 using ssize_t = SSIZE_T;
 #    define _SSIZE_T_DEFINED
 #  endif
@@ -17,3 +17,18 @@ using mode_t = unsigned short; // MSVC does not expose POSIX mode_t by default
 #    define _MODE_T_DEFINED
 #  endif
 #endif
+
+namespace archive_r {
+
+// Expose POSIX-like types within the archive_r namespace.
+// - On POSIX platforms, ssize_t/mode_t come from <sys/types.h>.
+// - On Windows, platform_compat provides fallback definitions above.
+#if defined(_WIN32)
+using ssize_t = SSIZE_T;
+using mode_t = unsigned short;
+#else
+using ssize_t = ::ssize_t;
+using mode_t = ::mode_t;
+#endif
+
+} // namespace archive_r

data/ext/archive_r/vendor/archive_r/include/archive_r/traverser.h

@@ -30,9 +30,31 @@ struct TraverserOptions {
  * and filesystem directories.
  *
  * Uses std::filesystem for directory traversal and ArchiveStackOrchestrator for archives.
-
  * @see Entry, ArchiveStackOrchestrator
  *
+ * \par Inputs
+ * - The input list must not be empty, and each PathHierarchy must not be empty.
+ *   Violations throw std::invalid_argument.
+ * - For the common single-root case, prefer make_single_path("...") or
+ *   Traverser(const std::string&, ...).
+ *
+ * \par How Roots Are Interpreted
+ * - If the root hierarchy is exactly one single path and it refers to a directory,
+ *   Traverser enumerates it using std::filesystem::recursive_directory_iterator.
+ * - Otherwise, Traverser attempts archive traversal using libarchive.
+ *
+ * \par Error Model (Exceptions vs Faults)
+ * - Invalid arguments are reported via exceptions (std::invalid_argument).
+ * - Recoverable data / I/O errors during archive traversal are reported via the
+ *   global fault callback (EntryFault) and traversal continues.
+ * - Directory traversal uses std::filesystem iterators; filesystem exceptions
+ *   (e.g. std::filesystem::filesystem_error) may be thrown and are not converted
+ *   to faults.
+ *
+ * \par Iterator Semantics
+ * - Traverser::Iterator is an input iterator (single-pass).
+ * - Dereferencing the end iterator throws std::logic_error.
+ *
  * Usage:
  *   Traverser traverser({make_single_path("archive.tar.gz")});  // or directory path
  *   for (Entry& entry : traverser) {
@@ -53,9 +75,21 @@ public:
    * Provide one or more paths to traverse. Single-path traversal can be
    * achieved by passing a container with one element:
    *   Traverser traverser({make_single_path("archive.tar.gz")});
+  *
+  * @throws std::invalid_argument if paths is empty or contains an empty hierarchy
    */
   explicit Traverser(std::vector<PathHierarchy> paths, TraverserOptions options = {});
 
+  /**
+   * @brief Construct traverser for a single hierarchy
+   */
+  explicit Traverser(PathHierarchy path, TraverserOptions options = {});
+
+  /**
+   * @brief Construct traverser for a single archive or directory path
+   */
+  explicit Traverser(const std::string &path, TraverserOptions options = {});
+
   ~Traverser();
 
   // Non-copyable

data/ext/archive_r/vendor/archive_r/src/path_hierarchy.cc

@@ -14,14 +14,9 @@ int entry_type_rank(const PathEntry &entry) {
   if (entry.is_single()) {
     return 0;
   }
-  if (entry.is_multi_volume()) {
-    return 1;
-  }
-  return 2;
+  return 1;
 }
 
-int compare_node_lists_impl(const PathEntry::NodeList &lhs, const PathEntry::NodeList &rhs);
-
 int compare_entries_impl(const PathEntry &lhs, const PathEntry &rhs) {
   const int lhs_rank = entry_type_rank(lhs);
   const int rhs_rank = entry_type_rank(rhs);
@@ -69,22 +64,6 @@ int compare_entries_impl(const PathEntry &lhs, const PathEntry &rhs) {
     return 0;
   }
 
-  return compare_node_lists_impl(lhs.nested_nodes(), rhs.nested_nodes());
-}
-
-int compare_node_lists_impl(const PathEntry::NodeList &lhs, const PathEntry::NodeList &rhs) {
-  const std::size_t lsize = lhs.size();
-  const std::size_t rsize = rhs.size();
-  const std::size_t compare_count = lsize < rsize ? lsize : rsize;
-  for (std::size_t i = 0; i < compare_count; ++i) {
-    const int cmp = compare_entries_impl(lhs[i], rhs[i]);
-    if (cmp != 0) {
-      return cmp;
-    }
-  }
-  if (lsize != rsize) {
-    return lsize < rsize ? -1 : 1;
-  }
   return 0;
 }
 

data/ext/archive_r/vendor/archive_r/src/path_hierarchy_utils.cc

@@ -203,27 +203,6 @@ bool flatten_entry_to_string(const PathEntry &entry, std::string &output) {
     return true;
   }
 
-  if (entry.is_nested()) {
-    std::string result;
-    bool first = true;
-    for (const auto &child : entry.nested_nodes()) {
-      std::string component;
-      if (!flatten_entry_to_string(child, component)) {
-        return false;
-      }
-      if (component.empty()) {
-        return false;
-      }
-      if (!first) {
-        result.push_back('/');
-      }
-      result += component;
-      first = false;
-    }
-    output = result;
-    return !result.empty();
-  }
-
   return false;
 }
 
@@ -275,17 +254,7 @@ std::string path_entry_display(const PathEntry &entry) {
     value.push_back(']');
     return value;
   }
-  std::string value = "{";
-  bool first = true;
-  for (const auto &child : entry.nested_nodes()) {
-    if (!first) {
-      value.push_back('/');
-    }
-    value += path_entry_display(child);
-    first = false;
-  }
-  value.push_back('}');
-  return value;
+  return {};
 }
 
 std::string hierarchy_display(const PathHierarchy &hierarchy) {

data/ext/archive_r/vendor/archive_r/src/traverser.cc

@@ -51,6 +51,12 @@ Traverser::Traverser(std::vector<PathHierarchy> paths, TraverserOptions options)
 
 }
 
+Traverser::Traverser(PathHierarchy path, TraverserOptions options)
+    : Traverser(std::vector<PathHierarchy>{std::move(path)}, std::move(options)) {}
+
+Traverser::Traverser(const std::string &path, TraverserOptions options)
+    : Traverser(std::vector<PathHierarchy>{make_single_path(path)}, std::move(options)) {}
+
 Traverser::~Traverser() = default;
 
 // ============================================================================

data/lib/archive_r.rb

@@ -35,7 +35,7 @@ rescue LoadError
 end
 
 module Archive_r
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
   # Common archive formats excluding libarchive's mtree/raw pseudo formats
   STANDARD_FORMATS = %w[
     7zip ar cab cpio empty iso9660 lha rar tar warc xar zip
@@ -87,6 +87,10 @@ module Archive_r
       def open(paths, opts = nil, &block)
         __archive_r_c_open(paths, Archive_r.normalize_options(opts), &block)
       end
+
+      def open_hierarchy(hierarchy, opts = nil, &block)
+        open([hierarchy], opts, &block)
+      end
     end
 
     alias_method :__archive_r_c_initialize, :initialize

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: archive_r_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - raizo.tcs
@@ -37,8 +37,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: Ruby bindings for archive_r that recursively walk nested and multipart
-  archives directly from the source stream without creating temporary files
+description: Ruby bindings for archive_r, a libarchive-based library for processing
+  many archive formats. It streams entry data directly from the source to recursively
+  read nested archives without extracting to temporary files or loading large in-memory
+  buffers.
 email:
 - raizo.tcs@users.noreply.github.com
 executables: []
@@ -104,7 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0
+rubygems_version: 4.0.1
 specification_version: 4
-summary: Ruby bindings for archive_r that traverse nested archives without temp extraction
+summary: 'Ruby bindings for archive_r: libarchive-based streaming traversal for recursive
+  nested archives (no temp files, no large in-memory buffers)'
 test_files: []