view release on metacpan or  search on metacpan

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

package Acme::Insult::Glax 1.1 {    # https://www.freepublicapis.com/insult-api
    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 adjective] ] );
    #
    use overload '""' => sub ( $s, $u, $b ) { $s->{insult} // () };
    my $api = URI->new('https://insult.mattbas.org/api/');
    #
    sub _http ( $endpoint, %params ) {
        state $http
            //= HTTP::Tiny->new( default_headers => { Accept => 'application/json' }, agent => sprintf '%s/%.2f ', __PACKAGE__, our $VERSION );
        ( my $hey = $api->clone )->path( '/api/' . $endpoint . '.json' );
        $hey->query_form(%params);
        my $res = $http->get( $hey->as_string );    # {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( insult => %args ); $ref ? bless $ref, __PACKAGE__ : $ref }

    sub adjective ( $lang //= 'en' ) {
        my $ref = _http( adjective => ( lang => $lang ) );
        $ref ? bless $ref, __PACKAGE__ : $ref;
    }
}
1;
__END__

=encoding utf-8

=head1 NAME

Acme::Insult::Glax - Programmatically Generate Insults

=head1 SYNOPSIS

    use Acme::Insult::Glax qw[insult];
    say insult( );

=head1 DESCRIPTION

Acme::Insult::Glax provides 'insulting' statements generated by the RESTful libInsult 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( lang => 'en_corporate', who => 'John and Eric', plural => 1 );
    print insult( lang => 'en_corporate', who => 'John' );
    print insult( lang => 'en_corporate', who => 'John' );

You may request specific insults by passing parameters.

Expected parameters include:

=over

=item C<lang>

Insult's language style. Expected styles include:

=over

=item C<en>

Plain English. This is the default.

=item C<en_corporate>

English with corporate jargon inserted. Perfect for the 4:50p work email.