README.rdoc in rest-graph-1.1.1 vs README.rdoc in rest-graph-1.2.0

@@ -1,61 +1,100 @@
-= rest-graph 1.1.1
+= rest-graph 1.2.0
 by Cardinal Blue ( http://cardinalblue.com )
 
 == LINKS:
 
 * {github}[http://github.com/cardinalblue/rest-graph]
 * {rubygems}[http://rubygems.org/gems/rest-graph]
 * {rdoc}[http://rdoc.info/projects/cardinalblue/rest-graph]
 
 == DESCRIPTION:
 
- super simple facebook open graph api client
+ A super simple Facebook Open Graph API client
 
 == FEATURES:
 
-* simple graph api call
-* simple fql call
-* utility to extract access_token and check sig in cookies
+* Simple Graph API call
+* Simple FQL call
+* Utility to extract access_token and check sig in cookies
 
 == SYNOPSIS:
 
+# If you feel SYNOPSIS is so hard to understand, please read
+# {examples}[http://github.com/cardinalblue/rest-graph/tree/master/example].
+
  require 'rest-graph'
 
- # every option is optional!!
+ # Every option is optional.
  rg = RestGraph.new(:access_token => '...',
                     :graph_server => 'https://graph.facebook.com/',
                     :fql_server   => 'https://api.facebook.com/',
                     :accept       => 'text/javascript',
                     :lang         => 'en-us', # this affect search
                     :auto_decode  => true,    # decode by json
                     :app_id       => '123',
-                    :secret       => '1829')
+                    :secret       => '1829',
 
+  # This handler callback is only called if auto_decode is set to true,
+  # otherwise, it's ignored.
+                    :error_handler =>
+                      lambda{ |hash| raise ::RestGraph::Error.new(hash) },
+
+  # You may want to do this in Rails to do debug logging:
+                    :log_handler =>
+                      lambda{ |duration, url|
+                        Rails.logger.debug("RestGraph "         \
+                                           "spent #{duration} " \
+                                           "requesting #{url}")
+                      })
+
+ # You may want to do redirect instead of raising exception, for example,
+ # in a Rails application, you might have this private controller method:
+ def redirect_to_authorize error = nil
+   redirect_to @rg.authorize_url(:redirect_uri => request.url)
+ end
+
+ # and you'll use that private method to do error handling:
+ def setup_rest_graph
+   @rg = RestGraph.new(:error_handler => method(:redirect_to_authorize))
+ end
+
+ # This way, you don't have to check if the token is expired or not.
+ # If the token is expired, it will automatically do authorization again.
+
+ # Other simple API call:
  rg.get('me')       # GET https://graph.facebook.com/me?access_token=...
  rg.get('4/likes')  # GET https://graph.facebook.com/4/likes?access_token=...
 
  # GET https://graph.facebook.com/search?q=taiwan&access_token=...
  rg.get('search', :q => 'taiwan')
 
  # GET https://graph.facebook.com/me?metadata=1&access_token=...
  rg.get('me', :metadata => '1')
 
- # POST https://graph.facebook.com/feed/me?message=bread%21&access_token=...
- rg.post('feed/me', :message => 'bread!')
+ # POST https://graph.facebook.com/me/feed?message=bread%21&access_token=...
+ rg.post('me/feed', :message => 'bread!')
 
  # for fully blown cookies hash
  rg = RestGraph.new(:app_id => '123', :secret => '1829')
  rg.parse_cookies!(cookies) # auto save access_token if sig checked
  rg.data['uid']             # => facebook uid
 
- # fql query, same as:
+ # FQL query, same as:
  # GET https://api.facebook.com/method/fql.query?query=
  #     SELECT+name+FROM+page+WHERE+page_id%3D%22123%22&
  #     format=json&access_token=...
  rg.fql('SELECT name FROM page WHERE page_id="123"')
 
+ # FQL multiquery, same as:
+ # GET https://api.facebook.com/method/fql.multiquery?query=
+ #     %7BSELECT+name+FROM+page+WHERE+page_id%3D%22123%22&%2C
+ #        SELECT+name+FROM+page+WHERE+page_id%3D%22456%22&%7D
+ #     format=json&access_token=...
+ rg.fql_multi(:q1 => 'SELECT name FROM page WHERE page_id="123"',
+              :q2 => 'SELECT name FROM page WHERE page_id="456"')
+
  # default setting:
  class RestGraph
    def self.default_app_id
      '456'
    end
@@ -88,10 +127,10 @@
  rg.access_token    # your access_token is now available
  rg.data['expires'] # other values as well
 
 == REQUIREMENTS:
 
-* tested with MRI 1.8.7 and 1.9.1
+* Tested with MRI 1.8.7 and 1.9.1
 * gem install rest-client
 * gem install json      (optional)
 * gem install json_pure (optional)
 * gem install rack      (optional, to parse access_token in HTTP_COOKIE)