ruby-aaws 0.6.0 → 0.7.0

data/INSTALL

@@ -0,0 +1,260 @@
+$Id: INSTALL,v 1.9 2009/06/15 12:17:56 ianmacd Exp $
+
+Requirements
+------------
+
+Ruby/AWS depends on Ruby 1.8.7 or later in the 1.8 series. It has also been
+tested to work with Ruby 1.9.1p129, the latest in the 1.9 series at the time
+of writing.
+
+You will also need at least version 0.9.8 of the OpenSSL libraries in order to
+use the the signature authentication code.
+
+
+Installation
+------------
+
+There are two ways to install Ruby/AWS.
+
+The standard way, which requires no extra software, uses Minero Aoki's
+setup.rb script. Extensive documentation for this script can be found at the
+end of this document.
+
+The following commands should be enough to install the package:
+
+  $ ruby setup.rb config
+  $ ruby setup.rb setup
+  # ruby setup.rb install
+
+  ("#" line may require root privilege)
+
+Alternatively, the RubyGems packaging system may be used:
+
+  $ wget http://www.caliban.org/files/ruby/ruby-aaws-x.x.x.gem
+  # gem install ruby-aaws-x.x.x.gem
+
+  ("#" line may require root privilege)
+
+Or even just:
+
+  # gem install ruby-aaws
+
+  ("#" line may require root privilege)
+
+See http://www.rubygems.org/ for more information on using RubyGems.
+
+
+Documentation
+-------------
+
+To create HTML documentation for Ruby/AWS, use rdoc as follows:
+
+  $ rdoc -SUx CVS lib
+
+rdoc has been bundled with Ruby since 1.8.1.
+
+
+
+-----------------------------------------------------------------------------
+
+Full instructions for setup.rb:
+
+Details
+-------
+    
+  Usage of install.rb/setup.rb is:
+
+      ruby install.rb <global options>
+      ruby install.rb [<global options>] <task> [<task options>]
+
+    
+    -q,--quiet
+        suppress message outputs
+    --verbose
+        output messages verbosely (default)
+    -h,--help
+        prints help and quit
+    -v,--version
+        prints version and quit
+    --copyright
+        prints copyright and quit
+    
+  These are acceptable tasks:
+    config
+        saves configurations
+    show
+        prints current configurations
+    setup
+        compiles extentions
+    install
+        installs files
+    clean
+        cleans created files
+    
+  Task Options for Config
+  -----------------------
+    
+    --prefix=PATH
+        a prefix of the installing directory path
+    --std-ruby=PATH
+        the directory for standard ruby libraries
+    --site-ruby-common=PATH
+        the directory for version-independent non-standard
+        ruby libraries
+    --site-ruby=PATH
+        the directory for non-standard ruby libraries
+    --bin-dir=PATH
+        the directory for commands
+    --rb-dir=PATH
+        the directory for ruby scripts
+    --so-dir=PATH
+        the directory for ruby extentions
+    --data-dir=PATH
+        the directory for shared data
+    --ruby-path=PATH
+        path to set to #! line
+    --ruby-prog=PATH
+        the ruby program using for installation
+    --make-prog=NAME
+        the make program to compile ruby extentions
+    --without-ext
+        forces to install.rb never to compile/install
+        ruby extentions.
+    --rbconfig=PATH
+        your rbconfig.rb to load
+    
+  You can view default values of these options by typing
+
+      $ ruby install.rb --help
+
+    
+  In addition, setup.rb accepts these options:
+    --with=NAME,NAME,NAME...
+        package names which you want to install
+    --without=NAME,NAME,NAME...
+        package names which you do not want to install
+    
+  [NOTE] You can pass options for extconf.rb like this:
+
+      ruby install.rb config -- --with-tklib=/usr/lib/libtk-ja.so.8.0
+
+    
+  Task Options for Install
+  ------------------------
+    
+    --no-harm
+        prints what to do and done nothing really.
+    --prefix=PATH
+        a prefix of the installing directory path.
+        This option may help binary package maintainers.
+        A default value is an empty string.
+    
+Installing Programs with setup.rb
+=================================
+    
+Quick Start
+-----------
+    
+  Type these lines on command line:
+  ("#" line may require root privilege)
+
+      $ ruby setup.rb config
+      $ ruby setup.rb setup
+      # ruby setup.rb install
+
+    
+Details
+-------
+    
+  Usage of setup.rb is:
+
+      ruby setup.rb <global options>
+      ruby setup.rb [<global options>] <task> [<task options>]
+
+    
+  Global Options
+  --------------
+    
+    -q,--quiet
+        suppress message outputs
+    --verbose
+        output messages verbosely (default)
+    -h,--help
+        prints help and quit
+    -v,--version
+        prints version and quit
+    --copyright
+        prints copyright and quit
+    
+  These are acceptable tasks:
+    config
+        Checks and saves configurations.
+    show
+        Prints current configurations.
+    setup
+        Compiles ruby extentions.
+    install
+        Installs files.
+    clean
+        Cleans created files.
+    distclean
+        Cleans created files.
+    
+  Task Options for CONFIG
+  -----------------------
+    
+    --prefix=PATH
+        a prefix of the installing directory path
+    --std-ruby=PATH
+        the directory for standard ruby libraries
+    --site-ruby-common=PATH
+        the directory for version-independent non-standard
+        ruby libraries
+    --site-ruby=PATH
+        the directory for non-standard ruby libraries
+    --bin-dir=PATH
+        the directory for commands
+    --rb-dir=PATH
+        the directory for ruby scripts
+    --so-dir=PATH
+        the directory for ruby extentions
+    --data-dir=PATH
+        the directory for shared data
+    --ruby-path=PATH
+        path to set to #! line
+    --ruby-prog=PATH
+        the ruby program using for installation
+    --make-prog=NAME
+        the make program to compile ruby extentions
+    --without-ext
+        forces to setup.rb never to compile/install
+        ruby extentions.
+    --rbconfig=PATH
+        your rbconfig.rb to load
+    
+  You can view default values of these options by typing
+
+      $ ruby setup.rb --help
+
+    
+  If there's the directory named "packages",
+  You can also use these options:
+    --with=NAME,NAME,NAME...
+        Package names which you want to install.
+    --without=NAME,NAME,NAME...
+        Package names which you do not want to install.
+    
+  [NOTE] You can pass options for extconf.rb like this:
+
+      ruby setup.rb config -- --with-tklib=/usr/lib/libtk-ja.so.8.0
+
+    
+  Task Options for INSTALL
+  ------------------------
+    
+    --no-harm
+        prints what to do and done nothing really.
+    --prefix=PATH
+        The prefix of the installing directory path.
+        This option may help binary package maintainers.
+        A default value is an empty string.

