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

3 files changed, 26 insertions, 5 deletions

diff --git a/README.rst b/README.rst
index 07dd4f6..7eb6c30 100644
--- a/README.rst
+++ b/README.rst
@@ -70,8 +70,8 @@ of the screen::
                                                       normal=normal)
     print rc  # Restore cursor position.
 
-Phew! That was long and full of incomprehensible trash! Let's try it again,
-this time with Blessings::
+That was long and full of incomprehensible trash! Let's try it again, this time
+with Blessings::
 
     from blessings import Terminal
 
@@ -238,7 +238,9 @@ Here are some of interest:
 
 ``move``
   Position the cursor elsewhere. Parameters are y coordinate, then x
-  coordinate.
+  coordinate::
+
+      print term.move(10, 1) + 'Hi, mom!'
 ``move_x``
   Move the cursor to the given column.
 ``move_y``
@@ -283,7 +285,14 @@ just one of them, leaving the other alone. For example... ::
     with term.location(y=10):
         print 'We changed just the row.'
 
-If you want to reposition permanently, see ``move``, in an example above.
+If you want to reposition permanently, see ``move``, in an example above. If
+you're doing a series of ``move`` calls and want to return the cursor to its
+original position afterward, call ``location()`` with no arguments, and it will
+do only the position restoring::
+
+    with term.location():
+        print term.move(1, 1) + 'Hi'
+        print term.move(9, 9) + 'Mom'
 
 Pipe Savvy
 ----------
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``.