Commits

Jonathan Eunice committed 1ffa82b

tweaked docs; extended tests

Comments (0)

Files changed (3)

  *  Indentation and wrapping (to help stucture output)
  *  Convenience printing functions for horizontal rules (lines), titles, and
     vertical whitespace.
- *  A convenient text aggregator class, Text, for easily building mutli-line
-    text objects a little bit at a time.
-
+ *  Convenient template/text aggregator objects for easily building,
+    reading, and writing mutli-line texts.
+    
 Usage
 =====
 
 ==================
 
 Often the job of output is not about individual text lines, but about creating
-multi-line files such as scripts and reports. ``say`` has you covered there as
+multi-line files such as scripts and reports. This often leads away from standard
+output mechanisms toward template pakcages, but ``say`` has you covered here as
 well.::
 
     from say import Text
 ``say`` ``Text`` objects, as their ``str()`` value is the full text you would
 assume. ``Text`` objects have both ``text`` and ``lines`` properties which
 can be either accessed or assigned to.
-    
-In the example above, the ``+=`` assignment shows how text can be incrementally
-added, but it isn't strictly necessary in this instance, because the
-``Text(...)`` constructor can itself accept a string or set of lines.
 
-Other in-place operators are available. If you
-want to preserve leading white space (no dedent), use ``|=``.
-If you don't want the string iterpreted at all, use
-``&=``. There is a ``read_from`()` method as well as the demonstrated
-``write_to()``.
+``+=`` incremental assignment 
+automatically removes blank starting and ending lines, and any whitespace prefix
+that is common to all of the lines (i.e. it will *dedent* any given text).
+This ensures you don't need to give up
+nice Python program formatting just to include a template.
 
-``Text`` objects are accessible via ``[]`` indexing, and they are iterable.
-Their ``len()`` is the number of lines they contain. As with lists, one can
+While ``+=`` is a handy way of incrementally building text, it
+isn't strictly necessary in the simple example above; the
+``Text(...)`` constructor itself accepts a string or set of lines.
+
+Other in-place operators are: `|=`` for adding text while preserving leading white
+space (no dedent) and ``&=`` adds text verbatim--without dedent or string
+interpolation. 
+
+One can ``read_from()`` a file (appending the contents of the file to the given
+text object, with optional interpolation and dedenting). One can also 
+``write_to()`` a file. Use the ``append`` flag if you wish to add to rather than
+overwrite the file of a given name, and you can set an output encoding if you
+like (``encoding='utf=8'`` is the default).
+
+So far we've discussed``Text`` objects almost like strings, but they also act
+as lists of individual lines (strings). They are, for example,
+indexible via ``[]``, and they are iterable.
+Their ``len()`` is the number of lines they contain. One can
 ``append()`` or ``extend()`` them with one or multiple strings, respectively.
 ``append()`` takes a keyword parameter ``interpolate`` that controls whether
-``{}`` expressions in the string are interpolated. ``extend()`` also takes an
-``interpolate`` flag, as well as a ``dedent`` flag that, if true, will
+``{}`` expressions in the string are interpolated. ``extend()`` additionally takes
+a ``dedent`` flag that, if true, will
 automatically remove blank starting and ending lines, and any whitespace prefix
 that is common to all of the lines.
 
 
 setup(
     name='say',
-    version=verno("0.871"),
+    version=verno("0.875"),
     author='Jonathan Eunice',
     author_email='jonathan.eunice@gmail.com',
     description='Super-simple templated printing. E.g.: say("Hello, {whoever}!", indent=1)',

test/test_text.py

     
 def test_init():
         
-    t = Text('someday\nsoon')
-    assert t.text == 'someday\nsoon'
+    d = 4409
     
-    t = Text(['someday', 'soon' ])
-    assert t.text == 'someday\nsoon'
+    t = Text('someday\nsoon {d}')
+    assert t.text == 'someday\nsoon 4409'
+    
+    t = Text(['someday', 'soon {d}' ])
+    assert t.text == 'someday\nsoon 4409'
     
     b = 'boy'
     
     t2 = Text('hey {b}')
     assert t2.text == 'hey boy'
     
+    t3 = Text('hey {b}', interpolate=False)
+    assert t3.text == 'hey {b}'
+    
+    t4 = Text("""
+        Now this
+        is more
+        like it!
+    """)
+    assert t4.text == "Now this\nis more\nlike it!"
+    
+    t5 = Text(dedent=False, data="""
+        Now this
+        is more
+        like it!
+    """)
+    assert t5.text == "\n        Now this\n        is more\n        like it!\n    "
+    
 def test_str():
     t = Text('someday\nsoon')