data/NEWS

@@ -1,4 +1,119 @@
-$Id: NEWS,v 1.18 2009/05/26 15:25:19 ianmacd Exp $
+$Id: NEWS,v 1.19 2009/06/15 23:48:49 ianmacd Exp $
+
+
+0.7.0 - 2009-06-16
+------------------
+
+1. This release introduces a shorthand module method for each of the AWS
+   operations. These can be used to create less verbose code at the expense of
+   flexibility.
+
+   For example, we might normally write the following code:
+
+     is = ItemSearch.new( 'Books', { 'Title' => 'Ruby' } )
+     rg = ResponseGroup.new( :Large )
+     req = Request.new
+     response = req.search( is, rg )
+     
+   but we could instead use ItemSearch's associated module method as follows:
+
+     response = Amazon::AWS.item_search( 'Books', { 'Title' => 'Ruby' } )
+
+   There are some important restrictions when compared to the standard way of
+   doing things:
+
+   a. Astute readers will note that there's no way to specify to the module
+      methods which response group(s) to use. Instead, a reasonable default
+      set for each type of operation will be used, as per the new
+      ResponseGroup::DEFAULT hash.
+
+      The exception to this is Amazon::AWS.multiple_operation, which has no
+      response groups of its own, instead applying those of the operations it
+      combines.
+
+      Because no access is provided to the Request object used by the module
+      method, it's also not possible to batch operations with Operation#batch
+      when using this form of the search.
+
+      On the other hand, you can use the Amazon::AWS.multiple_operation module
+      method to achieve more or less the same thing:
+
+	Amazon::AWS.multiple_operation( op1, op2 )
+
+      When op1 and op2 are of the same class, the effect is similar to
+      batching two operations. The main difference is in the structure of the
+      XML document returned by AWS.
+
+   b. Similarly, one can't influence the key ID, associate tag, locale, cache
+      or user agent used for the request. These are all set as per
+      ~/.amazonrc.
+   
+      Likewise, the number of results pages to fetch will always be 1.
+
+   c. The module methods have no RDoc documentation, because they are
+      dynamically generated.
+
+   Basically, the short form module methods are there as a convenience, but
+   that convenience comes at the expense of flexibility. If they don't meet
+   your needs, you will have to resort to the standard longhand form.
+
+2. There's now an alternative to passing the list of desired response groups
+   as the second parameter to Request#search.
+
+   The second parameter of that method is now optional and *nil* by default.
+   Instead, you may assign to the response_group attribute of your operation
+   object.
+
+   For example:
+
+   is = ItemSearch.new( 'Books', { 'Title' => 'Ruby' } )
+   is.response_group = ResponseGroup.new( :Large )
+   req = Request.new
+   response = req.search( is )
+
+   Note that the @response_group variable will be initialised at the
+   time the operation object is instantiated. It will be assigned the same
+   reasonable default as used by the equivalent module method, namely
+   that specified by the new ResponseGroup::DEFAULT hash.
+
+   Specifying the desired response groups inside your operation object has at
+   least two advantages over passing the list to Request#search:
+
+   a. You can maintain a separate response group set per operation, rather
+      than having to pass a differen set to Request#search for each operation.
+
+   b. A reasonable default response group set can be used for any given
+      operation if you don't supply one.
+
+3. More and more people are moving to Ruby 1.9, so this release of Ruby/AWS
+   has been tested to work with Ruby 1.9.1p129, the latest version at the time
+   of writing. Attaining ompatibility with 1.9 is a little tricky, because of
+   the way in which strings are no longer treated as sequences of bytes in
+   that version. Instead, they have knowledge of their encoding.
+   
+   There may be one or two obscure 1.9-related bugs remaining, but all of the
+   unit tests pass, at least.
+
+4. The signing of requests, introduced in Ruby/AWS 0.6.0, produced problems
+   for people with a version of OpenSSL earlier than 0.9.8.
+   
+   The code will now check whether there is OpenSSL support for the SHA-256
+   Secure Hash Algorithm before attempting to use it. If not, each attempt to
+   sign a request will result in a warning if $DEBUG is used.
+
+   Once again, I remind you that Amazon intends to make request authentication
+   compulsory on 15th August 2009, so this change to Ruby/AWS only lets users
+   with an ancient OpenSSL library off the hook until then.
+
+5. A second bug with the signing of requests occurred on Windows platforms.
+   Requests were not properly timestamped. This was due to deficiencies in the
+   underlying strftime(3) library function, but has now been fixed.
+
+6. Finally, knowledge of a handful of relatively new search indices, such as
+   UnboxVideo, was missing. This has now been added. The AWS documentation is
+   terribly inconsistent in this regard, providing several different, yet
+   supposedly complete lists of valid search indices at various points
+   throughout the document.
 
 
 0.6.0 - 2009-05-26

