File Coverage

lib/Term/Chrome.pod

Criterion	Covered	Total	%
statement	9	9	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	12	12	100.0

=encoding UTF-8

=head1 NAME

Term::Chrome - DSL for colors and other terminal chrome

=head1 SYNOPSIS

    use Term::Chrome qw;
    use feature qw; # Just for this example

    # Base color constant and attribute
    say Red, 'red text', Reset;

    # Composition, using operator overloading
    say Red/Blue+Bold, 'red on blue', Reset;

    # Extended xterm-256 colors
    say color(125) + Underline, 'Purple', Reset;

    # Define your own constants
    use constant Pink => color 213;

    # Use ${} around Chrome expression inside strings
    say "normal ${ Red+Bold } RED ${ +Reset } normal";

    # Extract components
    say( (Red/Blue)->bg, "blue text", (Green+Reset)->flags );

    # Get an efficient chromizer sub (applies given chrome before, and
    # Reset after the argument)
    my $boldifier = \&{ +Bold };
    # Use the chromizer
    say $boldifier->("bold text");

=head1 DESCRIPTION

C is a domain-specific language (DSL) for terminal decoration
(colors and other attributes).

In the current implementation stringification to ANSI sequences for C
and C is hard-coded (which means it doesn't use the L
database), but this gives optimized (short) strings.

Colors and attributes are exposed as objects that have overloading for
arithmetic operators.

=head1 EXPORTS

=head2 Functions

C)>

Build a L object with the given color number. You can use this
constructor to create your own set of color constants.

For example, C gives the same result as C (but not the same
object).

=head2 Colors

Each of these function return a Chrome object.

=over 4

=item *

C: C

=item *

C: C

=item *

C: C

=item *

C: C

=item *

C: C

=item *

C: C

=item *

C: C

=item *

C: C

=cut

# Secret: Chartreuse

=back

=head2 Decoration flags

The exact rendering of each flag is dependent on how the terminal implements
them. For example C and C may do nothing.

=over 4

=item *

C

=item *

C

=item *

C

=item *

C

=back

=head2 Special flags

=over 4

=item *

C : reset all colors and flags

=back

=head1 METHODS

Here are the methods on C objects:

=over 4

=item C

Extract the Chrome object of just the foreground color. Maybe C.

=item C

Extract the Chrome object of the just background color. Maybe C.

=item C

Extract a Chrome object of just the decoration flags. Maybe C.

=back

=head1 OVERLOADED OPERATORS

=over 4

=item C (mnemonic: "over")

Conmbine a foreground color (on the left) with a background color.

=item C<+>

Add decoration flags (on the right) to colors (on the left).

=item C<""> (stringification)

Transform the object into a sting of ANSI sequences. This is
particularly useful to directly use a Chrome object in a double quoted string.

=item C<${}> (scalar dereference)

Same result as C<""> (stringification). This operator is overloaded because
it is convenient to interpolate Chrome expressions in double-quoted strings.

Example:

    say "normal ${ Red } red ${ Reset }";

=item C<&{}> (code dereference, or "codulation")

Wrap some text with the given chrome and C.

Example:

    say Red->("red text");
    # Same result as:
    say Red, "red text", Reset;

Unfortunately perl had a bug
(L) that makes this feature not much usable in practice when applied to constants. That bug
is fixed in perl 5.21.4+.
On perl < 5.21.4 you have to wrap the chrome constant in a C:

    say do{ Red }->("red text");

This can also be used to extract a colorizer sub that will be more efficient
if you reuse it:

    my $redifier = \&{ Red };
    say $redifier->("red text");

=back

=head1 BUGS

See the warning about C<&{}> above.

=head1 SEE ALSO

Comments on each modules are opinions of the author.

=over 4

=item *

L: the same basic features (and the others should not be in
Term::ANSIColor itself but in an extension), but with an awful API I could never
even consider to use while keeping my sanity.

=item *

L

=item *

L

=item *

L or L: "The Angel's Prompt" is
the project for which C has been built. L,
the C compiler has special support for C values.

=back

=head1 TRIVIA

Did you know that I is one of the favorite color of Larry Wall?

=head1 AUTHOR

Olivier MenguE, L

=head1 COPYRIGHT & LICENSE

Copyright E 2013-2014 Olivier MenguE.

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

=cut
# vim:set et ts=8 sw=4 sts=4: