compress-bsc 1.0.0

data/examples/usage_example.rb

@@ -0,0 +1,215 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/compress/bsc'
+
+# Example usage of compress-bsc
+def main
+  puts "compress-bsc Example Usage"
+  puts "=" * 40
+
+  begin
+    # Initialize the BSC library
+    puts "Initializing BSC library..."
+    bsc = Compress::BSC.new
+    puts "✓ BSC library initialized successfully"
+
+    # Initialize with custom features
+    puts "\nInitializing BSC library with custom features..."
+    bsc_custom = Compress::BSC.new(features: Compress::BSC::Library::LIBBSC_FEATURE_FASTMODE)
+    puts "✓ BSC library with custom features initialized successfully"
+
+    # Initialize with multiple features
+    puts "\nInitializing BSC library with multiple features..."
+    bsc_multi = Compress::BSC.new(
+      features: Compress::BSC::Library::LIBBSC_FEATURE_FASTMODE |
+                Compress::BSC::Library::LIBBSC_FEATURE_MULTITHREADING |
+                Compress::BSC::Library::LIBBSC_FEATURE_LARGEPAGES
+    )
+    puts "✓ BSC library with multiple features initialized successfully"
+
+    # Test data
+    original_data = generate_test_data
+    puts "\nOriginal data size: #{original_data.bytesize} bytes"
+
+    # Basic compression/decompression
+    puts "\n1. Basic Compression Test"
+    puts "-" * 30
+
+    compressed = bsc.compress(original_data)
+    puts "Compressed size: #{compressed.bytesize} bytes"
+
+    ratio = original_data.bytesize.to_f / compressed.bytesize
+    puts "Compression ratio: #{ratio.round(2)}:1"
+
+    decompressed = bsc.decompress(compressed)
+    puts "Decompression successful: #{original_data == decompressed}"
+
+    # Advanced compression with custom settings
+    puts "\n2. Advanced Compression Test"
+    puts "-" * 30
+
+    compressor = Compress::BSC::Compressor.new(
+      block_sorter: Compress::BSC::Library::LIBBSC_BLOCKSORTER_BWT,
+      coder: Compress::BSC::Library::LIBBSC_CODER_QLFC_ADAPTIVE,
+      features: Compress::BSC::Library::LIBBSC_FEATURE_FASTMODE |
+                Compress::BSC::Library::LIBBSC_FEATURE_MULTITHREADING
+    )
+
+    compressed_advanced = compressor.compress(original_data)
+    puts "Advanced compressed size: #{compressed_advanced.bytesize} bytes"
+
+    ratio_advanced = original_data.bytesize.to_f / compressed_advanced.bytesize
+    puts "Advanced compression ratio: #{ratio_advanced.round(2)}:1"
+
+    decompressor = Compress::BSC::Decompressor.new
+    decompressed_advanced = decompressor.decompress(compressed_advanced)
+    puts "Advanced decompression successful: #{original_data == decompressed_advanced}"
+
+    # LZP preprocessing test
+    puts "\n3. LZP Preprocessing Test"
+    puts "-" * 30
+
+    lzp_compressor = Compress::BSC::Compressor.new(
+      lzp_hash_size: Compress::BSC::Library::LIBBSC_DEFAULT_LZPHASHSIZE,
+      lzp_min_len: Compress::BSC::Library::LIBBSC_DEFAULT_LZPMINLEN,
+      block_sorter: Compress::BSC::Library::LIBBSC_BLOCKSORTER_BWT,
+      coder: Compress::BSC::Library::LIBBSC_CODER_QLFC_STATIC
+    )
+
+    compressed_lzp = lzp_compressor.compress(original_data)
+    puts "LZP compressed size: #{compressed_lzp.bytesize} bytes"
+
+    ratio_lzp = original_data.bytesize.to_f / compressed_lzp.bytesize
+    puts "LZP compression ratio: #{ratio_lzp.round(2)}:1"
+
+    decompressed_lzp = decompressor.decompress(compressed_lzp)
+    puts "LZP decompression successful: #{original_data == decompressed_lzp}"
+
+    # Block info test
+    puts "\n4. Block Information Test"
+    puts "-" * 30
+
+    info = Compress::BSC::Decompressor.block_info(compressed)
+    puts "Block size: #{info[:block_size]} bytes"
+    puts "Data size: #{info[:data_size]} bytes"
+    puts "Header overhead: #{info[:block_size] - info[:data_size]} bytes"
+
+    # File compression test
+    puts "\n5. File Compression Test"
+    puts "-" * 30
+
+    test_file_compression
+
+    # Performance comparison
+    puts "\n6. Performance Comparison"
+    puts "-" * 30
+
+    performance_test(original_data)
+
+    puts "\n✓ All tests completed successfully!"
+
+  rescue Compress::BSC::Error => e
+    puts "❌ BSC Error: #{e.error_name} (#{e.code})"
+    puts e.message
+  rescue LoadError => e
+    puts "❌ Library not found: #{e.message}"
+    puts "Please install libbsc library"
+  rescue => e
+    puts "❌ Unexpected error: #{e.message}"
+    puts e.backtrace.first(3)
+  end
+end
+
+def generate_test_data
+  # Generate mixed test data for better compression testing
+  text_data = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. " * 200
+  repetitive_data = "ABCDEFGH" * 500
+  random_data = Random.bytes(1000)
+  binary_data = (0..255).to_a.pack('C*') * 10
+
+  text_data + repetitive_data + random_data + binary_data
+end
+
+def test_file_compression
+  test_content = generate_test_data
+  input_file = 'example_input.txt'
+  compressed_file = 'example_output.bsc'
+  decompressed_file = 'example_restored.txt'
+
+  begin
+    # Write test file
+    File.binwrite(input_file, test_content)
+
+    # Compress file
+    compressor = Compress::BSC::Compressor.new
+    compressed_size = compressor.compress_file(input_file, compressed_file)
+    puts "File compressed: #{File.size(input_file)} → #{compressed_size} bytes"
+
+    # Decompress file
+    decompressor = Compress::BSC::Decompressor.new
+    decompressed_size = decompressor.decompress_file(compressed_file, decompressed_file)
+    puts "File decompressed: #{compressed_size} → #{decompressed_size} bytes"
+
+    # Verify integrity
+    original_content = File.binread(input_file)
+    restored_content = File.binread(decompressed_file)
+    puts "File integrity verified: #{original_content == restored_content}"
+
+  ensure
+    # Clean up
+    [input_file, compressed_file, decompressed_file].each do |file|
+      File.delete(file) if File.exist?(file)
+    end
+  end
+end
+
+def performance_test(data)
+  require 'benchmark'
+
+  puts "Testing with #{data.bytesize} bytes of data..."
+
+  results = Benchmark.bm(20) do |x|
+    compressed_basic = nil
+    compressed_adaptive = nil
+    compressed_fast = nil
+    compressed_lzp = nil
+
+    x.report("Basic compression:") do
+      compressor = Compress::BSC::Compressor.new
+      compressed_basic = compressor.compress(data)
+    end
+
+    x.report("Adaptive coder:") do
+      compressor = Compress::BSC::Compressor.new(
+        coder: Compress::BSC::Library::LIBBSC_CODER_QLFC_ADAPTIVE
+      )
+      compressed_adaptive = compressor.compress(data)
+    end
+
+    x.report("Fast coder:") do
+      compressor = Compress::BSC::Compressor.new(
+        coder: Compress::BSC::Library::LIBBSC_CODER_QLFC_FAST
+      )
+      compressed_fast = compressor.compress(data)
+    end
+
+    x.report("With LZP:") do
+      compressor = Compress::BSC::Compressor.new(
+        lzp_hash_size: 15,
+        lzp_min_len: 128
+      )
+      compressed_lzp = compressor.compress(data)
+    end
+
+    # Show compression ratios
+    puts "\nCompression Ratios:"
+    puts "  Basic: #{(data.bytesize.to_f / compressed_basic.bytesize).round(2)}:1" if compressed_basic
+    puts "  Adaptive: #{(data.bytesize.to_f / compressed_adaptive.bytesize).round(2)}:1" if compressed_adaptive
+    puts "  Fast: #{(data.bytesize.to_f / compressed_fast.bytesize).round(2)}:1" if compressed_fast
+    puts "  LZP: #{(data.bytesize.to_f / compressed_lzp.bytesize).round(2)}:1" if compressed_lzp
+  end
+end
+
+if __FILE__ == $0
+  main
+end

