NAME

App::Tailor - easily tailor terminal output to meet your needs

VERSION

version 0.03

SYNOPSIS

#-------------------------------------------------------------------------------
# file: my-filter.pl
#-------------------------------------------------------------------------------
use App::Tailor;
use JSON::XS qw(decode_json);

# ignore lines containing /ping
ignore qr/\/ping/;

# parse JSON-encoded lines
modify qr/^{.*/ => sub{
  my $data = decode_json $_;
  my $msg  = $data->{message};
  my $ts   = $data->{timestamp};
  my $pri  = $data->{priority};
  return "[$ts] [$pri] $msg";
};

# make error lines white on red
colorize qr/\[ERROR\]/ => qw(white on_red);

# tail STDIN
tail;

#-------------------------------------------------------------------------------
# using your filter
#-------------------------------------------------------------------------------
$ tail /var/log/some-log-file | my-filter.pl

DESCRIPTION

There are a number of programs available to filter, colorize, and modify streaming output. Generating exactly the desired output often requires pipe-chaining many calls to grep, cut, cols, jq, et al, or using an inflexible config file or files, often in tandem with a long chain of piped commands.

App::Tailor makes it easier to do this by making it trivial to write quick scripts to filter, alter, and colorize output exactly as needed.

EXPORTS

ignore

Accepts a regex which, when matched, will cause a line of input to be ignored.

ignore qr/foo/;       # ignore any line containing 'foo'
ignore qr/foo(?=bar)  # ignore any line containing 'foo' followed by 'bar'

Ignored rules are applied to each line of input FIRST.

modify

Accepts a regex which, when matched, will cause a the first capture in the input to by modified. If the second argument is a string, it will replace the first capture in the matching regex. If the second argument is a function, it will be called on the first capture's matching text and its return value will replace the captured text in the line's output. For convenience, $_ is assigned to the value of the captured text.

If multiple matching rules exist, they are applied in the order in which they were defined.

modify qr/foo/ => sub{ uc $_ };   # foo => FOO
modify qr/FOO/ => 'FOOL';         # FOO => 'FOOL';

Indexed and named captures may be modified using the normal patterns, with the caveat that care must be taken to ensure that a replacement string is not interpolated as part of the definition. The rule will do a string eval on the modifier regex and modifier string so that the following will work:

# capture groups
modify qr/(a) (b)/ => sub{ "$1 -> $2" };
# interpolation is   ______^________^
# ok in a subroutine

modify qr/(a) (b)/ => '$1 -> $2'; 
# but not when the ___^________^
# replacement is a
# string

# named captures
modify qr/(?<first>a) (?<second>b)/ => sub{
  return $+{first} . ' -> ' . $+{second};
};

Modifier rules are applied to each line of input SECOND.

colorize

Accepts a regex which, when matched, will cause the entire match to be colorized using ANSI color escapes. The second argument is a list of color labels to be applied. See "Function-Interface" in Term::ANSIColor for acceptable labels.

# "foo" has fg:red, bg:white
colorize qr/foo/ => qw(red on_white);

# "foo" when followed by "bar" will become painful to look at;
# "bar" itself is not colorized.
colorize qr/foo(?=bar) => qw(bright_white on_bright_magenta);

Colorizing rules are applied to each line of input LAST.

tail

Tails an input stream. By default, reads from STDIN and prints to STDOUT, applying any rules defined with "ignore", "modify", and "colorize" to the emitted output.

Input and output streams may be overridden by passing positional parameters, both of which are optional:

tail $in, $out;

itail

Returns a function which reads from an input stream and returns lines of text after applying any rules defined with "ignore", "modify", and "colorize" to the emitted output. Returns undef when the input stream is closed.

As with "tail", the default input stream (STDIN) may be overridden.

my $tailor = itail $fh;

while (defined(my $line = $tailor->())) {
  print $line;
}

reset_rules

Clears all defined rules, resetting filtering state to initial load state.

DEBUGGING

To help with troubleshooting scripts built with App::Tailor, verbose logging may be enabled by setting the environment variable APP_TAILOR_DEBUG to a true value or by setting the value of $App::Tailor::DEBUG to a true value directly.

AUTHOR

Jeff Ober <[email protected]>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Jeff Ober.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.