HWPJS

    CLI 사용 가이드

    @ohah/hwpjs는 명령줄 인터페이스(CLI)를 제공하여 HWP 파일을 변환하고 처리할 수 있습니다.

    설치

    전역 설치

    npm install -g @ohah/hwpjs

    설치 후 hwpjs 명령어를 어디서나 사용할 수 있습니다.

    npx 사용 (전역 설치 없이)

    npx @ohah/hwpjs <command>

    기본 사용법

    도움말 보기

    hwpjs --help

    특정 명령어의 도움말을 보려면:

    hwpjs to-json --help
hwpjs to-markdown --help

    명령어

    to-json - JSON 변환

    HWP 파일을 JSON 형식으로 변환합니다.

    # stdout으로 출력
hwpjs to-json document.hwp

# 파일로 저장
hwpjs to-json document.hwp -o output.json

# Pretty print
hwpjs to-json document.hwp -o output.json --pretty

    옵션:

    • -o, --output <file>: 출력 파일 경로 (기본값: stdout)
    • --pretty: JSON을 포맷팅하여 출력

    to-markdown - Markdown 변환

    HWP 파일을 Markdown 형식으로 변환합니다.

    # 기본 변환
hwpjs to-markdown document.hwp -o output.md

# 이미지 포함 (base64)
hwpjs to-markdown document.hwp -o output.md --include-images

# HTML 태그 사용
hwpjs to-markdown document.hwp -o output.md --use-html

# 버전 정보 포함
hwpjs to-markdown document.hwp -o output.md --include-version

# 페이지 정보 포함
hwpjs to-markdown document.hwp -o output.md --include-page-info

    옵션:

    • -o, --output <file>: 출력 파일 경로 (기본값: stdout)
    • --include-images: 이미지를 base64 데이터 URI로 포함
    • --use-html: HTML 태그 사용 (테이블 등 개행 불가 영역에 <br> 사용)
    • --include-version: 버전 정보 포함
    • --include-page-info: 페이지 정보 포함

    to-html - HTML 변환

    HWP 파일을 HTML 형식으로 변환합니다.

    # 기본 변환 (이미지는 base64로 임베드)
hwpjs to-html document.hwp -o output.html

# 이미지를 별도 파일로 저장
hwpjs to-html document.hwp -o output.html --images-dir images

# 버전 정보 포함
hwpjs to-html document.hwp -o output.html --include-version

# 페이지 정보 포함
hwpjs to-html document.hwp -o output.html --include-page-info

    옵션:

    • -o, --output <file>: 출력 파일 경로 (기본값: stdout)
    • --images-dir <dir>: 이미지를 저장할 디렉토리 (지정하지 않으면 base64로 임베드)
    • --include-version: 버전 정보 포함
    • --include-page-info: 페이지 정보 포함

    특징:

    • 기본적으로 이미지는 base64 데이터 URI로 HTML에 임베드됩니다
    • --images-dir 옵션을 사용하면 이미지를 별도 파일로 저장하고 상대 경로로 참조합니다
    • 완전한 HTML 문서 (<html>, <head>, <body> 포함)를 생성합니다
    • CSS 클래스 기반 스타일링을 사용합니다

    info - 파일 정보

    HWP 파일의 기본 정보를 확인합니다.

    # 기본 정보 출력
hwpjs info document.hwp

# JSON 형식으로 출력
hwpjs info document.hwp --json

    출력 정보:

    • 버전 (Version)
    • 압축 여부 (Compressed)
    • 암호화 여부 (Encrypted)
    • 이미지 개수 (Images)

    옵션:

    • --json: JSON 형식으로 출력

    extract-images - 이미지 추출

    HWP 파일에서 이미지를 추출합니다.

    # 모든 이미지 추출
hwpjs extract-images document.hwp -o ./images

# 특정 형식만 추출
hwpjs extract-images document.hwp -o ./images --format jpg
hwpjs extract-images document.hwp -o ./images --format png

    옵션:

    • -o, --output-dir <dir>: 출력 디렉토리 (기본값: ./images)
    • --format <format>: 이미지 형식 필터 (jpg, png, bmp, all) (기본값: all)

    출력:

    • 각 이미지는 image-{index}.{format} 형식으로 저장됩니다.
    • 예: image-0.jpg, image-1.png

    batch - 배치 변환

    디렉토리 내의 모든 HWP 파일을 일괄 변환합니다.

    # JSON 형식으로 변환