data/lib/compress/bsc/compressor.rb

@@ -0,0 +1,81 @@
+module Compress
+  class BSC
+    class Compressor
+      attr_reader :lzp_hash_size, :lzp_min_len, :block_sorter, :coder, :features
+
+      def initialize(options = {})
+      @lzp_hash_size = options[:lzp_hash_size] || 0  # Disable LZP by default
+      @lzp_min_len = options[:lzp_min_len] || 0      # Disable LZP by default
+      @block_sorter = options[:block_sorter] || Library::LIBBSC_DEFAULT_BLOCKSORTER
+      @coder = options[:coder] || Library::LIBBSC_DEFAULT_CODER
+      @features = options[:features] || Library::LIBBSC_DEFAULT_FEATURES
+    end
+
+    def compress(input_data)
+      raise ArgumentError, "Input data cannot be nil" if input_data.nil?
+      raise ArgumentError, "Input data must be a string" unless input_data.is_a?(String)
+
+      return input_data if input_data.empty?
+
+      # Store original encoding for later restoration
+      original_encoding = input_data.encoding
+
+      # Convert to binary for compression (make a copy first!)
+      binary_data = input_data.dup.force_encoding(Encoding::BINARY)
+      input_size = binary_data.bytesize
+
+      # Calculate maximum possible output size (worst case)
+      # BSC adds a header, so we need at least input_size + HEADER_SIZE
+      max_output_size = input_size + Library::LIBBSC_HEADER_SIZE + 1024 # Add some buffer
+
+      # Allocate input and output buffers
+      input_ptr = FFI::MemoryPointer.new(:char, input_size)
+      input_ptr.put_bytes(0, binary_data)
+
+      output_ptr = FFI::MemoryPointer.new(:char, max_output_size)
+
+      begin
+        # Perform compression
+        result = Library.bsc_compress(
+          input_ptr,
+          output_ptr,
+          input_size,
+          @lzp_hash_size,
+          @lzp_min_len,
+          @block_sorter,
+          @coder,
+          @features
+        )
+
+        if result == Library::LIBBSC_NOT_COMPRESSIBLE
+          # Return original data if not compressible
+          return input_data
+        end
+
+        Error.check_result(result)
+
+        # Extract compressed data and add encoding marker
+        compressed_data = output_ptr.get_bytes(0, result)
+
+        # Store original encoding in the compressed data metadata
+        # We'll use a simple approach: prepend encoding name as a header
+        encoding_name = original_encoding.name
+        encoding_header = [encoding_name.bytesize, encoding_name].pack("Ca*")
+
+        # Return with encoding header
+        (encoding_header + compressed_data).force_encoding(Encoding::BINARY)
+      ensure
+        input_ptr.free if input_ptr
+        output_ptr.free if output_ptr
+      end
+    end
+
+    def compress_file(input_path, output_path)
+      input_data = File.binread(input_path)
+      compressed_data = compress(input_data)
+      File.binwrite(output_path, compressed_data)
+      compressed_data.bytesize
+    end
+    end
+  end
+end

