Skip to content
PDF Oxide

Ruby API 레퍼런스

PDF Oxide는 cdylib C ABI 위의 FFI로 구축된 네이티브 Ruby 바인딩(gem pdf_oxide)을 제공합니다. 이 gem은 사전 빌드된 네이티브 라이브러리를 함께 담고 있으며, Java 바인딩의 9개 클래스 구조를 PdfOxide 네임스페이스 아래에서 그대로 반영합니다.

gem install pdf_oxide

require 'pdf_oxide'

Rust API는 Rust API 레퍼런스를, Python API는 Python API 레퍼런스를 참고하세요. 타입에 대한 자세한 내용은 타입 및 열거형을 확인하세요.

핸들을 소유하는 모든 객체(PdfDocument, Pdf, DocumentEditor)는 네이티브 메모리를 소유하므로 반드시 닫아야 합니다. 가장 관용적인 방식은 자동으로 닫히는 블록 형태이며, #close는 멱등(idempotent)합니다.

PdfOxide (모듈)

최상위 편의 진입점과 프로세스 전역 토글을 제공합니다.

PdfOxide.open(source, password: nil) { |doc| ... } -> PdfDocument

읽기용으로 PDF를 엽니다. PdfDocument.open에 위임합니다. 파일 경로나 원시 PDF 바이트를 받으며, 블록 형태는 자동으로 닫힙니다.

PdfOxide.version -> String

라이브러리 버전 문자열을 반환합니다(예: "0.3.69").

PdfOxide.set_max_ops_per_stream(limit) -> Integer

프로세스 전역의 콘텐츠 스트림 연산자 상한을 설정합니다. 음수 limit은 기본값(1,000,000)을 복원하고, 0 이상의 값은 명시적 상한이 됩니다. 이전 상한을 반환합니다.

PdfOxide.set_preserve_unmapped_glyphs(preserve) -> Integer

텍스트 추출에서 사용하는 프로세스 전역 U+FFFD(매핑되지 않은 글리프) 보존 플래그를 토글합니다. truthy/0이 아닌 값은 보존하고, falsey/0은 필터링합니다(기본값). 이전 값(0 또는 1)을 반환합니다.

PdfDocument

추출, 검색, 변환, 렌더링, 페이지 접근을 담당하는 PDF의 주요 읽기 전용 진입점입니다.

doc = PdfOxide::PdfDocument.open('invoice.pdf')

생성자 및 클래스 메서드

PdfOxide::PdfDocument.open(source, password: nil) { |doc| ... } -> PdfDocument

파일 시스템 경로나 원시 PDF 바이트(바이너리 입력의 %PDF- 매직으로 자동 감지)에서 PDF를 엽니다. 블록 형태는 자동으로 닫히고, 블록이 없는 형태는 문서를 반환합니다. FileNotFoundError, ParseError, EncryptedError를 발생시킵니다.

PdfOxide::PdfDocument.new(source, password: nil) -> PdfDocument

블록 없이 직접 생성합니다. .open 사용을 권장합니다.

PdfOxide::PdfDocument.extract_text(source, page: 0) -> String

원샷 헬퍼: 열기, 단일 페이지의 텍스트 추출, 닫기를 한 번에 수행합니다.

문서 정보

doc.page_count -> Integer

문서의 페이지 수입니다.

doc.pdf_version -> String

PDF 버전 문자열(예: "1.7")이며, 알 수 없으면 "unknown"을 반환합니다.

doc.encrypted? -> Boolean

PDF가 암호화 딕셔너리를 갖고 있는지 여부입니다.

doc.path -> String

문서를 연 절대 경로입니다(바이트로 연 문서의 경우 <in-memory>).

인증

doc.authenticate(password) -> Boolean

이 문서의 암호화에 대해 인증합니다. 성공하거나 암호화되지 않은 문서의 경우 true를 반환합니다.

텍스트 추출

doc.extract_text(page_index) -> String

0부터 시작하는 단일 페이지에서 일반 텍스트를 추출합니다(텍스트 레이어가 없는 페이지는 빈 문자열).

doc.extract_structured(page) -> Hash

페이지의 구조화된 표현을 Hash로 추출합니다. page_index, page_width, page_height, 그리고 regions(각각 kind, text, bbox, spans, column_index 포함)를 담고 있습니다.

doc.extract_text_auto(page_index) -> String

