app_store 0.0.4 → 0.1.0

data/README.rdoc

@@ -21,9 +21,9 @@ It provides way to search for applications, navigate through categories.
    @fontpicker.company.title     # => "Etienne Segonzac"
 
 * Medias
-	@fontpicker.screenshots				 		# => [#<AppStore::Image:0x1017683e0 @width=320, @ra ...
-	@fontpicker.screenshots.first.url	# => "http://a1.phobos.apple.com/us/r1000/017/Purple/c4/99/6d/mzl.jtoxfers.480x480-75.jpg"
-	@fontpicker.icon.url							# => "http://a1.phobos.apple.com/us/r1000/026/Purple/39/40/54/mzl.yrrhymuu.100x100-75.jpg"
+   @fontpicker.screenshots            # => [#<AppStore::Image:0x1017683e0 @width=320, @ra ...
+   @fontpicker.screenshots.first.url  # => "http://a1.phobos.apple.com/us/r1000/017/Purple/c4/99/6d/mzl.jtoxfers.480x480-75.jpg"
+   @fontpicker.icon.url               # => "http://a1.phobos.apple.com/us/r1000/026/Purple/39/40/54/mzl.yrrhymuu.100x100-75.jpg"
 
 * User reviews
    @remote = AppStore::Application.find_by_id(284417350)
@@ -46,15 +46,46 @@ It provides way to search for applications, navigate through categories.
    @category = @categories.first
    @category.title                # => "Games"
    @category.item_count           # => 1573
-   
-   # Go through subcategories and applications
-   @subcategory = @category.items.last
-   @subcategory.class             # => AppStore::Category
-   @subcategory.title             # => "Word"
-   @subcategory.items.length      # => 26
-   @subcategory.items.first.class # => AppStore::Application
-   @subcategory.items.last.class  # => AppStore::Category
-   @subcategory.items.last.title  # => "Twenty Five More..."
+
+   # Category by id
+   @category = AppStore::Category.find_by_id(6014)
+   @category.title                # => "Games"
+
+   # Iterate through subcategories and applications
+   # This example will display all categories with all applications available in the current AppStore
+   def go_deeper(category)
+     puts "Category #{category.title}"
+     category.items.each do |item|
+       if item.is_a?(AppStore::Category)
+         go_deeper item
+       else
+         puts " => #{item.title} has id #{item.item_id}"
+       end
+     end
+   end
+
+   AppStore::Category.featured.each {|category| go_deeper category}
+
+=== List
+Every list elements returned by the Apple AppStore are limited to 25 elements.
+An additional element is provided at the end of the list to fetch the next elements.
+AppStore::List provides an abstraction to this list and allows to iterate through each element like a traditional enumerable object.
+
+   list = AppStore::Category.featured.first
+   list = Category.featured.first.items
+   list.count                          # => 23453
+   list.elements                       # => [AppStore::Category, AppStore::Category, ...]
+   list.collect {|item| item.item_id}  # => [9843509, 9028423, 8975435, 987345, ...]
+
+=== Agent
+There are several Apple AppStore defined by their country. You will have different results (applications, comments) from different store front. You can use AppStore::Agent to ensure you make all yours calls to a specific AppStore (store front).
+You have a list of available store fronts in the constant StoreFronts defined in AppStore::Client.
+
+   agent = AppStore::Agent.new(:store_front => :fr)
+   agent.category.featured                           # => will call Category.featured with store front set to :fr
+   agent.application.find_by_id(42)                  # => will call Application.find_by_id(42) with store front set to :fr
+   agent.application.find_by_id(42, :bleh => 'yeah') # => also accepts extra arguments and merge them with store front
+
 
 == REQUIREMENTS
 

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.1.0

data/lib/app_store/agent.rb

