NAME
    Number::Stars - Class for conversion between percent number to star
    visualization.

SYNOPSIS
     use Number::Stars;

     my $obj = Number::Stars->new(%params);
     my $stars_hr = $obj->percent_stars($percent);

METHODS
  "new"
     my $obj = Number::Stars->new(%params);

    Constructor.

    *       "number_of_stars"

            Number of stars.

            Default value is 10.

    Returns instance of object.

  "percent_stars"
     my $stars_hr = $obj->percent_stars($percent);

    Get stars structure for setting of star visualisation. (e.g.: 50% →
    ★★★★★☆☆☆☆☆) Output structure is defined by number of star and its value.
    Possible values are: 'nothing', 'half' and 'full', which define type of
    star.

    Returns reference to hash.

ERRORS
     new():
             From Class::Utils::set_params():
                     Unknown parameter '%s'.
             From Mo::utils::check_number():
                     Parameter 'number_of_stars' must be a number.
                             Value: %s

EXAMPLE1
     use strict;
     use warnings;

     use Number::Stars;
     use Data::Printer;

     if (@ARGV < 1) {
            print STDERR "Usage: $0 percent\n";
            exit 1;
     }
     my $percent = $ARGV[0];

     # Object.
     my $obj = Number::Stars->new;

     # Get structure.
     my $stars_hr = $obj->percent_stars($percent);

     # Print out.
     print "Percent: $percent\n";
     print "Output structure:\n";
     p $stars_hr;

     # Output for run without arguments:
     # Usage: __SCRIPT__ percent

     # Output for value '55':
     # Percent: 55
     # Output structure:
     # \ {
     #     1    "full",
     #     2    "full",
     #     3    "full",
     #     4    "full",
     #     5    "full",
     #     6    "half",
     #     7    "nothing",
     #     8    "nothing",
     #     9    "nothing",
     #     10   "nothing"
     # }

EXAMPLE2
     use strict;
     use warnings;

     use Number::Stars;
     use Readonly;
     use Unicode::UTF8 qw(decode_utf8 encode_utf8);

     Readonly::Scalar our $FULL_STAR => decode_utf8('★');
     Readonly::Scalar our $HALF_STAR => decode_utf8('⭒');
     Readonly::Scalar our $NOTHING_STAR => decode_utf8('☆');

     if (@ARGV < 1) {
            print STDERR "Usage: $0 percent\n";
            exit 1;
     }
     my $percent = $ARGV[0];

     # Object.
     my $obj = Number::Stars->new;

     # Get structure.
     my $stars_hr = $obj->percent_stars($percent);

     my $output;
     foreach my $star_num (sort { $a <=> $b } keys %{$stars_hr}) {
           if ($stars_hr->{$star_num} eq 'full') {
                   $output .= $FULL_STAR;
           } elsif ($stars_hr->{$star_num} eq 'half') {
                   $output .= $HALF_STAR;
           } elsif ($stars_hr->{$star_num} eq 'nothing') {
                   $output .= $NOTHING_STAR;
           }
     }

     # Print out.
     print "Percent: $percent\n";
     print 'Output: '.encode_utf8($output)."\n";

     # Output for run without arguments:
     # Usage: __SCRIPT__ percent

     # Output for value '55':
     # Percent: 55
     # Output: ★★★★★⭒☆☆☆☆

EXAMPLE3
     use strict;
     use warnings;

     use Number::Stars;
     use Readonly;
     use Unicode::UTF8 qw(decode_utf8 encode_utf8);

     Readonly::Scalar our $FULL_STAR => decode_utf8('★');
     Readonly::Scalar our $HALF_STAR => decode_utf8('⭒');
     Readonly::Scalar our $NOTHING_STAR => decode_utf8('☆');

     if (@ARGV < 1) {
            print STDERR "Usage: $0 number_of_stars percent [number_of_stars]\n";
            print STDERR "\tDefault value of number_of_stars is 10.\n";
            exit 1;
     }
     my $percent = $ARGV[0];
     my $number_of_stars = $ARGV[1] || 10;

     # Object.
     my $obj = Number::Stars->new(
             'number_of_stars' => $number_of_stars,
     );

     # Get structure.
     my $stars_hr = $obj->percent_stars($percent);

     my $output;
     foreach my $star_num (sort { $a <=> $b } keys %{$stars_hr}) {
           if ($stars_hr->{$star_num} eq 'full') {
                   $output .= $FULL_STAR;
           } elsif ($stars_hr->{$star_num} eq 'half') {
                   $output .= $HALF_STAR;
           } elsif ($stars_hr->{$star_num} eq 'nothing') {
                   $output .= $NOTHING_STAR;
           }
     }

     # Print out.
     print "Percent: $percent\n";
     print 'Output: '.encode_utf8($output)."\n";

     # Output for run without arguments:
     # Usage: __SCRIPT__ percent [number_of_stars]
     #         Default value of number_of_stars is 10.

     # Output for values 55, 10:
     # Percent: 55
     # Output: ★★★★★⭒☆☆☆☆

     # Output for values 55:
     # Percent: 55
     # Output: ★★★★★⭒☆☆☆☆

     # Output for values 55, 3:
     # Percent: 55
     # Output: ★⭒☆

DEPENDENCIES
    Class::Utils, Error::Pure, Mo::utils.

SEE ALSO
    Tags::HTML::Stars
        Tags helper for stars evaluation.

REPOSITORY
    <https://github.com/michal-josef-spacek/Number-Stars>

AUTHOR
    Michal Josef Špaček <mailto:skim@cpan.org>

    <http://skim.cz>

LICENSE AND COPYRIGHT
    © Michal Josef Špaček 2020-2024

    BSD 2-Clause License

VERSION
    0.04