Paragraph And Run
=================

``featherdoc::Paragraph`` is the editing handle for a Word paragraph.
``featherdoc::Run`` is the editing handle for text inside a paragraph with its
own run-level formatting, language, and direction metadata.

Common Tasks
------------

Use this page when editing text runs or paragraph layout:

* Replace a whole paragraph: call ``Paragraph::set_text(...)``.
* Add styled text inside a paragraph: call ``add_run(...)`` and then set run
  font, color, language, or direction metadata.
* Insert adjacent content: use ``insert_paragraph_before(...)``,
  ``insert_paragraph_after(...)``, ``insert_run_before(...)``, or
  ``insert_run_after(...)``.
* Preserve nearby formatting: use the ``insert_*_like_*`` helpers before
  changing text.
* Tune layout: use paragraph alignment, bidirectional layout, and indent APIs.

Success And Failure Semantics
-----------------------------

.. list-table::
   :header-rows: 1
   :widths: 24 36 40

   * - Return shape
     - Success
     - Failure or no-op
   * - ``bool``
     - ``true`` means the current paragraph or run XML node changed.
     - ``false`` means the current node was missing, unsupported, or unchanged.
   * - ``std::optional<T>``
     - Contains the requested formatting, layout, language, or direction value.
     - Empty means the property is not explicitly set or cannot be resolved.
   * - ``Paragraph`` / ``Run``
     - Returned handles point at inserted or appended paragraph/run nodes.
     - Use the returned handle for follow-up formatting.
   * - Iterator references
     - ``Paragraph &`` and ``Run &`` represent the current iterator position.
     - Call ``has_next()`` before advancing when iterating existing content.

Short Example
-------------

.. code-block:: cpp

   auto paragraph = doc.body_template().append_paragraph("Status:");
   auto value = paragraph.add_run(" approved", featherdoc::formatting_flag::bold);
   value.set_font_family("Aptos");
   paragraph.set_alignment(featherdoc::paragraph_alignment::center);

Typed Signature Guide
---------------------

Use this table when you need the exact argument shape before writing code.
Indexes are zero-based where an API accepts an index. Methods returning
``bool`` report whether the underlying XML node could be changed.

.. list-table::
   :header-rows: 1
   :widths: 38 34 28

   * - Signature
     - Parameters
     - Return semantics
   * - ``bool set_text(const std::string &text) const``
     - ``text``: replacement paragraph or run text.
     - ``true`` when the current node was rewritten.
   * - ``Run add_run(const std::string &text, formatting_flag formatting = formatting_flag::none)``
     - ``text``: appended text. ``formatting``: optional basic formatting flag.
     - New ``Run`` handle for the appended run.
   * - ``Paragraph insert_paragraph_before(const std::string &text, formatting_flag formatting = formatting_flag::none)``
     - ``text``: inserted paragraph text. ``formatting``: optional first-run formatting.
     - New paragraph handle inserted before the current paragraph.
   * - ``Paragraph insert_paragraph_after(const std::string &text, formatting_flag formatting = formatting_flag::none)``
     - ``text``: inserted paragraph text. ``formatting``: optional first-run formatting.
     - New paragraph handle inserted after the current paragraph.
   * - ``bool set_alignment(paragraph_alignment alignment) const``
     - ``alignment``: one of the documented paragraph alignment enum values.
     - ``true`` when paragraph properties were updated.
   * - ``bool set_indent_left_twips(std::uint32_t indent_twips) const``
     - ``indent_twips``: left indent in twips.
     - ``true`` when the paragraph indent was updated.
   * - ``Run insert_run_before(const std::string &text, formatting_flag formatting = formatting_flag::none)``
     - ``text``: inserted run text. ``formatting``: optional basic formatting flag.
     - New run handle inserted before the current run.
   * - ``Run insert_run_after(const std::string &text, formatting_flag formatting = formatting_flag::none)``
     - ``text``: inserted run text. ``formatting``: optional basic formatting flag.
     - New run handle inserted after the current run.
   * - ``bool set_font_family(std::string_view font_family) const``
     - ``font_family``: primary Latin font family name.
     - ``true`` when run properties were updated.
   * - ``bool set_language(std::string_view language) const``
     - ``language``: BCP-47 style language tag such as ``en-US``.
     - ``true`` when language metadata was updated.
   * - ``bool set_rtl(bool enabled = true) const``
     - ``enabled``: ``true`` to mark the run right-to-left.
     - ``true`` when run direction metadata was updated.

Paragraph Text And Iteration
----------------------------

.. list-table::
   :header-rows: 1
   :widths: 34 20 46

   * - Method
     - Returns
     - Purpose
   * - ``next()``
     - ``Paragraph &``
     - Advance the paragraph iterator to the next paragraph.
   * - ``has_next() const``
     - ``bool``
     - Check whether the iterator can advance.
   * - ``set_text(const std::string &text) const``
     - ``bool``
     - Replace all text in the current paragraph.
   * - ``remove()``
     - ``bool``
     - Remove the current paragraph.
   * - ``runs()``
     - ``Run &``
     - Access the run iterator for the current paragraph.
   * - ``add_run(text, formatting_flag formatting = none)``
     - ``Run``
     - Append a run with optional basic formatting.
   * - ``insert_paragraph_before(text, formatting)``
     - ``Paragraph``
     - Insert a paragraph before the current paragraph.
   * - ``insert_paragraph_after(text, formatting)``
     - ``Paragraph``
     - Insert a paragraph after the current paragraph.
   * - ``insert_paragraph_like_before()``
     - ``Paragraph``
     - Insert a paragraph before this one and copy paragraph properties.
   * - ``insert_paragraph_like_after()``
     - ``Paragraph``
     - Insert a paragraph after this one and copy paragraph properties.

