clide

#!/usr/bin/perl -w
# For Ed, who told me that color is for wussies. s/w/p/;

# clide - A program that takes a list of search expressions tied to color
#     sequences to use and reformats the output so that strings that matched
#     are colorized in ANSI colors according to the fg and bg specified.  Not
#     sure why there isn't already a program out there to do this.  Maybe there
#     is, just wasn't pushed hard enough.
#
# Version 0.9

# Copyright 2010, Mark Krenz <mark@suso.com>

#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see <http://www.gnu.org/licenses/>.

use Getopt::Long;
use strict;

# Handle term and int signals so that it resets the colors back to normal.
# Otherwise it will produce results that are not nice for the user.
$SIG{TERM}  = 'signal_handler';  # A normal kill command sends this.
$SIG{INT}   = 'signal_handler';  # Ctrl-C from the keyboard.

my $version_number = 0.9;

my @passed_expressions = (); # //,fg=yellow and so on.
my @definition_files = ();
my @expression_files = ();
my @general_highlights = ();
my $highlight_attributes = '';
my $gethelp = '';
my $warmfuzzy = '';
my $listcolors = 0;
my $liststyles = 0;
my $listdefinitions = 0;
my $reverse_precedence = 0;

GetOptions(
    "expression|e=s" => \@passed_expressions, # Searches passed on command line.
    "definitionfile|d=s" => \@definition_files,
    "expressionfile|f=s" => \@expression_files,
    "highlight|hl=s" => \@general_highlights,
    "highlightattributes|ha=s" => \$highlight_attributes,
    "listcolors" => \$listcolors,
    "liststyles" => \$liststyles,
    "listdefinitions" => \$listdefinitions,
    "help|h" => \$gethelp,
    "reverseprecedence|r" => \$reverse_precedence,
    "warmfuzzy|wf=s" => \$warmfuzzy
);


if ($gethelp) {
    &program_help;
    exit(0);
}

# If this is set, just do this and exit. 
if ($warmfuzzy) {
    &warmfuzzy($version_number, $warmfuzzy);
}


# Here are some initial thoughts on predefined searches. More in futher versions.
my %search_definitions = (
    'EMAIL'         => '/\b[a-z0-9:,\+_\.-]+\@[a-z0-9\.-]+\b/g',
    'URL'           =>  '/(http|ftp)s?:\/\/[^\s]+\b/g',
    'WHITESPACE'    =>  '/\b\s+\b/g',
    'DOMAIN'        =>  '/\b[a-z0-9-]+\.[a-z0-9]+\b/ig',
    'HOSTNAME'      =>  '/\b[^\b]+\.?[a-z0-9-]+\.[a-z0-9]+\b/ig',
    'HTMLTAG'       =>  '/<[^>]+>/g',
    'FILEPATH'      =>  '/\/[a-zA-Z0-9\.][^\s]*\b/g',
    'HASHCOMMENTS'  =>  '/\#.*/g',
    'CSTYLECOMMENTS'=>  '/\/*.**\//g', # single line only.
    'HTMLCOMMENTS'  =>  '/<!--.*-->/g', # single line only for now.
    'DATE'         =>  '/\b[0-9]{4}-[0-9]{2}-[0-9]{2}\b/g',
    'TIME'         =>  '/\b[0-9]{2}:[0-9]{2}:[0-9]{2}\b/g',
    'TWITTERGROUP'  =>  '/#[a-zA-Z0-9]+\b/g',
    'IDENTICAGROUP' =>  '/\![a-zA-Z0-9]+\b/g',
    'TWITTERMENTION'=>  '/\s\@[a-zA-Z0-9]+\b/g',
    'IDENTICAMENTION'=>  '/\s\@[a-zA-Z0-9]+\b/g', # same

);

my %fgcolors = (
    'black'     => 30,
    'red'       => 31,
    'green'     => 32,
    'yellow'    => 33,
    'blue'      => 34,
    'magenta'   => 35,
    'cyan'      => 36,
    'white'     => 37,
);

my %bgcolors = (
    'black'     => 40,
    'red'       => 41,
    'green'     => 42,
    'yellow'    => 43,
    'blue'      => 44,
    'magenta'   => 45,
    'cyan'      => 46,
    'white'     => 47,
);