data/lib/compress/bsc/decompressor.rb

@@ -0,0 +1,159 @@
+module Compress
+  class BSC
+    class Decompressor
+      attr_reader :features
+
+      def initialize(options = {})
+      @features = options[:features] || Library::LIBBSC_DEFAULT_FEATURES
+    end
+
+    def decompress(compressed_data)
+      raise ArgumentError, "Compressed data cannot be nil" if compressed_data.nil?
+      raise ArgumentError, "Compressed data must be a string" unless compressed_data.is_a?(String)
+
+      return compressed_data if compressed_data.empty?
+
+      # Extract encoding information from header
+      encoding_name = nil
+      actual_compressed_data = compressed_data
+
+      if compressed_data.bytesize > 1
+        # Try to extract encoding header
+        encoding_name_length = compressed_data.bytes[0]
+        if encoding_name_length > 0 && encoding_name_length < 50 && compressed_data.bytesize > encoding_name_length + 1
+          encoding_name = compressed_data[1, encoding_name_length]
+          actual_compressed_data = compressed_data[(encoding_name_length + 1)..-1]
+        end
+      end
+
+      input_size = actual_compressed_data.bytesize
+
+      # Need at least header size for the BSC data
+      if input_size < Library::LIBBSC_HEADER_SIZE
+        raise Error.new(Library::LIBBSC_DATA_CORRUPT)
+      end
+
+      # Allocate input buffer
+      input_ptr = FFI::MemoryPointer.new(:char, input_size)
+      input_ptr.put_bytes(0, actual_compressed_data)
+
+      # Get block info to determine output size
+      block_size_ptr = FFI::MemoryPointer.new(:int)
+      data_size_ptr = FFI::MemoryPointer.new(:int)
+
+      result = Library.bsc_block_info(
+        input_ptr,
+        input_size,
+        block_size_ptr,
+        data_size_ptr,
+        @features
+      )
+
+      Error.check_result(result)
+
+      block_size = block_size_ptr.read_int
+      data_size = data_size_ptr.read_int
+
+      # Validate sizes
+      if input_size < block_size || data_size <= 0
+        raise Error.new(Library::LIBBSC_DATA_CORRUPT)
+      end
+
+      # Allocate output buffer
+      output_ptr = FFI::MemoryPointer.new(:char, data_size)
+
+      begin
+        # Perform decompression
+        result = Library.bsc_decompress(
+          input_ptr,
+          input_size,
+          output_ptr,
+          data_size,
+          @features
+        )
+
+        Error.check_result(result)
+
+        # Extract decompressed data
+        decompressed_data = output_ptr.get_bytes(0, data_size)
+
+        # Restore original encoding if available
+        if encoding_name && !encoding_name.empty?
+          begin
+            target_encoding = Encoding.find(encoding_name)
+            decompressed_data.force_encoding(target_encoding)
+          rescue ArgumentError
+            # If encoding is not found, keep as binary
+            decompressed_data.force_encoding(Encoding::BINARY)
+          end
+        else
+          decompressed_data.force_encoding(Encoding::BINARY)
+        end
+
+        decompressed_data
+      ensure
+        input_ptr.free if input_ptr
+        output_ptr.free if output_ptr
+        block_size_ptr.free if block_size_ptr
+        data_size_ptr.free if data_size_ptr
+      end
+    end
+
+    def decompress_file(input_path, output_path)
+      compressed_data = File.binread(input_path)
+      decompressed_data = decompress(compressed_data)
+      File.binwrite(output_path, decompressed_data)
+      decompressed_data.bytesize
+    end
+
+    def self.block_info(compressed_data, features = Library::LIBBSC_DEFAULT_FEATURES)
+      raise ArgumentError, "Compressed data cannot be nil" if compressed_data.nil?
+      raise ArgumentError, "Compressed data must be a string" unless compressed_data.is_a?(String)
+
+      # Extract actual compressed data, skipping encoding header if present
+      actual_compressed_data = compressed_data
+
+      if compressed_data.bytesize > 1
+        # Try to extract encoding header
+        encoding_name_length = compressed_data.bytes[0]
+        if encoding_name_length > 0 && encoding_name_length < 50 && compressed_data.bytesize > encoding_name_length + 1
+          actual_compressed_data = compressed_data[(encoding_name_length + 1)..-1]
+        end
+      end
+
+      input_size = actual_compressed_data.bytesize
+
+      if input_size < Library::LIBBSC_HEADER_SIZE
+        raise Error.new(Library::LIBBSC_DATA_CORRUPT)
+      end
+
+      input_ptr = FFI::MemoryPointer.new(:char, input_size)
+      input_ptr.put_bytes(0, actual_compressed_data)
+
+      block_size_ptr = FFI::MemoryPointer.new(:int)
+      data_size_ptr = FFI::MemoryPointer.new(:int)
+
+      begin
+        result = Library.bsc_block_info(
+          input_ptr,
+          input_size,
+          block_size_ptr,
+          data_size_ptr,
+          features
+        )
+
+        Error.check_result(result)
+
+        {
+          block_size: block_size_ptr.read_int,
+          data_size: data_size_ptr.read_int
+        }
+      ensure
+        input_ptr.free if input_ptr
+        block_size_ptr.free if block_size_ptr
+        data_size_ptr.free if data_size_ptr
+      end
+    end
+    end
+  end
+end

