README

sc_anydoc

English README

firecrawl/anydoc 을 Windows DLL(C ABI) 로 감싸고, Delphi 에서 바로 쓸 수 있게 만든 래퍼.

Word / PowerPoint / Excel / OpenDocument / RTF / EPUB / CSV / PDF 를 GitHub Flavored Markdown 으로 변환한다.

anydoc 이란

Firecrawl 이 Rust 로 만든 문서 변환 라이브러리다. MIT 라이선스.

?????? ????????? ??? ?????? ?????? ??? ????????? ?????? ??? ?????? ?????? ?????? ??? GFM ?????????????????? ??? ????????????

포맷마다 파서가 따로 있지만 모두 하나의 공용 문서 모델로 수렴한 뒤 단일 시리얼라이저를 거친다. 그래서 어떤 포맷을 넣든 출력 마크다운의 스타일이 일관된다.

Office 설치가 필요 없다. COM 자동화도, 백그라운드 Word 프로세스도 없이 바이트를 직접 파싱한다.

왜 이 래퍼를 만들었나

anydoc 은 Node.js / Python / WebAssembly 바인딩은 제공하지만 C ABI 바인딩이 없다. Delphi 를 비롯한 네이티브 언어에서 부를 방법이 없다는 뜻이다. 이 프로젝트가 그 빈자리를 메운다.

Windows 데스크톱 앱에서 문서를 텍스트로 뽑아내려면 보통 이런 선택지가 있는데, 각각 문제가 있다.

anydoc 은 이미 이 문제를 잘 푼 라이브러리이고, Rust 라 cdylib 로 빌드하면 그대로 DLL 이 된다. 얇은 C ABI 계층만 얹으면 Delphi 에서 함수 호출 한 번으로 끝난다. 외부 프로세스도, 임시 파일도, Office 설치도 필요 없다.

설계할 때 지킨 것

업스트림을 포크하지 않는다. anydoc 은 활발히 업데이트되는 프로젝트다. 포크하거나 소스를 벤더링하면 업스트림을 따라가는 일이 곧 유지보수 부담이 된다. 그래서 crates.io 의 크레이트를 의존성으로만 참조한다. 새 버전 반영이 cargo update 한 줄로 끝난다.

업스트림이 바뀌어도 래퍼가 깨지지 않게 한다. 아래 네 가지를 미리 처리해 뒀다.

32비트도 같이 지원한다. 확인해 보니 extern "C" export 이름에 32비트에서도 데코레이션이 붙지 않아, Delphi 선언 한 벌로 Win32/Win64 를 모두 커버할 수 있었다. NativeUInt 도 Rust usize 와 자동으로 폭이 맞는다.

요구 사항

DLL 빌드

.\build_anydoc.ps1                  # Win64
.\build_anydoc.ps1 -Platform Win32
.\build_anydoc.ps1 -Platform All    # 양쪽 순차 빌드

빌드 → ABI 검증 → 배포 순으로 진행하며, 검증에 실패하면 기존 DLL 을 덮어쓰지 않고 멈춘다.

배포 위치

64?????? : C:\Works\lib\dll\sc_anydoc.dll
32?????? : C:\Works\lib\dll\win32\sc_anydoc.dll     ??? ?????????, ????????? ??????

32비트 프로세스는 64비트 DLL 을 로드할 수 없으므로 폴더로 분리한다. 이름이 같아 Delphi 선언을 플랫폼별로 나눌 필요가 없다.

빌드 결과

VC++ 재배포 패키지가 필요 없다. .cargo\config.toml 에 CRT 정적 링크(+crt-static)를 고정해 두어 VCRUNTIME140.dll 과 UCRT 의존이 사라진다. DLL 파일 하나만 복사하면 끝이다.

검증만 따로 실행

.\verify_dll.ps1 -Platform Win64
.\verify_dll.ps1 -Platform Win32   # 32비트 PowerShell 로 자동 재실행된다

포인터 폭, 포맷 감지, 한글 UTF-8 왕복, 확장자 힌트 폴백, 오류 경로, 반복 변환/해제 300회를 확인한다.

업스트림 반영

.\update_upstream.ps1          # 최신 버전 확인만 (아무것도 바꾸지 않음)
.\update_upstream.ps1 -Apply   # cargo update + 32/64 재빌드 + 검증 + 배포

업스트림이 0.2.x 처럼 Cargo.toml 의 허용 범위를 벗어나면 자동 반영을 거부하고 안내만 출력한다. 이때는 릴리스 노트를 확인하고 Cargo.toml 의 버전을 직접 올린 뒤 다시 실행한다.

