class Amazon::Search::Request

This is the class around which most others in this library revolve. It contains the most common search methods and exception classes and is the class from which most others in the library inherit.

Attributes

cache[RW]
config[R]
id[R]
locale[R]
token[R]

Public Class Methods

new(dev_token=nil, associate=nil, locale=nil, cache=nil, user_agent = USER_AGENT) click to toggle source

Use this method to instantiate a basic search request object. dev_token is your AWS developer token, associate is your Associates ID, locale is the search locale in which you wish to work (us, uk, de, fr, ca or jp), cache is whether or not to utilise a response cache, and user_agent is the name of the client you wish to pass when performing calls to AWS. locale and cache can also be set later, if you wish to change the current behaviour.

For example:

require 'amazon/search'
include Amazon::Search

r = Request.new('D23XFCO2UKJY82', 'foobar-20', 'us', false)

# Do a bunch of things in the US locale with the cache off, then:
#
r.locale = 'uk'                      # Switch to the UK locale
r.id = 'foobaruk-21'                 # Use a different Associates ID
                                     # in this locale.
r.cache = Cache.new('/tmp/amazon')   # Start using a cache.

Note that reassigning the locale will dynamically and transparently set up a new HTTP connection to the correct server for that locale.

You may also put one or more of these parameters in a configuration file, which will be read in the order of /etc/amazonrc and ~/.amazonrc. This allows you to have a system configuration file, but still override some of its directives in a per user configuration file.

For example:

dev_token = 'D23XFCO2UKJY82'
associate = 'calibanorg-20'
cache_dir = '/tmp/amazon/cache'

If you do not provide an Associate ID, the one belonging to the author of the Ruby/Amazon library will be used. If locale is not provided, us will be used. If cache == true, but you do not specify a cache_dir in a configuration file, /tmp/amazon will be used. However, this last convenience applies only when a Request object is instantiated. In other words, if you started off without a cache, but now wish to use one, you will need to directly assign a Cache object, as shown above.

If your environment requires the use a HTTP proxy server, you should define this in the environment variable $http_proxy. Ruby/Amazon will detect this and channel all outbound connections via your proxy server.

# File lib/amazon/search.rb, line 384
def initialize(dev_token=nil, associate=nil, locale=nil, cache=nil,
               user_agent = USER_AGENT)

  def_locale = locale
  locale = 'us' unless locale
  locale.downcase!

  configs = [ '/etc/amazonrc' ]
  configs << File.expand_path('~/.amazonrc') if ENV.key?('HOME')
  @config = {}

  configs.each do |config|
    if File.exists?(config) && File.readable?(config)
      Amazon::dprintf("Opening %s ...\n", config)

      File.open(config) { |f| lines = f.readlines }.each do |line|
        line.chomp!

        # Skip comments and blank lines
        next if line =~ /^(#|$)/

        Amazon::dprintf("Read: %s\n", line)

        # Store these, because we'll probably find a use for these later
        begin
          match = line.match(/^(\S+)\s*=\s*(['"]?)([^'"]+)(['"]?)/)
          key, begin_quote, val, end_quote = match[1,4]
          raise ConfigError if begin_quote != end_quote
        rescue NoMethodError, ConfigError
          raise ConfigError, "bad config line: #{line}"
        end

        @config[key] = val

        # Right now, we just evaluate the line, setting the variable if
        # it does not already exist
        eval line.sub(/=/, '||=')
      end
    end
  end

  # take locale from config file if no locale was passed to method
  locale = @config['locale'] if @config.key?('locale') && ! def_locale
  validate_locale(locale)

  if dev_token.nil?
    raise TokenError, 'dev_token may not be nil'
  end

  @token     = dev_token
  @id        = associate || DEFAULT_ID[locale]
  @user_agent = user_agent
  @cache     = unless cache == false
                  Amazon::Search::Cache.new(@config['cache_dir'] ||
                                            '/tmp/amazon')
                else
                  nil
                end
  self.locale = locale
end

Public Instance Methods

locale=(l) click to toggle source
# File lib/amazon/search.rb, line 446
def locale=(l)
  old_locale = @locale ||= nil
  @locale = validate_locale(l)

  # Use the new locale's default ID if the ID currently in use is the
  # current locale's default ID.
  @id = DEFAULT_ID[@locale] if @id == DEFAULT_ID[old_locale]

  # We must now set up a new HTTP connection to the correct server for
  # this locale, unless the same server is used for both.
  connect(@locale) unless LOCALES[@locale] == LOCALES[old_locale]
end