grec API

grec Module

Colorize terminal text with regular expressions.

This module implements all functionality required for grec.

class grec.grec.ColoredString(string)

String with colorized parts.

Variables:

• string – The plain string without any color information.
• intervals – Intervals instance associating intervals with colors.

__str__()

Return string with ANSI escape codes for colors.

apply_color(start, end, color_info)

Apply color to all characters within an interval.

Parameters:

• start (int) – index of first character in string to colorize
• end (int) – index of one past the last character to colorize
• color_info (tuple) – foreground and background color as strings

The characters of the string that have indices start through end - 1 will be assigned the colors specified in color_info.

If any characters in the interval already have a color set, their color will be replaced with the new color.

The strings in color_info need to be recognized by termcolor.

>>> s = ColoredString('a word with color')
>>> s.apply_color(2, 6, ('red', 'on_white'))
>>> print s
a word with color

class grec.grec.Intervals(intervals=None)

Dictionary with intervals as keys and arbitrary data as values.

Used to check whether intervals overlap.

An interval is a tuple of two integers, start and end. Like a slice, start marks the first value of the interval while end is one past the last value of the interval.

overlap(interval)

Return all intervals in dict overlapping the given interval.

Parameters:interval (tuple) – start and end of interval

class grec.grec.Matcher

Colorize text based on regular expression matches.

Variables:patterns – OrderedDict of all configured patterns

>>> m = Matcher()
>>> m.add_pattern('A', 'red')
>>> m.add_pattern('B.', 'blue')
>>> colored = m.match('ABC')
>>> colored.string
'ABC'
>>> print colored
ABC

add_group_pattern(regex, *args)

Add regular expression with groups for text colorization.

Parameters:

• regex (string) – regular expression
• args (tuple) – color information for each matched group

Works like add_pattern() but colors matched groups instead of the whole match.

Takes a variable number of arguments where each is a tuple with color information: (foreground, background). These will be used to colorize the corresponding group matches in the same order.

When a regular expression contains more groups than colors, the color information specified in the last argument is repeated for all remaining groups.

When a regular expression contains less groups than colors then excess colors are ignored.

>>> m = Matcher()
>>> m.add_group_pattern('^#.*(ERROR)', ('red',))
>>> m.add_group_pattern('A(B)C(D)', ('blue', 'white'), ('red',))

add_pattern(regex, foreground=None, background=None)

Add regular expression for text colorization.

Parameters:

• regex (string) – regular expression
• foreground (string) – foreground color
• background (string) – background color

The order of additions is significant. Matching and colorization will be applied in the same order as they are added with this method.

If the passed regular expression regex is identical to an already added one (color information not considered), then that old pattern will be replaced with this one. The ordering will still be updated, so any other already present patterns will be processed before this one when matching.

>>> m = Matcher()
>>> m.add_pattern('^$', 'red')
>>> m.add_pattern('[A-Z]+', 'blue', 'white')

match(text)

Colorize text according to pattern matches.

Parameters:text (string) – string to match for colorization Return type:ColoredString instance

Returns a ColoredString which may or may not have an actual color, depending on whether any patterns matched the passed string.

Printing the instance in the terminal will show the string with its assigned colors.

>>> m = Matcher()
>>> m.add_pattern('5', 'red')
>>> colored_string = m.match('1 2 3 4 5')
>>> colored_string  
<grec....ColoredString object at 0x...>
>>> print colored_string
1 2 3 4 5

match_iter(iterable)

Return an iterator of match results.

Parameters:iterable – iterable of strings to match Return type:iterator

For each string in iterable, the returned iterator yields a ColoredString instance which is the result of performing a pattern match on the string.

>>> m = Matcher()
>>> m.add_pattern('2', 'green')
>>> for colored_string in m.match_iter(['1', '2', '3']):
...     print colored_string
1
2
3

remove_pattern(regex)

Remove the pattern with the given regular expression.

Parameters:regex (string) – regular expression of a previously added pattern

>>> m = Matcher()
>>> m.add_pattern('[A-Z]', 'blue')
>>> len(m.patterns)
1
>>> m.remove_pattern('[A-Z]')
>>> len(m.patterns)
0

class grec.grec.PatternAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Action class to handle pattern arguments with argparse.

To retain ordering between -m and -g arguments from command-line input, this class aggregates them in order into a list.

grec.grec.main(args=None)

Run grec command.

grec.grec.parse_arguments(args)

Parse command line arguments.

grec.grec.split_colors(color)

Convert color from command line into foreground and background.

Parameters:color (string) – color(s) to translate

Backgrounds can be optionally prepended by ‘on’.

>>> split_colors("yellow")
['yellow']
>>> split_colors("red_on_blue")
['red', 'blue']
>>> split_colors("green white")
['green', 'white']