#--
# $Id: README.rdoc,v 1.13 2004/06/25 07:10:36 ianmacd Exp $
#++
#
#
# = Ruby/Amazon - a Ruby language interface to the Amazon Web Services API
# 
# == Introduction
# 
# Ruby/Amazon is a Ruby language library that allows programmatic access to
# the popular Amazon Web site via the REST (XML over HTTP) based Amazon Web
# Services. In addition to the original
# amazon.com[http://www.amazon.com/exec/obidos/redirect-home/calibanorg-20]
# site, the
# amazon.co.uk[http://www.amazon.co.uk/exec/obidos/redirect-home/caliban-21],
# amazon.de[http://www.amazon.de/] and amazon.co.jp[http://www.amazon.co.jp/]
# properties are also supported.
#
# Although the library is still in development, it already provides support
# for the vast majority of the AWS v3.1 API. For example, all forms of product
# search are implemented, along with the transaction details API and the
# remote shopping-cart API.
#
# Ruby/Amazon also offers advanced features not directly available via the AWS
# API, such as the ability to retrieve all results pages for a particular
# search, rather than having to deal with AWS responses of 10 results per
# page. Ruby/Amazon will even use parallel threads to improve the performance
# of such multi-page searches.
#
# Another advanced feature is the ability to cache responses returned by AWS.
# If the cache is used (as it is by default), the results of each unique
# query will be cached and used for 24 hours. The cache can be manually
# flushed of all or just the expired entries.
#
# One other useful advanced feature is the ability to determine the
# appropriate Amazon locale for a client, based on its IP address or hostname.
# This allows you to direct AWS operations to be performed within the correct
# geographical Amazon site for the given client. German clients can be made to
# operate within amazon.de, British clients sent to amazon.co.uk, etc.
#
# More features are planned for future versions, such as Amazon Web Services
# for Sellers. See the TODO file included with the software.
#
#
# == Installation
#
# Please see the INSTALL file supplied with the software for details of how to
# install Ruby/Amazon. It's very simple and involves running just a single
# script.
#
#
# == Prerequisites
#
# Before you can use this library, you need to obtain an Amazon Web Services
# developer
# token[https://associates.amazon.com/exec/panama/associates/join/developer/application.html].
#
# You should also apply for an Associates
# account[https://associates.amazon.com/exec/panama/associates/apply/]. This
# isn't strictly necessary, however. If you do not explicitly provide one, the
# Associates token belonging to the Ruby/Amazon author will be used.
#
#
# == Examples
#
# === Keyword search (just one of many available types of search)
# 
#  require 'amazon/search'
#  
#  include Amazon::Search  # don't want to have to fully qualify identifiers
#  
#  ASSOCIATES_ID = "webservices-20" # if you don't have one of these, don't
#				    # pass the second argument to Request.new
#  
#  DEV_TOKEN     = "D23XFCO2UKJY82" # your development token
#  
#  # You can grab information straight from one of the Amazon sites
#  #
#  request  = Request.new(DEV_TOKEN, ASSOCIATES_ID)  # second argument optional
#  response = request.keyword_search('ruby programming') do |product|
#               printf("Found a product:\n%s---\n", product)
#             end
#  printf("Search had unique request ID %s\n", response.args['RequestID'])
#
#  products = response.products
#  product1 = products[0]
#  puts "Properties available for the first product returned:",
#    product1.properties
#
#  # Three ways to print a property of a product:
#  #
#  puts product1.asin	        # instance variable
#  puts product1['our_price']   # feels more like a Hash
#  puts product1[:authors]      # a variation on the Hash theme
#  
#
#  # You can also pull information from a previously saved
#  # Amazon::Search::Response (which is not the same thing as using the cache
#  # -- cache access is transparent)
#  #
#  file = File.new('/path/to/my/file.xml')
#  Response.new(file) { |product| puts product }
#
#
# Hopefully, the above usage is pretty much self-explanatory. Much more than
# this can be done, however. Please see the RDoc documentation for full
# details of the Ruby/Amazon API.
#
#
# === Remote shopping cart
#
#  require 'amazon/shoppingcart'
#
#  include Amazon
#
#  DEV_TOKEN = "D23XFCO2UKJY82"	  # your development token
#  sc = ShoppingCart.new(DEV_TOKEN)
#
#  ARGV.each { |asin| sc.add_items(asin, 1) }
#
#  puts sc.purchase_url
#
# The above snippet takes a series of one or more ASINs supplied on the
# command line and adds them to a remote shopping cart. It finishes by
# displaying a purchase URL, which can be entered into a browser, causing the
# contents of the cart to be uploaded to the user's centralised Amazon
# shopping cart.
#
# If you've read the AWS documentation, you'll note from the above snippet
# that there's no need to track the shopping cart ID or the HMAC security
# token assigned by the AWS servers. This state information is tracked
# internally within each shopping-cart object. You, the programmer, need never
# worry about it.
# 
# 
# == See Also
# 
# Ultimately, the way to get the most from this library is to read the AWS
# documentation to get a feel for what is possible, and then experiment with
# this library to see how the AWS calls are mapped into the Ruby world. You
# should also review this library's RDoc documentation.
#
# Please see the Amazon Web Services
# documentation[http://www.amazon.com/gp/browse.html/103-8028883-0351026?node=3435361]
# for definitive information on the capabilities and inner workings of the AWS
# API.
# 
# 
# ---
# Author::   Ian Macdonald <mailto:ian@caliban.org>
# Version::  0.8.3
# Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]