Delphi 에서 사용

delphi\src\SCAnydoc.pas 를 프로젝트에 추가한다. DLL 은 실행 파일 옆에 두거나 배포 폴더를 PATH 에 넣는다.

uses
  SCAnydoc;

// 1) 파일 변환 — 파일 읽기를 델파이가 담당하므로 유니코드 경로에 안전하다
var LMarkdown := TSCAnydoc.ToMarkdownFile('C:\docs\보고서.docx');

// 2) 메모리 변환 — CSV 는 시그니처가 없어 확장자 힌트가 필수
var LMarkdown := TSCAnydoc.ToMarkdown(LBytes, 'csv');

// 3) 포맷만 감지 ('docx', 'pdf', 'excel' ... 실패 시 빈 문자열)
var LFormat := TSCAnydoc.DetectFormat(LBytes);

// 4) DLL 가용성 확인 (예외를 던지지 않는다)
if not TSCAnydoc.IsAvailable then
begin
  ShowMessage('sc_anydoc.dll 을 찾을 수 없습니다.');
end;

오류 처리

실패는 EAnydocError 로 올라온다. Status 로 원인을 구분하고, Detail 에는 코어가 준 원본(영문) 메시지가 담긴다.

try
  LMarkdown := TSCAnydoc.ToMarkdownFile(LFileName);
except
  on E: EAnydocError do
  begin
    if E.Status = asEncrypted then
    begin
      TSCLog.Instance.Warn('암호화 문서 건너뜀: ' + LFileName, 'DOC');
    end
    else
    begin
      TSCLog.Instance.Error(E.Message, 'DOC');
      raise;
    end;
  end;
end;

스레드

변환은 동기 blocking 이다. 큰 문서에서 UI 가 멈추므로, UI 프로젝트에서는 워커 스레드에서 호출하고 결과만 TThread.Queue 로 메인 스레드에 넘긴다.

TThread.CreateAnonymousThread(
  procedure
  var
    LMarkdown: string;   // 익명 메서드가 캡처하므로 var 블록에 선언
  begin
    LMarkdown := TSCAnydoc.ToMarkdown(LBytes, LExt);
    TThread.Queue(nil,
      procedure
      begin
        memResult.Lines.Text := LMarkdown;
      end);
  end).Start;

DLL 은 전역 상태를 두지 않아 여러 스레드에서 동시에 호출해도 안전하다.

VCL 데모

delphi\demo\ 에 표준 VCL 샘플이 있다. UI 는 영문이다.

cd delphi\demo
.\build_demo.ps1 -Run                  # Win64 빌드 후 실행
.\build_demo.ps1 -Platform Win32

sc_anydoc.dll 을 실행 파일 옆에 함께 복사하므로 PATH 설정 없이 실행된다. IDE 에서 열려면 AnydocDemo.dpr 을 File > Open Project 로 열면 .dproj 가 자동 생성된다.

데모가 보여주는 것:

• 문서 열기 / 창으로 드래그 앤 드롭(WM_DROPFILES) / 실행 파일에 문서를 떨어뜨려 실행
• 변환을 워커 스레드에서 수행하고 UI 갱신만 TThread.Queue 로 위임
• FormCloseQuery 로 변환 중 종료 차단 — Queue 로 넘긴 코드가 해제된 폼을 건드리는 AV 방지
• EAnydocError.Status / Detail 로 실패 원인 표시
• 상태바에 포맷·소요 시간·코어 버전 표시, 결과를 UTF-8 .md 로 저장 (UTF-8 BOM 체크박스로 BOM 유무 선택, 기본은 BOM 없음)
• Preview 탭에서 TEdgeBrowser(WebView2) 로 마크다운 렌더링 — 아래 참조
• PerMonitorV2 DPI 매니페스트 포함

마크다운 프리뷰

Preview.pas 가 TEdgeBrowser 를 프리뷰어로 운전한다. 마크다운 → HTML 변환은 marked 가 담당하며, sc_anydoc.dll 과 C ABI 는 이 기능에 관여하지 않는다.

