Add a convenience script net/twitauth to get access tokens.

Makefile.in

@@ -26,7 +26,7 @@ LOCAL_PATHS = @LOCAL_PATHS@
 PACKAGE   = Gauche-net-twitter
 
 ARCHFILES = 
-SCMFILES  = $(srcdir)/net/twitter.scm
+SCMFILES  = $(srcdir)/net/twitter.scm $(srcdir)/net/twitauth.scm
 HEADERS   = 
 
 TARGET    = $(ARCHFILES)

README

@@ -1,11 +1,74 @@
-This module is based on the code brewed among several blogs.
+This module provides an interface to Twitter API using OAuth authentication.
 
-By Saito Atsushi: http://d.hatena.ne.jp/SaitoAtsushi/20100429/1272545442
-By tana-laevatein: http://d.hatena.ne.jp/tana-laevatein/20100505/1273025284
-By sirocco634: http://d.hatena.ne.jp/sirocco634/20100605#1275743091
+Overview of steps:
+
+1. Install the package.
+
+   From tarball:
+
+     $ gauche-package install [-S root] Gauche-net-twitter-1.0.tgz
+
+   From source:
+
+     $ git clone git://github.com/shirok/Gauche-net-twitter.git
+     $ cd Gauche-net-twitter
+     $ ./DIST gen
+     $ ./configure
+     $ make
+     $ make -s check
+     $ [sudo] make install
+
+   ('-S root' option or 'sudo' may be required if you want to install
+   the package system-wide.
+
+2. Register your application at http://twitter.com/oauth_clients
+   * Check 'Client' in the Application Type question.
+   * No need to check 'Use Twitter for login' box.
+   * Save "Consumer key" and "Consumer secret" shown in the next screen.
+
+3. Let the user to grant access to his/her twitter account via your client.
+   How to handle this depends on your client.  If you (application author)
+   just want to grant your application to access *your* twitter account,
+   there's a simple script net/twitauth that handles the process.  Run
+   it as 'gosh net/twitauth'.   It asks you to type your application's
+   consumer key and consumer secret.
+
+     $ gosh net/twitauth
+     Enter consumer key: XXXXXXXXXXXXXXXXXXX
+     Enter consumer secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx
+
+   Then it shows an URL you should access by your browser.
+
+     Open the following url and type in the shown PIN.
+     https://api.twitter.com/oauth/authorize?oauth_token=XXXXXXXXXXXXXXXXXXX
+     Input PIN: 
 
+   The page asks you if you grant access to the applicatio or not.
+   If you click "Accept", it shows 7-digit PIN.   Type that PIN
+   into the above 'Input PIN' prompt.
 
-Usage:
+   Then the script shows information necessary to access to your Twitter
+   account.  Save them.
+
+   (
+    (consumer-key        . "XXXXXXXXXXXXXXXXXXXX")
+    (consumer-secret     . "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
+    (access-token        . "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
+    (access-token-secret . "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
+   )
+
+   NB: If you intend to distribute your application to others and allow
+   them to grant the application's access to their Twitter account, you
+   would want to have better UI.  You can design your interaction with
+   twitter-authenticate-client procedure described below.
+
+
+4. In your program, create a <twitter-cred> instance with the above
+   information, and use it to call Twitter API.
+
+
+
+Module API:
 
 [Module] net.twitter
 
@@ -50,4 +113,12 @@ Usage:
 
 
 
-
+Credits:
+
+This module is based on the code brewed among several blogs.
+
+By Saito Atsushi: http://d.hatena.ne.jp/SaitoAtsushi/20100429/1272545442
+By tana-laevatein: http://d.hatena.ne.jp/tana-laevatein/20100505/1273025284
+By sirocco634: http://d.hatena.ne.jp/sirocco634/20100605#1275743091
+
+

net/twitauth.scm

@@ -0,0 +1,41 @@
+;;;
+;;;  This is a convenience script to obtain access token.
+;;;  
+
+(use net.twitter)
+(use util.match)
+
+(define (usage)
+  (print "Usage: gosh net/twitauth [consumer-key consumer-secret]")
+  (print "  Without arguments, it prompts to enter the application's")
+  (print "  consumer-key and consumer-secret.")
+  (print "  After it obtains a request token, it asks the user to")
+  (print "  visit a twitter url and get a PIN shown there, and promts")
+  (print "  the user to enter the PIN.  Then it prints access-token")
+  (print "  and access-token-secret, with consumer-key and consumer-secret,")
+  (print "  to the stdout.  Copy them to your application settings to")
+  (print "  to access Twitter by the application on behalf of the user.")
+  (exit 0))
+
+(define (main args)
+  (match (cdr args)
+    [()
+     (display "Enter consumer key: ") (flush)
+     (let1 key (read-line)
+       (when (eof-object? key) (exit 1 "aborted."))
+       (display "Enter consumer secret: ") (flush)
+       (let1 secret (read-line)
+         (when (eof-object? secret) (exit 1 "aborted."))
+         (report (twitter-authenticate-client key secret))))]
+    [(key secret) (report (twitter-authenticate-client key secret))]
+    [_ (usage)])
+  0)
+
+(define (report cred)
+  (print "(")
+  (print " (consumer-key        . \""(ref cred'consumer-key)"\")")
+  (print " (consumer-secret     . \""(ref cred'consumer-secret)"\")")
+  (print " (access-token        . \""(ref cred'access-token)"\")")
+  (print " (access-token-secret . \""(ref cred'access-token-secret)"\")")
+  (print ")"))
+