- NAME
- DESCRIPTION
- BINARY APPLICATION
- SYNOPSIS
- METHODS
  - new
  - fetch
  - print
  - file
  - max_results
  - min_score
  - min_syllables
  - multi_word
  - return_raw
  - sort_by
- PRIVATE METHODS
  - _args
  - _process
  - _uri
- EXAMPLE OUTPUT (fetch())
- EXAMPLE OUTPUT (print())
- AUTHOR
- LICENSE AND COPYRIGHT

# NAME

Word::Rhymes - Takes a word and fetches rhyming matches from RhymeZone.com

# DESCRIPTION

Provides the ability to fetch words that rhyme with a word, while allowing for context if desired (eg. find all words that rhyme with baseball that relate to breakfast).

Ability to change sort order, minimum rhyme match score, maximum number of words returned etc.

# BINARY APPLICATION

We've conveniently installed a pre-written program that uses this library to get you up and running right away.

See rhyme

# SYNOPSIS

        use Word::Rhymes;

        my $wr = Word::Rhymes->new;

        # Simply display the output

        $wr->print('disdain');

        # Print all matching rhyming words that have three syllables

        my $rhyming_words = $wr->fetch('disdain');
        print "$_\n" for @{ $rhyming_words->{3} };

        # With context (rhymes with 'disdain', but only words relating to 'farm')

        $rhyming_words = $wr->fetch('disdain', 'farm');

# METHODS

## new

Instantiates and returns a new Word::Rhymes object.

Parameters:

All parameters are passed in within a hash, and are every one of them optional.

The parameters have an associated setter/getter method, so to see details for each parameter, follow through to the relevant method documentation.

        file => $filename

Used mainly for testing. Allows you to re-use existing, saved data. See "file".

        max_results => $integer

Sets the maximum number of rhyming words that'll be fetched over the Internet. See "max_results".

        min_score => $integer

We ignore rhyming words with a score less than what you set here. See "min_score".

        min_syllables => $integer

Ignore rhyming words with less than the set number of syllables. See "min_syllables".

        multi_word => $bool

By default, we ignore rhyming "words" that have more than one word (ie. a phrase). You can use this parameter to include them. See "multi_word".

        return_raw => $bool

Set to true to get returned via "fetch" the data prior to all filtering and manipulation taking place. Used primarily for development and testing. See "return_raw".

        sort_by => $string

Sort by `score_desc` (default), `score_asc`, `alpha_asc` or `alpha_desc`. See "sort_by".

Returns: Word::Rhymes object.

## fetch

Performs the fetching of the rhyming words.

Parameters:

        $word

Mandatory, String: The word that'll be used to find rhyming matches to.

        $context

Optional, String: This word is used to surround the rhyming words with context. For example, if `$word` is `animal` and `$context` is `zoo`, we'll fetch words that rhyme with animal but that are only related to a zoo somehow.

Returns: A hash reference where the keys are the number of syllables in the rhyming words, and the values are array reference with the ordered data structure containing the word, the number of syllables and the score.

See "EXAMPLE OUTPUT (fetch())" for a real world example.

## print

This method will display to the screen instead of returning results which is what "fetch" is used for.

Parameters:

        $word

Mandatory, String: The word that'll be used to find rhyming matches to.

        $context

Optional, String: This word is used to surround the rhyming words with context. For example, if `$word` is `animal` and `$context` is `zoo`, we'll fetch words that rhyme with animal but that are only related to a zoo somehow.

Returns: 0 upon success.

See "EXAMPLE OUTPUT (print())" for a real world example.

## file

Used primarily for development and testing, allows you to skip fetching results from the Internet, and instead fetches the data from a pre-saved file.

Parameters:

        $file

Optional, String: The name of a pre-existing file.

Default: Empty string.

Returns: The name of the file if set, empty string otherwise.

## max_results

Sets the maximum number of rhyming words to fetch over the Internet.

Parameters:

        $max

Optional, Integer: An integer in the range of 1-1000.

Default: 1000

Returns: Integer, the currently set value.

## min_score

We will only return rhyming words with a score higher than the number set here.

Parameters:

        $min

Optional, Integer: An integer in the range of 0-1000000.

Default: 0

Returns: Integer, the currently set value.

## min_syllables

