Merge branch 'main' into chore/license-metadata-alignment

Author: airmang

README.md

@@ -156,6 +156,8 @@ for obj in ObjectFinder("문서.hwpx").find_all(tag="tbl"):
     print(obj.tag, obj.path)
 ```
 
+`hp:tab`과 `ctrl id="tab"`은 탭 문자(`\t`)로 보존됩니다. 따라서 `Paragraph.text`, `TextExtractor`, `export_text()`/`export_html()`/`export_markdown()` 경로에서 같은 탭 의미를 유지한 채 roundtrip 할 수 있습니다. 필요하면 `preserve_breaks=False`로 줄바꿈/탭을 공백 기반으로 평탄화할 수 있습니다.
+
 ### 🎨 스타일 기반 텍스트 치환
 
 서식(색상, 밑줄, charPrIDRef)으로 런을 필터링해 선택적으로 교체합니다.
@@ -221,37 +223,6 @@ python-hwpx
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
 
-## CLI
-
-```bash
-# HWPX 문서 스키마 유효성 검사
-hwpx-validate 문서.hwpx
-
-# ZIP/OPC/HWPX 패키지 구조 검사
-hwpx-validate-package 문서.hwpx
-
-# HWPX 풀기 / 다시 묶기 (기본값: XML/HWPF 바이트 보존)
-hwpx-unpack 문서.hwpx ./unpacked
-hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
-hwpx-pack ./unpacked ./repacked.hwpx
-
-# 레퍼런스 문서 분석과 작업 디렉터리 추출
-hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
-hwpx-pack ./template-parts ./template-roundtrip.hwpx
-hwpx-validate-package ./template-roundtrip.hwpx
-
-# plain / markdown 텍스트 추출
-hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
-
-# 문서 구조 변화 징후 비교
-hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
-```
-
-`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 같은 구조 지표를 비교해 편집 전후 변화 징후를 빠르게 점검합니다.
-
-`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 전제로 두지 않고, `META-INF/container.xml`과 실제 rootfile/manifest 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
-
-`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

docs/usage.md

