BarGraph(3)

📦

version 0.5 · 2 versions

0.5 · fedora 43 (latest)
0.5 · fedora 44

💖 NAME 💖

okay so bestie, welcome to the BarGraph(3) page — yes, it's giving manual page but make it cute. This one is all about HTML::BarGraph — generate multiset bar graphs using plain HTML. not me being obsessed with a Perl module, but here we are. 💅

✨ SYNOPSIS ✨

the vibe check: you use HTML::BarGraph; and then you call graph() with a whole list of key => value args. like this, fr fr:

       use HTML::BarGraph;

        print graph(
                    direction           => 'h',        ###  or 'v' or '|' / '-'
                    graphminsize        => 250,
                    bartype             => 'pixel',    ###  or 'html'
                    barlength           => 100,
                    barwidth            => 10 ,
                    baraspect           => .03,
                    color               => 'blue',
                    colors              => [ 'blue', 'red', 'lightblue' ],
                    pixeldir            => '/images',
                    pixelfmt            => 'PNG',
                    data                => [
                                             [ val11, val12, ... ],
                                             [ val21, val22, ... ],
                                           ],
                    tags                =>   [  one,  two, ...   ],
                    setspacer           => 0,
                    highlighttag        => [ tag1... ], ###  or tag1 (one value)
                       # OR
                    highlightpos        => [ 5, ...],   ###  or 5 (one value)
                    highlightcolor      => 'red',
                    addalt              => 1,
                    showaxistags        => 1,
                    showvalues          => 1,
                    valuesuffix         => '%',
                    valueprefix         => '=> ',
                    bordertype          => 'flat',     ### or 'reised'
                    bordercolor         => '#333333',  ### or '#RRGGBB'
                    borderwidth         => 1,
                    bgcolor             => 'bisque',   ### or '#RRGGBB'
                    textcolor           => 'black',    ### or '#RRGGBB'
                    title               => 'title',
                    titlecolor          => 'black',    ### or '#RRGGBB'
                    titlealign          => 'center',   ### or 'left' or 'right'
                    fontface            => 'sansserif',
                    ylabel              => 'randoms',
                    ylabelalign         => 'middle',   ### or 'top' or 'bottom'
                    xlabel              => 'index',
                    xlabelalign         => 'center',   ### or 'left' or 'right'
                    labeltextcolor      => 'yellow',
                    labelbgcolor        => 'black',
                  );

🎀 DESCRIPTION 🎀

so HTML::BarGraph is a module that creates graphics for one or more datasets, using plain HTML and, optionally, one-pixel images, which are stretched using the width and height attributes of the HTML img tag.

Multiple customization options are provided, such as the maximum bar length, bar colors etc. highkey a lot, bestie.

The main subroutine, graph(), returns the HTML code for a graphic, and it accepts the following parameters to define the graphic to be drawn. the way that it just hands you HTML back? iconic.

`direction`

Default: h. this arg tells you the orientation of the graphic bars — horizontal, h or -, or vertical, v or |. pick your fighter. 💅

`graphminsize`

Optional arg. It lets you specify the minimum size of the graph in the direction of bar length. this can be used to get a consistent size when multiple graphics are displayed. so iconic for layouts. ✨

`bartype`

Default: html. This arg indicates whether the color bars should be build as HTML tables with a certain width, height and bgcolor, or out of a pixel image (value pixel) "stretched" with the width and hight attributes of img tag. literally tables or pixel magic, iykyk.

`barlength`

Default: 100. This arg indicates the length of the bar (in pixels) for the maximum value to be represented in the graphic. so if your max value is 100, the longest bar is 100px, periodt.

`barwidth`

This arg indicates the width of a graphic's bar. If this arg is missing, it is calculated based on barlength and baraspect (using their default values if they are missing too). no cap.

`baraspect`

Default: 0.5. This arg indicates the aspect between the graphic bar's width and length. If both barwidth and baraspect are set, barwidth is used. so barwidth wins, okay? 👑

`color`