data/README

@@ -1,4 +1,4 @@
-$Id: README,v 1.21 2009/05/25 23:38:24 ianmacd Exp $
+$Id: README,v 1.23 2009/06/15 12:07:51 ianmacd Exp $
 
 
 Introduction
@@ -11,7 +11,7 @@ site, the local sites amazon.co.uk, amazon.de, amazon.fr, amazon.ca and
 amazon.co.jp are also supported.
 
 Development of Ruby/AWS has been quite swift since the appearance of the first
-alpha version, 0.0.1, in late March 2008. Although Ruby/AWS shares almost no
+alpha version, 0.0.1, in late March of 2008. Although Ruby/AWS shares almost no
 code with its now obsolete predecessor, Ruby/Amazon, many lessons were learnt
 whilst developing that library, and the experience gained has been rolled into
 Ruby/AWS.
@@ -44,6 +44,12 @@ to call this library by a name so general as Ruby/Amazon, because it
 provides an interface to just one of the Amazon Web APIs. Therefore, the
 monicker for this library is Ruby/AWS.
 
+Unfortunately for Ruby/AWS, Amazon changed the name once again in May 2009,
+referring to it now as the Product Advertising API. Changing Ruby/AWS's name
+would create more confusion than it would mitigate, however, so I'm not about
+to do so. Similarly, I will continue to refer to the Amazon API in question as
+AWS.
+
 Ruby/AWS is built around version 4 of the Amazon AWS API, which is
 fundamentally different to version 3, both in terms of how requests are made
 and the data returned. The underlying structure of the XML response has
