h1. Speak to the Web

h1. → 'webspeak'


h2. What

WebSpeak is a simple utility that allows you to access websites, or any other
HTTP based service, using a simple script that accesses the basics functions
of HTTP. WebSpeak comes with a parser, that will parse small WebSpeak scripts
and execute them. WebSpeak script is simple Ruby code, so anything you can do
in Ruby, you can also do in a WebSpeak script. WebSpeak can also be used in
console mode.

h2. Installing

<pre syntax="ruby">sudo gem install webspeak</pre>

h2. The basics

There are two applications that come with WebSpeak. The main WebSpeak
application, or parser, is called _webspeak_. There is also a handy utility
called _web_speak_listener_. The listener will accept a single HTTP request,
and output the WebSpeak script required to duplicate that request elsewhere.

The WebSpeak parser is called with a script name as a parameter. The script is
run, and whatever output the script generates will be displayed.  Optionally, 
the _--console_ flag can be given to _webspeak_ to enter console mode.  In console
mode, you can interactively 


h2. Demonstration of usage

This short script does a simple web search on Google for this plugin.

<pre syntax="ruby">
# setup our request information
host 'www.google.com'
path '/search'
param 'q' => 'webspeak'
get

# display the body
puts response.body
</pre>

This is a quick example of using the console. Note that the console is based
on IRB and you don't need to use _puts_ to output information, as IRB will
show you the result.

<pre syntax="ruby">
>> host 'www.google.com'
=> www.google.com
>> get
=> #<Net::HTTPOK:0x15607d8>
>> response.cookies
=> PREF => ID=f084b753306b7514:TM=1192998250:LM=1192998250:S=pGL2fPv7N8V7Mnql
  expires: Tue, 20-Oct-2009 20:24:10 GMT
  path: /
  domain: .google.com
</pre>


h2. Further Usage

This utility came out of a set of scripts I originally wrote to help test an
application feature to manage Paypal's Instant Payment Notification (IPN).
Paypal uses an HTTP Post to transmit IPN information. To help test and debug
the application, I wanted to mock out Paypal, and used a set of Ruby scripts
to do that. When that project was over, I moved those scripts into a less
specific, but more useful tool, and WebSpeak was born.

h2. Forum

"http://groups.google.com/group/webspeak":http://groups.google.com/group/webspeak

h2. How to submit patches

Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.

The trunk repository is <code>svn://rubyforge.org/var/svn/webspeak/trunk</code> for anonymous access.

h2. License

This code is free to use under the terms of the MIT license. 

h2. Contact

Comments are welcome. Send an email to "Darren Boyd":mailto:darren.boyd@gmail.com via the "forum":http://groups.google.com/group/webspeak