The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-HistogramChart-0.005
River stage zero No dependents
++
/ Text::HistogramChart

NAME

Text::HistogramChart - Make Text Histogram (Upright Bars) Charts

VERSION

Version 0.005

SYNOPSIS

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

DESCRIPTION

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.

USAGE

The following variables are available to fine tune the chart (see SYNOPSIS for an example of usage):

screen_height, horizontal_width, legend_horizontal_width

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.

write_legend Set this to 1 if you want the legend values prepended to the left edge of the chart.
write_floor_value, write_value, write_always_over_value, write_always_under_value

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.

bar_char, floor_char, over_value_char, under_value_char

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.

roof_value, bottom_value, floor_value, write_floor, use_floor

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.

DEPENDENCIES

Requires Perl version 5.008.001.

Requires the following modules:

Hash::Util

EXPORT

Text::HistogramChart is a purely object-oriented module. No exported functions.

SUBROUTINES/METHODS

new

Creator function.

chart

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.

INTERNAL SUBROUTINES

center_text

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!

AUTHOR

Mikko Koivunalho, <mikko.koivunalho at iki.fi>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::HistogramChart

You can also look for information at:

ACKNOWLEDGEMENTS

None.

DIAGNOSTICS

None.

CONFIGURATION AND ENVIRONMENT

Please see the examples.

INCOMPATIBILITIES

None known.

BUGS AND LIMITATIONS

Plenty I'm sure. Using roof_value and bottom_value together to restrict the bars into a certain scope is not yet implemented.

LICENSE AND COPYRIGHT

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.