make install    # you need to be root

Windows users without a working "make" can get nmake from:

    ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

=head1 METHODS

=head2 MAIN METHODS

=over

=item C<$captcha = Authen::Captcha-E<gt>new();>

This creates a new Captcha object.
Optionally, you can pass in a hash with configuration information.
See the method descriptions for more detail on what they mean.

=over 2

   data_folder => '/some/folder', # required
   output_folder => '/some/http/folder', # required
   expire => 300, # optional. default 300
   width =>  25, # optional. default 25
   height => 35, # optional. default 35
   images_folder => '/some/folder', # optional. default to lib dir
   keep_failures => 0, # optional, defaults to 0(false)
   debug => 0, # optional. default 0

=back

=item C<$md5sum = $captcha-E<gt>generate_code( $number_of_characters );>

Creates a captcha. Image filename is "$md5sum.png"

It can also be called in array context to retrieve the string of characters used to generate the captcha (the string the user 
is expected to respond with). This is useful for debugging.
ex.

C<($md5sum,$chars) = $captcha-E<gt>generate_code( $number_of_characters );>

=item C<$results = $captcha-E<gt>check_code($code,$md5sum);>

check for a valid submitted captcha

$code is the submitted letter combination guess from the user

$md5sum is the submitted md5sum from the user (that we gave them)

If the $code and $md5sum are correct, the image file and database entry will be removed.

If the $md5sum matches one in the database, and "keep_failures" is false (the default), the image file and database entry 
will be removed to avoid repeated attempts on the same captcha.

$results will be one of:

    1 : Passed
    0 : Code not checked (file error)
   -1 : Failed: code expired
   -2 : Failed: invalid code (not in database)
   -3 : Failed: invalid code (code does not match crypt)

=back

=head2 ACCESSOR METHODS

=over

=item C<$captcha-E<gt>data_folder( '/some/folder' );>

Required. Sets the directory to hold the flatfile database that will be used to store the current non-expired valid captcha 
md5sum's.
Must be writable by the process running the script (usually the web server user, which is usually either "apache" or "http"), 
but should not be accessable to the end user.

=item C<$captcha-E<gt>output_folder( '/some/folder' );>

Required. Sets the directory to hold the generated Captcha image files. This is usually a web accessable directory so that 
the user can view the images in here, but it doesn't have to be web accessable (you could be attaching the images to an 
e-mail for some verification, or some other Captcha implementation).
Must be writable by the process running the script (usually the web server user, which is usually either "apache" or "http").


=item C<$captcha-E<gt>images_folder( '/some/folder' );>

Optional, and may greatly affect the results... use with caution. Allows you to override the default character graphic png's 
and backgrounds with your own set of graphics. These are used in the generation of the final captcha image file. The defaults 
are held in:
    [lib install dir]/Authen/Captcha/images

=item C<$captcha-E<gt>expire( 300 );>

Optional. Sets the number of seconds this captcha will remain valid. This means that the created captcha's will not remain 
valid forever, just as long as you want them to be active. Set to an appropriate value for your application. Defaults to 300.


=item C<$captcha-E<gt>width( 25 );>

Optional. Number of pixels high for the character graphics. Defaults to 25.

=item C<$captcha-E<gt>height( 35 );>

Optional. Number of pixels wide for the character graphics. Defaults to 35.

=item C<$captcha-E<gt>keep_failures( [0|1] );>

Optional. Defaults to zero. This option controls whether or not the captcha will remain valid after a failed attempt. By 
default, we only allow one attempt to solve it. This greatly reduces the possibility that a bot could brute force a correct 
answer. Change it at your own risk.

=item C<$captcha-E<gt>debug( [0|1|2] );>

Optional.