my %styles = (
    'reset'      => 0,
    'bold'       => 1,
    'dark'       => 2,
    'underline'  => 4,
    'underscore' => 4,
    'blink'      => 5,
    'reverse'    => 7,
    'concealed'  => 8,
);

if ($listcolors) {
    print "Foreground/Background colors available: (fg=<color>,bg=<color>)\n";
    # right now there shouldn't be any difference between fg and bg.
    foreach my $key (sort keys %fgcolors) {
        print "\t$key\n";
    }
    exit(0);
}

if ($liststyles) {
    print "Styles available (some may not be supported in your terminal))\n";
    foreach my $key (sort keys %styles) {
        print "\t$key\n";
    }
    exit(0);
}

if ($listdefinitions) {
    print "Predefined search expressions (usage example: -e DEFNAME,fg=red )\n";
    printf("\t%-25s\t%-40s\n", "Name", "Pattern");
    printf("\t%-25s\t%-40s\n", '-'x25, '-'x40);
    foreach my $key (sort keys %search_definitions) {
        printf("\t%-25s\t%-40s\n", $key, $search_definitions{$key});
    }
    exit(0);
}

# Need to represent the colors as something besides their normal
# 3-4 character escape codes because a user's match expression may end
# up matching the ansi sequence itself and mess it up.
# Later we can do this in a way that's friendly towards UTF-8 and international encoding.
# But for now, we can only process 7-bit ASCII only data. We'll skip any input lines
# that have non 7-bit data.
my %shifted_styles = ();
my %rev_shifted_styles = ();
foreach my $key (keys %styles) {
    $shifted_styles{$key} = pack("C", $styles{$key}  |  128);
    $rev_shifted_styles{$shifted_styles{$key}} = $key;
}

my %shifted_fgcolors = ();
my %rev_shifted_fgcolors = ();
foreach my $key (keys %fgcolors) {
    $shifted_fgcolors{$key} = pack("C", $fgcolors{$key}  |  128);
    $rev_shifted_fgcolors{$shifted_fgcolors{$key}} = $key;
}

my %shifted_bgcolors = ();
my %rev_shifted_bgcolors = ();
foreach my $key (keys %bgcolors) {
    $shifted_bgcolors{$key} = pack("C", $bgcolors{$key}  |  128);
    $rev_shifted_bgcolors{$shifted_bgcolors{$key}} = $key;
}

# I was thinking that one way we could handle UTF at least is to use 2 of the characters
# in upper 8-bit that UTF doesn't touch (like 254 and 255) and then make a 9 character
# sequence out of those characters so that we have enough combinations to represent
# even 256 foreground and background colors and the styles.  I guess Konsole supports
# 24-bit color in terminals. Sheesh.


my $style_search_expression = join("|", keys(%styles)); # To help check if an option is valid.