Default: blue. This arg indicates the default color to be used in drawing the graphic's bars for a single dataset representation (see also colors). lowkey the main character of single-dataset graphs. 💙

`colors`

Default: color. This arg should be an arrayref to a list of colors to be used in displaying the bars for multiple dataset graphs. If this arg is missing, the bars for all datasets will be displayed in color color. If the number of colors is smaller then the number of datasets to be represented, the values are "recycled". See also the Note for color argument. yes, "smaller then" — that's the original, don't come for me. 💀

`pixeldir`

Optional argument to indicate the directory where the color pixel files are located; for web scripts, this will have to be relative to the htdocs dir. This argument is ignored unless bartype is set to pixel. so if you're not in pixel mode, it's just vibes. ✨

`pixelfmt`

Default: PNG. Optional argument to indicate the graphic format of the color pixel files; the lc() of this argument's value is used as pixel file's extension (eg for PNG files, pixel files will be colorname.png. This argument is ignored unless bartype is set to pixel.

`data`

This is a required arg, and should contain the datasets to be represented in the graphic. It should be passed as arrayref of scalars (one set) or arrayrefs (multiple sets). no data, no graph, bestie. it's giving mandatory. 🫶

`tags`

If this arg is present, it should indicate the tags that should be used to identify the values in datasets. It should be an arrayref to a list of scalars, with at least that many elements as the number of elements in the largest dataset. so if your biggest dataset has 10 things, you need at least 10 tags. periodt.

`setspacer`

Default: true. If true, this arg indicate that a space should be inserted to separate the consecutive representations of datasets, for a cleaner view. It is set to false on single set representations. so multi-set gets a lil gap, single set doesn't. cute. 🎀

`highlighttag`

This arg has effect only for a single dataset representation, and only when tags is present as well (when dataset has no tags, see highlightpos). It can be an arrayref or scalar. If present, its values are compared with tags values, and in case it matches one exactly, the color of the correspondent bar will be set to highlightcolor, if specified (see below). If both highlighttag and highlightpos are specified, highlightpos is ignored. so highlighttag wins, fr fr.

`highlightpos`

This arg has effect only for a single dataset representation. It can be an arrayref or scalar. If present, the color of the correspondent 1-indexed position(s) in data will be set to highlightcolor, if specified (see below). If both highlighttag and highlightpos are specified, highlightpos is ignored. note: 1-indexed, not 0-indexed, bestie. so position 1 is the first one. 💅

`highlightcolor`

Default: red. This arg has effect only when highlighttag or highlightpos has effect (see above). it's giving spotlight. 🔥

`addalt`

Default: true. If true, the addalt attribute is added to the HTML img tag, having as value the value that is represented on the bar. so accessibility-ish, love that. ✨

`showaxistags`

Default: true. If true, tags are displayed along the base axis, if provided. so your labels show up, iykyk. 🦋

`showvalues`

Default: true. If true, the values are displayed at the end of each bar. so you can see the number, periodt. 💯

`valuesuffix`

If showvalues is true, any text string assigned to this argument will be displayed after the max value. so like % or whatever. 💖

`valueprefix`

If showvalues is true, any text string assigned to this argument will be displayed before the max value. so like => if you want. ✨

`bordertype`

Default: undef. This arg sets the type of border the whole graph will be surrounded by. Valid values are flat (a frame of borderwidth width and bordercolor color will be drawn around the graphic, using <table> on <table> technique) or reised (the border attribute of the HTML table will be set to borderwidth value) (see below). note: yes, it's reised, not raised — that's the original spelling. 💀

`bordercolor`

Default: black. This arg has effect only when bordertype is set to flat, and it indicates the color for the graph's frame). The value of this arg can be a "well-known" color name (ie white, black etc) or the RGB value, as specified in the HTML spec. so you can use white, black, etc, or an RGB value. 🎨

`borderwidth`

Default: 3 for bordertype set to flat, and 1 for reised. This arg has effect only when bordertype is set, and it indicates the width of the graph's border, in pixels. so flat gets 3 by default, reised gets 1. periodt.

`bgcolor`

Default: white. This arg indicates the background color of the graph area. See format of color args at bordercolor. so same color rules as above. 🤍

`textcolor`

Default: black. This arg indicates the font color of tags and values. so your labels and numbers, bestie. 🖤

`title`

This arg indicates a string to be displayed as the title of the graph. main character energy. 👑

`titlecolor`

Default: textcolor. This arg only has effect when title is specified, and indicates the font color of title. so if you set a title, you can color it. 🎨

`titlealign`

Default: center. This arg only has effect when title is specified, and it indicates the justification of the title on the graph. Other valid values are left and right. so center, left, or right. 💅

`fontface`

Default: TimesRoman. This arg indicates the font face to be used in the text displayed in the graph. The title is displayed using size +2, the tags and axis labels (see below) in normal size, and the max values at the head of graph bars in -1. so title is big, labels normal, max values smaller. no cap.

`xlabel`, `ylabel`

This args indicate the labels to be displayed on the base (x) and values (y) axis of the graph. Note: for a horizontal graph, the names of the axes are reversed as normal (ie the x axis is the vertical one). so if your graph is horizontal, don't get confused, bestie. 🔄

`xlabelalign`

Default: center. This arg only has effect when a xlabel is specified, and it indicates the justification of the xlabel on the graph. Other valid values are left and right. so center, left, or right. 🎀

`ylabelalign`

Default: middle. This arg only has effect when a ylabel is specified, and it indicates the justification of the ylabel on the graph. Other valid values are top and bottom. so middle, top, or bottom. ✨

`labeltextcolor`

Default: black. This arg indicates a color for the xlabel and ylabel text. so your axis labels get a color. 🖤

`labelbgcolor`

Default: bgcolor. This arg indicates a background color for the row and column that contain the xlabel and ylabel. so the label area gets a background. 🎨

🎀 TODO 🎀

okay bestie, this is the wishlist — the stuff that is not done yet but that we are manifesting. it's giving vision board, fr fr:

alternate background color for dataset rows/cols 🌈
accept a formatting string for max values (for sprintf)
"showaxis"
support same size bars: ######___ 66%
ranges in tags, and "highlighttag"/"highlightpos" to fit in a range
accept args to specify the text height for title, tags, max vals
trick so that "ALT" attrib of "IMG" tags are displayed in netscape/linux
support for negative values (1 col/row for +, 1 col/row for -)
implement an object oriented interface
use HTML table building modules?
test in IE 💀

💀 BUGS 💀

not me exposing the flaws but okay we're being honest here, transparency is the vibe:

in several cases, the bars are not perfectly aligned (left for 'h' and bottom for 'v') and the values are written on the next line for 'h' graphics
values are not middle "valigned" for 'h'/'bgcolor' graphics

no cap, these are real. know them, love them, work around them. 🙈

👑 AUTHOR 👑

this icon right here:

Vlad Podgurschi <cpan@podgurschi.org>

give them their flowers, periodt. 🌸

📜 LICENSE 📜

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

so like… go off, remix it, share it, just keep it free bestie. 💖

🦋 SEE ALSO 🦋

perl(1)

and that's a wrap on the whole page, babe 🫶 this was BarGraph(3) from perl v5.42.0, dated 2025-07-25 — you're officially caught up. go make some gorgeous lil graphs, ily, bye!! ✨🎀💅

📦 where this page comes from

fedora 43: perl-HTML-BarGraph 0.5-44.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

BarGraph(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🎀 DESCRIPTION 🎀

direction

graphminsize

bartype

barlength

barwidth

baraspect

color

colors

pixeldir

pixelfmt

data

tags

setspacer

highlighttag

highlightpos

highlightcolor

addalt

showaxistags

showvalues

valuesuffix

valueprefix

bordertype

bordercolor

borderwidth

bgcolor

textcolor

title

titlecolor

titlealign

fontface

xlabel, ylabel

xlabelalign

ylabelalign

labeltextcolor

labelbgcolor