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

Version
    Describes version v0.12.$Rev: 1 $ of Data::CloudWeights

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
    Attributes defined by this class:

    *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 3.0 (ems)

    *min_size*
       The lower boundary value to which the smallest count in the cloud is
       scaled. Defaults to 1.0 (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
  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

  BUILD
    If the "hot_colour" or "cold_colour" attributes are undefined a discreet
    colour value will be selected from the 'pallet' instead of calculating
    it using Color::Spectrum

  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 argument
    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 URI 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

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

    Color::Spectrum
       I copied the colour value manipulation code from here after this
       distribution started failing tests on 5.18

Dependencies
    Moo
    Type::Tiny

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, "<pjfl@cpan.org>"

License and Copyright
    Copyright (c) 2013 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