자동 라우팅 추출: 텍스트가 있는 곳은 네이티브 텍스트를, 스캔된 영역은 ocr 기능이 있을 때 OCR을 사용하며, 네이티브 폴백으로 자연스럽게 처리합니다("OCR unavailable"을 절대 발생시키지 않습니다).

변환

doc.to_markdown(page_index = nil) -> String

한 페이지를 Markdown으로 변환하거나, page_index가 nil이면 문서 전체를 변환합니다.

doc.to_html(page_index = nil) -> String

한 페이지를 HTML로 변환하거나, page_index가 nil이면 문서 전체를 변환합니다.

검색

doc.search(query, case_sensitive: false, regex: false) -> Array<Hash>

문서를 검색합니다. 각 매치는 { page:, text:, bbox: { x:, y:, width:, height: } } 형태입니다. regex: true를 전달하면 query를 정규식으로 해석합니다(빌드에 정규식 검색이 없으면 UnsupportedFeatureError를 발생시킵니다).

폼

doc.form_fields -> Array<Hash>

AcroForm 필드를 { name:, value:, type:, page: } 해시로 반환합니다. 빌드에 폼 추출 접근자가 없으면 []을 반환합니다.

렌더링

doc.render(page_index, dpi: 150) -> String

지정한 DPI로 단일 페이지를 PNG 바이트(BINARY)로 렌더링합니다.

doc.render_with_layers(page_index, dpi: 150, format: 0,
                       background: [1.0, 1.0, 1.0, 1.0], transparent: false,
                       render_annotations: true, jpeg_quality: 90,
                       excluded_layers: []) -> String

전체 RenderOptions 표면과 Optional-Content-Group(OCG) 레이어 필터링을 함께 사용하여 페이지를 렌더링합니다. format: 0 = PNG, 1 = JPEG이며, excluded_layers는 숨길 OCG /Name 목록입니다. 인코딩된 이미지 바이트(BINARY)를 반환합니다.

페이지 접근

doc.page(index) -> PdfPage

index 위치 페이지의 가벼운 PdfPage 뷰입니다.

doc.pages -> Array<PdfPage>

문서의 모든 페이지입니다(즉시 평가).

자동 추출

doc.auto_extractor -> AutoExtractor

이 문서에 대해 구성된 AutoExtractor입니다(메모이즈됨).

수명 주기

doc.close -> nil

네이티브 핸들을 해제합니다. 멱등합니다.

doc.open? -> Boolean
doc.closed? -> Boolean

문서가 아직 열려 있는지 / 이미 닫혔는지 여부입니다.

PdfPage

PdfDocument에서 빌려온 가벼운 페이지별 뷰입니다. 자체 네이티브 핸들을 갖지 않습니다. PdfDocument#page 또는 #pages로 생성합니다.

page = doc.page(0)

속성

page.parent -> PdfDocument
page.index -> Integer

소유 문서와 0부터 시작하는 페이지 인덱스입니다.

기하 정보

page.width -> Float
page.height -> Float

PDF 사용자 공간 단위의 페이지 너비와 높이입니다.

page.media_box -> Hash
page.crop_box -> Hash

미디어 박스 / 크롭 박스에 대한 { x:, y:, width:, height: }입니다(크롭 박스는 미디어 박스로 폴백).

page.rotation -> Integer

페이지 회전 각도(도 단위)입니다.

텍스트

page.text -> String

이 페이지의 텍스트를 추출합니다(parent.extract_text(index)와 동일).

page.to_s -> String
page.inspect -> String

