hwarang 0.1.0

data/Cargo.toml

@@ -0,0 +1,6 @@
+[workspace]
+members = ["ext/hwarang"]
+resolver = "2"
+
+[profile.release]
+strip = true

data/README.md

@@ -0,0 +1,115 @@
+# hwarang
+
+HWP/HWPX 문서에서 텍스트를 빠르게 추출하는 Ruby gem입니다.
+
+Rust로 작성된 [hwarang](https://crates.io/crates/hwarang) 크레이트의 Ruby 바인딩입니다.
+
+## 지원 포맷
+
+- **HWP** (OLE 바이너리) - 한/글 5.x 이상
+- **HWPX** (ZIP/XML) - 한/글 최신 XML 기반 포맷
+- **HWPML** (순수 XML)
+
+## 주요 기능
+
+- 매직 바이트 기반 포맷 자동 감지
+- 압축/비압축 스트림 모두 지원
+- 배포문서 복호화 (AES/ECB)
+- 표를 마크다운 테이블로 변환
+- 머리글/꼬리글, 각주/미주, 글상자, 숨은설명 추출
+- rayon 기반 병렬 배치 처리
+
+## 설치
+
+```ruby
+gem install hwarang
+```
+
+또는 Gemfile에 추가:
+
+```ruby
+gem "hwarang"
+```
+
+주요 플랫폼(x86_64-linux, aarch64-linux, arm64-darwin)에는 프리컴파일된 네이티브 gem이 제공됩니다. 그 외 플랫폼에서는 소스 gem이 설치되며 Rust 툴체인이 필요합니다.
+
+## 사용법
+
+### 텍스트 추출
+
+```ruby
+require "hwarang"
+
+text = Hwarang.extract_text("document.hwp")
+puts text
+```
+
+### OLE 스트림 목록
+
+```ruby
+streams = Hwarang.list_streams("document.hwp")
+# => ["/FileHeader", "/BodyText/Section0", ...]
+```
+
+### 배치 처리
+
+여러 파일을 병렬로 처리합니다:
+
+```ruby
+paths = Dir.glob("documents/**/*.hwp")
+results = Hwarang.extract_batch(paths)
+
+results.each do |path, result|
+  if result.key?("text")
+    puts "#{path}: #{result["text"].length} chars"
+  else
+    puts "#{path}: ERROR - #{result["error"]}"
+  end
+end
+```
+
+## 에러 처리
+
+모든 예외는 `Hwarang::Error`를 상속합니다:
+
+```ruby
+begin
+  Hwarang.extract_text("file.hwp")
+rescue Hwarang::PasswordProtectedError
+  puts "암호가 걸린 문서입니다"
+rescue Hwarang::FileError => e
+  puts "파일 오류: #{e.message}"
+rescue Hwarang::Error => e
+  puts "처리 오류: #{e.message}"
+end
+```
+
+| 예외 클래스 | 설명 |
+|-------------|------|
+| `Hwarang::Error` | 기본 예외 클래스 |
+| `Hwarang::FileError` | 파일 I/O 오류 |
+| `Hwarang::InvalidSignatureError` | HWP 파일 시그니처 불일치 |
+| `Hwarang::UnsupportedVersionError` | 지원하지 않는 HWP 버전 |
+| `Hwarang::PasswordProtectedError` | 암호 보호된 문서 |
+| `Hwarang::StreamNotFoundError` | OLE 스트림 없음 |
+| `Hwarang::InvalidRecordHeaderError` | 레코드 헤더 파싱 실패 |
+| `Hwarang::DecompressFailedError` | 스트림 압축 해제 실패 |
+| `Hwarang::DecryptFailedError` | 복호화 실패 |
+| `Hwarang::ParseError` | 일반 파싱 오류 |
+| `Hwarang::UnsupportedFormatError` | 지원하지 않는 파일 형식 |
+| `Hwarang::HwpxError` | HWPX 처리 오류 |
+
+## 벤치마크
+
+| 항목 | 결과 |
+|------|------|
+| 파일 수 | 49,353개 (HWP/HWPX) |
+| 총 용량 | 1.0 GB |
+| 소요 시간 | 43.27초 |
+| 처리 속도 | 1,140 files/s |
+| 성공률 | 99.94% (49,321/49,353) |
+| 환경 | Apple M1, 16GB RAM, 8코어, Ruby 4.0 |
+
+## License
+
+MIT

data/ext/hwarang/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "hwarang-ruby"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[lib]
+name = "hwarang"
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+hwarang_core = { package = "hwarang", version = "0.1.0", default-features = false }
+rayon = "1"

data/ext/hwarang/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("hwarang/hwarang")

data/ext/hwarang/src/lib.rs

@@ -0,0 +1,147 @@
+use std::path::Path;
+
+use magnus::class::Class;
+use magnus::value::{InnerRef, Lazy, ReprValue};
+use magnus::{function, prelude::*, Error, ExceptionClass, RHash, Ruby};
+use rayon::prelude::*;
+
+macro_rules! define_lazy_error {
+    ($static_name:ident, $ruby_name:expr, $parent:expr) => {
+        static $static_name: Lazy<ExceptionClass> = Lazy::new(|ruby| {
+            let parent = $parent.get_inner_ref_with(&ruby);
+            let module = ruby.define_module("Hwarang").unwrap();
+            let cls = module
+                .define_class($ruby_name, parent.as_r_class())
+                .unwrap();
+            ExceptionClass::from_value(cls.as_value()).unwrap()
+        });
+    };
+}
+
+static HWARANG_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
+    let module = ruby.define_module("Hwarang").unwrap();
+    let cls = module
+        .define_class("Error", ruby.exception_standard_error().as_r_class())
+        .unwrap();
+    ExceptionClass::from_value(cls.as_value()).unwrap()
+});
+
+define_lazy_error!(FILE_ERROR, "FileError", HWARANG_ERROR);
+define_lazy_error!(
+    INVALID_SIGNATURE_ERROR,
+    "InvalidSignatureError",
+    HWARANG_ERROR
+);
+define_lazy_error!(
+    UNSUPPORTED_VERSION_ERROR,
+    "UnsupportedVersionError",
+    HWARANG_ERROR
+);
+define_lazy_error!(
+    PASSWORD_PROTECTED_ERROR,
+    "PasswordProtectedError",
+    HWARANG_ERROR
+);
+define_lazy_error!(
+    STREAM_NOT_FOUND_ERROR,
+    "StreamNotFoundError",
+    HWARANG_ERROR
+);
+define_lazy_error!(
+    INVALID_RECORD_HEADER_ERROR,
+    "InvalidRecordHeaderError",
+    HWARANG_ERROR
+);
+define_lazy_error!(
+    DECOMPRESS_FAILED_ERROR,
+    "DecompressFailedError",
+    HWARANG_ERROR
+);
+define_lazy_error!(DECRYPT_FAILED_ERROR, "DecryptFailedError", HWARANG_ERROR);
+define_lazy_error!(PARSE_ERROR, "ParseError", HWARANG_ERROR);
+define_lazy_error!(
+    UNSUPPORTED_FORMAT_ERROR,
+    "UnsupportedFormatError",
+    HWARANG_ERROR
+);
+define_lazy_error!(HWPX_ERROR, "HwpxError", HWARANG_ERROR);
+
+fn hwp_error_to_magnus(ruby: &Ruby, err: hwarang_core::error::HwpError) -> Error {
+    use hwarang_core::error::HwpError;
+    let msg = err.to_string();
+    let cls = match &err {
+        HwpError::Io(_) => *FILE_ERROR.get_inner_ref_with(ruby),
+        HwpError::InvalidSignature => *INVALID_SIGNATURE_ERROR.get_inner_ref_with(ruby),
+        HwpError::UnsupportedVersion(..) => *UNSUPPORTED_VERSION_ERROR.get_inner_ref_with(ruby),
+        HwpError::PasswordProtected => *PASSWORD_PROTECTED_ERROR.get_inner_ref_with(ruby),
+        HwpError::StreamNotFound(_) => *STREAM_NOT_FOUND_ERROR.get_inner_ref_with(ruby),
+        HwpError::InvalidRecordHeader => *INVALID_RECORD_HEADER_ERROR.get_inner_ref_with(ruby),
+        HwpError::DecompressFailed(_) => *DECOMPRESS_FAILED_ERROR.get_inner_ref_with(ruby),
+        HwpError::DecryptFailed(_) => *DECRYPT_FAILED_ERROR.get_inner_ref_with(ruby),
+        HwpError::Parse(_) => *PARSE_ERROR.get_inner_ref_with(ruby),
+        HwpError::UnsupportedFormat => *UNSUPPORTED_FORMAT_ERROR.get_inner_ref_with(ruby),
+        HwpError::Hwpx(_) => *HWPX_ERROR.get_inner_ref_with(ruby),
+    };
+    Error::new(cls, msg)
+}
+
+fn extract_text(ruby: &Ruby, path: String) -> Result<String, Error> {
+    hwarang_core::extract_text_from_file(Path::new(&path)).map_err(|e| hwp_error_to_magnus(ruby, e))
+}
+
+fn list_streams(ruby: &Ruby, path: String) -> Result<Vec<String>, Error> {
+    hwarang_core::list_streams(Path::new(&path)).map_err(|e| hwp_error_to_magnus(ruby, e))
+}
+
+fn extract_batch(ruby: &Ruby, paths: Vec<String>) -> Result<RHash, Error> {
+    let results: Vec<(String, Result<String, String>)> = paths
+        .par_iter()
+        .map(|p| {
+            let result = hwarang_core::extract_text_from_file(Path::new(p));
+            match result {
+                Ok(text) => (p.clone(), Ok(text)),
+                Err(e) => (p.clone(), Err(e.to_string())),
+            }
+        })
+        .collect();
+
+    let hash = ruby.hash_new();
+    for (path, result) in results {
+        let inner = ruby.hash_new();
+        match result {
+            Ok(text) => {
+                inner.aset(ruby.str_new("text"), ruby.str_new(&text))?;
+            }
+            Err(msg) => {
+                inner.aset(ruby.str_new("error"), ruby.str_new(&msg))?;
+            }
+        }
+        hash.aset(ruby.str_new(&path), inner)?;
+    }
+    Ok(hash)
+}
+
+#[magnus::init(name = "hwarang")]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Hwarang")?;
+
+    // Force-initialize all error classes
+    Lazy::force(&HWARANG_ERROR, ruby);
+    Lazy::force(&FILE_ERROR, ruby);
+    Lazy::force(&INVALID_SIGNATURE_ERROR, ruby);
+    Lazy::force(&UNSUPPORTED_VERSION_ERROR, ruby);
+    Lazy::force(&PASSWORD_PROTECTED_ERROR, ruby);
+    Lazy::force(&STREAM_NOT_FOUND_ERROR, ruby);
+    Lazy::force(&INVALID_RECORD_HEADER_ERROR, ruby);
+    Lazy::force(&DECOMPRESS_FAILED_ERROR, ruby);
+    Lazy::force(&DECRYPT_FAILED_ERROR, ruby);
+    Lazy::force(&PARSE_ERROR, ruby);
+    Lazy::force(&UNSUPPORTED_FORMAT_ERROR, ruby);
+    Lazy::force(&HWPX_ERROR, ruby);
+
+    module.define_module_function("extract_text", function!(extract_text, 1))?;
+    module.define_module_function("list_streams", function!(list_streams, 1))?;
+    module.define_module_function("extract_batch", function!(extract_batch, 1))?;
+
+    Ok(())
+}

data/lib/hwarang/version.rb

@@ -0,0 +1,3 @@
+module Hwarang
+  VERSION = "0.1.0"
+end

data/lib/hwarang.rb

@@ -0,0 +1,7 @@
+require_relative "hwarang/version"
+
+begin
+  require "hwarang/#{RUBY_VERSION.to_f}/hwarang"
+rescue LoadError
+  require "hwarang/hwarang"
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: hwarang
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lee Wonsup
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby bindings for the hwarang Rust library. Extracts text from HWP and
+  HWPX documents.
+email: onesup.lee@gmail.com
+executables: []
+extensions:
+- ext/hwarang/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- README.md
+- ext/hwarang/Cargo.toml
+- ext/hwarang/extconf.rb
+- ext/hwarang/src/lib.rs
+- lib/hwarang.rb
+- lib/hwarang/version.rb
+homepage: https://github.com/teammilestone/hwarang-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Fast HWP/HWPX document text extractor
+test_files: []