data/lib/compress/bsc/error.rb

@@ -0,0 +1,18 @@
+module Compress
+  class BSC
+    class Error < StandardError
+      attr_reader :code, :error_name
+
+      def initialize(code)
+        @code = code
+        @error_name = Library.error_name(code)
+        super("BSC Error: #{@error_name} (#{@code})")
+      end
+
+      def self.check_result(result)
+        raise Error.new(result) if result < Library::LIBBSC_NO_ERROR
+        result
+      end
+    end
+  end
+end

data/lib/compress/bsc/library.rb

@@ -0,0 +1,100 @@
+require 'ffi'
+
+module Compress
+  class BSC
+    module Library
+      extend FFI::Library
+
+      begin
+        ffi_lib 'bsc'
+      rescue LoadError
+        ffi_lib '/usr/local/lib/libbsc.so'
+      rescue LoadError
+        ffi_lib 'libbsc'
+      end
+
+      # Version constants
+      LIBBSC_VERSION_MAJOR = 3
+      LIBBSC_VERSION_MINOR = 3
+      LIBBSC_VERSION_PATCH = 9
+      LIBBSC_VERSION_STRING = "3.3.9"
+
+      # Error codes
+      LIBBSC_NO_ERROR = 0
+      LIBBSC_BAD_PARAMETER = -1
+      LIBBSC_NOT_ENOUGH_MEMORY = -2
+      LIBBSC_NOT_COMPRESSIBLE = -3
+      LIBBSC_NOT_SUPPORTED = -4
+      LIBBSC_UNEXPECTED_EOB = -5
+      LIBBSC_DATA_CORRUPT = -6
+      LIBBSC_GPU_ERROR = -7
+      LIBBSC_GPU_NOT_SUPPORTED = -8
+      LIBBSC_GPU_NOT_ENOUGH_MEMORY = -9
+
+      # Block sorter constants
+      LIBBSC_BLOCKSORTER_NONE = 0
+      LIBBSC_BLOCKSORTER_BWT = 1
+      LIBBSC_BLOCKSORTER_ST3 = 3
+      LIBBSC_BLOCKSORTER_ST4 = 4
+      LIBBSC_BLOCKSORTER_ST5 = 5
+      LIBBSC_BLOCKSORTER_ST6 = 6
+      LIBBSC_BLOCKSORTER_ST7 = 7
+      LIBBSC_BLOCKSORTER_ST8 = 8
+
+      # Coder constants
+      LIBBSC_CODER_NONE = 0
+      LIBBSC_CODER_QLFC_STATIC = 1
+      LIBBSC_CODER_QLFC_ADAPTIVE = 2
+      LIBBSC_CODER_QLFC_FAST = 3
+
+      # Feature constants
+      LIBBSC_FEATURE_NONE = 0
+      LIBBSC_FEATURE_FASTMODE = 1
+      LIBBSC_FEATURE_MULTITHREADING = 2
+      LIBBSC_FEATURE_LARGEPAGES = 4
+      LIBBSC_FEATURE_CUDA = 8
+
+      # Default values
+      LIBBSC_DEFAULT_LZPHASHSIZE = 15
+      LIBBSC_DEFAULT_LZPMINLEN = 128
+      LIBBSC_DEFAULT_BLOCKSORTER = LIBBSC_BLOCKSORTER_BWT
+      LIBBSC_DEFAULT_CODER = LIBBSC_CODER_QLFC_STATIC
+      LIBBSC_DEFAULT_FEATURES = LIBBSC_FEATURE_FASTMODE | LIBBSC_FEATURE_MULTITHREADING
+
+      # Header size
+      LIBBSC_HEADER_SIZE = 28
+
+      # Function bindings
+      attach_function :bsc_init, [:int], :int
+      attach_function :bsc_init_full, [:int, :pointer, :pointer, :pointer], :int
+
+      attach_function :bsc_compress, [:pointer, :pointer, :int, :int, :int, :int, :int, :int], :int
+      attach_function :bsc_decompress, [:pointer, :int, :pointer, :int, :int], :int
+
+      attach_function :bsc_block_info, [:pointer, :int, :pointer, :pointer, :int], :int
+
+      # Platform functions
+      attach_function :bsc_malloc, [:size_t], :pointer
+      attach_function :bsc_zero_malloc, [:size_t], :pointer
+      attach_function :bsc_free, [:pointer], :void
+
+      # Error code names for debugging
+      ERROR_NAMES = {
+        LIBBSC_NO_ERROR => 'LIBBSC_NO_ERROR',
+        LIBBSC_BAD_PARAMETER => 'LIBBSC_BAD_PARAMETER',
+        LIBBSC_NOT_ENOUGH_MEMORY => 'LIBBSC_NOT_ENOUGH_MEMORY',
+        LIBBSC_NOT_COMPRESSIBLE => 'LIBBSC_NOT_COMPRESSIBLE',
+        LIBBSC_NOT_SUPPORTED => 'LIBBSC_NOT_SUPPORTED',
+        LIBBSC_UNEXPECTED_EOB => 'LIBBSC_UNEXPECTED_EOB',
+        LIBBSC_DATA_CORRUPT => 'LIBBSC_DATA_CORRUPT',
+        LIBBSC_GPU_ERROR => 'LIBBSC_GPU_ERROR',
+        LIBBSC_GPU_NOT_SUPPORTED => 'LIBBSC_GPU_NOT_SUPPORTED',
+        LIBBSC_GPU_NOT_ENOUGH_MEMORY => 'LIBBSC_GPU_NOT_ENOUGH_MEMORY'
+      }.freeze
+
+      def self.error_name(code)
+        ERROR_NAMES[code] || "UNKNOWN_ERROR(#{code})"
+      end
+    end
+  end
+end

