Document an idiom for restoring the cursor location after a series of manual moves. Closes #17.

2 files changed, 13 insertions, 1 deletions

diff --git a/blessings/__init__.py b/blessings/__init__.py
index 080fe26..dbd4b69 100644
--- a/blessings/__init__.py
+++ b/blessings/__init__.py
@@ -213,7 +213,10 @@ class Terminal(object):
                     print 'I can do it %i times!' % x
 
         Specify ``x`` to move to a certain column, ``y`` to move to a certain
-        row, or both.
+        row, both, or neither. If you specify neither, only the saving and
+        restoration of cursor position will happen. This can be useful if you
+        simply want to restore your place after doing some manual cursor
+        movement.
 
         """
         return Location(self, x, y)
diff --git a/blessings/tests.py b/blessings/tests.py
index a02a392..72236ae 100644
--- a/blessings/tests.py
+++ b/blessings/tests.py
@@ -102,6 +102,15 @@ def test_horizontal_location():
                              unicode_cap('rc'))
 
 
+def test_null_location():
+    """Make sure ``location()`` with no args just does position restoration."""
+    t = TestTerminal(stream=StringIO(), force_styling=True)
+    with t.location():
+        pass
+    eq_(t.stream.getvalue(), unicode_cap('sc') +
+                             unicode_cap('rc'))
+
+
 def test_null_fileno():
     """Make sure ``Terminal`` works when ``fileno`` is ``None``.