@@ -0,0 +1,25 @@
+require 'app_store/client'
+require 'app_store/application'
+require 'app_store/helpers/string'
+require 'app_store/helpers/proxy'
+
+# Define an agent which is linked to a specific store front and can perform all calls to this specific store.
+# Accepts every AppStore class as a method, ex :
+# = Examples
+#  agent = AppStore::Agent.new(:store_front => :fr)
+#  agent.category.featured                           # => will call Category.featured with store front set to :fr
+#  agent.application.find_by_id(42)                  # => will call Application.find_by_id(42) with store front set to :fr
+#  agent.application.find_by_id(42, :bleh => 'yeah') # => also accepts extra arguments and merge them with store front
+class AppStore::Agent
+  def initialize(args = {})
+    @store_front = AppStore::Client::StoreFronts[args[:store_front]] || AppStore::Client::DefaultStoreFront
+    @client = AppStore::Client.new(:store_front => @store_front)
+  end
+  
+  private
+  def method_missing(method, *args)
+    # OPTIMIZE: we should use a 'camelize' method instead of capitalize
+    AppStore::Helper::Proxy.new :to => "AppStore::#{method.to_s.capitalize}".constantize,
+                                :extra => {:client => @client}
+  end
+end

data/lib/app_store/application.rb

@@ -66,17 +66,19 @@ class AppStore::Application < AppStore::Base
     }
   
   # Search an Application by its <tt>id</tt>. Accepts only one <tt>id</tt> and returns an Application instance.
-  def self.find_by_id(id)
-    plist = AppStore::Caller.get(AppStore::Caller::ApplicationURL, :id => id)
+  def self.find_by_id(id, options = {})
+    client = options[:client] || AppStore::Client.new
+    plist = client.get(AppStore::Client::ApplicationURL, :id => id)
     # TODO : Check if everything was right before instancianting
-    new :plist => plist['item-metadata']
+    new :client => client, :plist => plist['item-metadata']
   end
   
   # Search an Application by a <tt>text</tt>.
   # Returns an array with matching application or an empty array if no result found.
-  def self.search(text)
-    plist = AppStore::Caller.get(AppStore::Caller::SearchURL, :media => 'software', :term => text)
-    AppStore::List.new :list => plist['items']
+  def self.search(text, options = {})
+    client = options[:client] || AppStore::Client.new
+    plist = client.get(AppStore::Client::SearchURL, :media => 'software', :term => text)
+    AppStore::List.new :client => client, :list => plist['items']
   end
   
   def initialize(attrs = {})
@@ -87,7 +89,7 @@ class AppStore::Application < AppStore::Base
   # Returns an AppStore::List of UserReview objects.
   def user_reviews
     if @user_reviews.nil?
-      plist = AppStore::Caller.get(@raw['view-user-reviews-url'])
+      plist = @client.get(@raw['view-user-reviews-url'])
       @user_reviews = AppStore::List.new(:list => plist['items'])
     end
     @user_reviews
@@ -99,7 +101,7 @@ class AppStore::Application < AppStore::Base
   
   def icon
     if @icon.nil?
-      parsed = AppStore::Caller.itunes_get(AppStore::Caller::ApplicationURL, :id => item_id)
+      parsed = @client.itunes_get(AppStore::Client::ApplicationURL, :id => item_id)
       @icon = AppStore::Image.new(:plist => parsed.search('PictureView[@height="100"][@width="100"]').first)
     end
     

data/lib/app_store/base.rb

@@ -1,4 +1,4 @@
-require "app_store/caller"
+require "app_store/client"
 require "app_store/helpers/plist"
 
 # Implements basic operations for AppStore objects : initialization, plist parsing, ...
@@ -11,7 +11,8 @@ class AppStore::Base
   # <tt>attrs</tt> accepts:
   # * <tt>:plist</tt>: a plist object to be parsed
   def initialize(attrs = {})
-    init_from_plist attrs[:plist] if attrs[:plist]
+    init_from_plist attrs.delete(:plist) if attrs[:plist]
+    attrs.each { |key, value| instance_variable_set "@#{key}", value}
   end
   
   protected

data/lib/app_store/category.rb

@@ -1,11 +1,40 @@
 require "app_store/base"
 require "app_store/application"
-require 'pp'
 
 # A category like categories on the AppStore.
 # Available attributes:
 # * <tt>item-count</tt>: total items count for this category.
 # * <tt>title</tt>: title for the category.