# First, read in the search definitions from any files specified.
foreach my $definitionfile (@definition_files) {
    open my $dfh, "<", $definitionfile or warn "Couldn't read definition file: $!\n";
    while (<$dfh>) {
        chomp($_);
        next if ($_ =~ /^#/); # Skip comments.
        if ($_ =~ m/^([A-Z0-9]+)\s+(\/.*\/[ig]*)$/) {
            my $def = $1;
            my $exp = $2;
            $search_definitions{$1} = $2;
        } else {
            warn "Invalid definition '$_' in file $definitionfile on line $.\n";
        }
    }
    close($dfh);
}

# Instead of having two seperate repeating blocks of code for parsing expression
# We'll just read the lines of expressions that come from files into an array
# and then join that with the passed expressions (if any).
my @all_expressions = ();
foreach my $expressionfile (@expression_files) {
    open my $efh, "<", $expressionfile or warn "Couldn't read expression file: $!\n";
    while (<$efh>) {
        chomp($_);
        next if ($_ =~ /^#/); # Skip comments.
        push(@all_expressions, $_); # No validity checking, code below handles that.
    }
    close($efh);    
}

my $highlights_expression = "";
# Now make the expression for the general highlights if there are any.
if (($#general_highlights + 1) > 0) {
    unless ($highlight_attributes) {
        # This is a default that will be familiar to most people.
        $highlight_attributes = "bold,bg=yellow";
    }

    my $all_highlights_string = join(",", @general_highlights);
    # The --highlights option will take strings literally, so we need to escape any character
    # that would have meaning in PCRE.
    $all_highlights_string =~ s/([\$\^\*\(\)\+\|\[\]\.\?])/\\$1/g;
    $all_highlights_string =~ s/,/|/g;
    $highlights_expression = "/($all_highlights_string)/gi,$highlight_attributes";
    push(@all_expressions, @passed_expressions, $highlights_expression);
} else {
    push(@all_expressions, @passed_expressions);
}


# Now read all the expressions into a priority tree that we can use later per each line of input.
my %searches = ();

my $p = 0;
foreach my $expression (@all_expressions) {

    my $predefined_search = 0;
    my $search_expression = "";
    my $search_flags = "";
    my $options = "";

    #if ($expression =~ m{^(/[^/]*[^\\]*/[ig]*),(.*)$}) {  # This is what I'd like to use, but it can't match /.*\/.*/ properly.
    if ($expression =~ m/^\//) { # If expression starts with a /, that means we're doing a custom search.
        # Because PCRE is very flexible and we want to retain that flexibility, we will validate
        # The expression by assuming that the options part is fairly simple.

        #$expression =~ m{^(/.*/[ig]*),(.*)$}) { 
        $expression =~ m{^(/.*/[ig]*),([,a-z=]*)$};

        $searches{$p}{'searchexpression'} = $1;
        $searches{$p}{'options'} = $2;
    } elsif ($expression =~ m/^([A-Z]+),(.*)$/) {
        if ($search_definitions{$1}) {
            $searches{$p}{'searchexpression'} = $search_definitions{$1};
            $searches{$p}{'options'} = $2;
        } else {
            die("No such search definition: $1\n");
        }
    } else {
        die("Invalid search expression: $expression\n");
    }

    my @options_array = split(/,/, $searches{$p}{'options'});

    foreach my $option (@options_array) {
        if ($option =~ m/fg=(.*)/) {
            $searches{$p}{'fg'} = $1;
        } elsif ($option =~ m/bg=(.*)/) {
            $searches{$p}{'bg'} = $1;
        } elsif ($option =~ m/^($style_search_expression)$/) {
            $searches{$p}{'styles'}{$option} = 1;
        } else {
            die("Invalid expression option: $option\n");
        }
    }

    if ($searches{$p}{'searchexpression'} =~ m/\/([a-z]+)$/) {
        my $passedflags = $1;
        foreach my $flag (split(//, $passedflags)) {
            if ($flag !~ m/[ig]/) {  # i and g are the only pcre flags we can accept right now.
                die("Sorry, search expressions can only accept pcre 'i' and 'g' at this time.\n");
            }
        }
        $searches{$p}{'searchflags'} = $1;
    }

    $searches{$p}{'searchexpression'} =~ s/^\///;
    $searches{$p}{'searchexpression'} =~ s/\/[a-z]*$//;


    # Build the escapes before running through the data loop to save processing time.
    my $fgcolor = 0;
    my $bgcolor = 0;

    if ($searches{$p}{'fg'}) {
        $fgcolor = $shifted_fgcolors{$searches{$p}{'fg'}};
    }
    if ($searches{$p}{'bg'}) {
        $bgcolor = $shifted_bgcolors{$searches{$p}{'bg'}};
    }
    my $style_escape = "";
    foreach my $style (keys(%{$searches{$p}{'styles'}})) {
        if ($searches{$p}{'styles'}{$style} == 1) {
            $style_escape .= $shifted_styles{$style};
        }
    }

    my $fgcolor_escape = $fgcolor;
    my $bgcolor_escape = $bgcolor;

    my $total_escape = "";

    if ($style_escape) { $total_escape .= $style_escape; }
    if ($bgcolor_escape) { $total_escape .= $bgcolor_escape; }
    if ($fgcolor_escape) { $total_escape .= $fgcolor_escape; }

    $searches{$p}{'pre_escape_string'} = $total_escape;

    $p++;
}


my $reset_escape = $shifted_styles{'reset'};


while (<>) { # Never realized before, but perl's while (<>) is special in that it automatically handles multiple files or stdin in.

    # For now, if there is any upper 8-bit data in the line, just skip the line.
    # We'll try to make this program deal with that in a future version.
    if ($_ =~ m/[\x80-\xFF]/) {
        print $_;
        next;
    }

    # Now we go through the output line by line and colorize matches as found.

    # Remember that the way this works, you can't have overlapping escapes because
    # once an expression has changed the line, other expressions won't match, unless
    # of course they were setup to match the escape.
    # We could keep track of the original line.

    my @searchkeys = ();
    if ($reverse_precedence) {
        @searchkeys = sort { $searches{$a} <=> $searches{$b} } keys %searches;
    } else {
        @searchkeys = sort { $searches{$b} <=> $searches{$a} } keys %searches;
    }

    foreach my $i (@searchkeys) {

        my $search_string = $searches{$i}{'searchexpression'};
        my $search_flags = "";
        if ($searches{$i}{'searchflags'}) {
            $search_flags = $searches{$i}{'searchflags'};
        }

        my $pre_escape_string = $searches{$i}{'pre_escape_string'};


        if ($search_flags =~ m/(gi|ig)/) {
            # these first expressions will make sure that if the sub expression is in the middle of a color that
            # it will get preserved after this expression's color replacement. Pretty cool, eh?
            $_ =~ s/($search_string)/${pre_escape_string}$1${reset_escape}/gi;
        } elsif ($search_flags =~ m/g/) {
            $_ =~ s/($search_string)/${pre_escape_string}$1${reset_escape}/g;
        } elsif ($search_flags =~ m/i/) {
            $_ =~ s/($search_string)/${pre_escape_string}$1${reset_escape}/i;
        } else { # Act as if no flags where passed.
            $_ =~ s/($search_string)/${pre_escape_string}$1${reset_escape}/;
        }

    }


    # Cascading and substituting ANSI sequences is an expensive operation so we'll only do it if something was put in the line.
    if ($_ =~ m/[\x80-\xFF]/) {
        $_ = cascade_sequences($_);

        my $line_length = length($_);
        for (my $i = 0; $i < $line_length; $i++) {
            my $char = substr($_, $i, 1);

            if ($rev_shifted_styles{$char}) {
                my $escape_number = $styles{$rev_shifted_styles{$char}};
                substr($_, $i, 1, "\e[${escape_number}m");
                $line_length += 3 + length($escape_number) - 1; # We need to increase the line_length value by the number of characters we are adding.
            }

            if ($rev_shifted_fgcolors{$char}) {
                my $escape_number = $fgcolors{$rev_shifted_fgcolors{$char}};
                substr($_, $i, 1, "\e[${escape_number}m");
                $line_length += 3 + length($escape_number) - 1; # We need to increase the line_length value by the number of characters we are adding.
            }

            if ($rev_shifted_bgcolors{$char}) {
                my $escape_number = $bgcolors{$rev_shifted_bgcolors{$char}};
                substr($_, $i, 1, "\e[${escape_number}m");
                $line_length += 3 + length($escape_number) - 1; # We need to increase the line_length value by the number of characters we are adding.
            }
        }
    }
    print $_;
}

# As a last measure, printout out a reset escape code just in case something didn't work out above.
print "\e[0m";


# This function takes a string and goes through and makes sure that
# After a color/attribute gets reset, that we return back to the color/attribute
# that was active before it.
sub cascade_sequences {
    my $passed_string = shift;
    my @sequences_array = ();
    my $reset_char = chr 0x80;
    my $my_sequences = "";
    for (my $i = 0; $i < length($passed_string); $i++) {
        my $char = substr($passed_string, $i, 1);
        if ($char =~ m/[\x81-\xFF]/) {
            push(@sequences_array, $my_sequences);
            $passed_string = substr($passed_string, 0, $i) . $reset_char . substr($passed_string, $i);
            $i++;
            $my_sequences = "";
            while ($char =~ m/[\x81-\xFF]/) {
                $my_sequences .= $char;
                $i++;
                $char = substr($passed_string, $i, 1);
            }
        } elsif ($char =~ m/[\x80]/) {
            while ($char =~ m/[\x80]/) { # This will condence multiple resets in a row into one, which is probably what people want.
               $i++;
               $char = substr($passed_string, $i, 1);
            }
            # After the while above, we've moved 1 past the reset, so we need to move back one for the next for loop.
            $i--;
            $char = substr($passed_string, $i, 1);
            if (my $seq = pop(@sequences_array)) {
                # put the code for inserting the sequence back after the reset here.
                $passed_string = substr($passed_string, 0, $i + 1) . $seq . substr($passed_string, $i + 1);
                $my_sequences = $seq;
                $i += length($seq);
            } else {
                $my_sequences = "";
            }
        }

    }
    # From doing this loop, we might end up with a reset before the first character or a sequence after the last, fix that.
    $passed_string =~ s/^[\x80]+//;
    $passed_string =~ s/[\x81-\xFF]+$//;
    return $passed_string;
}




sub warmfuzzy {
    # This is like Zawinski's law in effect.
    # Send the developer a warm fuzzy to let him know that the user liked the program.
    my $version = shift;
    my $message = shift;

    my $url = 'http://suso.suso.org/warmfuzzy.cgi';
    # Create a user agent object
    if (eval { require LWP::UserAgent } ) {  # Fail nicely if the user doesn't have this module.
        my $ua = LWP::UserAgent->new;
        $ua->agent("clide/$version ");

        # Create a request
        my $req = HTTP::Request->new(POST => $url);
        $req->content_type('application/x-www-form-urlencoded');
        $req->content("appname=clide&version=$version&message=$message");
        my $res = $ua->request($req);

        # Check the outcome of the response
        if ($res->is_success) {
#            print "results of request: ", $res->content;
            print "Thanks. I wanted to have this option because I think Open Source developers\nneed more feedback from users and encouragement.\n";
        } else {
            print "Error: ", $res->status_line, "\n";
        }
    # I'd rather not have this program execute anything external, but just so that
    # everything seems more seamless, we'll go ahead and try.
    } elsif (-x '/usr/bin/curl') {
        print "Using curl to send your message. Thanks.\n";
        exec('/usr/bin/curl', '-d', 'appname=clide', '-d', "version=$version", '-d', "message=$message", $url);
    } elsif (-x '/usr/bin/wget') {
        print "Using wget to send your message. Thanks.\n";
        exec('/usr/bin/wget', '--quiet', '-O-', '--post-data', "appname=clide&version=$version&message=$message", $url); 
    } else {
        print "Well, I appreciate the sentiment, but you don't have the Perl LWP module,\ncurl or wget installed so I can't make the request.\n";
        print "Try sending feedback instead of mark\@suso.org directly.\n";
    }
    exit(0);
}




sub signal_handler {
    print "\e[0m\n";  # Make sure we reset things before exiting out so the user doesn't have to reset manually.
    exit(1);
}


sub program_help {
    print <<"EOT";
clide - color and style highlighting program for text

Usage:
  clide [options] [file1] [file2] [...fileN]
  | clide [options]  (STDIN through pipe)

Options:
  -h, --help  - this output

 (Each of these options can be used multiple times)
  -e, --expression <expression>,<attributes>
      Examples:
         -e /searchpattern/,fg=red,bold
         -e HTMLTAG,fg=blue,bg=yellow

  -d, --definitionfile <file>
  -f, --expressionfile <file>

  --highlight, --hl <word1>[,word2,word3,...]
         Quickly highlight the words specified by the comma seperated
         string you provide.

  --highlightattributes, --ha <attribute1>[,attribute2,attribute3,...]
          The default attributes used by the highlight option.
          This option uses the same comma seperate values taht
          can be defined in an normal expression.

  --listcolors - Show a list of foreground and background colors
                 that can be used.
  --liststyles - Show a list of styles that can be used (not all
                 of which may work on your display)
  --listdefinitions - Show a list of predefined search expressions

  --reverseprecedence, -r - Reverse the precedence order in which
                 expressions are run through.

  --wf, --warmfuzzy "<message>" = Send the developer a short message
                     to let him know that you like this program.

Please see the clide man page for more detailed information.
EOT
}

=pod

=head1 NAME

B<clide> - color and style highlighting program for text

=head1 SYNOPSIS

B<clide> [options] [file1] [file2] [...fileN]

B<| clide> [options] (STDIN through pipe)

B<clide> [options] (STDIN. Use Ctrl-D to finish input)


=head1 DESCRIPTION

clide is a program that allows you to colorize and add various display altering attributes to text based on search patterns
and expressions. Currently the focus is on creating ANSI color and style escape codes for use in terminal displays.

=head1 OPTIONS

  -h, --help - Show some terse help for the program

  -e, --expression <expression>,<attributes>
      Examples:
         -e /searchpattern/,fg=red,bold
         -e HTMLTAG,fg=blue,bg=yellow

  -d, --definitionfile <file>

  -f, --expressionfile <file>

  --highlight, --hl <word1>[,word2,word3,...] - Quickly highlight
     the words given in the comma seperated list of words.

  --highlightattributes, --ha <attribute1>[,attribute2,attribute3,...]
          The default attributes used by the highlight option.
          This option uses the same comma seperate values taht
          can be defined in an normal expression.

  --listcolors - Show a list of foreground and background colors
                 that can be used.

  --liststyles - Show a list of styles that can be used (not all
                 of which may work on your display)

  --listdefinitions - Show a list of predefined search expressions

  --reverseprecedence, -r - Reverse the precedence order in which
                 expressions are run through.

  --wf, --warmfuzzy "<message>" -
                Send the developer a short message to let him know that you like this program.


=head1 EXAMPLES

=head2 FILE ARGUMENTS

One way to utilize clide is to process the contents of a file or multiple
files. This is done simply by passing the files as arguments after the
other options you wish to specify for matching expressions:

 clide -e HTMLTAG,fg=yellow index.html


=head2 PIPELINES

Another way to use clide is by passing the output of one program into it.
You are sending the standard output (STDOUT) of one program to the standard
input (STDIN) of clide.  Like this command that sends the output of ls
through clide, which colors lines that are directory entries:

 ls -l | clide -e /^d.*/,fg=blue,bold


=head2 SHELL ESCAPING

If you are creating more complex search patterns, you are probably going to need
to put quotes around the whole argument that is passed to a -e option.  This
is because your shell will interpret certain characters like (, ), $, &, [, ], etc.
For example, this command uses an expression that will change the percentage
display of a filesystem to red if it is 94% or more:

 df -h | clide -e "/(100|9[4-9])%/,fg=red,bold"

But because ( ) is used in most shells as a subshell sequence, you have to put
quotes around the whole expression so that its not processed by your shell.


=head1 EXPRESSIONS

Expressions can be specified on the command line using one or more -e options.
You can also use the -f option one or more times to specify premade expression
files.

=head2 QUICK HIGHLIGHTING

If you're in a hurry and don't want to come up with an expression for matching
words or characters that you'd like to highlight, you can use the --highlight
option along with a comma seperated list of values you want to match. Like
this:

  clide --highlight car,truck,boat insurance-readme.txt

By default clide will highlight these words in yellow.  you can override
this with the --highlightattributes option, specifying what you want
in the same way you would pass attribute arguments in a -e argument.

You can use the --highlight option in combination with -e of -f options,
but the expressions will be applied after the expressions specified with
-e or -f.

=head2 PERL REGULAR EXPRESSIONS

clide works by passing the expression that you specify into a PERL matching
operator. This means that you can pass almost any valid PERL regular expression
to clide and it should work as expected.

The only limitation is in what flags you can pass to the search. Currently, you
can only pass a 'i' (case insensitive) and/or a 'g' (global search) flag to the
search expression. The multiline flag 'm' is not supported.

For more information about perl regular expressions, see the pcre(1) man page.

=head2 REGULAR EXPRESSION SEARCH

The basic way to tell clide what text you want to affect is to use the regular
expression search operator.  This is passed to the -e option along with
a command seperated list of attributes to set.

 clide -e /failed/i,fg=yellow,bg=red,bold

The above expression searches for the word failed (using the i option after the
second / means make the search case insensitive). It will change the word failed
to have a foreground color of bold yellow (bright) and a background color of red.


=head2 PREDEFINED SEARCH PATTERNS

A list of helpful predefined search patterns is included with clide to make
pattern matching easier for the user. A list of the patterns is available by
running clide with the --listdefinitions option.  You can also put your own
definitions in files and use the -f option to include them.

Using a predefined search expression is simply a matter of using its name for
the first part of the -e argument, like this:

 clide -e HOSTNAME,bold logfile.txt

WARNING: Predefined search patterns MUST use all uppercase names.  In the future
clide may have other expression functions that start with lower case letters and
there needs to be a way to differentiate between a pattern definition and an
operation.

=head1 FILE FORMATS

NOTE: The author would like to encourage you to put your expression and definition
files in a directory called .clide in your home directory. Future versions of
clide may make it easier to use these files if you have them located in such a
named directory.

=head2 EXPRESSION FILE

The expression file is pretty simple, you put each expression one per line
in exactly the same way that you would pass it to the -e option. expression
definitions can be used as the expressions themselves are parsed after all
the predefined expressions are read in.  You can include these files using
the -f option.

So an expression file called microblogging might look like this:

 HTMLTAG,fg=red,bg=black
 URL,fg=yellow,bold,underline
 TWITTERGROUP,fg=blue,bold
 # Highlight some of my MB account names
 /@(mkrenz|climagic|suso)/,fg=yellow,bg=blue,bold
 TWITTERMENTION,fg=cyan
 IDENTICAGROUP,fg=blue,bold

Then you'd use it like this:

 twidge lsrecent | clide -f ~/.clide/microblogging

Comments can be made using a # character at the beginning of the line.

=head2 DEFINITION FILE

The definition file has a bit more of a format to it. Each line has two columns
seperated by whitespace. The first column is the name of the definition in all
uppercase letters. The second column is the search expression starting with a
forward slash and terminated by a forward slash and one or more pcre flags (i or g)

 # These are IPs I'm watching out for.
 INTERESTINGIPS /\b(3\.14\.159\.26|206\.97\.64\.[29]|10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3})\b/g
 # Words I care about.
 LOGINWORDS /(error|failed|failure|success|successful)/gi

Then just include the file using -d for each file you want to include.

Note that you don't need to escape or backslash as much in the searches
when you put them in a file as compared with when you specify the pattern
on the command line. Keep this in mind if you copy and paste your expressions
into a file.

=head1 BUGS AND LIMITATIONS

Because one expression matching will actually alter the line in order to 
add the escape sequences, matching expressions that are run later may not
match what the user expects them to match because the string has changed.
This is going to be fixed in a future release.

Currently clide can only work on 7-bit ASCII text. If it encounters a line
with upper 8-bit (binary) characters, it will simply print the line with
out doing any processing on it. If you're really curious as to why, you can
read the comments in the code or ask the author. A future version of clide
may not have this limitation.

Most terminal emulators and the console itself have some limitations as to
what they can display.  Most of them don't support blinking text, only some
support dark mode, etc. This is not a limitation of clide, it is your
terminal software.

clide doesn't support multiline matching at this time.

=head1 SEE ALSO

L<pcre>

=head1 WARMFUZZY

If you like clide, you should let the author know by sending a short message
using the --warmfuzzy option, like this:

 clide --warmfuzzy "I like clide"

This option makes an HTTP request to a website that will in turn let the 
author know what you thought.

I included this option because I think that open source projects need an easier
way for users to give the developers a little reward for their efforts.

=head1 COPYRIGHT

This code is copyright 2010 by Mark Krenz under the terms of the GNU GPL version 3.
See the file COPYING that comes with clide for more details.

=head1 MORE INFO

You can find more information about clide at its website at

 L<http://suso.suso.org/xulu/clide>

If you'd like to get involved with development in any way, please feel free to contact
the author.

=head1 AUTHOR

clide was written by Mark Krenz <mark@suso.com>

=cut