hwpjs batch ./documents -o ./output --format json

# Markdown 형식으로 변환
hwpjs batch ./documents -o ./output --format markdown

# 재귀적으로 하위 디렉토리 포함
hwpjs batch ./documents -o ./output --format json --recursive

# Pretty print JSON
hwpjs batch ./documents -o ./output --format json --pretty

# Markdown에 이미지 포함
hwpjs batch ./documents -o ./output --format markdown --include-images

# HTML 형식으로 변환 (이미지는 base64로 임베드)
hwpjs batch ./documents -o ./output --format html

# HTML 형식으로 변환 (이미지를 별도 파일로 저장)
hwpjs batch ./documents -o ./output --format html --images-dir images

    옵션:

    • -o, --output-dir <dir>: 출력 디렉토리 (기본값: ./output)
    • --format <format>: 출력 형식 (json, markdown, html) (기본값: json)
    • -r, --recursive: 하위 디렉토리 포함
    • --pretty: JSON 포맷팅 (json 형식만)
    • --include-images: 이미지 포함 (markdown 형식만)
    • --images-dir <dir>: 이미지를 저장할 디렉토리 (html 형식만, 기본값: images)

    출력:

    • 각 HWP 파일은 동일한 이름으로 변환된 파일이 생성됩니다.
    • 예: document.hwp → document.json 또는 document.md

    사용 예제

    예제 1: 단일 파일 변환

    # HWP 파일을 JSON으로 변환
hwpjs to-json report.hwp -o report.json --pretty

# HWP 파일을 Markdown으로 변환 (이미지 포함)
hwpjs to-markdown report.hwp -o report.md --include-images

# HWP 파일을 HTML로 변환 (이미지는 base64로 임베드)
hwpjs to-html report.hwp -o report.html

# HWP 파일을 HTML로 변환 (이미지를 별도 파일로 저장)
hwpjs to-html report.hwp -o report.html --images-dir images

    예제 2: 여러 파일 일괄 처리

    # documents 폴더의 모든 HWP 파일을 JSON으로 변환
hwpjs batch ./documents -o ./output --format json --recursive

# 변환된 파일 확인
ls ./output

    예제 3: 이미지 추출

    # HWP 파일에서 모든 이미지 추출
hwpjs extract-images presentation.hwp -o ./images

# JPG 이미지만 추출
hwpjs extract-images presentation.hwp -o ./images --format jpg

    예제 4: 파일 정보 확인

    # 파일 정보 확인
hwpjs info document.hwp

# JSON 형식으로 정보 확인 (스크립트에서 사용)
hwpjs info document.hwp --json | jq

    스크립트에서 사용

    CLI를 스크립트에서 사용할 수도 있습니다:

    Node.js
    #!/bin/bash

# 모든 HWP 파일을 JSON으로 변환
for file in *.hwp; do
  hwpjs to-json "$file" -o "${file%.hwp}.json" --pretty
done
    // Node.js 스크립트
const { execSync } = require('child_process');

try {
  // HWP 파일 정보 가져오기
  const info = JSON.parse(
    execSync('hwpjs info document.hwp --json', { encoding: 'utf-8' })
  );
  
  console.log(`Version: ${info.version}`);
  console.log(`Images: ${info.imageCount}`);
} catch (error) {
  console.error('오류:', error);
}

    문제 해결

    명령어를 찾을 수 없음

    전역 설치가 되어 있지 않은 경우:

    # 전역 설치
npm install -g @ohah/hwpjs

# 또는 npx 사용
npx @ohah/hwpjs <command>

    참고사항

    • CLI는 Node.js 환경에서만 작동합니다.
    • 모든 명령어는 --help 옵션으로 상세한 도움말을 볼 수 있습니다.
    • 출력 파일이 이미 존재하는 경우 덮어씌워집니다.
    • 배치 변환 시 오류가 발생한 파일은 스킵되고 계속 진행됩니다.