xref: /onnv-gate/usr/src/cmd/perl/5.8.4/distrib/lib/Pod/Text/Color.pm (revision 0:68f95e015346) 
1# Pod::Text::Color -- Convert POD data to formatted color ASCII text
2# $Id: Color.pm,v 1.4 2002/07/15 05:46:00 eagle Exp $
3#
4# Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>
5#
6# This program is free software; you may redistribute it and/or modify it
7# under the same terms as Perl itself.
8#
9# This is just a basic proof of concept.  It should later be modified to make
10# better use of color, take options changing what colors are used for what
11# text, and the like.
12
13##############################################################################
14# Modules and declarations
15##############################################################################
16
17package Pod::Text::Color;
18
19require 5.004;
20
21use Pod::Text ();
22use Term::ANSIColor qw(colored);
23
24use strict;
25use vars qw(@ISA $VERSION);
26
27@ISA = qw(Pod::Text);
28
29# Don't use the CVS revision as the version, since this module is also in Perl
30# core and too many things could munge CVS magic revision strings.  This
31# number should ideally be the same as the CVS revision in podlators, however.
32$VERSION = 1.04;
33
34
35##############################################################################
36# Overrides
37##############################################################################
38
39# Make level one headings bold.
40sub cmd_head1 {
41    my $self = shift;
42    local $_ = shift;
43    s/\s+$//;
44    $self->SUPER::cmd_head1 (colored ($_, 'bold'));
45}
46
47# Make level two headings bold.
48sub cmd_head2 {
49    my $self = shift;
50    local $_ = shift;
51    s/\s+$//;
52    $self->SUPER::cmd_head2 (colored ($_, 'bold'));
53}
54
55# Fix the various formatting codes.
56sub seq_b { return colored ($_[1], 'bold')   }
57sub seq_f { return colored ($_[1], 'cyan')   }
58sub seq_i { return colored ($_[1], 'yellow') }
59
60# Output any included code in green.
61sub output_code {
62    my ($self, $code) = @_;
63    $code = colored ($code, 'green');
64    $self->output ($code);
65}
66
67# We unfortunately have to override the wrapping code here, since the normal
68# wrapping code gets really confused by all the escape sequences.
69sub wrap {
70    my $self = shift;
71    local $_ = shift;
72    my $output = '';
73    my $spaces = ' ' x $$self{MARGIN};
74    my $width = $$self{width} - $$self{MARGIN};
75    while (length > $width) {
76        if (s/^((?:(?:\e\[[\d;]+m)?[^\n]){0,$width})\s+//
77            || s/^((?:(?:\e\[[\d;]+m)?[^\n]){$width})//) {
78            $output .= $spaces . $1 . "\n";
79        } else {
80            last;
81        }
82    }
83    $output .= $spaces . $_;
84    $output =~ s/\s+$/\n\n/;
85    $output;
86}
87
88##############################################################################
89# Module return value and documentation
90##############################################################################
91
921;
93__END__
94
95=head1 NAME
96
97Pod::Text::Color - Convert POD data to formatted color ASCII text
98
99=head1 SYNOPSIS
100
101    use Pod::Text::Color;
102    my $parser = Pod::Text::Color->new (sentence => 0, width => 78);
103
104    # Read POD from STDIN and write to STDOUT.
105    $parser->parse_from_filehandle;
106
107    # Read POD from file.pod and write to file.txt.
108    $parser->parse_from_file ('file.pod', 'file.txt');
109
110=head1 DESCRIPTION
111
112Pod::Text::Color is a simple subclass of Pod::Text that highlights output
113text using ANSI color escape sequences.  Apart from the color, it in all
114ways functions like Pod::Text.  See L<Pod::Text> for details and available
115options.
116
117Term::ANSIColor is used to get colors and therefore must be installed to use
118this module.
119
120=head1 BUGS
121
122This is just a basic proof of concept.  It should be seriously expanded to
123support configurable coloration via options passed to the constructor, and
124B<pod2text> should be taught about those.
125
126=head1 SEE ALSO
127
128L<Pod::Text>, L<Pod::Parser>
129
130The current version of this module is always available from its web site at
131L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
132Perl core distribution as of 5.6.0.
133
134=head1 AUTHOR
135
136Russ Allbery <rra@stanford.edu>.
137
138=head1 COPYRIGHT AND LICENSE
139
140Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>.
141
142This program is free software; you may redistribute it and/or modify it
143under the same terms as Perl itself.
144
145=cut
146