ConsoleFormat overview

ConsoleFormat is a console/shell output formatting library and script.

Command-Line interface
======================
The command line interface is via a script of the name "consoleformat".  Input
may be specified with a flag of ``--input`` or simply piped in via ``stdin``::
  
  $ consoleformat <options> --input 'this be my input string thankyouverymuch'

  $ cat ./catsndogs.txt | consoleformat <options>

The command-line arguments for each formatting code are of the form::
    
  --<code> 'string'

eg::
  
  $ cat ./sweets_v_meats.html | consoleformat --lt-fg-blue '/<p[^>]*>(.*?)</p>/'

For a full listing of available formatting options as well as examples of how
the formatted text appears in your console, consult the current help text via 
the ``-h|--help`` and ``-p|--print-examples`` options.

Formatting codes
================
All formatting codes are given as strings, with foreground and background 
colors being prefixed by either ``fg_`` or ``bg_`` and the ``light`` versions 
of each color being further prefixed with ``lt_``, e.g::

  lt_fg_yellow = Light Yellow Foreground 
  bg_blue = Blue Background

Multiple occurrences of a formatting code and associated string argument
will be honored.  Strings containing whitespace should be quoted.
Match strings enclosed in forward slashes will be converted into 
regular expressions, e.g.::

    --fg-red "/Once upon a (.*?),.*/"

Target/Match arguments
======================
Strings one wants to be formatted should be targeted either with plain 
strings or regexes, the latter being surrounded by forward slashes, e.g.::

  $ consoleformat --bg-blue "/puppy(.*)/" --fg-red "dragons"

Syntax files
============
External syntax files may be passed to cut down on command line verbosity. 
The name of the file is irrelevant but it must be in valid python syntax 
and contain a dictionary assigned to the name ``CONSOLE_FORMAT`` with target 
strings or regexes as keys and lists of formatting codes as values, e.g.::

  # example syntax file
  
  CONSOLE_FORMAT = {
      "/^wolves:.*$/": ['bg_red'],
      "/.*meatball[0-9]{4}/": ['fg_blue', 'bg_white'],
      "frogman": ['lt_fg_green', 'bg_black'],
  }


Known Issues
============
Overlapping escape sequences will most likely *NOT* output what one would 
expect, e.g.::

  $ echo 'these tweezers are dull' | \
      consoleformat --lt-fg-blue tweezers --bg-red these\ tweezers\ are

This example will result in the words ``these tweezers`` having a red 
background and ``tweezers`` having a blue foreground, but ``are`` will remain 
unformatted because of the "reset" escape at the end of ``tweezers``.  
"What!?", you say, "is up with that?"  Call it a bug for now.

Full support for case-insensitivity and first/all matching of regular expression
strings isn't yet ready.

.. vim:fileencoding=utf-8:filetype=rst