run: add Run.text setter

Steve Canny · Steve Canny · commit 6a85cabfef80 · 2014-06-25T22:37:34.000-07:00
diff --git a/docx/oxml/text.py b/docx/oxml/text.py
@@ -196,6 +196,11 @@ def text(self):
                 text += '\n'
         return text
 
+    @text.setter
+    def text(self, text):
+        self.clear_content()
+        _RunContentAppender.append_to_run_from_text(self, text)
+
     @property
     def underline(self):
         """
@@ -319,3 +324,59 @@ def val(self, value):
 
         val = WD_UNDERLINE.to_xml(value)
         self.set(qn('w:val'), val)
+
+
+class _RunContentAppender(object):
+    """
+    Service object that knows how to translate a Python string into run
+    content elements appended to a specified ``<w:r>`` element. Contiguous
+    sequences of regular characters are appended in a single ``<w:t>``
+    element. Each tab character ('\t') causes a ``<w:tab/>`` element to be
+    appended. Likewise a newline or carriage return character ('\n', '\r')
+    causes a ``<w:cr>`` element to be appended.
+    """
+    def __init__(self, r):
+        self._r = r
+        self._bfr = []
+
+    @classmethod
+    def append_to_run_from_text(cls, r, text):
+        """
+        Create a "one-shot" ``_RunContentAppender`` instance and use it to
+        append the run content elements corresponding to *text* to the
+        ``<w:r>`` element *r*.
+        """
+        appender = cls(r)
+        appender.add_text(text)
+
+    def add_text(self, text):
+        """
+        Append the run content elements corresponding to *text* to the
+        ``<w:r>`` element of this instance.
+        """
+        for char in text:
+            self.add_char(char)
+        self.flush()
+
+    def add_char(self, char):
+        """
+        Process the next character of input through the translation finite
+        state maching (FSM). There are two possible states, buffer pending
+        and not pending, but those are hidden behind the ``.flush()`` method
+        which must be called at the end of text to ensure any pending
+        ``<w:t>`` element is written.
+        """
+        if char == '\t':
+            self.flush()
+            self._r.add_tab()
+        elif char in '\r\n':
+            self.flush()
+            self._r.add_cr()
+        else:
+            self._bfr.append(char)
+
+    def flush(self):
+        text = ''.join(self._bfr)
+        if text:
+            self._r.add_t(text)
+        del self._bfr[:]
diff --git a/docx/text.py b/docx/text.py
@@ -371,6 +371,10 @@ def text(self):
         """
         return self._r.text
 
+    @text.setter
+    def text(self, text):
+        self._r.text = text
+
     @property
     def underline(self):
         """
diff --git a/features/run-access-content.feature b/features/run-access-content.feature
@@ -4,7 +4,6 @@ Feature: Access run content
   I need ways to access the run content
 
 
-  @wip
   Scenario: Get run content as Python text
     Given a run having mixed text content
      Then the text of the run represents the textual run content
diff --git a/features/run-add-content.feature b/features/run-add-content.feature
@@ -10,7 +10,6 @@ Feature: Add content to a run
      Then the tab appears at the end of the run
 
 
-  @wip
   Scenario: Assign mixed text to text property
     Given a run
      When I assign mixed text to the text property
diff --git a/tests/test_text.py b/tests/test_text.py
@@ -223,6 +223,11 @@ def it_knows_the_text_it_contains(self, text_get_fixture):
         run, expected_text = text_get_fixture
         assert run.text == expected_text
 
+    def it_can_replace_the_text_it_contains(self, text_set_fixture):
+        run, text, expected_xml = text_set_fixture
+        run.text = text
+        assert run._r.xml == expected_xml
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -433,6 +438,21 @@ def text_get_fixture(self, request):
         run = Run(r_bldr.element)
         return run, expected_text
 
+    @pytest.fixture(params=[
+        ('abc',      ('xabc',)),
+        ('abc\tdef', ('xabc', 't', 'xdef')),
+        ('abc\rdef', ('xabc', 'n', 'xdef')),
+    ])
+    def text_set_fixture(self, request):
+        text, expected_elm_codes = request.param
+        # starting run contains text, so can tell if it doesn't get replaced
+        r_bldr = self.r_content_bldr(('xfoobar'))
+        run = Run(r_bldr.element)
+        # expected_xml -----------------
+        r_bldr = self.r_content_bldr(expected_elm_codes)
+        expected_xml = r_bldr.xml()
+        return run, text, expected_xml
+
     @pytest.fixture(params=[
         (None,     None),
         ('single', True),
