recaptcha.pl -- Add reCAPTCHA functionality to a form

This module is a plugin for the SWI-Prolog HTTP/HTML framework to add reCAPTCHA functionality to a form. It works as follows:

Load library(http/recaptcha) and define the reCAPTCHA keys as described in key/2.
Create a form, typically using method('POST') and include, in addition to the data you request from the human user, the reCAPTCHA widget using e.g.,
```
\recaptcha([theme(red)])
```

In the handler of the form, you must ask for the recaptcha parameters and pass them to recaptcha_verify/2. You can do that as follows:

process_recaptcha_form(Request) :-
       recaptcha_parameters(RecapthaParams),
       http_parameters(Recaptha,
                       [ name(Name, []),
                         age(Age, []),
                         ...
                       | RecapthaParams
                       ]),
       (   recaptcha_verify(Request, RecapthaParams)
       ->  <process normal user fields>
       ;   <you are not human>
       ).

See also: - examples/demo.pl contains a fully functional demo.
Compatibility: - This library is compliant with Google recaptcha v2.

recaptcha(+Options)// is det

Display the reCAPTCHA widget. Defined options are:

theme(+Theme): Set the theme. The default theme is clean.

See also: - https://developers.google.com/recaptcha/docs/customization describes the available themes

recaptcha_parameters(-List) is det

List is a list of parameters for http_parameters/3 that is needed for recaptcha_verify/2.

recaptcha_verify(+Request, +Parameters) is semidet

Is true if the user solved the captcha correctly. Fails if the user did not solve the captcha correctly but there was no error processing the request.

Errors: - recaptcha_error(Error) is raised if there was an error processing the captcha.
See also: - https://developers.google.com/recaptcha/docs/verify lists the errors.

key(+Which, -Key) is det[multifile]

This hook must unify Key to the reCAPTCHA public key if Which us public and to the reCAPTCHA private key if Which is private.

We leave the key handling to a hook to accomodate different ways for storing and transferring the keys. A simple implementation is:

:- use_module(library(http/recaptcha)).

:- multifile recaptcha:key/2.

recaptcha:key(public,  'Public key goes here').
recaptcha:key(private, 'Private key goes here').

When missing, a reserved test key pair is used.