+# = Examples
+# === Fetch featured categories
+#  @categories = AppStore::Category.featured
+#  @categories.class              # => Array
+#  @categories.length             # => 20
+# 
+# === Use category
+#  @category = @categories.first
+#  @category.title                # => "Games"
+#  @category.item_count           # => 1573
+# 
+# === Category by id
+#  @category = AppStore::Category.find_by_id(6014)
+#  @category.title                # => "Games"
+# 
+# === Iterate through subcategories and applications
+# This example will display all categories with all applications available in the current AppStore
+#  def go_deeper(category)
+#    puts "Category #{category.title}"
+#    category.items.each do |item|
+#      if item.is_a?(AppStore::Category)
+#        go_deeper item
+#      else
+#        puts " => #{item.title} has id #{item.item_id}"
+#      end
+#    end
+#  end
+#  
+#  AppStore::Category.featured.each {|category| go_deeper category}
+#
 class AppStore::Category < AppStore::Base
   plist :mapping => {
     'item-count'  => :item_count,
@@ -14,33 +43,37 @@ class AppStore::Category < AppStore::Base
   
   # Returns an array of featured categories (main categories).
   # It is the same list as the one displayed in the iPhone AppStore.
-  def self.featured
-    plist = AppStore::Caller.get(AppStore::Caller::FeaturedCategoriesURL)
-    plist['items'].collect { |item| new :plist => item }
+  def self.featured(options = {})
+    client = options[:client] || AppStore::Client.new
+    plist = client.get(AppStore::Client::FeaturedCategoriesURL)
+    plist['items'].collect { |item| new :client => client, :plist => item }
   end
   
-  def self.find_by_id(id)
-    # TODO: pass item_id to new
-    category = new(:plist => AppStore::Caller.get(AppStore::Caller::CategoryURL, :id => id))
+  # Search a Category by its <tt>id</tt>. Accepts only one <tt>id</tt> and returns a Category instance.
+  def self.find_by_id(id, options = {})
+    client = options[:client] || AppStore::Client.new
+    new :item_id  => id,
+        :client   => client,
+        :plist    => client.get(AppStore::Client::CategoryURL, :id => id)
   end
   
   # Returns id for this category
   def item_id
-    @item_id ||= @raw['url'].match("id=([0-9]+)")[1]
+    @item_id ||= @raw['url'].match("mobile-software-applications/id([0-9]+)")[1]
   end
   
-  # Returns an array of items contained in the category, with a maximum of 25 items (Apple limitation).
-  # If there are more than 25 items in the category, an extra item is added at the end of the list
-  # as a link to the next 25 entries.
-  # Each element can be either a Category or an Application.
+  # Returns an instance of List which contains items elements.
+  # Each element in the list can be either another category (subcategory) or a Link to an application.
   def items
     if @items.nil?
-      plist = @raw['items'] ? @raw : AppStore::Caller.get(@raw['url'])
+      plist = @raw['items'] ? @raw : @client.get(@raw['url'])
       @items = AppStore::List.new(
+        :client               => @client,
         :list                 => plist['items'],
         :element_type         => 'link',
         :element_initializer  => lambda {|element|
-          (element['link-type'] == 'software' ? AppStore::Link : AppStore::Category).new(:plist => element)
+          (element['link-type'] == 'software' ? AppStore::Link : AppStore::Category).new(:client => @client,
+                                                                                         :plist => element)
         }
       )
     end

data/lib/app_store/{caller.rb → client.rb}

@@ -5,35 +5,42 @@ require "plist"
 
 require "app_store"
 
-# Caller regroups all the calling and xml parsing mechanism to call the AppStore.
-module AppStore::Caller
-  extend self
-  
+# Client regroups all the calling and xml parsing mechanism to call the AppStore.
+class AppStore::Client
+
+  # Urls
   FeaturedCategoriesURL = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewFeaturedSoftwareCategories"
   ApplicationURL        = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware"
   CategoryURL           = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewGenre"
   SearchURL             = "http://ax.search.itunes.apple.com/WebObjects/MZSearch.woa/wa/search"
-
-  # Call the Apple AppStore using given <tt>url</tt> and passing <tt>params</tt> with an HTTP Get method.
-  def iphone_get(url, params = {})
+  
+  # Store Front
+  StoreFronts           = {
+    :us   => "143441",
+    :fr   => "143442"
+  }
+  DefaultStoreFront     = StoreFronts[:us]
+  
+  def initialize(args = {})
     # About the X-Apple-Store-Front header: this is used to select which store and which language.
     # Format is XXXXXX-Y,Z where XXXXXX is the store number (us, french, ...), Y the language and Z the return format.
     # If you omit the language, the default one for the store is used.
     # Return format can be either "1" or "2" : "1" returns data to be directly displayed and "2" is a more structured format.
-    # apple app store codes:
-    # * 143441 : US
-    # * 143442 : FR
-    answer = iphone_agent.get(:url => url, :headers => {"X-Apple-Store-Front" => '143441,2'}, :params => params)
-    raise AppStore::RequestError if answer.code.to_s != '200'
-    Plist::parse_xml answer.body
+    @store_front = "#{args[:store_front] || DefaultStoreFront},2"
+  end
+
+  # Call the Apple AppStore using given <tt>url</tt> and passing <tt>params</tt> with an HTTP Get method.
+  # Call is seen as a fake iPhone iTunes client.
+  def iphone_get(url, params = {})
+    Plist::parse_xml make_call_and_handle_answer(iphone_agent, url, params).body
   end
   
   alias :get :iphone_get
   
+  # Call the Apple AppStore using given <tt>url</tt> and passing <tt>params</tt> with HTTP Get method.
+  # Call is seen as a fake Mac OS X iTunes client.
   def itunes_get(url, params = {})
-    answer = itunes_agent.get(url, params)
-    raise AppStore::RequestError if answer.code.to_s != '200'
-    Nokogiri.parse answer.body
+    Nokogiri.parse make_call_and_handle_answer(itunes_agent, url, params).body
   end
   
   protected
@@ -44,5 +51,19 @@ module AppStore::Caller
   def itunes_agent
     @itunes_agent ||= WWW::Mechanize.new { |a| a.user_agent = 'iTunes/9.0.1 (Macintosh; Intel Mac OS X 10.6.1) AppleWebKit/531.9' }
   end
+  
+  def headers
+    {
+      "X-Apple-Store-Front" => @store_front
+    }
+  end
+  
+  # Make call using given <tt>agent</tt>, <tt>url</tt> and <tt>params</tt>.
+  # Handle answer code and returns answer if answer code was correct.
+  def make_call_and_handle_answer(agent, url, params)
+    answer = agent.get(:url => url, :headers => headers, :params => params)
+    raise AppStore::RequestError if answer.code.to_s != '200'
+    answer
+  end
 
 end

data/lib/app_store/helpers/proxy.rb

@@ -0,0 +1,28 @@
+require 'app_store/helper'
+
+# Proxy class, call class methods on given class (<tt>to</tt>) with <tt>extra</tt> arguments
+# for each method called on a proxy instance
+class AppStore::Helper::Proxy
+  # Instanciate a new proxy object. Acceptable arguments :
+  # * <tt>to</tt>: receiver class
+  # * <tt>extra</tt>: extra arguments passed to each methods
+  def initialize(args = {})
+    @to = args[:to]
+    @extra = args[:extra]
+  end
+  
+  private
+  def method_missing(method, *args)
+    raise "method #{method} not found for #{@to}" unless @to.methods.include?(method.to_s)
+    # OPTIMIZE: define method instead of sending each time
+    hash = args.last.is_a?(Hash) ? args.last : {}
+    case @to.method(method).arity
+    when -2
+      @to.send(method, args.first, @extra.merge(hash))
+    when -1
+      @to.send(method, @extra.merge(hash))
+    else
+      raise "method #{method} not supported by proxy"
+    end
+  end
+end

data/lib/app_store/helpers/string.rb

@@ -0,0 +1,13 @@
+class String
+  # Taken from ActiveSupport::Inflector
+  def constantize
+    names = split('::')
+    names.shift if names.empty? || names.first.empty?
+
+    constant = Object
+    names.each do |name|
+      constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+    end
+    constant
+  end
+end

data/lib/app_store/link.rb

@@ -1,5 +1,4 @@
 require "app_store/base"
-require "app_store/caller"
 
 class AppStore::Link < AppStore::Base
   plist :mapping => {
@@ -8,11 +7,11 @@ class AppStore::Link < AppStore::Base
     'title'       => :title,
     'url'         => :url
   }
-  
+
   def destination
     @destination ||= case @item_type
     when 'software'
-      AppStore::Application.new :plist => AppStore::Caller.get(@url)['item-metadata']
+      AppStore::Application.new :plist => @client.get(@url)['item-metadata']
     else
       raise 'unsupported'
     end

data/lib/app_store/list.rb

@@ -5,6 +5,12 @@ require 'app_store'
 # sends only 24 elements followed by a link for the next 24 elements.
 # This class represents an abstraction of Apple AppStore lists, have
 # a real count attribute and is enumerable over the entire list.
+# = Example
+#  list = Category.featured.first.items
+#  list.count                          # => 23453
+#  list.elements                       # => [AppStore::Category, AppStore::Category, ...]
+#  list.collect {|item| item.item_id}  # => [9843509, 9028423, 8975435, 987345, ...]
+#
 class AppStore::List
   include Enumerable
   
@@ -17,6 +23,7 @@ class AppStore::List
   def initialize(attrs = {})
     @element_initializer  = attrs[:element_initializer]
     @element_type         = attrs[:element_type]
+    @client               = attrs[:client] || AppStore::Client.new
     @elements ||= []
     
     process_new_elements attrs[:list]
@@ -28,11 +35,14 @@ class AppStore::List
     @count ||= @elements.count
   end
   
+  # Iterates the given block using each object in the list.
   def each(&block)
     collect(&block)
     @elements
   end
   
+  # Iterates the given block using each object in the list,
+  # returns an array containing the execution block result for each element.
   def collect
     # First, iterate through already fetched elements
     result = @elements.collect {|element| yield element}
@@ -51,7 +61,7 @@ class AppStore::List
   # Return last fetched elements if any, nil otherwise
   def fetch_next_elements
     return nil if @link_to_next_elements.nil?
-    process_new_elements(AppStore::Caller.get(@link_to_next_elements)['items'])
+    process_new_elements(@client.get(@link_to_next_elements)['items'])
   end
   
   def process_new_elements(new_elements)
@@ -63,11 +73,11 @@ class AppStore::List
       when @element_type
         result << initialize_element_and_append(element)
       when 'software'
-        result << append_element(AppStore::Application.new(:plist => element))
+        result << append_element(AppStore::Application.new(:client => @client, :plist => element))
       when 'review'
-        result << append_element(AppStore::UserReview.new(:plist => element))
+        result << append_element(AppStore::UserReview.new(:client => @client, :plist => element))
       when 'link'
-        result << append_element(AppStore::Link.new(:plist => element))
+        result << append_element(AppStore::Link.new(:client => @client, :plist => element))
       when 'more'
         @count                  = element['total-items']
         @link_to_next_elements  = element['url']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: app_store
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - Fabien Jakimowicz
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-07 00:00:00 +01:00
+date: 2009-11-09 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,14 +79,17 @@ files:
 - Rakefile
 - VERSION
 - lib/app_store.rb
+- lib/app_store/agent.rb
 - lib/app_store/application.rb
 - lib/app_store/artwork.rb
 - lib/app_store/base.rb
-- lib/app_store/caller.rb
 - lib/app_store/category.rb
+- lib/app_store/client.rb
 - lib/app_store/company.rb
 - lib/app_store/helper.rb
 - lib/app_store/helpers/plist.rb
+- lib/app_store/helpers/proxy.rb
+- lib/app_store/helpers/string.rb
 - lib/app_store/image.rb
 - lib/app_store/link.rb
 - lib/app_store/list.rb
@@ -94,7 +97,7 @@ files:
 - test/application_test.rb
 - test/artwork_test.rb
 - test/base_test.rb
-- test/caller_test.rb
+- test/client_test.rb
 - test/image_test.rb
 - test/output.txt
 - test/plist_test.rb
@@ -137,7 +140,7 @@ test_files:
 - test/application_test.rb
 - test/artwork_test.rb
 - test/base_test.rb
-- test/caller_test.rb
+- test/client_test.rb
 - test/image_test.rb
 - test/plist_test.rb
 - test/test_helper.rb