archive_r_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ef63ef41cb26313bcc87243183c84d78e9b8fbc14ae05dd76b3db70b8f0fa48
+  data.tar.gz: f4a2cb797ce90ee25cd95f033df55a71c52db54376931bdd6e531b2ba493baf1
+SHA512:
+  metadata.gz: 55ab5d4f7b2d7636bdf3fb46a0bc562dc1e445eed7c14a6b217888982d38cc59d68f0791b69911c47ba20ec482e2dac31504ee5a22189acb434c972868b81973
+  data.tar.gz: 32993a36c25247c88ff17d9b577fba22f5f75516964e2176f6dc6e25df4892eb5ea422df44d2b7da89b3c5095ee045805c67b137968838af70123b4d60364ece

data/LICENSE

@@ -0,0 +1,56 @@
+archive_r License
+Version: 0.1.0 (2025-10-25)
+
+----------------------------------------
+Primary License
+----------------------------------------
+
+MIT License
+
+Copyright (c) 2025 archive_r Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------
+Third-Party Notices
+----------------------------------------
+
+This distribution bundles or links against the following third-party
+components. Their respective license terms apply in addition to the MIT
+License shown above.
+
+1. libarchive
+   - Purpose: core archive reading and writing functionality for the C++
+     library and language bindings.
+   - License: New BSD License (https://www.libarchive.org/)
+
+2. pybind11
+   - Purpose: header-only binding generator for the Python extension module.
+   - License: BSD-style License (https://github.com/pybind/pybind11)
+
+3. rake (development dependency for Ruby bindings)
+   - Purpose: build and release tasks for the Ruby gem.
+   - License: MIT License (https://github.com/ruby/rake)
+
+4. minitest (development dependency for Ruby bindings)
+   - Purpose: unit testing framework for the Ruby gem.
+   - License: MIT License (https://github.com/minitest/minitest)
+
+Users of archive_r should review the linked third-party licenses to ensure
+compliance with their terms when redistributing this software.

data/README.md

@@ -0,0 +1,103 @@
+# archive_r Ruby Binding
+
+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
+
+- Ruby 3.2 (same toolchain as the development environment)
+- libarchive 3.x (shared library and headers)
+- Build tools: `rake`, `minitest`, a C++17 compiler, and `make`
+
+## Installing the Gem
+
+### Recommended: build.sh workflow
+
+1. From the repository root run:
+   ```bash
+   ./build.sh --with-ruby
+   ```
+   Ruby packaging is enabled by default, so the command above builds the core library, compiles the binding, and creates `build/bindings/ruby/archive_r-<version>.gem`.
+2. Install the freshly built gem into your desired GEM_HOME:
+   ```bash
+   gem install --local build/bindings/ruby/archive_r-*.gem
+   ```
+3. When developing inside this repository the tests automatically install the gem into `build/ruby_gem_home` and set `ARCHIVE_R_CORE_ROOT=build` so the native extension links against the just-built static library.
+
+### Working inside bindings/ruby
+
+If you prefer to build from the `bindings/ruby` directory:
+
+```bash
+cd bindings/ruby
+bundle install
+bundle exec rake compile   # builds ext/archive_r
+bundle exec rake test      # runs test/test_traverser.rb
+bundle exec rake build     # creates archive_r-<version>.gem locally
+```
+
+The `rake test` task compiles the extension, installs it into `lib/`, and executes the Minitest suite.
+
+## Running the full repository test suite
+
+`./run_tests.sh` prepares a clean GEM_HOME (`build/ruby_gem_home`), installs the gem produced in `build/bindings/ruby`, and runs `bindings/ruby/test/test_traverser.rb`. The script now streams the `gem install` log to the console and preserves it in `build/logs/ruby_gem_install.log` for later inspection.
+
+## Usage Example
+
+```ruby
+require 'archive_r'
+
+SAFE_FORMATS = Archive_r::STANDARD_FORMATS
+
+def search_in_entry(entry, keyword)
+  overlap = ''
+  loop do
+    chunk = entry.read(8192)
+    break if chunk.nil? || chunk.empty?
+
+    search_text = overlap + chunk
+    return true if search_text.include?(keyword)
+
+    overlap = if chunk.length >= keyword.length - 1
+      chunk[-(keyword.length - 1)..-1]
+    else
+      chunk
+    end
+  end
+  false
+end
+
+Archive_r.traverse('test.zip', formats: SAFE_FORMATS) do |entry|
+  puts "#{entry.path} (depth=#{entry.depth})"
+  next unless entry.file? && entry.path.end_with?('.txt')
+  puts "  Found keyword" if search_in_entry(entry, 'search_keyword')
+end
+
+Archive_r.traverse('protected.zip', passphrases: ['password123'], formats: SAFE_FORMATS) do |entry|
+  puts entry.path
+end
+```
+
+## Thread Safety
+
+The Ruby bindings follow the same thread-safety rules as the C++ core library:
+
+**Safe:**
+- Each thread creates and uses its own `Traverser` instance
+- Concurrent traversal of different archives from different threads
+
+**Unsafe:**
+- Sharing a single `Traverser` instance across multiple threads
+- Calling `Archive_r.register_stream_factory` or `Archive_r.on_fault` from multiple threads (these modify process-wide global state)
+
+**Summary:** Create one `Traverser` per thread. Do not call global configuration methods (`register_stream_factory`, `on_fault`) concurrently.
+
+## Environment Notes
+
+- Set `ARCHIVE_R_CORE_ROOT` to the repository `build/` directory (or another archive_r build) if the gem needs to link against a pre-built static library instead of compiling the vendored core sources.
+- When installing into a sandbox (e.g., CI), configure `GEM_HOME`/`GEM_PATH` before invoking `gem install` so that the extension picks up the correct core library.
+
+## Further Help
+
+- Issue tracker: <https://github.com/raizo-tcs/archive_r/issues>
+- Releases / changelog: <https://github.com/raizo-tcs/archive_r/releases>
+- For C++/Python usage and overall project information, see the repository root `README.md`.