Version 0.2.2, Timeout +some documentation love

CHANGELOG

@@ -1,4 +1,9 @@
-== 0.2.0 / 2009-09-14
+== 0.2.2 / 2009-09-14
+
+* Add a timeout to the validator
+* Give the documentation some love
+
+== 0.2.1 / 2009-09-14
 
 * Removed Ambethia namespace, and restructured classes a bit
 * Added an example rails app in the example-rails branch

README.rdoc

@@ -1,60 +1,90 @@
-= ReCAPTCHA
+= reCAPTCHA
 
 Author::    Jason L Perry (http://ambethia.com)
 Copyright:: Copyright (c) 2007 Jason L Perry
-License::   MIT
-Info::      http://ambethia.com/recaptcha/
+License::   {MIT}[http://creativecommons.org/licenses/MIT/]
+Info::      http://ambethia.com/recaptcha
 Git::       http://github.com/ambethia/recaptcha/tree/master
 Bugs::      http://github.com/ambethia/recaptcha/issues
 
-This plugin adds helpers for the ReCAPTCHA API (http://recaptcha.net/). In your views you can use
+This plugin adds helpers for the {reCAPTCHA API}[http://recaptcha.net]. In your views you can use
 the +recaptcha_tags+ method to embed the needed javascript, and you can validate in your controllers
 with +verify_recaptcha+.
 
-You'll want to add your public and private API keys in the environment variables RECAPTCHA_PUBLIC_KEY
-and RECAPTCHA_PRIVATE_KEY, respectively. You could also specify them in config/environment.rb if you
-are so inclined. Exceptions will be raised if you call these methods and the keys can't be found.
+You'll want to add your public and private API keys in the environment variables +RECAPTCHA_PUBLIC_KEY+
+and +RECAPTCHA_PRIVATE_KEY+, respectively. You could also specify them in <tt>config/environment.rb</tt> if you
+are so inclined (see below). Exceptions will be raised if you call these methods and the keys can't be found.
 
 == Rails Installation
 
-ReCaptcha for rails can be installed as a gem:
+reCAPTCHA for Rails can be installed as a gem:
 
   config.gem "ambethia-recaptcha", :lib => "recaptcha/rails", :source => "http://gems.github.com"
 
 Or, as a standard rails plugin:
 
   script/plugin install git://github.com/ambethia/recaptcha.git
 
+== Setting up your API Keys
+
+There are two ways to setup your reCAPTCHA API keys once you {obtain}[http://recaptcha.net/whyrecaptcha.html]
+a pair. You can pass in your keys as options at runtime, for example:
+
+  recaptcha_tags :public_key => '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+
+and later,
+
+  verify_recaptcha :private_key => '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+
+
+Or, preferably, you can keep your keys out of your code base by exporting the environment variables
+mentioned earlier. You might do this in the .profile/rc, or equivalent for the user running your
+application:
+
+  export RECAPTCHA_PUBLIC_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+  export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+
+If that's not your thing, and dropping things into <tt>config/environment.rb</tt> is, you can just do:
+
+  ENV['RECAPTCHA_PUBLIC_KEY']  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
+  ENV['RECAPTCHA_PRIVATE_KEY'] = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
+
 == +recaptcha_tags+
 
 Some of the options available:
 
 <tt>:ssl</tt>::         Uses secure http for captcha widget (default +false+)
 <tt>:noscript</tt>::    Include <noscript> content (default +true+)
 <tt>:display</tt>::     Takes a hash containing the +theme+ and +tabindex+ options per the API. (default +nil+)
-<tt>:public_key</tt>::  Your public API key, takes precedence over the ENV variable (default +nil+).
-<tt>:error</tt>::       Override the error in +flash[:recaptcha_error]+ (default +nil+).
+<tt>:ajax</tt>::        Render the dynamic AJAX captcha per the API. (default +false+)
+<tt>:public_key</tt>::  Your public API key, takes precedence over the ENV variable (default +nil+)
+<tt>:error</tt>::       Override the error code returned from the reCAPTCHA API (default +nil+)
+
+You can also override the html attributes for the sizes of the generated +textarea+ and +iframe+
+elements, if CSS isn't your thing. Inspect the source of +recaptcha_tags+ to see these options.
 
 == +verify_recaptcha+
 
-This method returns +true+ or +false+ after processing the parameters from the ReCAPTCHA widget. Why
+This method returns +true+ or +false+ after processing the parameters from the reCAPTCHA widget. Why
 isn't this a model validation? Because that violates MVC. Use can use it like this, or how ever you
 like. Passing in the ActiveRecord object is optional, if you do--and the captcha fails to verify--an
 error will be added to the object for you to use.
 
 Some of the options available:
 
-<tt>:model</tt>::      Model to set errors
-<tt>:message</tt>::    Custom error message
+<tt>:model</tt>::       Model to set errors
+<tt>:message</tt>::     Custom error message
+<tt>:private_key</tt>:: Your private API key, takes precedence over the ENV variable (default +nil+).
+<tt>:timeout</tt>::     The number of seconds to wait for reCAPTCHA servers before give up. (default +3+)
 
   respond_to do |format|
-    if verify_recaptcha(:model => @post, :message => 'Oh! It's error with ReCaptcha!') && @post.save
+    if verify_recaptcha(:model => @post, :message => 'Oh! It's error with reCAPTCHA!') && @post.save
       # ...
     else
       # ...
     end
   end
-  
+
 == TODO
 * Remove Rails/ActionController dependencies
 * Framework agnostic

Rakefile

@@ -4,11 +4,12 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name           = "recaptcha"
-    gem.description    = "This plugin adds helpers for the ReCAPTCHA API "
-    gem.summary        = "Helpers for the ReCAPTCHA API"
+    gem.description    = "This plugin adds helpers for the reCAPTCHA API "
+    gem.summary        = "Helpers for the reCAPTCHA API"
     gem.homepage       = "http://github.com/ambethia/recaptcha"
     gem.authors        = ["Jason L. Perry"]
     gem.email          = "jasper@ambethia.com"
+    gem.files.reject! { |fn| fn.include? ".gitignore" }
   end
 rescue LoadError
   puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"

VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

lib/recaptcha.rb

@@ -2,6 +2,15 @@
 require 'recaptcha/verify'
 
 module Recaptcha
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 2
+    TINY  = 2
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+
+
   RECAPTCHA_API_SERVER        = 'http://api.recaptcha.net';
   RECAPTCHA_API_SECURE_SERVER = 'https://api-secure.recaptcha.net';
   RECAPTCHA_VERIFY_SERVER     = 'api-verify.recaptcha.net';

recaptcha.gemspec

@@ -5,22 +5,20 @@
 
 Gem::Specification.new do |s|
   s.name = %q{recaptcha}
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason L. Perry"]
   s.date = %q{2009-09-14}
-  s.description = %q{This plugin adds helpers for the ReCAPTCHA API }
+  s.description = %q{This plugin adds helpers for the reCAPTCHA API }
   s.email = %q{jasper@ambethia.com}
   s.extra_rdoc_files = [
     "LICENSE",
      "README.rdoc"
   ]
   s.files = [
-    ".gitignore",
-     "CHANGELOG",
+    "CHANGELOG",
      "LICENSE",
-     "Manifest",
      "README.rdoc",
      "Rakefile",
      "VERSION",
@@ -38,7 +36,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Helpers for the ReCAPTCHA API}
+  s.summary = %q{Helpers for the reCAPTCHA API}
   s.test_files = [
     "test/recaptcha_test.rb",
      "test/verify_recaptcha_test.rb"