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

Version
    0.2.$Rev: 50 $

Synopsis
       use Data::CloudWeights;

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

       # Add one or more tags to the cloud
       $cloud->add( $tag, $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)

   limit
    Limits the size of the returned list. Defaults to zero, no limit

   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)

   sort_field
    Select the field to sort the output by. Values are; *tag*, *count* or
    *value*. If set to *undef* the output order will be the same as the
    order of the calls to "add". If set to a code ref it will be called as a
    sort comparison subroutine and passed two tag references whose keys are
    values listed above

   sort_order
    Either *asc* for ascending or *desc* for descending sort order

   sort_type
    Either *alpha* to use the "cmp" operator or *numeric* to use the "<=>"
    operator in sorting comparisons

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

    HTML::TagCloud::Sortable
       I lifted the sorting code from here

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) 2008 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

