Text::HistogramChart - Make Text Histogram (Upright Bars) Charts
Version 0.005
Text::HistogramChart creates graphical charts for terminal displays or any other display device where bitmap graphics is not available! You can supply the Y axel legend (vertical) values or Text::HistogramChart can calculate them from the input values.
require Text::HistogramChart; my $chart = Text::HistogramChart->new(); @values = (1, 2, 3, 4, 5, 4, 3, 2, 1, 0, -1, -2, -3, -4, -5, -4, -3, -2, -1, 0); @legend_values = (4, 3, 2, 1, 0, -1, -2, -3, -4); $chart->{'values'} = \@values; $chart->{'legend_values'} = \@legend_values; $chart->{'screen_height'} = 9; # (height reserved for the graph.) $chart->{'roof_value'} = 0; # (active if != 0), # Arbitrarily squeeze or extend the size (height) of bars (not screen) $chart->{'floor_value'} = 0; # (the "floor" of the chart, default: 0) $chart->{'write_floor'} = 1; # (make floor visible) $chart->{'use_floor'} = 1; # (use the floor value) $chart->{'write_floor_value'} = 1; # If value == floor_value, then write value (mostly "0"). $chart->{'write_legend'} = 1; # (Prepend legend to each row.) $chart->{'legend_horizontal_width'} = 4; # width of the space left for legend (left edge of chart) $chart->{'horizontal_width'} = 2; # Horizontal width of one bar. This parameter directly influences the width of the screen (i.e. chart). $chart->{'write_value'} = 1; # (YES = 1, NO = 0, default: no; write the value on the end of the bar), $chart->{'write_always_over_value'} = 0; # (YES = 1, NO = 0, default: yes; write the value only if it is too high for the graph), $chart->{'write_always_under_value'} = 0; # (YES = 1, NO = 0, default: yes; write the value only if it is too low for the graph), $chart->{'bar_char'} = '|'; # (default: '|') $chart->{'floor_char'} = '-'; # (default '-' ) $chart->{'over_value_char'} = '+'; # (default: '+') $chart->{'under_value_char'} = '_'; # (default: '-' ) $rval = $chart->chart(); if($rval >= 1) { my @ready_chart = @{$chart->{'screen'}}; print (join '\n', @ready_chart) . "\n"; } else { print "Error in creating chart: " . $chart->error_string . "\n"; } # Result: # 4 4 5 4 # 3 3 | | | 3 # 2 2 | | | | | 2 # 1 1 | | | | | | | 1 # 0 ------------------0 ------------------0 # -1 -1| | | | | | | -1 # -2 -2| | | | | -2 # -3 -3| | | -3 # -4 -4-5-4
Text::HistogramChart creates graphical charts for terminal displays or any other display device where bitmap graphics is not available or desired! You can supply the Y axel legend (vertical) values or Text::HistogramChart can calculate them from the input values.
The following variables are available to fine tune the chart (see SYNOPSIS for an example of usage):
The 'screen' is the area in which the chart is drawn. The size is defined with three variables. screen_height is the absolute Y-axis height in character rows. horizontal_width is the number of characters used for one bar (one value). If you have 10 values and horizontal_width is 3, then the length of the screen (the X-axis) is 10 * 3 = 30 characters (without legend). Use legend_horizontal_width to define the legend width. The default for both is 5 characters. Screen height defaults to 10 characters.
Set write_value to 1 if you want the value of each bar written to the top (or bottom if the value is negative). Set write_always_over_value and write_always_under_value to 1 if you only want want the value written when the value is greater than the maximum given legend value (or less than the minimum). Set write_floor_value to 1 if you want the value written when it equals to 'floor', normally when the value is 0.
These variables define the characters used for writing the chart over_value_char and under_value_char are used when the value is off the scale (too big or too small). floor_char is the horizontal line usually at 0. bar_char is the normal 'bar'.
Any of these charaters can be more than one character is size. If you want "fatter" vertical bars, just set bar_char to '||'. Remember to set the other values to double digits as well.
With roof_value and bottom_value you can restrict the chart into a certain 'height'. E.g. you are measuring the CPU performance of a server. The performance is usually between 70% and 95% of total capacity. To show the occasional drops to 0%-70% is a waste of (terminal) space. So you set roof_value to 95 and bottom_value to 70. This feature not yet implemented. Set write_floor to 1 if you want a horizontal bar across the screen at 0.
Requires Perl version 5.008.001.
Requires the following modules:
Text::HistogramChart is a purely object-oriented module. No exported functions.
Creator function.
Create the chart. Writes the ready chart into $self->{'screen'}. The ready chart is an array of strings without linefeed. Returns >= 1, if successful, else $self->{'error_string'} contains the error.
Center a string into a string buffer. Return the buffer. Parameters: text to be centered, field width, fill character (default: " "), start direction (default: left). If text is longer than field width, it is not truncated!
Mikko Koivunalho, <mikko.koivunalho at iki.fi>
<mikko.koivunalho at iki.fi>
Please report any bugs or feature requests to bug-text-histogram at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-HistogramChart. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-text-histogram at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Text::HistogramChart
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-HistogramChart
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Text-HistogramChart
CPAN Ratings
http://cpanratings.perl.org/d/Text-HistogramChart
Search CPAN
http://search.cpan.org/dist/Text-HistogramChart/
None.
Please see the examples.
None known.
Plenty I'm sure. Using roof_value and bottom_value together to restrict the bars into a certain scope is not yet implemented.
Copyright 2012 Mikko Koivunalho.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Text::HistogramChart, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::HistogramChart
CPAN shell
perl -MCPAN -e shell install Text::HistogramChart
For more information on module installation, please visit the detailed CPAN module installation guide.