Name
    Data::CloudWeights - Calculate values for an HTML tag cloud

Version
    0.1.$Rev: 44 $

Synopsis
       use Data::CloudWeights;

       # Create a new cloud
       my $cloud = Data::CloudWeights->new( \%cfg );

       # Add one or more tags to the cloud
       $cloud->add( $name, $count, $value );

       # Calculate the tag cloud values
       my $nimbus = $cloud->formation();

Description
    Each tag added to the cloud has a unique name to identify it, a count
    which represents the size of the tag and a value that is associated with
    the tag. The reference returned by "$cloud->formation()" is a list of
    hash refs, one hash ref per tag. In addition to the input parameters
    each hash ref contains the scaled size, the percentage of total and a
    colour value in the range hot to cold.

    The cloud typically displays the tag name and count in the calculated
    colour with a font size set equal to the scaled value in the result

Configuration and Environment
  new
       $cloud = Data::CloudWeights->new( [{] attr => value, ... [}] )

    This is a class method, the constructor for Data::CloudWeights. Options
    are passed as either a list of keyword value pairs or a hash ref.
    Options are:

   cold_colour
    The six character hex colour for the smallest count in the cloud.
    Defaults to 0000FF (blue)

   colour_pallet
    An array ref of hex colour values. If the cold_colour attribute is set
    to null then the colour values from the pallet are used instead of
    calculating the colour value from the scaled count. Defaults to twelve
    values that give an even transition from blue to red

   decimal_places
    The number of decimal places returned in the size attribute. Defaults to
    2. With the default values for high and low this lets you set the tags
    font size in ems. If set to 0 and the high/low values suitably changed
    tag font size can be set in pixies

   hot_colour
    The six character hex colour for the highest count in the cloud.
    Defaults to FF0000 (red)

   max_size
    The upper boundary value to which the highest count in the cloud is
    scaled. Defaults to 2.0 (ems)

   min_size
    The lower boundary value to which the smallest count in the cloud is
    scaled. Defaults to 0.66 (ems)

Subroutines/Methods
  add
       $cloud->add( $name, $count, $value );

    Adds the tag name, count, and value triple to the cloud. The formation
    method returns a ref to an array of hash refs. Each hash ref contains
    one of these triples and the calculated attributes. The value arg is
    optional. Passing a count of zero will do nothing but returns the
    current cumulative total count for this tag name

  formation
       $cloud->formation();

    Return a ref to an array of hash refs. The attributes of each hash ref
    are:

   colour
    Calculated or dereferenced via the pallet, this is the hex colour string
    for this tag

   count
    The supplied size for this tag. Multiple calls to the add method for the
    same tag cause these counts to accumulate

   percent
    The percentage of the total count that this tag represents

   size
    The count scaled to a value between max_size and min_size

   tag
    The supplied name for this tag

   value
    The supplied value for this tag. This is usually an href but can be any
    scalar. If multiple calls to add the same tag were made this will be an
    array ref containing each of the passed values

  _hex2dec
       $class->_hex2dec( $index, $hex_value );

    Private method converts a two character string representation of a
    number to a decimal integer in the range 0 - 255

  _calculate_temperature
       $obj->_calculate_temperature( $count );

    Private method used internally to calculate a colour value for a tag. If
    the 'hot' or 'cold' value is undefined a discreet colour value will be
    selected from the 'pallet' instead of calculating it using a continuous
    function

Diagnostics
    None

Acknowledgements
    Originally WWW::CloudCreator
        This did not let me calculate font sizes in ems

Dependencies
    Class::Accessor::Fast
    Readonly

Incompatibilities
    There are no known incompatibilities in this module.

Bugs and Limitations
    There are no known bugs in this module. Please report problems to the
    address below. Patches are welcome.

Author
    Peter Flanigan, "<Support at RoxSoft.co.uk>"

License and Copyright
    Copyright (c) 2007 Peter Flanigan. All rights reserved.

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

    This program is distributed in the hope that it will be useful, but
    WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE.