Add attributes for colors, background colors, and bright colors. Closes #2.

3 files changed, 103 insertions, 10 deletions

diff --git a/README.rst b/README.rst
index 5b0e527..b0d27f0 100644
--- a/README.rst
+++ b/README.rst
@@ -108,6 +108,35 @@ detail, but I elected to keep Blessings easy to integrate and quick to learn.
 
   .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
 
+Color
+-----
+
+16 colors, both foreground and background, are available as easy-to-remember
+attributes::
+
+    from blessings import Terminal
+
+    term = Terminal()
+    print term.red + term.bg_green + 'Red on green? Ick!' + term.normal
+    print term.bright_red + term.bg_bright_blue + 'This is even worse!' + term.normal
+
+The available colors are...
+
+* ``black``
+* ``red``
+* ``green``
+* ``yellow``
+* ``blue``
+* ``magenta``
+* ``cyan``
+* ``white``
+
+In addition, there is a ``bright`` version of each. If your terminal does not
+support the bright palette, it will usually render them as black.
+
+You can set the background color instead of the foreground by prepending
+``bg_``, as in ``bg_blue`` or ``bg_bright_white``.
+
 Parametrized Capabilities
 -------------------------
 
@@ -118,15 +147,10 @@ pass the parameters right in::
     from blessings import Terminal
 
     term = Terminal()
-    print 'I am ' + term.color(2) + 'green' + term.normal + '!'
+    print term.create_window(1, 1, 20, 20)
 
-Parametrized capabilities of interest include...
-
-* ``color`` (takes a number 0-15)
-* ``bg_color`` (background color, also takes a number 0-15)
-
-If you need more, you can also reference any string-returning capability listed
-on the `terminfo man page`_ by the name under the "Cap-name" column.
+You can reference any string-returning capability listed on the `terminfo man
+page`_ by the name under the "Cap-name" column.
 
 .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
 
@@ -186,6 +210,9 @@ Bugs or suggestions? Visit the `issue tracker`_.
 Version History
 ===============
 
+1.1
+  * Added nicely named attributes for colors.
+
 1.0
   * Extracted Blessings from nose-progressive, my `progress-bar-having,
     traceback-shortcutting, rootin', tootin' testrunner`_. It provided the
diff --git a/blessings/__init__.py b/blessings/__init__.py
index 481d411..0b8cc97 100644
--- a/blessings/__init__.py
+++ b/blessings/__init__.py
@@ -62,9 +62,9 @@ class Terminal(object):
                   clear_eol='el',
                   position='cup',
 
-                  # TODO: Make this perhaps try setf first then fall back to setaf:
+                  # You can use these if you want, but the named equivalents
+                  # like "red" and "bg_green" are probably easier.
                   color='setaf',
-                  # TODO: Perhaps see if setb is true, then fall back to setab.
                   bg_color='setab',
 
                   normal='sgr0',
@@ -73,6 +73,12 @@ class Terminal(object):
                   underline='smul',
                   no_underline='rmul')
 
+    def _color(self, color):
+        return (self.setaf or self.setf)(color)
+
+    def _bg_color(self, color):
+        return (self.setab or self.setb)(color)
+
     def __getattr__(self, attr):
         """Return parametrized terminal capabilities, like bold.
 
@@ -114,6 +120,51 @@ class Terminal(object):
         return Location(x, y, self)
 
 
+def _add_color_methods():  # Really, really private
+    """Return an iterable of method pairs that set fg and bg colors.
+
+    The methods in the pair return the escape sequences to set the foreground
+    or background color, respectively.
+
+    """
+    # TODO: Does curses automatically exchange red and blue and cyan and yellow
+    # when a terminal supports setf/setb rather than setaf/setab? I'll be
+    # blasted if I can find any documentation. The following assumes it does.
+    def colorers(color, offset=0):
+        """Return a method that returns the formatting string to set a certain color.
+
+        curses constants go up to only 7, so pass in an offset to get at the
+        bright colors at 8-15.
+
+        """
+        const = 'COLOR_' + color.upper()
+
+        @property
+        def some_color(self):
+            return self._color(getattr(curses, const) + offset)
+
+        @property
+        def some_bg_color(self):
+            return self._bg_color(getattr(curses, const) + offset)
+
+        return some_color, some_bg_color
+
+    for color in ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']:
+        # Foreground and background:
+        fg_method, bg_method = colorers(color)
+        setattr(Terminal, color, fg_method)
+        setattr(Terminal, 'bg_' + color, bg_method)
+
+        # Foreground and background, bright:
+        fg_method, bg_method = colorers(color, offset=8)
+        setattr(Terminal, 'bright_' + color, fg_method)
+        setattr(Terminal, 'bg_bright_' + color, bg_method)
+
+
+# Add color and background color attrs, like red and bg_red:
+_add_color_methods()
+
+
 class CallableString(str):
     """A string which can be called to parametrize it as a terminal capability"""
     def __call__(self, *args):
diff --git a/blessings/tests.py b/blessings/tests.py
index e412077..11d5c19 100644
--- a/blessings/tests.py
+++ b/blessings/tests.py
@@ -72,3 +72,18 @@ def test_null_fileno():
     out.fileno = None
     t = Terminal(stream=out)
     eq_(t.save, '')
+
+
+def test_mnemonic_colors():
+    """Make sure color shortcuts work."""
+    # Avoid testing red, blue, yellow, and cyan, since they might someday
+    # chance depending on terminal type.
+    t = Terminal()
+    eq_(t.white, '\x1b[37m')
+    eq_(t.green, '\x1b[32m')  # Make sure it's different than white.
+    eq_(t.bg_black, '\x1b[40m')
+    eq_(t.bg_green, '\x1b[42m')
+    eq_(t.bright_black, '\x1b[90m')
+    eq_(t.bright_green, '\x1b[92m')
+    eq_(t.bg_bright_black, '\x1b[100m')
+    eq_(t.bg_bright_green, '\x1b[102m')