histogram.1

.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HISTOGRAM 1"
.TH HISTOGRAM 1 "2016-01-19" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
histogram \- output a bar\-graph representing frequency of inputs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Normal operation:
.PP
\&\fBhistogram\fR [\fIoptions\fR] ['\fIawk-program\fR'] [<input\-file> ...]
.PP
Provide summary usage information concerning options:
.PP
\&\fBhistogram\fR \-h
.PP
Provide detailed usage information concerning options:
.PP
\&\fBhistogram\fR \-H
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Creates a histogram of the input data, using an awk-defined filter,
and outputs to the tty a horizontal bar-graph representing the histogram.
.PP
After all \fIoptions\fR are processed, the first non-option argument is
tested to see if it is a file that exists; if not, it is treated as an
\&\fIawk-program\fR and is provided to \fBawk\fR. Otherwise, the \fIawk-program\fR
provided to awk is simply \f(CW\*(C`{print}\*(C'\fR, so that awk behaves like \fBcat\fR. All
arguments, including any awk-specific options and input-files, are
passed as arguments to awk. Standard-input is also passed to awk. The
output from awk is then read in by \fBhistogram\fR, and each input line is
grouped and counted. After all inputs have been consumed, \fBhistogram\fR
outputs a bar graph, where each output line represents one of the input
lines and the frequency of that line's occurrence in the input stream.
Unless otherwise specified (\fB\-w\fR), the entire width of the \s-1TTY\s0 is used,
with the graph for the item of highest frequency using the full line
width.  If an item is found only once, its frequency will be represented
by at least one glyph.  A threshold (\fB\-t\fR) can be set so that
only items which appear \fIn\fR times in the input will appear in the output.
.PP
The output is by default sorted in alphanumeric order by the input line,
or optionally by frequency (\fB\-q\fR) of occurrence. This output order
can be reversed (\fB\-r\fR).  Optionally, the output can display an exact
count (\fB\-c\fR) beside each graph. Unless otherwise specified (with either
\&\fB\-x\fR or \fB\-k\fR), the keys are right-aligned to a column which is the lesser of
the longest key-length or 20% of the \s-1TTY\s0 width. If the longest key is
greater than this 20%, the output for each item is split onto two lines,
one for the key and the other for the graph, but one-line output can be
forced (\fB\-x\fR, \fB\-1\fR). The graph will be scaled from 1 to the maximum 
frequency, but it can be also scaled from the minimum frequency found 
to the maximum (\fB\-m\fR). The maximum can be treated as the total number
of items found and scaled accordingly; in this case, a graph representing
this total is shown for comparison purposes (\fB\-T\fR).
.PP
An \fIawk-program\fR looks like this:
   <expression> { \fIprogram\fR }
.PP
See the \fBawk\fR manual for how to formulate \fIexpression\fR and
\&\fIprogram\fR. It's usually as simple as a regular expression. See
\&\s-1EXAMPLES\s0 below.
.SH "OPTIONS"
.IX Header "OPTIONS"
Many, some of which are passed to awk. See the output of either \-h or \-H.
The input-files, if any, are passed to awk; if none are provided, awk
will use \fBhistogram\fR's standard-input. The options \-f, \-F, \-v, and \-W are
typical awk options; \fBhistogram\fR always passes these arguments on to awk.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1AWKPATH\s0" 5
.IX Item "AWKPATH"
The path of the awk program to be used.
.IP "\s-1COLUMNS\s0" 5
.IX Item "COLUMNS"
The width of the \s-1TTY,\s0 usually changed by the shell upon \s-1SIGWINCH,\s0 but can
be overridden on the command line with B(<\-w>).
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
Zero on help and if something was output and no error.
One if there was no input from awk to be processed (grep-like behavior).
Otherwise, the error-code from awk is given.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
awk
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "Group error messages from /var/log/messages." 3
.IX Item "Group error messages from /var/log/messages."
.Vb 1
\& grep \*(Aqerror\*(Aq /var/log/messages | histogram
.Ve
.IP "Use histogram's built-in awk filter to histogram the hours of those messages:" 3
.IX Item "Use histogram's built-in awk filter to histogram the hours of those messages:"
.Vb 1
\& grep \*(Aqerror\*(Aq /var/log/messages | histogram \*(Aq{ print substr($3,1,2) "h"; }\*(Aq
.Ve
.IP "The above command, where the graph is sorted by decreasing frequency, not the hour." 3
.IX Item "The above command, where the graph is sorted by decreasing frequency, not the hour."
.Vb 1
\& grep \*(Aqerror\*(Aq /var/log/messages | histogram \-q \-r \*(Aq{ print substr($3,1,2) "h"; }\*(Aq
.Ve
.IP "Just like the first command, now grouped by hostname; sort & truncate hostnames to 10 characters." 3
.IX Item "Just like the first command, now grouped by hostname; sort & truncate hostnames to 10 characters."
.Vb 1
\& histogram \-q \-k 10 \*(Aq/error/ { print $4 }\*(Aq /var/log/messages
.Ve
.IP "Same as the previous example, but include a graph representing the total items found:" 3
.IX Item "Same as the previous example, but include a graph representing the total items found:"
.Vb 1
\& histogram \-q \-k 10 \-T \*(Aq/error/ { print $4 }\*(Aq /var/log/messages
.Ve
.IP "Same as before, but don't truncate or align the keys." 3
.IX Item "Same as before, but don't truncate or align the keys."
.Vb 1
\& histogram \-q \-T \-x \*(Aq/error/ { print $4 }\*(Aq /var/log/messages
.Ve
.SH "VERSION"
.IX Header "VERSION"
Version 1.2
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Otheus <otheus@gmail.com>
.SH "LICENSE"
.IX Header "LICENSE"
Licensed under \s-1GNU\s0 Public License (\s-1GPL\s0) 2.0 or greater.