run: add Run.clear()

Steve Canny · Steve Canny · commit 30b79f5a8053 · 2014-06-25T00:18:31.000-07:00
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -149,6 +149,14 @@ def add_drawing(self, inline_or_anchor):
         drawing.append(inline_or_anchor)
         return drawing
 
+    def clear_content(self):
+        """
+        Remove all child elements except the ``<w:rPr>`` element if present.
+        """
+        content_child_elms = self[1:] if self.rPr is not None else self[:]
+        for child in content_child_elms:
+            self.remove(child)
+
     @property
     def style(self):
         """
diff --git a/docx/text.py b/docx/text.py
@@ -172,6 +172,14 @@ def bold(self):
         """
         return 'b'
 
+    def clear(self):
+        """
+        Return reference to this run after removing all its content. All run
+        formatting is preserved.
+        """
+        self._r.clear_content()
+        return self
+
     @boolproperty
     def complex_script(self):
         """
diff --git a/features/run-clear-run.feature b/features/run-clear-run.feature
@@ -4,7 +4,6 @@ Feature: Remove the content of a run
   I need a way to clear the content of a run
 
 
-  @wip
   Scenario: Clear run content
     Given a run having known text and formatting
      When I clear the run
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -9,6 +9,7 @@
 )
 
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
+from docx.oxml import OxmlElement
 from docx.oxml.ns import qn
 from docx.oxml.text import CT_P, CT_R
 from docx.text import Paragraph, Run
@@ -210,6 +211,13 @@ def it_knows_the_text_it_contains(self, text_prop_fixture):
         run, expected_text = text_prop_fixture
         assert run.text == expected_text
 
+    def it_can_remove_its_content_while_preserving_formatting(
+            self, clear_fixture):
+        run, expected_xml = clear_fixture
+        _run = run.clear()
+        assert run._r.xml == expected_xml
+        assert _run is run
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -366,6 +374,22 @@ def bool_prop_set_fixture(self, request):
         expected_xml = an_r().with_nsdecls().with_child(rPr_bldr).xml()
         return run, bool_prop_name, value, expected_xml
 
+    @pytest.fixture(params=[
+        ('bi', 'foobar'), ('bi', None), ('', 'foobar'), ('', None)
+    ])
+    def clear_fixture(self, request):
+        formatting, text = request.param
+        r = OxmlElement('w:r')
+        if 'b' in formatting:
+            r.get_or_add_rPr()._add_b().val = True
+        if 'i' in formatting:
+            r.get_or_add_rPr()._add_i().val = True
+        expected_xml = r.xml
+        if text is not None:
+            r.add_t(text)
+        run = Run(r)
+        return run, expected_xml
+
     @pytest.fixture(params=['Foobar', None])
     def style_get_fixture(self, request):
         style = request.param
