CLI 레퍼런스
hwpforge(Hammer)는 HwpForge의 명령줄 도구입니다. 이 장은 hwpforge --help와 hwpforge <명령> --help가 보여 주는 23개 명령을 정리합니다. 플래그 이름과 기본값은 clap 정의(crates/hwpforge-bindings-cli/src/main.rs)를 그대로 옮겼으므로, 버전이 올라 의심스러우면 --help가 우선입니다.
설치
hwpforge-bindings-cli는 crates.io에 배포하지 않으므로(publish = false) git 또는 로컬 경로에서 설치합니다. hwpforge-smithy-pdf(krilla) 의존 때문에 워크스페이스 MSRV(1.89)보다 높은 Rust 1.92 이상이 필요합니다(rust-version = "1.92").
cargo install --git https://github.com/ai-screams/HwpForge hwpforge-bindings-cli
# 또는 clone 후 로컬 경로에서
git clone https://github.com/ai-screams/HwpForge && cd HwpForge
cargo install --path crates/hwpforge-bindings-cli
설치되는 바이너리 이름은 hwpforge입니다([[bin]] name = "hwpforge").
전역 옵션
| 옵션 | 설명 |
|---|---|
--json | 결과를 machine-readable JSON으로 출력합니다 |
-h, --help | 도움말 |
-V, --version | 버전 |
--json은 모든 명령이 받습니다. 에이전트가 결과를 파싱할 때는 이 플래그를 붙이세요.
명령 한눈에 보기
--help는 HWP5·PDF 명령을 먼저 나열하고 그 뒤에 HWPX 명령을 나열합니다. 아래 표는 용도별로 다시 묶었습니다.
| 용도 | 명령 |
|---|---|
| HWP5 · PDF | audit-hwp5, census-hwp5, convert-hwp5, to-pdf |
| 만들기 · 변환 | convert, to-json, from-json, to-md |
| 읽기 · 검사 | inspect, outline, fields, read, diff, validate |
| 편집 | fill, set-cell, patch, insert-para, delete-para, stamp-plan, stamp |
| 부가 | templates, schema |
HWP 입력과 HWPX 출력
다음 14개 명령은 HWPX와 HWP5(.hwp) 입력을 받습니다. HWP5는 메모리에서 HWPX로 변환한 뒤 기존 연산에 전달합니다. 확장자가 아니라 내용으로 판별하며, 정상 ZIP으로 열리는 접두사 HWPX는 그대로 처리합니다.
| 용도 | 명령 |
|---|---|
| 읽기·검사 | inspect, outline, read, fields, to-md, to-json, validate, diff(양쪽 입력), stamp-plan |
| 편집 | fill, set-cell, insert-para, delete-para, stamp |
편집 문서 결과는 **.hwpx**입니다. .hwp 저장은 지원하지 않으며, 편집 5개 명령은 .hwp 출력 확장자를 대소문자 구분 없이 INVALID_EXTENSION으로 거부합니다. 읽기 명령의 JSON·Markdown 출력 형식은 그대로입니다.
hwpforge inspect form.hwp --json
hwpforge fill form.hwp --set name=홍길동 -o form.filled.hwpx --json
변환 손실 정책
읽기 명령은 변환 경고를 보고합니다. 편집 5개 명령은 의미 손실이 있으면 쓰기 전에 HWP5_CONVERSION_LOSS로 거부합니다. 거부된 경고를 확인한 뒤 --accept-conversion-loss로 변환 손실을 명시적으로 허용합니다. 이 옵션은 편집 자체의 admission 검사나 인코드 의미 손실 거부(ENCODE_SEMANTIC_LOSS)를 해제하지 않습니다.
글꼴 분류 정보(style.font.type_info)와 메모 모양 정의(header.memo_shape_definition)의 생략은 정책상 비손실이며 경고는 남습니다. 시각적으로 차이가 없다는 보장은 아닙니다. 조판 캐시 생략도 의미 손실 거부 대상이 아닙니다. 개요 번호 모양 참조(section.outlineShapeIDRef), 변경 추적 정의, 중첩 구역 설정, 언어별 장평, 자동 간격과 미분류 경고는 손실로 취급합니다.
변환 메타데이터
HWP5_CONVERSION_LOSS의 JSON details.warnings는 거부된 경고만 담으며, 각 항목은 stage, code, message와 선택적인 location을 갖습니다. 성공 JSON은 기존 warnings의 형과 내용을 유지하고, HWP5 입력일 때만 별도 conversion: {source_format: "hwp5", warnings: [...]}를 더합니다. 변환 경고가 없어도 conversion.warnings는 빈 배열입니다.
diff는 conversion.base·conversion.revised에 변환된 입력의 메타데이터만 담습니다. diff -o 보고서 본문과 to-json·to-md의 문서 본문에는 변환 메타데이터를 섞지 않습니다. 사람용 모드는 표준 오류로 변환 사실과 경고를 알리고, --json 모드는 결과 메타데이터로 전달합니다.
HWP 원본 보호
HWP5 입력을 자동 변환한 경우, 이미 있는 출력 파일이 입력과 같은 파일이면 INVALID_OUTPUT_PATH(종료 1)로 쓰기 전에 거부합니다. 편집 5개 명령의 문서 출력과 stamp의 manifest뿐 아니라 diff -o(양쪽 입력), to-json -o, to-md의 Markdown·추출 이미지 출력에도 적용합니다. 상대·절대 경로, 심볼릭 링크, 하드 링크와 대소문자를 구분하지 않는 파일 시스템의 별칭도 파일 정체성으로 비교합니다.
아직 없는 출력은 이 비교로 거부하지 않습니다. 정체성 확인 실패는 FILE_WRITE_FAILED이며 insert-para·delete-para는 종료 2, 나머지 자동 변환 대상 명령은 종료 1입니다. HWPX 입력의 제자리 편집은 계속 허용합니다. 실행 도중 다른 프로세스가 경로를 바꾸는 경우는 보호 범위에 포함하지 않습니다.
자동 변환 제외 경로
CLI from-json --base·patch, Python from_json(base=...)·patch·restyle과 MCP의 문서 입력(restyle 포함)은 HWP5를 자동 변환하지 않으며 HWP5_INPUT으로 거부합니다. 이 경로에는 convert-hwp5 또는 Python convert_hwp5로 명시적으로 변환한 HWPX를 전달합니다. Python의 지원 연산과 저장 보호는 Python 입력 정책을 참고합니다.
자동 변환 도입은 오류 코드 계약의 breaking change입니다. 대상 명령의 HWP5 입력은 기존 HWP5_INPUT 대신 변환 결과 또는 HWP5_DECODE_FAILED, HWP5_CONVERT_FAILED, VALIDATION_FAILED, ENCODE_FAILED를 반환합니다. 변환 실패는 기존 연산의 인자 검사보다 먼저이며, 변환 손실 거부는 기존 편집 검사 다음이면서 쓰기 전입니다. 기존 코드의 명령별 종료 값은 유지합니다(set-cell의 validation/encode 오류는 1, 나머지 변환 오류는 2). .hwp 출력 거부도 기존 동작의 변경입니다.
HWP5 · PDF
convert-hwp5
HWP5(.hwp)를 HWPX로 변환합니다.
hwpforge convert-hwp5 [OPTIONS] --output <OUTPUT> <INPUT>
| 옵션 | 설명 |
|---|---|
-o, --output | 출력 HWPX 경로(필수) |
--no-layout-cache | HWP5의 조판 캐시(PARA_LINE_SEG)를 싣지 않습니다. 줄 나눔은 여는 쪽이 다시 계산합니다 |
기본값은 조판 캐시를 HWPX <hp:linesegarray>로 싣습니다. 그래서 결과가 원본의 줄 나눔 자리를 담고 to-pdf의 렌더 대상이 됩니다. 줄 시작 자리를 정확히 옮길 수 없는 문단(차트, 알 수 없는 컨트롤, 경계로 가를 수 없는 줄 시작)은 잘못된 데이터를 싣는 대신 LAYOUT_CACHE_DROPPED 경고와 함께 캐시를 버립니다. 예전 옵션 --carry-layout-cache는 계속 받지만 기본값과 같은 출력을 내며, --no-layout-cache와 함께 줄 수 없습니다.
to-pdf
HWPX 또는 HWP5 문서를 조판 캐시 재생 방식으로 PDF로 렌더합니다. 입력 형식은 확장자가 아니라 내용으로 판별합니다.
hwpforge to-pdf [OPTIONS] <INPUT>
| 옵션 | 설명 |
|---|---|
-o, --output | 출력 PDF 경로(기본값: 입력 경로의 확장자를 .pdf로 바꾼 것) |
--font-dir <FONT_DIRS> | 폰트를 찾을 디렉터리(반복 가능) |
--discovery <DISCOVERY> | 폰트 자동 탐색: explicit(결정적, 기본값) | hancom | platform |
--degraded | 렌더 실패를 오류 대신 경고로 낮춥니다. 없는 스타일·축 폰트는 regular로 그리고, 렌더할 수 없는 이미지는 건너뜁니다 |
--partial-cache-reject | 조판 캐시가 없는 문단이 하나라도 있으면 문서를 거부합니다(기본값: 경고 후 그 문단을 건너뜀) |
조판 캐시가 있는 문서만 렌더할 수 있습니다. convert나 --base 없는 from-json이 새로 만든 문서에는 캐시가 없어 거부됩니다. from-json --base는 믿을 수 있는 바뀌지 않은 캐시만 이어받습니다.
audit-hwp5
HWP5 원본과 변환된 HWPX 결과의 구조·의미 동등성을 점검합니다. 픽셀 단위 시각·쪽 나눔 동등성은 보장하지 않으며, 후속 시각 검증용 체크리스트를 보고서에 담습니다.
hwpforge audit-hwp5 [OPTIONS] <SOURCE> <RESULT>
<SOURCE>는 원본 .hwp, <RESULT>는 변환된 .hwpx입니다.
census-hwp5
HWP5 파일(과 선택적 HWPX 짝 파일)의 원시 fixture census를 만듭니다.
hwpforge census-hwp5 [OPTIONS] <INPUT>
| 옵션 | 설명 |
|---|---|
--companion <COMPANION> | 중첩 XML·경로 census용 HWPX 짝 fixture(선택) |
-o, --output | census 데이터셋을 JSON으로 저장할 경로(선택) |
만들기 · 변환
convert
Markdown을 HWPX로 변환합니다.
hwpforge convert [OPTIONS] --output <OUTPUT> <INPUT>
| 옵션 | 설명 |
|---|---|
<INPUT> | Markdown 파일. -를 주면 stdin에서 읽습니다 |
-o, --output | 출력 HWPX 경로(필수) |
--preset <PRESET> | 스타일 프리셋 이름(기본값: default) |
사용 가능한 프리셋은 templates list로 확인합니다.
to-json
HWPX 또는 HWP5를 편집 가능한 JSON으로 내보냅니다.
hwpforge to-json [OPTIONS] --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
-o, --output | 출력 JSON 경로(필수, stdout 내보내기는 없습니다) |
--section <SECTION> | 특정 섹션만 추출(0부터 시작하는 인덱스) |
--no-styles | 스타일 정보를 제외합니다 |
--section 없이 내보낸 문서 전체 JSON은 from-json이, --section N으로 내보낸 섹션 JSON은 patch가 읽습니다. 두 JSON은 서로 다른 형식입니다.
두 JSON 모두 맨 위에 "format_version": 3 를 쓰고, 문단 여백 다섯 가지(margin_left, margin_right, indent, spacing_before, spacing_after)와 탭 위치(position)를 단위와 값으로 씁니다. hwpunit 은 1/100 pt, char 는 1/500 글자입니다.
"margin_left": { "unit": "hwpunit", "value": 2000 },
"indent": { "unit": "char", "value": -1000 }
from-json 과 patch 는 이전 판이 쓴 버전 없는 JSON 을 이렇게 다룹니다.
- 탭 위치가 하나라도 있으면
LEGACY_JSON_TABS로 거부합니다. 옛 JSON 에는 탭 단위가 남아 있지 않아 추측하지 않습니다. - 탭 위치가 없으면 문단 여백을 옛 표현에서 풀어 읽고
LEGACY_PARAGRAPH_MEASURES경고를 냅니다. 옛 JSON 이 이미 잃은 단위는 되살리지 못합니다. - 명시 v2는 문단 style_id를 정의 배열 위치로 해석해 v3로 이행합니다. 그 밖의 버전 번호나 정수가 아닌
format_version은 거부합니다.
어느 경우든 원본 HWPX 또는 HWP5 에서 새 판의 to-json 을 다시 실행하는 것이 가장 정확합니다.
스타일 글자 모양의 그림자는 0.17.0 부터 shadow 객체로 나옵니다(이전 키 shadow_type 은 종류만 담았습니다).
"shadow": { "kind": "Continuous", "color": "#123456", "offset_x": -3, "offset_y": 4 }
color 는 "#RRGGBB" 또는 "none" 입니다. 이전 판이 쓴 "shadow_type": "Drop" JSON 도 from-json 이 읽고, 이때 색·간격은 기본값 #C0C0C0·10·10 이 됩니다(이전 출력 #B2B2B2 보다 밝음).
from-json
JSON을 HWPX로 되돌립니다.
hwpforge from-json [OPTIONS] --output <OUTPUT> <INPUT>
| 옵션 | 설명 |
|---|---|
-o, --output | 출력 HWPX 경로(필수) |
--base <BASE> | 이미지를 물려받을 기준 HWPX(왕복 충실도용) |
to-md
HWPX 또는 HWP5를 Markdown으로 변환합니다.
hwpforge to-md [OPTIONS] <INPUT>
| 옵션 | 설명 |
|---|---|
-o, --output | 출력 디렉터리(기본값: 입력과 같은 디렉터리) |
--mode <MODE> | styled(기본값, 스타일을 따르고 이미지 포함) | lossy(스타일 정보 없는 읽기용) | lossless(보존 범위를 확인하는 기계용 보기. 보존 범위의 보존 목록은 보존, 거부 목록에 든 개체가 있으면 오류, 그 밖의 값은 빠질 수 있음. 프론트매터에 metadata.format: lossless 가 붙고 convert 는 이 출력을 MD_DECODE_FAILED 로 거부하므로, 왕복 편집에는 to-json/from-json 을 사용) |
읽기 · 검사
inspect
HWPX 또는 HWP5 문서를 디코드한 구조를 보여 줍니다. HWP5 입력의 변환 경고는 별도로 보고합니다.
hwpforge inspect [OPTIONS] <FILE>
| 옵션 | 설명 |
|---|---|
--styles | 스타일 상세(문자·문단 모양)를 포함합니다 |
outline
문서의 내비게이션 맵(제목, 표, 이름 있는 누름틀, 책갈피)을 보여 줍니다. 이름 앵커(제목 텍스트, 표 순번, 필드·책갈피 이름)가 1차 키이고 {section, para} 위치는 구조 편집 뒤에 낡을 수 있으므로, 읽기·편집 전에 한 번 받아 두는 용도입니다.
hwpforge outline [OPTIONS] <FILE>
fields
이름 있는 누름틀(click-here field)과 각각이 채울 수 있는 필드인지 나열합니다.
hwpforge fields [OPTIONS] <FILE>
read
문서 전체를 내보내지 않고 목표 하나만 텍스트로 읽습니다. 목표는 정확히 하나만 지정합니다.
hwpforge read [OPTIONS] <FILE>
| 옵션 | 설명 |
|---|---|
--section <SECTION> | 문단을 읽을 섹션 인덱스 |
--paras <PARAS> | 닫힌 문단 범위 "A..B" 또는 단일 "N"(--section 필요) |
--table <TABLE> | 표 순번. 논리 격자 텍스트 행렬로 읽습니다(병합 영역은 앵커에 한 번, span과 함께) |
--field <FIELD> | 이름 있는 누름틀 하나 |
텍스트가 아닌 내용(표, 이미지, 컨트롤)은 조용히 버려지지 않고 명시적인 표지로 드러납니다. 읽기 전용입니다.
diff
HWPX 또는 HWP5 입력 둘을 두 채널로 비교해 편집이 실제로 무엇을 바꿨는지 확인합니다.
hwpforge diff [OPTIONS] <BASE> <REVISED>
| 옵션 | 설명 |
|---|---|
-o, --output | 전체 JSON 보고서를 이 경로에도 씁니다 |
semantic 채널은 디코드한 Core 구조를 필드 값, 표 셀 텍스트 {table, row, col}, 문단 텍스트 {section, para}, 구조 개수, 상한이 있는 미분류 잔여로 분류합니다. package 채널은 ZIP 엔트리를 바이트로 비교합니다. 바뀐 엔트리 안의 wire 내용(예: hp:linesegarray 조판 캐시)은 항목별로 나열하지 않으며 보고서가 그렇게 밝힙니다. fill·set-cell·stamp·patch 뒤에 돌려 의도한 변경만 반영됐는지 확인하세요.
validate
HWPX 또는 HWP5가 디코드되고 Core의 구조 불변식(Document::validate)을 만족하는지 편집 없이 검사합니다.
hwpforge validate [OPTIONS] <FILE>
종료 코드는 --help에 다음과 같이 정의돼 있습니다.
| 종료 코드 | 의미 |
|---|---|
| 0 | 문서가 유효합니다 |
| 1 | 파일을 읽을 수 없음(없거나 읽을 수 없거나 크기 상한을 넘는 파일) |
| 2 | 명령행 인자가 잘못됐거나 디코드·HWP5 변환에 실패합니다 |
| 3 | 디코드는 되지만 검증에 실패합니다(오류가 아니라 판정이며, --json 출력의 errors를 보세요). 파서는 통과하고 Core 중첩 깊이가 32를 넘는 문서는 디코드에서 거부되므로 3이 아니라 DECODE_FAILED(종료 2)입니다 |
인자를 잘못 준 경우(필수 인자 누락, 알 수 없는 옵션)는 clap이 종료 코드 2로 끝냅니다. 아래 오류 계약은 다른 명령의 종료 정책도 함께 설명합니다.
편집
fill·set-cell·insert-para·delete-para·stamp는 HWP5 입력의 의미 손실을 기본 거부합니다. 공통 옵션 --accept-conversion-loss는 변환 손실만 허용하며 편집 문서 출력은 .hwpx입니다. 자세한 내용은 입력 정책을 참고합니다.
fill·set-cell·insert-para·delete-para·stamp·patch는 결과를 -o로 지정한 출력 경로에 씁니다(필수 옵션). stamp-plan은 파일을 쓰지 않으므로 -o가 없습니다. 편집 뒤에는 diff로 변경 범위를 확인하세요.
fill
이름 있는 누름틀을 값으로 채웁니다. 기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기(Preview)를 지우고 PREVIEW_REMOVED 경고를 냅니다. 한컴에서 다시 저장하면 미리보기가 다시 만들어집니다. 내용이 같으면 원본 파일을 돌려줍니다. 머리글 정규화·스타일 정의 변경 등 문서 재인코드가 필요하거나 이전 형식의 문서 전체 JSON을 쓰는 경우는 이 보장 밖입니다.
hwpforge fill [OPTIONS] --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
--set <NAME=VALUE> | 채울 이름=값 쌍(반복 가능). 하나 이상 필수 |
-o, --output | 출력 HWPX 경로(필수) |
요청한 값을 모두 먼저 검증(알 수 없는·중복된·채울 수 없는 이름, 빈 값)하고, 하나라도 실패하면 아무것도 쓰지 않습니다. 누름틀이 들어 있는 서식 문서에서만 동작하므로 convert로 막 만든 문서에는 필드가 없습니다. 이름은 fields로 먼저 확인하세요.
set-cell
요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.
표 셀을 논리 격자 주소로 편집하며, batch는 전부 성공하거나 아무것도 쓰지 않습니다.
hwpforge set-cell [OPTIONS] --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
--table <TABLE> | 표 순번(문서 순서, 0부터). 단일 편집에는 필수(--map 일괄 편집에서는 쓰지 않음) |
--at <R,C> | 격자 좌표 "row,col"(덮인 위치는 병합 앵커로 해석) |
--right-of <LABEL> | 유일하게 라벨된 셀의 오른쪽 셀을 대상으로 합니다 |
--below <LABEL> | 유일하게 라벨된 셀의 아래쪽 셀을 대상으로 합니다 |
--text <TEXT> | 바꿀 텍스트(빈 문자열은 셀을 비웁니다). 단일 편집에는 필수 |
--map <MAP_JSON> | 일괄 편집용 명세 맵(CellSpec JSON 배열). 위 플래그들과 함께 쓸 수 없습니다 |
-o, --output | 출력 HWPX 경로(필수) |
patch
기존 HWPX의 섹션 하나를 교체합니다.
hwpforge patch [OPTIONS] --section <SECTION> --output <OUTPUT> <BASE> <SECTION_JSON>
<SECTION_JSON>은 to-json --section N으로 내보낸 섹션 JSON이며, <BASE>가 이미지와 나머지 패키지의 기준입니다. 문서 전체 JSON을 넣으면 스키마 불일치로 거부됩니다. 구조(문단 수)를 바꾸려면 insert-para·delete-para나 from-json을 쓰세요.
insert-para
기준 문단 앞이나 뒤에 새 최상위 문단을 삽입합니다. 관련 없는 내용을 유지하며, 영향을 받는 조판 캐시를 고칩니다. 한컴 저장 문서는 아래 사전 검사에서 거부됩니다.
hwpforge insert-para [OPTIONS] --section <SECTION> --anchor <ANCHOR> --text <TEXTS> --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
--section <SECTION> | 섹션 인덱스 |
--anchor <ANCHOR> | 기준 문단 인덱스(새 문단이 이 문단의 문단·문자 모양을 그대로 물려받습니다) |
--before | 기준 앞에 삽입합니다(기본값은 뒤) |
--text <TEXTS> | 새 문단의 한 줄 일반 텍스트. 반복하면 연속된 블록을 한 번의 검증된 편집으로 삽입합니다 |
-o, --output | 출력 HWPX 경로(필수) |
섹션의 첫 문단(secPr를 담은 문단) 앞 삽입은 거부됩니다. 왕복 안전한 입력만 편집할 수 있습니다.
delete-para
최상위 본문 문단을 인덱스로 삭제합니다. 전부 성공하거나 전부 취소됩니다. 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.
CONTENT_LOST는 입력을 Core로 읽을 때 표현하지 못한 정보가 있다는 경고입니다. 원문 보존 삭제는 그 정보가 출력 원문에 보존되고 삭제 판정에 영향을 주지 않음을 별도로 확인한 경우에만 성공하며, 입력 decode 경고는 순서와 횟수 그대로 남습니다. 이는 원문 XML에 정보가 남는 일부 손실(예: 언어별 글자 값)에만 해당하며, 그 밖의 CONTENT_LOST 입력은 기존 거부를 유지합니다. 전체 재인코드 편집의 입력 손실 거부는 유지됩니다.
hwpforge delete-para [OPTIONS] --section <SECTION> --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
--section <SECTION> | 섹션 인덱스 |
--index <INDICES>... | 삭제할 최상위 문단 인덱스(일괄 삭제는 반복). 하나 이상 필수 |
-o, --output | 출력 HWPX 경로(필수) |
참조(책갈피·상호참조·각주 등)를 담은 문단, 강제 쪽·단 나눔이 있는 문단, 섹션 속성(secPr)을 담은 첫 문단, 삭제하면 섹션이 비게 되는 경우는 거부합니다(fail-closed).
stamp-plan
산문 속 자리표시자(체크박스, 괄호 빈칸, 날짜 빈칸, 단독 @, 도장 토큰) 후보를 찾아 템플릿 스탬핑 계획을 만듭니다.
hwpforge stamp-plan [OPTIONS] <FILE>
출력의 각 후보에 {"field":{"name":"…"}} 또는 "ignore" 액션을 붙여 명세 맵을 만든 뒤 stamp --map을 실행합니다. 지침 문맥의 후보(guarded)는 자동 적용되지 않습니다.
stamp
명세 맵을 적용해 자리표시자를 이름 있는 누름틀로 승격합니다. 전부 성공하거나 전부 취소되며, 스탬프된 HWPX와 매니페스트를 씁니다.
hwpforge stamp [OPTIONS] --map <MAP_JSON> --output <OUTPUT> <FILE>
| 옵션 | 설명 |
|---|---|
--map <MAP_JSON> | StampSpec JSON 배열(필수) |
-o, --output | 출력 HWPX 경로(필수) |
--manifest <MANIFEST> | 매니페스트 JSON 경로(기본값: <output>.manifest.json) |
실패 시 아무것도 쓰지 않는 admission 게이트(무변경 왕복 + ZIP 닫힌 세계 검사) 뒤에서 동작하고, 결과물은 곧바로 fields·fill에 쓸 수 있습니다.
부가
templates
스타일 프리셋을 관리합니다. 하위 명령은 두 개입니다.
hwpforge templates list # 사용 가능한 프리셋 목록
hwpforge templates show <NAME> # 프리셋 상세
schema
문서·스타일 타입의 JSON Schema를 출력합니다.
hwpforge schema [OPTIONS] [TYPE_NAME]
TYPE_NAME은 document(기본값), exported-document, exported-section 중 하나입니다. exported-document가 to-json의 전체 JSON, exported-section이 --section JSON의 형식입니다.
다음 단계
- 같은 연산을 AI 도구에서 부르려면 MCP 서버 레퍼런스를 보세요.
- Python에서 부르려면 Python 가이드를 보세요.
0.18 오류 코드와 종료 상태
CLI JSON의 code, MCP 도구 오류의 code, Python HwpForgeError.code는 같은 실패 단계와 도메인 거부 사유에 같은 OpsCode 문자열을 사용합니다. 여러 결함이 있으면 실제로 먼저 실패한 검사로 분류하며, 메시지·힌트·응답 봉투까지 같다는 뜻은 아닙니다. 퇴역 별명과 옛 문자열 lookup은 제공하지 않습니다.
| 실패 단계·원인 | 코드 |
|---|---|
| 보류 명령의 HWPX 입력에 HWP5(.hwp)를 전달 | HWP5_INPUT (종료 2) |
| HWP5 변환의 의미 손실로 편집 거부 | HWP5_CONVERSION_LOSS (종료 1) |
편집 문서 출력이 .hwp | INVALID_EXTENSION (종료 1) |
편집 문서·manifest 또는 diff·to-json·to-md 출력이 HWP5 입력과 같은 파일 | INVALID_OUTPUT_PATH (종료 1) |
| 입력 HWPX / Markdown / HWP5 해석 | DECODE_FAILED / MD_DECODE_FAILED / HWP5_DECODE_FAILED |
| 편집 전 no-op 검증·인코드·재디코드 또는 의미 왕복 불일치 | INPUT_NOT_ROUNDTRIP_SAFE |
| 입력 ZIP 엔트리 미보존 | INPUT_ENTRIES_NOT_CARRIED |
| 명시적 문서 검증·메모리 문서 깊이 검사 | VALIDATION_FAILED |
| 출력 생성 / 의미 손실 때문에 출력 거부 | ENCODE_FAILED / ENCODE_SEMANTIC_LOSS |
| 생성 산출물 읽기·재디코드·대조 | SELF_VERIFY_FAILED |
| 보호 필드 침범 / 내부 불변식 파손 | PROTECTED_FIELD_RANGE / INTERNAL_INVARIANT |
| 보존 patch의 변경·metadata 거부 / fill 고유 거부 | PATCH_FAILED / FILL_FAILED |
| 아직 분류하지 않은 상류 variant | UPSTREAM_UNMAPPED |
HWP5_INPUT이면 먼저 hwpforge convert-hwp5 <in.hwp> -o <out.hwpx>로 변환하세요. 확장자가 아닌 내용으로 판정하며, ZIP으로 열리는 접두사 HWPX는 이 코드로 재분류하지 않습니다.
전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.
INPUT_NOT_ROUNDTRIP_SAFE는 현재 코덱으로 무변경 왕복을 확인하지 못했다는 뜻입니다. 원문을 보존하는 to-json --section N → patch, 누름틀 fill, 보존 가능한 한 문단·한 Text run 칸의 set-cell 경로를 검토하세요. 입력 바이트의 깊이 초과는 DECODE_FAILED이고, Rust Draft 셀 편집의 깊이 초과는 VALIDATION_FAILED입니다.
종료 상태는 (명령, 코드)로 결정합니다. 같은 명령·코드는 오류 payload나 발생 경로에 따라 달라지지 않습니다. 0은 성공이고, validate의 3은 디코드된 문서가 유효하지 않다는 판정입니다(Core 중첩 깊이 32 초과는 디코드 거부라 DECODE_FAILED입니다). 오류의 1·2만으로 원인을 구분하지 말고 code를 확인하세요.
| I/O 코드 | 종료 상태 |
|---|---|
FILE_NOT_FOUND, FILE_READ_FAILED | to-md·convert-hwp5는 2, 나머지는 1 |
INPUT_TOO_LARGE | 일반 파일 사전 검사·FIFO 모두 1 |
FILE_WRITE_FAILED | delete-para·insert-para·convert-hwp5는 2, 나머지는 1 |
0.18에서 바뀌는 종료 값은 다음 일곱 변경군입니다.
delete-para의 사전 validate·encode·재decode 실패도 INPUT_NOT_ROUNDTRIP_SAFE / 1입니다. 마지막 의미 왕복 비교 또는 ZIP carry 호출의 실패만 원문 보존 삭제를 시도하며, 그 시도에서 어느 검증이든 실패하면 원래 오류를 그대로 반환합니다.
| 명령·실패 | 이전 | 0.18 코드·종료 |
|---|---|---|
insert-para: no-op validate·encode·재decode | 2 | INPUT_NOT_ROUNDTRIP_SAFE / 1 |
stamp: no-op validate·encode·재decode | 2 | INPUT_NOT_ROUNDTRIP_SAFE / 1 |
set-cell: 입력 decode·원본 패키지 읽기 | 1 | DECODE_FAILED / 2 |
delete-para·insert-para: 출력 decode·생성 산출물 읽기·fragment 파싱 | 2 | SELF_VERIFY_FAILED / 1 |
to-md·convert-hwp5: 크기 한도를 넘는 FIFO 입력 | 2 | INPUT_TOO_LARGE / 1 |
convert-hwp5: 쓰기 성공 직후 stat 실패 | 1 | FILE_WRITE_FAILED / 2 |
validate: 파서는 통과하고 Core 중첩 깊이가 32를 넘는 HWPX | 3(판정) | DECODE_FAILED / 2 |
CLI 전용 INVALID_SET·DUPLICATE_SET과 진단용 네 코드는 유지합니다. 잘못된 명령행 문법은 기존 파서의 종료 2와 사용법 텍스트를 유지합니다. PDF의 cause.code는 별도 렌더러 코드 체계입니다.
이전 코드로 분기하던 소비자는 다음 이행표를 참고하세요. 아래 왼쪽 열은 과거 이름이며 0.18 출력이나 lookup 별명이 아닙니다.
| 이전 코드·용도 | 0.18 코드 |
|---|---|
DECODE_ERROR, HWPX_DECODE_FAILED | DECODE_FAILED |
ENCODE_ERROR | ENCODE_FAILED |
VALIDATION_ERROR, VALIDATE_FAILED | VALIDATION_FAILED |
MD_DECODE_ERROR, JSON_PARSE_ERROR | MD_DECODE_FAILED, JSON_PARSE_FAILED |
SERIALIZE_ERROR, STAMP_MANIFEST_SERIALIZE | JSON_SERIALIZE_FAILED |
UNKNOWN_PRESET | PRESET_NOT_FOUND |
STYLE_STORE_ERROR, STYLE_REBIND_ERROR | STYLE_STORE_FAILED, STYLE_REBIND_FAILED |
FILL_ERROR, 포괄 FILL_FAILED | 고유 fill 거부는 FILL_FAILED, 나머지는 실패 단계·patch·불변식 코드 |
PATCH_ERROR, 포괄 PATCH_FAILED | 보존 정책 거부는 PATCH_FAILED, 나머지는 실패 단계·보호 필드·불변식·구역 범위 코드 |
SET_CELL_CODEC_FAILED, STAMP_CODEC_FAILED, STRUCTURAL_CODEC | 해당 단계 코드, PROTECTED_FIELD_RANGE, INTERNAL_INVARIANT; 의미 손실은 ENCODE_SEMANTIC_LOSS |
READ_SECTION_OUT_OF_RANGE, READ_TABLE_OUT_OF_RANGE, READ_FIELD_NOT_FOUND | SECTION_OUT_OF_RANGE, TABLE_NOT_FOUND, FIELD_NOT_FOUND |
STAMP_DELTA_MISMATCH, STAMP_CELL_TARGET_DUPLICATE | SELF_VERIFY_FAILED, CELL_TARGET_DUPLICATE |
INDEX_OUT_OF_RANGE | SECTION_OUT_OF_RANGE 또는 PARAGRAPH_OUT_OF_RANGE |
UNCARRIED_ZIP_ENTRIES | INPUT_ENTRIES_NOT_CARRIED |
MCP 앞 삽입 거부의 SECTION_PROPERTIES_PARAGRAPH | INSERT_BEFORE_SECTION_PROPERTIES; 원래 구역 속성 문단 보호에는 기존 코드 유지 |
STRUCTURAL_EDIT_FAILED | 정밀 도메인 코드 또는 UPSTREAM_UNMAPPED |
SECTION_WORKFLOW_FAILED, SECTION_WORKFLOW_ERROR, SET_CELL_FAILED, STAMP_FAILED fallback | UPSTREAM_UNMAPPED |
포괄 HWP5_CONVERT_FAILED | decode는 HWP5_DECODE_FAILED, 직접 검증은 VALIDATION_FAILED, 출력 생성은 ENCODE_FAILED; layout replay는 기존 코드 유지 |
READ_ERROR, METADATA_ERROR, STDIN_READ_FAILED | FILE_READ_FAILED; 입력 부재는 FILE_NOT_FOUND |
WRITE_ERROR, DIR_CREATE_ERROR, DIR_CREATE_FAILED | 출력 I/O는 FILE_WRITE_FAILED, 출력 경로 정책은 INVALID_OUTPUT_PATH |
과거 로그의 포괄 코드는 당시 실패 단계를 모르면 새 코드 하나로 자동 변환할 수 없습니다.
MCP의 도구 필드 역직렬화 실패는 필드 경로를 메시지에 포함한 INVALID_PARAMS입니다. 경고가 있는 18개 도구는 {code, message, hint?} 객체 배열을 반환하며, 빈 경고는 생략합니다. templates에는 경고 필드가 없습니다. 전송·JSON-RPC·알 수 없는 도구·worker 실패는 기존 프로토콜 경계를 유지합니다.
Python 파일 I/O는 HwpForgeError와 OSError로 포착할 수 있고, 입력 부재는 FileNotFoundError로도 포착할 수 있습니다. 정확한 타입 비교나 PermissionError 같은 세부 포착은 달라집니다. Python 호출 규약·인자 변환의 TypeError·ValueError는 유지합니다.
스타일 참조와 JSON 이행
v3 문단의 style_ref는 문서 내부 참조입니다. styles.style_positions[ref]가 styles.styles 정의 배열의 위치를 가리킵니다. 숫자 ref 0은 wire 0과 다를 수 있으며, null은 출력에서 wire 0을 사용합니다. 대응표는 모든 정의를 정확히 한 번 포함해야 합니다. schema의 Document는 Core 구조이고 ExportedDocument/ExportedSection은 이 교환 envelope를 설명합니다.
독립 from-json은 non-null 참조가 있으면 styles를 요구합니다(base 제공 여부와 무관). styles 없는 구역 patch는 제출한 base의 참조 공간으로 해석합니다. 동일 section과 다른 header를 가진 파일의 출처 차이까지 검출하지는 않습니다. 완전 왕복에는 styles를 포함하세요. v2는 위치 참조를 단방향 이행하며, styles 없는 v2 문서 작성은 default preset을 사용합니다. 버전 없는 JSON은 기존 여백 단위 이행을 먼저 수행합니다.
MCP from-json의 문자열 인자 안 JSON도 같은 계약입니다. 별도 MCP schema 도구는 없으며 CLI schema를 사용합니다. Python의 dict 반환 타입과 callable은 그대로이고, 그 내부 데이터 계약만 v3로 바뀝니다.
v3에서 Core JSON의 style_id는 style_ref로 바뀌었으며, 교환에는 envelope를 사용하세요. to-json --no-styles로 내보낸 v3 문서는 non-null 참조에 필요한 styles가 없어 그대로 from-json에 넣으면 거절됩니다.