• 셸 페이지는 한 번만 로드한다. preview.html 에 marked.min.js 를 통째로 인라인해(둘 다 RCDATA 리소스) NavigateToString 으로 띄운 뒤, 이후 마크다운은 PostWebMessageAsString 으로 원문 그대로 넘긴다 — 재탐색도 JS 문자열 이스케이프도 없다
• 초기화는 Preview 탭을 처음 열 때까지 지연된다. 프리뷰를 쓰지 않으면 WebView2 생성 비용을 전혀 치르지 않는다
• 소스가 바뀌면 dirty 로만 표시하고, 실제 렌더는 탭이 보일 때 한 번에 한다
• CSP 로 외부 리소스를 차단한다. 인라인 스크립트·스타일과 https 이미지만 허용
• 문서 안의 링크는 WebView 안에서 열지 않고 ShellExecute 로 기본 브라우저에 넘긴다
• WebView2 런타임이 없으면 프리뷰 탭에 사유를 표시하고 변환·저장 기능은 그대로 동작한다. 런타임은 시스템에 설치되는 구성요소이며 exe 옆에 복사하는 파일이 아니다

build_demo.ps1 은 sc_anydoc.dll 과 함께 아키텍처에 맞는 WebView2Loader.dll(webview2\x64 / webview2\x86)을 실행 파일 옆에 복사한다. 다만 Delphi 13 은 loader 를 실행 파일에 정적 링크하므로 데모가 이 DLL 을 실제로 로드하지는 않는다 — 배포 묶음의 완결성을 위해 함께 둘 뿐이다.

C ABI

Delphi 외의 언어에서 쓸 때 참고. 모든 함수가 cdecl(extern "C") 이며, 32비트에서도 export 이름에 데코레이션이 붙지 않아 Win32/Win64 선언이 동일하다.

상태 코드

규약

• 출력 문자열은 UTF-8, 길이가 함께 반환된다. NUL 종단도 붙지만 길이 사용을 권장한다
• anydoc_free 에는 함께 받은 길이를 그대로 넘긴다. Rust 할당자가 해제하므로 호출 측에서 free/FreeMem 하면 안 된다
• 모든 진입점이 catch_unwind 로 감싸여 있어 Rust 패닉이 FFI 경계를 넘지 않는다
• format_hint 는 확장자 문자열("docx", ".pdf", "csv"). 점은 있어도 없어도 된다. 포맷은 내용 감지를 먼저 시도하고 실패 시 힌트로 폴백하므로, 시그니처가 없는 CSV 는 힌트가 필수다
• 파일 경로를 넘기는 API 는 일부러 두지 않았다. 호출 측이 바이트를 읽어 넘기면 Windows 유니코드 경로 인코딩 문제가 아예 발생하지 않는다

알려진 제약

• PDF 는 문서 모델(to_document)을 지원하지 않는다 (업스트림 제약). 마크다운 변환만 가능하며, 스캔본/이미지 PDF 는 OCR 이 필요해 Unsupported 로 떨어진다. PDF 변환 품질은 업스트림이 쓰는 pdf-inspector 수준에 종속되므로, 실사용 샘플로 확인해 보는 것이 좋다
• Win32 메모리 한계 — 문서 전체를 메모리에 올려 파싱한다. 32비트 프로세스의 주소 공간(기본 2GB) 안에서 수백 MB 급 문서는 실패할 수 있다. 해당 시나리오가 있으면 호출 측에서 입력 크기 상한을 두는 편이 안전하다
• 업스트림 to_document(문서 모델 트리)는 C ABI 로 노출하지 않았다. 필요하면 JSON 직렬화 형태로 추가할 수 있다

구성

Cargo.toml                crates.io ??? anydoc ??? ??????????????? ?????? (????????????????? ??????)
.cargo\config.toml        ????????? CRT ?????? ?????? ??????
build.rs                  Cargo.lock ??? ?????? ????????? DLL ??? ??????
src\lib.rs                C ABI ??????
build_anydoc.ps1          ?????? ??? ?????? ??? ??????
verify_dll.ps1            ABI ?????? (32????????? ?????? ?????????)
update_upstream.ps1       ???????????? ?????? ??? ??????
delphi\src\SCAnydoc.pas   Delphi ?????????
delphi\demo\              VCL ?????? (dpr/pas/dfm/manifest/rc + build_demo.ps1)
  Preview.pas             TEdgeBrowser ??? ???????????? ???????????? ?????????
  preview.html            ????????? ??? ????????? (RCDATA)
  marked.min.js           ???????????? ????????? (RCDATA, MIT)
  webview2\x64|x86\       WebView2Loader.dll (?????? ??? exe ????????? ??????)

라이선스

MIT — LICENSE 참조.

업스트림 anydoc 크레이트도 MIT 다. 이 프로젝트가 만든 바이너리에 정적으로 링크되므로, 재배포할 때 해당 고지를 유지한다 — THIRD-PARTY-NOTICES.md 참조.