=head1 SYNOPSIS

    use Data::Printer theme => 'Monokai'; # sets a theme

    my $var = ...

    p $var;                     # colored if terminal supports it
    p $var, colored => 'auto';  # same! it's the default :)
    p $var, colored => 1;       # force colored output
    p $var, colored => 0;       # NO color

    my $dump = np $var;                 # NO color
    $dump    = np $var, colored => 1;   # force colored output

=head1 Colors and Themes

=head2 Disabling Colors

Data::Printer's default color mode is 'auto', meaning it will colorize
the output only when all conditions below are met:

* There is no ANSI_COLORS_DISABLED environment variable;
* The output is going to the terminal, not just returned;
* The output handle (STDERR by default) is not being piped;
* Your terminal supports colors (most do).

To never colorize anything, just set `colored` to 0.


=head2 Customizing Colors

Setting any color to C<undef> means I<< "Don't colorize this" >>.
Otherwise, the color is a string which can be one of the following:

=head3 Named colors, Term::ANSIColor style (discouraged)

Only 8 named colors are supported:

black, red, green, yellow, blue, magenta, cyan, white

and their C<bright_XXX>, C<on_XXX> and C<on_bright_XXX> variants.

Those are provided only as backards compatibility with older versions
of Data::Printer and, because of their limitation, we encourage you
to try and use one of the other representations.

=head3 SGR Escape code (Terminal style)

You may provide any SGR escape sequence, and they will be honored
as long as you use double quotes (e.g. C<"\e[38;5;196m">). You may
use this to achieve extra control like blinking, etc. Note, however,
that some terminals may not support them.

=head3 An RGB value in one of those formats (Recommended)

    'rgb(0,255,30)'
    '#00FF3B'

B<NOTE:> There may not be a real 1:1 conversion between RGB and
terminal colors. In those cases we use approximation to achieve the
closest option.


=head2 Using Themes

For a list of all available themes:

    my @themes = Data::Printer::available_themes();

TODO: image of themes, from github.

Run C<< examples/color_themes.pl >> to see them in action on your own terminal!

=head2 Creating your own theme

You just have to create a package named C<< Data::Printer::Theme::MyTheme >>,
where C<MyTheme> is the name of your theme.

That package needs to implement a single function called `colors`, that
returns the same hash reference as a regular Data::Printer call:

    sub colors {
        return {
        }
    }

