# KORE Ruby Gem Development
This directory contains the Ruby bindings and RubyGem package for KORE file format compression.
## Project Structure
```
kore-fileformat-ruby/
├── lib/
│ ├── kore_fileformat.rb # Main entry point and public API
│ └── kore_fileformat/
│ ├── version.rb # Version constant
│ ├── native.rb # FFI bindings to native library
│ ├── compressor.rb # Compression wrapper
│ └── decompressor.rb # Decompression wrapper
├── spec/
│ ├── spec_helper.rb # RSpec configuration
│ └── kore_fileformat_spec.rb # Comprehensive tests
├── ext/
│ └── kore_fileformat/
│ └── extconf.rb # Extension configuration (if building C wrapper)
├── Rakefile # Build tasks
├── kore-fileformat.gemspec # Gem configuration
└── README.md # This file
```
## Building & Installation
### Prerequisites
- Ruby 2.7 or later
- Bundler
- Native KORE library installed on system
### Build Commands
```bash
cd kore-fileformat-ruby
# Install dependencies
bundle install
# Run tests
bundle exec rspec spec/
# Build gem
gem build kore-fileformat.gemspec
# Install locally
gem install kore-fileformat-*.gem
```
## Usage
### Installing from RubyGems
```bash
gem install kore-fileformat
```
### In Gemfile
```ruby
gem 'kore-fileformat'
```
### Basic Usage
```ruby
require 'kore_fileformat'
# Compress data
original = "Hello World! " * 100
compressed = KoreFileFormat.compress(original)
puts "Compressed #{original.bytesize} bytes to #{compressed.bytesize} bytes"
# Decompress data
decompressed = KoreFileFormat.decompress(compressed)
puts "Matches original: #{decompressed == original}"
# With compression levels
fast = KoreFileFormat.compress_with_level(original, :fast)
balanced = KoreFileFormat.compress_with_level(original, :balanced)
maximum = KoreFileFormat.compress_with_level(original, :maximum)
```
## API Reference
### `KoreFileFormat.compress(data)`
Compresses data using KORE compression with default (Balanced) level.
- **Parameters**:
- `data`: Input data (String or Bytes)
- **Returns**: Compressed data as String
- **Raises**: `ArgumentError`, `KoreFileFormat::CompressionError`
### `KoreFileFormat.compress_with_level(data, level = :balanced)`
Compresses data with specified compression level.
- **Parameters**:
- `data`: Input data (String or Bytes)
- `level`: Compression level (`:fast`, `:balanced`, `:maximum`)
- **Returns**: Compressed data as String
- **Raises**: `ArgumentError`, `KoreFileFormat::CompressionError`
### `KoreFileFormat.decompress(data)`
Decompresses KORE-compressed data.
- **Parameters**:
- `data`: Compressed data (String or Bytes)
- **Returns**: Decompressed data as String
- **Raises**: `ArgumentError`, `KoreFileFormat::CompressionError`
## Requirements
- Native library: `libkore_fileformat.so` (Linux), `libkore_fileformat.dylib` (macOS), `kore_fileformat.dll` (Windows)
- FFI gem (automatically installed as dependency)
- Ruby 2.7 or later
## Performance
- **Throughput**: 19.1 GB/s (verified)
- **Compression Ratio**: 42.1% (adaptive)
- **Metadata Latency**: <1ms
- **Supported Ruby**: 2.7, 3.0, 3.1, 3.2+
## Status
**v1.2.1** - Production Release
- ✅ Full FFI bindings
- ✅ 3 compression levels
- ✅ Cross-platform support
- ✅ Comprehensive test coverage
## Development
```bash
# Run tests in development
bundle exec rspec spec/ --verbose
# Run specific test file
bundle exec rspec spec/kore_fileformat_spec.rb
```
## Support
For issues, questions, or contributions, visit: https://github.com/arunkatherashala/Kore