We will only return rhyming words with a syllable count equal to or higher than the number set here.

Parameters:

        $min

Optional, Integer: An integer in the range of 1-100 (yeah, I haven't heard of a word with 100 syllables either, but I digress).

Default: 1

Returns: Integer, the currently set value.

## multi_word

Some rhyming words are actually multi-word phrases. By default, we skip over these. Set this to a true value to have the multi worded rhyming words included in the results.

Parameters:

        $bool

Optional, Bool: Set to true to include multi-words, and false to skip over them.

Default: 0 (false)

Returns: Bool, the currently set value.

## return_raw

Used primarily for development and testing. Set to true to have "fetch" return the results as they were received, prior to any other processing.

Parameters:

        $bool

Optional, Bool: Set to true to have the results returned before any processing occurs.

Default: 0 (false)

Returns: Bool, the currently set value.

## sort_by

This method allows you to modify the sorting of the rhyming words prior to them being returned.

Parameters:

        $sort_order

Optional, String: The values for the parameter are as such:

        score_desc

The rhyming words will be sorted according to score, in a descending order (ie. highest to lowest). This is the default.

        score_asc

Return the rhyming words in ascending score order (ie. lowest to highest).

        alpha_desc

Return the rhyming words in alphabetical descending order (ie. a-z).

        alpha_asc

Return the rhyming words in alphabetical ascending order (ie. z-a).

Default: `score_desc` (0x00).

Returns: Integer, the currently set value:

        score_desc:     0x00
        score_asc:      0x01
        ascii_desc:     0x02
        ascii_asc:      0x03

# PRIVATE METHODS

## _args

Handles the processing of parameters sent into "new". See that documentation for details on the various valid parameters.

## _process

Called by "fetch", processes the data retrieved from RhymeZone.com.

## _uri

Generates and returns the appropriate URL for the RhymeZone.com REST API.

# EXAMPLE OUTPUT (fetch())

        use warnings;
        use strict;

        use Data::Dumper;
        use Words::Rhyme;

        my $wr->new;

        print Dumper $wr->fetch('organize');

        # Several entries snipped for brevity

        $VAR1 = {
            '5' => [
                {
                    'score' => 778,
                    'word' => 'materialize',
                    'numSyllables' => 5
                },
                {
                    'numSyllables' => 5,
                    'score' => 399,
                    'word' => 'compartmentalize'
                },
            ],
            '2' => [
                {
                    'numSyllables' => 2,
                    'word' => 'arise',
                    'score' => 36368
                },
                {
                    'numSyllables' => 2,
                    'score' => 3444,
                    'word' => 'advise'
                },
            ],
            '7' => [
                {
                    'numSyllables' => 7,
                    'word' => 'deinstitutionalize',
                    'score' => 81
                }
            ],
            '3' => [
                {
                    'score' => 3888,
                    'word' => 'analyze',
                    'numSyllables' => 3
                },
            ],
            '4' => [
                {
                    'score' => 1547,
                    'word' => 'apologize',
                    'numSyllables' => 4
                },
            ],
            '1' => [
                {
                    'score' => 3483,
                    'word' => 'rise',
                    'numSyllables' => 1
                },
            ]
        };

# EXAMPLE OUTPUT (print())

        use warnings;
        use strict;

        use Word::Rhymes;

        my $wr = Word::Rhymes->new;

        print $wr->print('organize');

        # Below output significantly reduced for brevity

        Rhymes with 'organize'

        Syllables: 7

            deinstitutionalize

        Syllables: 6

            editorialize      undercapitalize

        Syllables: 5

            materialize        compartmentalize   memorialize        sensationalize
            decriminalize      overemphasize      demilitarize       denationalize

        Syllables: 4

            apologize        proselytize      prioritize       capitalize
            marginalize      antagonize       metastasize      hypothesize

        Syllables: 3

            analyze        compromise     exercise       enterprise     otherwise
            emphasize      galvanize      improvise      utilize        scrutinize

        Syllables: 2

            arise        advise       comprise     demise       surmise
            franchise    surprise     disguise     reprise      revise

        Syllables: 1

            rise     mize     wise     eyes     size     prize    guise    flies

# AUTHOR

Steve Bertrand, `<steveb at cpan.org>`

# LICENSE AND COPYRIGHT

Copyright 2020 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0