The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Colorist-0.150460
River stage zero No dependents
2 ++
/ App::Colorist::Colorizer

NAME

App::Colorist::Colorizer - the brain behind App::Colorist

VERSION

version 0.150460

SYNOPSIS

  my $colorizer = App::Colorist::Colorizer->enw(
      commandset => 'mycommand',
  );
  $colorizer->run;

DESCRIPTION

This is primarily engineered as a separate module to make testing easier. However, if you want to embed a colorizer in some other program for some reason or you want to extend colorizer, this provides the tools for that as well. This is why I decided to provide documentation for this module here.

If you do provide extensions, I would love to see them. Patches are welcome.

ATTRIBUTES

configuration

This is the name of the master configuration to use. This is usually the name of the command whose output you are colorizing. Each configuration must contain at least one ruleset and one colorset configuration. See "CONFIGURATION" in App::Colorist for details on how this is used to locate the configuration files.

ruleset

This is the name of the rule set to use. See "CONFIGURATION" in App::Colorist for how rule sets are defined and located.

colorset

This is the name of the color set to use. See "CONFIGURATION" in App::Colorist for how color sets are defined and located.

include

This is an array of extra include paths to search when looking for colorist configuration files.

debug

This is mostly useful for testing the app itself. When set to a true value, the colors are not output but a numeric representation like "{12}" is output instead.

inputs

This is an array of file handles to use for input. A builder lazily sets this to an array containing only the ARGV file handle by default. If more than one file handle is passed, this will capture output of all file handles and display from each as they come.

selected_inputs

This is an IO::Select built from the list of input file handles in "inputs".

input_buffers

This is an array of strings used as input buffers. This is used with the non-blocking I/O code to store any partially read lines encountered.

output

This is the fil ehandle to use for output. A builder lazily sets this to STDOUT by default.

search_path

This contains the full search path. You do not normally want to set this yourself, but use "include" instead. It is lazily instantiated to includ the values set in "include", the value of the COLORIST_CONFIG environment variable, followed by ~/.colorist and finally /etc/colorist.

ruleset_file

This is set to the name of the actual ruleset file found by searching "search_paths" and "ruleset".

colorset_file

This is the actual colorset file found by searching "search_paths" for colorset.

colors_mtime

When the colorset file is loaded, this mtime is set to the current mtime of the file. Every time a line is colored it checks to see if the colorset file has changed and will reload it automatically if it has.

colors

This is the actual colorset configuration. It's a set of keys naming the various color names defined in the ruleset and the values are the color definitions. See "CONFIGURATION" in App::Colorist for details.

rules_mtime

Whenever the rules are loaded, this mtime is recorded. If the file changes, the rules are reloaded.

rules

This contains the actual rules. This is an array where the even number indices point to a regular expression used to match lines and group submatches. The odd indices contain an array of names matching the overall match and the group matches, which are looked up in the "colors" configuration. See "CONFIGURATION" in App::Colorist for details.

METHODS

load_colorset_file

Loads the colorset configuration using YAML.

refresh_colorset_file

Checks to see if the "colors" need to be reloaded and calls "load_colorset_file" if they do.

load_ruleset_file

Reads in the ruleset configuration using a Perl do.

refresh_ruleset_file

Checks to see if the ruleset file has changed since it's last load and calls load_ruleset_file to reload the configuration if it has.

Prints the escape code to reset everything to the terminal default.

get_fg

  my $code = $c->get_fg(10);

Returns the escape code required to change the foreground color to the given color number.

get_bg

  my $code = $self->get_bg(10);

Returns the escape code that will change the background color to the given color code.

gray

  my $number = $c->gray(10);

Given a number identifying the desired shade of gray, returns that color number. Only works on terminals supporting 256 colors.

rgb

  my $number = $c->rgb(1, 3, 4);

Given 3 numbers identifying the desired RGB color cube, returns that color number. Only works on terminals supporting 256 colors.

eval_color

  my $number = $c->eval_color('blue');
  my $number = $c->eval_color(10);
  my $number = $c->eval_color([ 8 ]);
  my $number = $c->eval_color([ 1, 2, 3 ]);

Given one of the possible color configuration types from the color set configuration, returns a color number for it.

fg

  my $code = $c->fg('blue');
  my $code = $c->fg(10);
  my $code = $c->fg([ 8 ]);
  my $code = $c->fg([ 1, 2, 3 ]);

Returns the escape code for changing the foreground color to the given color identifier.

bg

  my $code = $c->bg('blue');
  my $code = $c->bg(10);
  my $code = $c->bg([ 8 ]);
  my $code = $c->bg([ 1, 2, 3 ]);

Returns the escape code for changing the background color to the given color identifier.

c

  my $code = $c->c('rufus');

Given the name of a color defined in the colorset, returns the escape codes defined for that color to change the background and foreground as configured.

run

Runs the colorization process to colorize input and send that to the output.

readline

Given an IO::Select object, returns the first line it finds from the selected file handles. This handles all buffering on the file handles and blocks until a complete line is available. It returns only the first line that comes available. It makes no guarantees about the order the file handles will be read or processed. It does try to conserve memory and keep the buffers relatively small.

loop_and_colorize

Reads each line of input, reloads the ruleset and colorset configuration if they have changed, and calls "colorize" to add color to the input and send it to the output.

colorize

  $c->colorize('some input');

Given a line of input, this method matches the ruleset rules agains the line until it finds a match. It then applies all the colors for the line and groups defined in the colorset and outputs that line to the output file handle.

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Qubling Software LLC.

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