@@ -1028,11 +1028,13 @@ with TextExtractor("sample.hwpx") as extractor:
             print(text)
 ```
 
+`hp:tab` 또는 `ctrl id="tab"`이 들어 있는 문단도 같은 방식으로 처리됩니다. 예를 들어 `left<tab>right` 형태의 런은 `paragraph.text()`에서 `"left\tright"`로 보이며, `HwpxDocument`로 다시 저장한 뒤 다시 열어도 탭 의미가 유지됩니다.
+
 문단 객체(`ParagraphInfo`)의 `text()` 메서드에는 추가로 다음과 같은 인자를 전달할 수 있습니다.
 
 - `object_behavior`: 표, 도형 등 인라인 개체를 `"skip"`, `"placeholder"`, `"nested"` 중 하나로 처리합니다.
 - `object_placeholder`: 자리표시자 모드를 사용할 때 형식을 지정합니다.
-- `preserve_breaks`: 줄바꿈과 탭을 유지할지 여부를 결정합니다.
+- `preserve_breaks`: 줄바꿈과 탭을 유지할지 여부를 결정합니다. 기본값은 `True`이며, `hp:tab`과 `ctrl id="tab"`은 `\t`로 렌더링됩니다. `False`로 주면 탭/줄바꿈을 공백 기반으로 평탄화할 수 있습니다.
 
 `iter_sections()`와 `iter_paragraphs()` 메서드를 사용하면 원하는 구역에만 접근하거나 중첩 문단을 제외하는 등 탐색 범위를 세밀하게 조정할 수 있습니다.
 

src/hwpx/oxml/body.py

@@ -43,7 +43,7 @@
 }
 
 InlineMark = Union[GenericElement, "TrackChangeMark"]
-RunChild = Union[GenericElement, "Control", "Table", "InlineObject", "TextSpan"]
+RunChild = Union[GenericElement, "Control", "Table", "InlineObject", "TextSpan", "Tab"]
 ParagraphChild = Union["Run", GenericElement]
 
 
@@ -105,6 +105,12 @@ class InlineObject:
     children: List[GenericElement] = field(default_factory=list)
 
 
+@dataclass(slots=True)
+class Tab:
+    tag: str
+    attributes: Dict[str, str] = field(default_factory=dict)
+
+
 @dataclass(slots=True)
 class Table:
     tag: str
@@ -120,6 +126,7 @@ class Run:
     controls: List[Control] = field(default_factory=list)
     tables: List[Table] = field(default_factory=list)
     inline_objects: List[InlineObject] = field(default_factory=list)
+    tabs: List[Tab] = field(default_factory=list)
     text_spans: List[TextSpan] = field(default_factory=list)
     other_children: List[GenericElement] = field(default_factory=list)
     attributes: Dict[str, str] = field(default_factory=dict)
@@ -227,6 +234,10 @@ def parse_table_element(node: etree._Element) -> Table:
     )
 
 
+def parse_tab_element(node: etree._Element) -> Tab:
+    return Tab(tag=node.tag, attributes={key: value for key, value in node.attrib.items()})
+
+
 def parse_run_element(node: etree._Element) -> Run:
     attributes = {key: value for key, value in node.attrib.items()}
     char_pr_id_ref = parse_int(attributes.pop("charPrIDRef", None))
@@ -247,6 +258,10 @@ def parse_run_element(node: etree._Element) -> Run:
             span = parse_text_span(child)
             run.text_spans.append(span)
             run.content.append(span)
+        elif name == "tab":
+            tab = parse_tab_element(child)
+            run.tabs.append(tab)
+            run.content.append(tab)
         elif name == "tbl":
             table = parse_table_element(child)
             run.tables.append(table)
@@ -342,6 +357,10 @@ def _text_span_to_xml(span: TextSpan) -> etree._Element:
     return node
 
 
+def _tab_to_xml(tab: Tab) -> etree._Element:
+    return etree.Element(_qualified_tag(tab.tag, "tab"), dict(tab.attributes))
+
+
 def _control_to_xml(control: Control) -> etree._Element:
     attrs = dict(control.attributes)
     if control.control_type is not None:
@@ -376,6 +395,8 @@ def serialize_run(run: Run) -> etree._Element:
             node.append(_text_span_to_xml(child))
         elif isinstance(child, Control):
             node.append(_control_to_xml(child))
+        elif isinstance(child, Tab):
+            node.append(_tab_to_xml(child))
         elif isinstance(child, Table):
             node.append(_table_to_xml(child))
         elif isinstance(child, InlineObject):

src/hwpx/oxml/document.py

@@ -121,6 +121,45 @@ def _memo_id() -> str:
     return str(uuid4().int & 0xFFFFFFFF)
 
 
+def _refresh_copied_paragraph_subtree_ids(paragraph: ET.Element) -> None:
+    """Assign fresh local identifiers inside a copied paragraph subtree.
+
+    This is intentionally narrow: it refreshes paragraph ids for the copied
+    paragraph and any nested paragraphs (for example inside table cells), plus
+    common object identifiers used by tables/shapes/notes. Reference-style
+    attributes such as ``borderFillIDRef`` are left untouched.
+    """
+
+    for node in paragraph.iter():
+        if node.tag == f"{_HP}p":
+            node.set("id", _paragraph_id())
+            continue
+
+        if "id" in node.attrib and node.tag in {
+            f"{_HP}tbl",
+            f"{_HP}pic",
+            f"{_HP}container",
+            f"{_HP}ole",
+            f"{_HP}equation",
+            f"{_HP}textart",
+            f"{_HP}video",
+            f"{_HP}header",
+            f"{_HP}footer",
+        }:
+            node.set("id", _object_id())
+
+        if "instId" in node.attrib:
+            node.set("instId", _object_id())
+
+
+def _clone_paragraph_element(paragraph: ET.Element) -> ET.Element:
+    """Return a deep-copied paragraph element with refreshed local ids."""
+
+    cloned = deepcopy(paragraph)
+    _refresh_copied_paragraph_subtree_ids(cloned)
+    return cloned
+
+
 def _create_paragraph_element(
     text: str,
     *,
@@ -154,9 +193,7 @@ def _create_paragraph_element(
 
     run = paragraph.makeelement(f"{_HP}run", run_attrs)
     paragraph.append(run)
-    text_element = run.makeelement(f"{_HP}t", {})
-    run.append(text_element)
-    text_element.text = text
+    _append_text_with_tabs(run, text)
     return paragraph
 
 
@@ -192,6 +229,20 @@ def _append_child(
     return child
 
 
+def _is_tab_control_element(node: ET.Element) -> bool:
+    return node.tag == f"{_HP}ctrl" and (node.get("id") or "").lower() == "tab"
+
+
+def _append_text_with_tabs(run: ET.Element, value: str) -> None:
+    segments = value.split("\t")
+    for index, segment in enumerate(segments):
+        text_element = run.makeelement(f"{_HP}t", {})
+        text_element.text = _sanitize_text(segment)
+        run.append(text_element)
+        if index < len(segments) - 1:
+            run.append(run.makeelement(f"{_HP}tab", {}))
+
+
 def _normalize_length(value: str | None) -> str:
     if value is None:
         return ""
@@ -2097,9 +2148,7 @@ def add_paragraph(
             run_attrs["charPrIDRef"] = "0"
 
         run = _append_child(paragraph, f"{_HP}run", run_attrs)
-        t = run.makeelement(f"{_HP}t", {})
-        t.text = _sanitize_text(text)
-        run.append(t)
+        _append_text_with_tabs(run, text)
 
         self.table.mark_dirty()
         section = self.table.paragraph.section
@@ -2762,9 +2811,13 @@ def runs(self) -> list[HwpxOxmlRun]:
     def text(self) -> str:
         """Return the concatenated textual content of this paragraph."""
         texts: list[str] = []
-        for text_element in self.element.findall(f".//{_HP}t"):
-            if text_element.text:
-                texts.append(text_element.text)
+        for run in self._run_elements():
+            for child in run:
+                if child.tag == f"{_HP}t":
+                    if child.text:
+                        texts.append(child.text)
+                elif child.tag == f"{_HP}tab" or _is_tab_control_element(child):
+                    texts.append("\t")
         return "".join(texts)
 
     @text.setter
@@ -2780,10 +2833,10 @@ def text(self, value: str) -> None:
         # Identify first run — its charPrIDRef will be kept.
         first_run = self._ensure_run()
 
-        # Remove <hp:t> from ALL runs.
+        # Remove existing text/tab nodes from all runs.
         for run in runs:
             for child in list(run):
-                if child.tag == f"{_HP}t":
+                if child.tag == f"{_HP}t" or child.tag == f"{_HP}tab" or _is_tab_control_element(child):
                     run.remove(child)
 
         # Remove non-first runs that are now empty (only had text).
@@ -2794,10 +2847,8 @@ def text(self, value: str) -> None:
             if len(list(run)) == 0:
                 self.element.remove(run)
 
-        # Write the new text into the first run.
-        text_element = first_run.makeelement(f"{_HP}t", {})
-        text_element.text = _sanitize_text(value)
-        first_run.append(text_element)
+        # Write the new text into the first run, preserving tabs as <hp:tab/>.
+        _append_text_with_tabs(first_run, value)
         _clear_paragraph_layout_cache(self.element)
         self.section.mark_dirty()
 
@@ -3668,14 +3719,43 @@ def add_paragraph(
 
             run = paragraph.makeelement(f"{_HP}run", run_attrs)
             paragraph.append(run)
-            text_element = run.makeelement(f"{_HP}t", {})
-            text_element.text = text
-            run.append(text_element)
+            _append_text_with_tabs(run, text)
 
         self._element.append(paragraph)
         self._dirty = True
         return HwpxOxmlParagraph(paragraph, self)
 
+    def insert_paragraphs(
+        self,
+        index: int,
+        paragraphs: Sequence[HwpxOxmlParagraph | ET.Element],
+    ) -> list[HwpxOxmlParagraph]:
+        """Insert paragraph copies at *index* and return wrappers for them."""
+
+        existing = self.paragraphs
+        if index < 0 or index > len(existing):
+            raise IndexError(f"단락 인덱스 {index}이(가) 범위를 벗어났습니다 (총 {len(existing)}개)")
+
+        inserted: list[HwpxOxmlParagraph] = []
+        for offset, paragraph in enumerate(paragraphs):
+            source_element = paragraph.element if isinstance(paragraph, HwpxOxmlParagraph) else paragraph
+            cloned = _clone_paragraph_element(source_element)
+            self._element.insert(index + offset, cloned)
+            inserted.append(HwpxOxmlParagraph(cloned, self))
+
+        if inserted:
+            self._dirty = True
+        return inserted
+
+    def copy_paragraph_range(self, start: int, end: int) -> list[ET.Element]:
+        """Return deep-copied paragraph elements for the inclusive range."""
+
+        paragraphs = self.paragraphs
+        total = len(paragraphs)
+        if start < 0 or end < 0 or start >= total or end >= total or start > end:
+            raise IndexError(f"문단 범위 {start}..{end}이(가) 유효하지 않습니다 (총 {total}개)")
+        return [_clone_paragraph_element(paragraphs[index].element) for index in range(start, end + 1)]
+
     def mark_dirty(self) -> None:
         self._dirty = True
 
@@ -4649,6 +4729,42 @@ def remove_paragraph(
         else:
             paragraph.remove()
 
+    def copy_paragraph_range(
+        self,
+        start: int,
+        end: int,
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> list[ET.Element]:
+        """Return deep-copied paragraph elements for an inclusive range."""
+
+        if section is None and section_index is not None:
+            section = self._sections[section_index]
+        if section is None:
+            if not self._sections:
+                raise ValueError("document does not contain any sections")
+            section = self._sections[-1]
+        return section.copy_paragraph_range(start, end)
+
+    def insert_paragraphs(
+        self,
+        index: int,
+        paragraphs: Sequence[HwpxOxmlParagraph | ET.Element],
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> list[HwpxOxmlParagraph]:
+        """Insert copied paragraphs into the requested section."""
+
+        if section is None and section_index is not None:
+            section = self._sections[section_index]
+        if section is None:
+            if not self._sections:
+                raise ValueError("document does not contain any sections")
+            section = self._sections[-1]
+        return section.insert_paragraphs(index, paragraphs)
+
     # ------------------------------------------------------------------
     # Section management
     # ------------------------------------------------------------------