짧은 검사 레이블(#<PdfOxide::PdfPage index=N>)입니다.

Pdf

PDF를 생성하고 저장합니다: Markdown/HTML/텍스트/이미지 소스, 바이트 내보내기, 북마크 기반 분할 계획.

pdf = PdfOxide::Pdf.from_markdown("# Title\n\nBody")

팩토리 메서드

PdfOxide::Pdf.from_markdown(markdown) { |pdf| ... } -> Pdf

Markdown으로부터 PDF를 만듭니다.

PdfOxide::Pdf.from_html(html) { |pdf| ... } -> Pdf

HTML로부터 PDF를 만듭니다(html_css 파이프라인을 통해 CSS 반영).

PdfOxide::Pdf.from_text(text) { |pdf| ... } -> Pdf

일반 텍스트로부터 PDF를 만듭니다.

PdfOxide::Pdf.from_images(images) { |pdf| ... } -> Pdf

JPEG/PNG 바이트 블롭 배열로부터 PDF를 만듭니다(매직 바이트로 포맷 자동 감지).

PdfOxide::Pdf.create_empty { |pdf| ... } -> Pdf

빈 단일 페이지 PDF를 생성합니다.

정적 헬퍼

PdfOxide::Pdf.version -> String

라이브러리 버전입니다.

PdfOxide::Pdf.prefetch_models(languages) -> String

지정한 BCP-47/ISO 언어 태그에 대해 OCR 모델을 미리 가져옵니다. 캐시 디렉터리 경로를 반환합니다(OCR이 없는 빌드에서는 빈 문자열).

PdfOxide::Pdf.prefetch_available? -> Boolean

빌드가 OCR 모델 프로비저닝을 지원하는지 여부입니다.

PdfOxide::Pdf.plan_split_by_bookmarks_count(source_pdf, level) -> Integer

source_pdf(원시 바이트)를 level(1 = 최상위, 0 = 전체)에서 분할할 때 생성될 북마크 분할 세그먼트 수를 출력 없이 계산합니다.

인스턴스 메서드

pdf.to_bytes -> String

PDF를 BINARY로 인코딩된 바이트로 반환합니다.

pdf.save(path) -> String

PDF를 path에 기록합니다. 기록된 절대 경로를 반환합니다.

pdf.close -> nil
pdf.closed? -> Boolean

네이티브 핸들을 해제합니다(멱등) / 닫혔는지 여부입니다.

DocumentEditor

쓰기 측 에디터: 파괴적 redaction, 메타데이터 정리(scrub), 폼 채우기, 증분 저장을 수행합니다. 모든 redaction 작업은 실패 시 안전하게 차단됩니다(0이 아닌 반환값은 예외를 발생시킴).

PdfOxide::DocumentEditor.open('source.pdf') do |ed|
  ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
  ed.apply_redactions!
  ed.save_to('redacted.pdf')
end

생성자

PdfOxide::DocumentEditor.open(source) { |ed| ... } -> DocumentEditor

디스크상의 PDF 또는 메모리상의 바이트에 대해 에디터를 엽니다. 블록 형태는 자동으로 닫힙니다.

PdfOxide::DocumentEditor.new(source) -> DocumentEditor

블록 없이 직접 생성합니다.

Redaction

ed.add_redaction(page:, rect:, color: [0.0, 0.0, 0.0]) -> self

redaction 사각형을 큐에 넣습니다(rect = PDF 사용자 공간의 [x1, y1, x2, y2], color = [r, g, b]). apply_redactions!를 호출하기 전까지는 적용되지 않습니다.

ed.redaction_count(page) -> Integer

해당 페이지에 큐에 들어간 총 redaction 수입니다.

ed.apply_redactions!(scrub_metadata: false, fill_color: [0.0, 0.0, 0.0]) -> self

큐에 들어간 모든 redaction을 파괴적으로 적용하며, 선택적으로 /Info, XMP, JS를 정리합니다.

ed.scrub_metadata -> self

redaction 영역 없이 메타데이터만 제거합니다.

폼

ed.set_form_field(name, value) -> self

점으로 구분된 전체 이름으로 AcroForm 필드를 설정합니다. Boolean value는 체크박스/라디오를 대상으로 하고, 그 외에는 텍스트 값을 설정합니다.

저장 및 수명 주기

ed.save_to(path) -> String

편집한 PDF를 저장합니다. 기록된 절대 경로를 반환합니다.

ed.to_bytes -> String

편집한 PDF를 BINARY로 인코딩된 바이트로 반환합니다.

ed.close -> nil
ed.closed? -> Boolean

네이티브 핸들을 해제합니다(멱등) / 닫혔는지 여부입니다.

AutoExtractor

타입화된 이유(reason)를 제공하는 자동 추출(텍스트 대 OCR 라우팅, 네이티브 폴백 포함)입니다. PdfDocument로부터 생성합니다.

ax = PdfOxide::AutoExtractor.new(doc)
result = ax.extract_page(0)
warn "degraded: #{result[:reason]}" unless ax.ok?(result[:reason])

생성자 및 속성

PdfOxide::AutoExtractor.new(document) -> AutoExtractor

자동 추출을 위해 PdfDocument를 감쌉니다.

ax.document -> PdfDocument

감싼 문서입니다.

분류

ax.classify_page(page_index) -> Hash

저렴한 페이지별 분류기입니다(OCR/래스터화 없음). { reason:, kind:, confidence:, classification: }를 반환합니다.

ax.classify_document -> Hash

문서 전체 분류기이며, 디코딩된 JSON 엔벨로프를 반환합니다.

추출

ax.extract_text(page_index) -> Hash

자동 라우터를 통해 페이지의 텍스트를 추출합니다. { text:, reason:, kind:, confidence:, classification: }를 반환합니다.

ax.extract_page(page_index, options: nil) -> Hash

전체 PageExtraction 엔벨로프(텍스트 + 영역별 bbox + reason + confidence)를 Hash로 병합하여 반환하는 풍부한 페이지별 추출입니다.

술어(Predicate)

ax.ok?(reason) -> Boolean

reason이 깨끗한 추출을 나타내는지 여부입니다.

ax.ocr_fallback?(reason) -> Boolean

OCR 사용 불가에 따른 자연스러운 폴백 경로가 작동했는지 여부입니다.

PdfOxide::AutoExtractor.prefetch_available? -> Boolean

빌드가 OCR 프로비저닝을 지원하는지 여부입니다.

상수

AutoExtractor::REASONS — 타입화된 이유 심볼의 frozen 배열(:ok, :native_text_high_confidence, :no_text_layer_present, :ocr_requested_but_unavailable 등)입니다. AutoExtractor::PAGE_KINDS — 페이지 종류 심볼(:text_layer, :scanned, :image_text, :mixed, :empty)입니다.

MarkdownConverter

PdfDocument를 Markdown 또는 HTML로 변환하는 상태 비저장(stateless) 모듈입니다.

PdfOxide::MarkdownConverter.to_markdown(doc, page_index = nil) -> String

페이지(또는 page_index가 nil이면 문서 전체)를 Markdown으로 변환합니다.

PdfOxide::MarkdownConverter.to_html(doc, page_index = nil) -> String

페이지(또는 문서 전체)를 HTML로 변환합니다.

PdfPolicy

한 번만 설정 가능한(set-once) 의미를 가진 프로세스 전역 암호 거버넌스 정책입니다. 다른 모든 PDF Oxide 작업 이전에 .set을 호출하세요.

PdfOxide::PdfPolicy.current -> Symbol

현재 프로세스 정책 모드(:compat, :strict, :fips_strict)입니다.

PdfOxide::PdfPolicy.set(mode) -> Symbol

프로세스 전역 정책 모드를 설정합니다. 이미 설정되었거나 빌드가 지원하지 않으면 예외를 발생시킵니다.

PdfOxide::PdfPolicy.compat -> Symbol
PdfOxide::PdfPolicy.strict -> Symbol
PdfOxide::PdfPolicy.fips_strict -> Symbol

프리셋 모드 심볼: 모든 알고리즘 허용 / 레거시 알고리즘 거부 / FIPS 140-3 전용입니다.

PdfPolicy::MODES — 모드 심볼을 cdylib 서수(ordinal)로 매핑하는 frozen 매핑입니다.

PdfSigner

PAdES B-B / B-T / B-LT / B-LTA 디지털 서명 서명기입니다. 서명은 보안 작업이므로, 0이 아닌 모든 반환값은 실패 시 안전하게 차단됩니다.

PdfOxide::PdfSigner.new(certificate_handle) -> PdfSigner

불투명한 PKCS#12/PEM 자격 증명 핸들로부터 서명기를 생성합니다.

signer.sign(pdf, level:, tsa_url: nil, reason: nil, location: nil) -> String

요청한 PAdES 레벨(:b, :t, :lt, :lta)로 원시 PDF 바이트에 서명합니다. :t 이상의 레벨에는 tsa_url이 필요합니다. BINARY로 인코딩된 서명된 PDF 바이트를 반환합니다.

PdfOxide::PdfSigner.sign(pdf:, certificate_handle:, level:, tsa_url: nil, reason: nil, location: nil) -> String

정적 편의 메서드: 서명기 인스턴스를 생성하지 않고 서명합니다.

PdfOxide::PdfSigner.pades_level(signature_handle) -> Integer

기존 서명 핸들의 PAdES 레벨 서수입니다.

PdfOxide::PdfSigner.document_has_timestamp?(document_handle) -> Boolean

문서가 문서 범위의 /DocTimeStamp를 갖고 있는지 여부입니다.

PdfSigner::LEVELS — 레벨 심볼을 코드로 매핑하는 frozen 매핑입니다. PdfSigner::PadesSignOptions — C의 PadesSignOptionsC 레이아웃을 반영하는 패킹된 FFI::Struct입니다.

PdfValidator

상태 비저장 PDF/A 및 PDF/UA 준수 검증입니다.

PdfOxide::PdfValidator.pdf_a?(doc, level: :a1b) -> Boolean

문서가 level(:a1b, :a1a, :a2b, :a2a, :a2u, :a3b, :a3a, :a3u)에 대해 PDF/A를 준수하는지 여부입니다.

PdfOxide::PdfValidator.pdf_ua?(doc, level: :ua1) -> Boolean

문서가 level(:ua1 또는 :ua2)에 대해 PDF/UA를 준수하는지 여부입니다.

PdfOxide::PdfValidator.validate_pdf_a(doc, level: :a1b) -> Hash

간소화된 PDF/A 결과: { compliant:, violations: }입니다.

PdfOxide::PdfValidator.validate_pdf_ua(doc, level: :ua1) -> Hash

간소화된 PDF/UA 결과: { compliant:, violations: }입니다.

PdfValidator::PDF_A_LEVELS와 PdfValidator::PDF_UA_LEVELS — 레벨을 서수로 매핑하는 frozen 매핑입니다.

오류 처리

모든 PDF Oxide 예외는 PdfOxide::Error에서 파생됩니다. 네이티브 오류 코드는 아래 하위 클래스와 1대1로 매핑됩니다.

begin
  doc = PdfOxide::PdfDocument.open('file.pdf')
  text = doc.extract_text(0)
rescue PdfOxide::FileNotFoundError
  warn 'file not found'
rescue PdfOxide::ParseError => e
  warn "malformed PDF: #{e.message}"
rescue PdfOxide::Error => e
  warn "PDF error: #{e.message}"
ensure
  doc&.close
end
예외 원인
Error 모든 PDF Oxide 오류의 기반 클래스
UnsupportedPlatformError 함께 제공된 cdylib가 지원하지 않는 호스트 플랫폼
ArgumentError 네이티브 호출 전에 인수 검증 실패
IoError 파일 시스템 / I/O 실패
FileNotFoundError 파일 없음(IoError의 특수화)
ParseError 잘못된 헤더, 손상된 xref, 추출 실패
StateError 잘못된 작업 순서
InvalidStateError 이미 닫힌 핸들에 대한 작업(StateError의 특수화)
EncryptedError 암호화 / 잘못된 비밀번호 실패
PermissionError 추출/서명 권한이 없는 암호화된 PDF
UnsupportedFeatureError 이 cdylib 빌드에 컴파일되지 않은 기능
SignatureError PAdES 서명 / 검증 실패
RedactionError 파괴적 redaction 실패(실패 시 안전하게 차단)
ComplianceError PDF/A · PDF/UA 검증 실패
SearchError 네이티브 텍스트 검색 실패
InternalError 일반적인 네이티브 측 실패

전체 예제

require 'pdf_oxide'

# --- Extraction ---
PdfOxide::PdfDocument.open('input.pdf') do |doc|
  puts "Pages: #{doc.page_count}"
  doc.page_count.times do |i|
    puts "Page #{i + 1}: #{doc.extract_text(i).length} characters"
  end

  # Search
  doc.search('configuration', case_sensitive: false).each do |m|
    puts "Page #{m[:page] + 1}: '#{m[:text]}' at (#{m[:bbox][:x]}, #{m[:bbox][:y]})"
  end

  # Render page 1 to PNG
  File.binwrite('page1.png', doc.render(0, dpi: 150))
end

# --- Creation ---
PdfOxide::Pdf.from_markdown("# Report\n\nGenerated by PDF Oxide.") do |pdf|
  pdf.save('report.pdf')
end

# --- Redaction ---
PdfOxide::DocumentEditor.open('source.pdf') do |ed|
  ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
  ed.apply_redactions!(scrub_metadata: true)
  ed.save_to('redacted.pdf')
end

# --- Validation ---
PdfOxide::PdfDocument.open('archive.pdf') do |doc|
  puts "PDF/A-1b compliant: #{PdfOxide::PdfValidator.pdf_a?(doc, level: :a1b)}"
end

Other Language Bindings

PDF Oxide는 모든 주요 생태계를 위한 네이티브 바인딩을 제공합니다: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir

다음 단계