@@ -132,7 +138,7 @@ Ruby/AWS is currently beta software. Amongst other things, this means:
     CartModify
     CartClear
 
-  Version 0.4.0 adds the remaining shopping-cart operation, which I had first
+  Version 0.4.0 added the remaining shopping-cart operation, which I had first
   thought superfluous:
 
     CartGet
@@ -194,9 +200,9 @@ Its contents should look something like this:
   locale = 'uk'
   encoding = 'iso-8859-15'
 
-Including your secret key is a new feature in version 0.6.0 of Ruby/AWS. If
-you choose to do so, your requests to AWS will be signed for authentication by
-the Amazon's servers.
+The ability to include your secret key was a feature added in version 0.6.0 of
+Ruby/AWS. If you choose to do so, your requests to AWS will be signed for
+authentication by the Amazon's servers.
 
 Amazon plans to make this practice obligatory as of 15th August 2009, so I
 recommend that you adopt it well ahead of time.
@@ -330,7 +336,7 @@ AWS as an HTTP GET operation:
 
 http://ecs.amazonaws.co.uk/onca/xml?AWSAccessKeyId=01234567890123456789&AssociateTag=calibanorg-21&Operation=ItemSearch&ResponseGroup=Small&SearchIndex=Books&Service=AWSECommerceService&Title=Ruby&Version=2008-03-03
 
-The following (truncated) AWS XML response was received:
+The following (abbreviated) AWS XML response was received:
 
 <ItemSearchResponse>
   <OperationRequest>

data/README.rdoc

@@ -1,5 +1,5 @@
 #--
-# $Id: README.rdoc,v 1.23 2009/05/26 15:25:19 ianmacd Exp $
+# $Id: README.rdoc,v 1.25 2009/06/15 23:51:11 ianmacd Exp $
 #++
 #
 #
@@ -118,9 +118,11 @@
 # {mailing-list}[http://www.caliban.org/mailman/listinfo/ruby-aws] available,
 # where you can discuss any Ruby/AWS-related subjects and issues.
 #
-# Please see the Amazon Web Services API
+# Please see the AWS Developer Resources {home
+# page}[https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html],
+# the Amazon Web Services API
 # documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5],
-# not forgetting the {release
+# and, in particular, the {release
 # notes}[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=17]
 # for definitive information on the capabilities and inner workings of the AWS
 # API.
@@ -128,16 +130,16 @@
 #
 # == Download
 #
-# Version 0.6.0
-# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.6.0.tar.gz]
-# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.6.0.gem]
-# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.6.0-1.fc9.noarch.rpm]
-# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.6.0-1.fc9.noarch.rpm]
-# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.6.0-1.fc9.src.rpm]
+# Version 0.7.0
+# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.7.0.tar.gz]
+# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.7.0.gem]
+# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.7.0-1.fc9.noarch.rpm]
+# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.7.0-1.fc9.noarch.rpm]
+# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.7.0-1.fc9.src.rpm]
 # 
 # 
 # ---
 # Author::   Ian Macdonald <mailto:ian@caliban.org>
-# Version::  0.6.0
+# Version::  0.7.0
 # Copyright:: (C) 2008-2009 Ian Macdonald
 # Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]