Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sysread/app-tailor

Easily tailor terminal output to meet your needs with simple perl scripts
https://github.com/sysread/app-tailor

colorize console filter grep inputstream log logging outputstream perl perl5 terminal

Last synced: about 1 month ago
JSON representation

Easily tailor terminal output to meet your needs with simple perl scripts

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



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



=head1 VERSION



version 0.03



=head1 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



=head1 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.



C makes it easier to do this by making it trivial to write quick

scripts to filter, alter, and colorize output exactly as needed.



=head1 EXPORTS



=head2 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 B.



=head2 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, C<$_> 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/(?a) (?b)/ => sub{

    return $+{first} . ' -> ' . $+{second};

  };



Modifier rules are applied to each line of input B.



=head2 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 L 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 B.



=head2 tail



Tails an input stream. By default, reads from C and prints to C,

applying any rules defined with L, L, and L to the

emitted output.



Input and output streams may be overridden by passing positional parameters,

both of which are optional:



  tail $in, $out;



=head2 itail



Returns a function which reads from an input stream and returns lines of text

after applying any rules defined with L, L, and L

to the emitted output. Returns C when the input stream is closed.



As with L, the default input stream (C) may be overridden.



  my $tailor = itail $fh;



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

    print $line;

  }



=head2 reset_rules



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



=head1 DEBUGGING



To help with troubleshooting scripts built with C, verbose logging

may be enabled by setting the environment variable C to a

true value or by setting the value of C<$App::Tailor::DEBUG> to a true value

directly.



=head1 AUTHOR



Jeff Ober 



=head1 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.



=cut