Paragraph Layout
----------------

.. list-table::
   :header-rows: 1
   :widths: 34 20 46

   * - Method
     - Returns
     - Purpose
   * - ``bidi() const``
     - ``std::optional<bool>``
     - Inspect right-to-left paragraph layout metadata.
   * - ``set_bidi(bool enabled = true) const``
     - ``bool``
     - Enable or disable right-to-left paragraph layout.
   * - ``clear_bidi() const``
     - ``bool``
     - Remove explicit right-to-left paragraph metadata.
   * - ``alignment() const``
     - ``std::optional<paragraph_alignment>``
     - Read paragraph alignment.
   * - ``set_alignment(paragraph_alignment alignment) const``
     - ``bool``
     - Set paragraph alignment.
   * - ``clear_alignment() const``
     - ``bool``
     - Remove explicit paragraph alignment.
   * - ``indent_left_twips() const`` / ``indent_right_twips() const``
     - ``std::optional<std::uint32_t>``
     - Read left or right indent in twips.
   * - ``first_line_indent_twips() const`` / ``hanging_indent_twips() const``
     - ``std::optional<std::uint32_t>``
     - Read first-line or hanging indent.
   * - ``set_indent_left_twips(indent_twips) const``
     - ``bool``
     - Set the left indent in twips.
   * - ``set_indent_right_twips(indent_twips) const``
     - ``bool``
     - Set the right indent in twips.
   * - ``set_first_line_indent_twips(indent_twips) const``
     - ``bool``
     - Set the first-line indent.
   * - ``set_hanging_indent_twips(indent_twips) const``
     - ``bool``
     - Set the hanging indent.

Run Text And Styling
--------------------

.. list-table::
   :header-rows: 1
   :widths: 34 20 46

   * - Method
     - Returns
     - Purpose
   * - ``get_text() const``
     - ``std::string``
     - Read the current run text.
   * - ``set_text(const std::string &text) const``
     - ``bool``
     - Replace the current run text.
   * - ``remove()``
     - ``bool``
     - Remove the current run.
   * - ``insert_run_before(text, formatting)``
     - ``Run``
     - Insert a run before the current run.
   * - ``insert_run_after(text, formatting)``
     - ``Run``
     - Insert a run after the current run.
   * - ``insert_run_like_before()``
     - ``Run``
     - Insert a run before this one and copy run properties.
   * - ``insert_run_like_after()``
     - ``Run``
     - Insert a run after this one and copy run properties.
   * - ``style_id() const``
     - ``std::optional<std::string>``
     - Read the run style id.
   * - ``font_family() const``
     - ``std::optional<std::string>``
     - Read the primary run font family.
   * - ``set_font_family(font_family) const``
     - ``bool``
     - Set the primary run font family.
   * - ``text_color() const``
     - ``std::optional<std::string>``
     - Read the run text color value.
   * - ``bold() const`` / ``italic() const`` / ``underline() const``
     - ``std::optional<bool>``
     - Inspect basic run styling.
   * - ``strikethrough() const``
     - ``std::optional<bool>``
     - Inspect strikethrough styling.
   * - ``superscript() const`` / ``subscript() const``
     - ``std::optional<bool>``
     - Inspect vertical script styling.
   * - ``font_size_points() const``
     - ``std::optional<double>``
     - Read the run font size in points.

Run Language And Direction
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 34 20 46

   * - Method
     - Returns
     - Purpose
   * - ``language() const``
     - ``std::optional<std::string>``
     - Read the primary language metadata.
   * - ``east_asia_language() const``
     - ``std::optional<std::string>``
     - Read East Asian language metadata.
   * - ``bidi_language() const``
     - ``std::optional<std::string>``
     - Read bidirectional language metadata.
   * - ``set_language(language) const``
     - ``bool``
     - Set the primary language metadata.
   * - ``set_east_asia_language(language) const``
     - ``bool``
     - Set East Asian language metadata.
   * - ``set_bidi_language(language) const``
     - ``bool``
     - Set bidirectional language metadata.
   * - ``rtl() const``
     - ``std::optional<bool>``
     - Inspect right-to-left run metadata.
   * - ``set_rtl(bool enabled = true) const``
     - ``bool``
     - Enable or disable right-to-left run metadata.

Example
-------

.. code-block:: cpp

   auto paragraph = doc.body_template().append_paragraph("Title");
   paragraph.set_alignment(featherdoc::paragraph_alignment::center);

   auto emphasized = paragraph.add_run(
       " approved",
       featherdoc::formatting_flag::bold);
   emphasized.set_language("en-US");

   auto &run = paragraph.runs();
   if (run.has_next()) {
       run.next().set_font_family("Aptos");
   }