Home

Awesome

hl

CPAN License

Universal PCRE-based terminal highlighter which is compatible with older 8-color and modern 256-color terminals. It consists of a Perl module Term::Highlight that is capable of inserting ANSI terminal color escape sequences at positions calculated for specified regular expressions, and a Perl script hl that uses the module.

Table of contents

Motivational example

<p align="center"> <img src="../images/images/POE_RAVEN.png?raw=true" alt="poe_raven"/> </p>

In this example output of cat RAVEN_POE with the famous Poe's masterpiece verse is piped to hl. All words that start with capital letters (\b[A-Z]\w*) are highlighted with foreground color that corresponds to ANSI code 37 (-37) in bold typeface (-b), all single-character words (\b.\b, a and I here) are highlighted with foreground color 68 in normal typeface (-rb stands for reset bold), all non-word characters (\W) are highlighted with foreground color 119, all words that end with ing and ed (ing\b and ed\b) are highlighted with foreground color 41 and background color 23 (-23.1), all characters at column 31 ((?<=^.{30}).) are highlighted with the previously defined foreground color (41) and background color 124.

In the next command an environment variable HL_INITSTRING is defined. It contains default highlight options for hl. In this example the variable is equal to -46 that defines default foreground color for patterns. In the next command hl is not fed with specific patterns, therefore all text is highlighted with color 46. Finally, the command cat RAVEN_POE | hl 'ing\b' 'ed\b' highlights gerunds and participles with default color 46 in the Poe's masterpiece.

Installation

In the following listings prompt $ belongs to a regular user while prompt # — to a superuser.

$ perl Makefile.PL
$ make
# make install

or simply

# cpan install Term::Highlight

Highlighting rules aka snippets

Typing long highlight options like in the commands from the above example in a terminal is boring and error-prone. Hl allows reading highlight options from file .hlrc located in the home directory. Examples of such highlighting rules or snippets can be found in conf/.hlrc.

Integration with shell

Ubiquitous UNIX and Linux programs like make, diff and ack can make use of rich highlighting features of hl via their own configuration settings or dedicated shell functions. Below are shown examples of such integration that use snippets from conf/.hlrc, special settings for ack from conf/.ackrc, and various shell functions from conf/.hl_functions. To automatically enable highlighting in shell functions after login to the system, add line

. $HOME/.hl_functions

into $HOME/.bashrc.

<p align="center"> <img src="../images/images/ACK_CGREP.png?raw=true" alt="ack_cgrep"/> </p> <p align="center"> <img src="../images/images/DIFF.png?raw=true" alt="diff"/> </p> <p align="center"> <img src="../images/images/NGREP.png?raw=true" alt="ngrep"/> </p>

Grep-like functionality

hl can be used as an easy grep-like utility. Below is an example.

<p align="center"> <img src="../images/images/HLGREP.png?raw=true" alt="hlgrep"/> </p>

(hlgrep is a shell function from .hl_functions)

man hl

SYNOPSIS

hl [global-options] [[--] highlight-options [patterns] ...] [- file1 [file2] ...]

DESCRIPTION

hl reads text from list of files or standard input and prints it on terminal with specified patterns highlighted using ANSI color escape sequences. Patterns are intrinsically Perl-compatible regular expressions.

Global options are processed internally by hl whereas highlight options are passed into Term::Highlight module, therefore they should not mix. The first occurrence of an option which has not been recognized as global is regarded as beginning of highlight options. Highlight options can be explicitly separated from global options with option -- (must not be confused with option - that separates list of files from highlight options).

Global options:

Highligh options:

Highlight options apply to following them regexp patterns or to the whole text if trailing highlight options are not followed by patterns.

It is possible to define common highlight options on session level. hl supports environment variable HL_INITSTRING which value will be prepended to any highlight options given in command line.

Highlight options separators:

ENVIRONMENT VARIABLES

HL_INITSTRING

defines common highlight options which will be prepended to any highlight options given in command line. For example setting HL_INITSTRING='-21 -i' will make hl highlight patterns with color id 21 and ignore cases without explicit definition of highlight options in command line. Note: HL_INITSTRING must not contain global options!

HL_LOCATION

defines highlight options for file names and line numbers when they are printed. For example setting HL_LOCATION='-224 (?<=:)\d+$ -248' will make hl print file names with color id 248 and line numbers with color id 224.

HL_CTXDELIM

defines highlight options for context chunks delimiters (double dashes) when they are printed. For example setting HL_CTXDELIM=-248 will make hl print context chunks delimiters with color id 248.

EXAMPLES

ls | hl -b -46.1 -21 '\bw.*?\b'

reads output of command ls and highlights words that start with w in color id 21 using color id 46 for background and bold font.

FILES

~/.hlrc and ~/.hlrc_<snippet-name>

currently these files may contain only snippets that can be loaded with option -s. The format of the snippet line is

snippet name highlight_options

where snippet is a keyword, name is the name of the snippet and highlight_options contains highlight options possibly preceded by the global option -u. Here is an example of a snippet to highlight words that start with a capital letter.

snippet W -130 (?:^|[\s])[A-Z]\S+

Lines that do not match the snippet line pattern are ignored. Arguments of highlight_options are naturally split by white spaces. If you want to use white spaces inside patterns then put single quotes around the patterns. Single quote by itself must be escaped by a backslash. Too long lines can be split into multiple lines using backslashes.

Files with names containing specific snippet names are loaded before ~/.hlrc: they are supposed to declare a single snippet (perhaps with a few auxiliary snippets) to help hl start faster.

man Term::Highlight

SYNOPSIS

use Term::Highlight;
$obj = Term::Highlight->new( tagtype => $TAGTYPE, skip_nl_check => 0 );
$obj->LoadPatterns( \@ptns );
$obj->LoadArgs( \@args );
$obj->GetPatterns( );
$obj->ClearPatterns( );
$obj->Process( \$string );

DESCRIPTION

Term::Highlight is a Perl module aimed to support highlighting of regexp patterns in color terminals. It supports 256 color terminals as well as older 8 color terminals.

OPTIONS

tagtype

sets type of color tags. Only term and term-debug tag types are currently supported. If tagtype is term then boundaries of found patterns will be enclosed in ANSI terminal color escape sequence tags. If tagtype is term-debug then they will be marked by special symbolic sequences: this is supposed to use for debug purposes.

skip_nl_check

defines how to treat newlines in input lines. Set this to non-zero value if input lines do not contain newlines: this will gain a bit of speed.

EXPORTS

LoadPatterns

expects a reference to an array of references to arrays of type [ $pattern, $fg, $bold, $bg ]. Loads patterns to be processed.

LoadArgs

expects an array of references to strings. Loads patterns to be processed. This is just a convenient version of LoadPatterns. Example of array to be loaded: [ "-46", "-25.1", "-i", "\bw.*?\b", "-100" ].

GetPatterns

returns a reference to the loaded patterns.

ClearPatterns

clears the loaded patterns.

Process

expects a reference to a string. Makes substitution of color tags inside the string. Returns count of found matches.

See also

There are some articles about hl in my blog all written in Russian:

  1. Использование пользовательской подсветки команд в терминале (на примере make).
  2. Статистика, diff, подсветка.

Hl at cpan.org: hl, Term::Highlight.