data/lib/compress/bsc/version.rb

@@ -0,0 +1,5 @@
+module Compress
+  class BSC
+    VERSION = "1.0.0"
+  end
+end

data/lib/compress/bsc.rb

@@ -0,0 +1,26 @@
+require 'ffi'
+require_relative 'bsc/version'
+require_relative 'bsc/library'
+require_relative 'bsc/compressor'
+require_relative 'bsc/decompressor'
+require_relative 'bsc/error'
+
+module Compress
+  class BSC
+    # Initialize the BSC library with configurable features
+    def initialize(features: Library::LIBBSC_DEFAULT_FEATURES)
+      result = Library.bsc_init(features)
+      raise Error.new(result) unless result == Library::LIBBSC_NO_ERROR
+    end
+
+    # Simple compression interface
+    def compress(data, options = {})
+      Compressor.new(options).compress(data)
+    end
+
+    # Simple decompression interface
+    def decompress(data, options = {})
+      Decompressor.new(options).decompress(data)
+    end
+  end
+end

data/lib/compress-bsc.rb

@@ -0,0 +1,5 @@
+# Convenience file for requiring compress-bsc
+# This allows users to do: require 'compress-bsc'
+# which is equivalent to: require 'compress/bsc'
+
+require_relative 'compress/bsc'