view release on metacpan or  search on metacpan

lib/Acme/Insult/Evil.pm  view on Meta::CPAN

package Acme::Insult::Evil 1.1 {    # https://www.freepublicapis.com/evil-insult-generator
    use v5.38;
    use HTTP::Tiny;
    use JSON::Tiny qw[decode_json];
    use URI;
    use parent 'Exporter';
    our %EXPORT_TAGS = ( all => [ our @EXPORT_OK = qw[insult] ] );
    #
    use overload '""' => sub ( $s, $u, $b ) { $s->{insult} // () };
    #
    sub _http (%params) {
        state $http
            //= HTTP::Tiny->new( default_headers => { Accept => 'application/json' }, agent => sprintf '%s/%.2f ', __PACKAGE__, our $VERSION );
        state $api //= URI->new('https://evilinsult.com/generate_insult.php');

        # API accepts languages as a param named 'lang' but returns the language in a field called 'language'... why?
        $api->query_form( type => 'json', ( defined $params{language} ? ( lang => delete $params{language} ) : () ), %params );
        my $res = $http->get($api);    # {success} is true even when advice is not found but we'll at least know when we have valid JSON
        $res->{success} ? decode_json( $res->{content} ) : ();
    }
    #
    sub insult (%args) { my $ref = _http(%args); $ref ? bless $ref, __PACKAGE__ : $ref }
}
1;
__END__

=encoding utf-8

=head1 NAME

Acme::Insult::Evil - Programmatically Generate Evil Insults

=head1 SYNOPSIS

    use Acme::Insult::Evil qw[insult];
    say insult( ); # stringify

=head1 DESCRIPTION

Acme::Insult::Evil provides 'evil' 'insulting' statements generated by the RESTful Evil Insult Generator API.

=head1 METHODS

These functions may be imported by name or with the C<:all> tag.

=head2 C<insult( [...] )>

Tear someone down.

    my $shade = insult( ); # Random insult
    print insult( language => 'fr' ); # stringify

You may request specific insults by passing parameters.

Expected parameters include:

=over

=item C<language>

Insult's language. The default is C<en>. Supported languages include: C<en>, C<fr>, C<cn>, C<ja>, C<es>, etc.

=back

On success, an insult is returned as a blessed hash reference containing the following data:

=over

=item C<active>

Boolean value. If true, the insult is part of the public API.

=item C<comment>

This often provides contextual information about the insult's source of the insult itself.

=item C<created>