lib/gscraper/sponsored_links.rb in gscraper-0.2.4 vs lib/gscraper/sponsored_links.rb in gscraper-0.3.0

@@ -1,7 +1,6 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # This program is free software; you can redistribute it and/or modify
@@ -15,202 +14,371 @@
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'gscraper/sponsored_ad'
 
+require 'enumerator'
+
 module GScraper
   class SponsoredLinks < Array
+
     #
-    # Creates a new SponsoredLinks object with the given _ads_. If a
-    # _block_ is given, it will be passed the newly created SponsoredLinks
-    # object.
+    # Creates a new SponsoredLinks object.
     #
-    def initialize(ads=[],&block)
+    # @param [Array] ads
+    #   The ads to populate the sponsored links object with.
+    #
+    # @yield [links]
+    #   If a block is given, it will be passed the new sponsored links
+    #   object.
+    #
+    # @yieldparam [SponsoredLinks] links
+    #   The new sponsored links object.
+    #
+    def initialize(ads=[])
       super(ads)
 
-      block.call(self) if block
+      yield self if block_given?
     end
 
     #
-    # Returns a mapped Array of the ads within the SponsoredLinks
-    # using the given _block_. If the _block_ is not given, the
-    # SponsoredLinks will be returned.
+    # Maps the sponsored ads.
     #
-    #   sponsored.map # => SponsoredLinks
+    # @yield [ad]
+    #   The given block will be passed each ad.
     #
-    #   sponsored.map { |ad| ad.url } # => [...]
+    # @yieldparam [SponsoredAd] ad
+    #   The sponsored ad.
     #
-    def map(&block)
-      return self unless block
+    # @return [Array, Enumerator]
+    #   The mapped result. If no block was given, an Enumerator object will
+    #   be returned.
+    #
+    # @example
+    #   sponsored.map
+    #   # => SponsoredLinks
+    #
+    # @example
+    #   sponsored.map { |ad| ad.url }
+    #   # => [...]
+    #
+    def map
+      return enum_for(:map) unless block_given?
 
       mapped = []
 
-      each { |ad| mapped << block.call(ad) }
+      each { |ad| mapped << yield(ad) }
       return mapped
     end
 
     #
-    # Selects the ads within the SponsoredLinks which match the given _block_.
+    # Selects the ads within the sponsored links.
     #
+    # @yield [ad]
+    #   The given block will determine which ads to select.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   A sponsored ad.
+    #
+    # @return [Array, Enumerator]
+    #   The selected ads. If no block is given, an Enumerator object will
+    #   be returned.
+    #
+    # @example
     #   sponsored.select { |ad| ad.title =~ /consume/i }
     #
     def select(&block)
-      SponsoredLinks.new(super(&block))
+      unless block
+        enum_for(:select)
+      else
+        SponsoredLinks.new(super(&block))
+      end
     end
 
+    alias ads_with select
+
     #
-    # Selects the ads using the specified _block_.
+    # Selects the ads with the matching title.
     #
-    #   sponsored.ads_with { |ad| ad.title =~ /status symbol/ }
+    # @param [String, Regexp] title
+    #   The title to search for.
     #
-    def ads_with(&block)
-      select(&block)
-    end
-
+    # @yield [ad]
+    #   Each matching ad will be passed to the given block.
     #
-    # Selects the ads with the matching _title_. The _title_ may be
-    # either a String or a Regexp. If _block_ is given, each matching
-    # ad will be passed to the _block_.
+    # @yieldparam [SponsoredAd] ad
+    #   A sponsored ad with the matching title.
     #
-    #   sponsored.ads_with_title('be attractive') #=> SponsoredLinks
+    # @return [Array, Enumerator]
+    #   The sponsored ads with the matching title. If no block is given,
+    #   an Enumerator object will be returned.
     #
+    # @example
+    #   sponsored.ads_with_title('be attractive')
+    #   # => SponsoredLinks
+    #
+    # @example
     #   sponsored.ads_with_title(/buy me/) do |ad|
     #     puts ad.url
     #   end
     #
-    def ads_with_title(title,&block)
-      if title.kind_of?(Regexp)
-        ads = ads_with { |ad| ad.title =~ title }
-      else
-        ads = ads_with { |ad| ad.title == title }
-      end
+    def ads_with_title(title)
+      return enum_for(:ads_with_title,title) unless block_given?
 
-      ads.each(&block) if block
-      return ads
+      comparitor = if title.kind_of?(Regexp)
+                     lambda { |ad| ad.title =~ title }
+                   else
+                     lambda { |ad| ad.title == title }
+                   end
+
+      return ads_with do |ad|
+        if comparitor.call(ad)
+          yield ad
+
+          true
+        end
+      end
     end
 
     #
-    # Selects the ads with the matching _url_. The _url_ may be
-    # either a String or a Regexp. If _block_ is given, each matching
-    # ad will be passed to the _block_.
+    # Selects the ads with the matching URL.
     #
-    #   sponsored.ads_with_url(/\.com/) # => SponsoredLinks
+    # @param [String, Regexp] url
+    #   The URL to search for.
     #
-    def ads_with_url(url,&block)
-      if url.kind_of?(Regexp)
-        ads = ads_with { |ad| ad.url =~ url }
-      else
-        ads = ads_with { |ad| ad.url == url }
-      end
+    # @yield [ad]
+    #   Each matching ad will be passed to the given block.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   A sponsored ad with the matching URL.
+    #
+    # @return [Array, Enumerator]
+    #   The sponsored ads with the matching URL. If no block is given,
+    #   an Enumerator object will be returned.
+    #
+    # @example
+    #   sponsored.ads_with_url(/\.com/)
+    #   # => SponsoredLinks
+    #
+    def ads_with_url(url)
+      return enum_for(:ads_with_url,url) unless block_given?
 
-      ads.each(&block) if block
-      return ads
+      comparitor = if url.kind_of?(Regexp)
+                     lambda { |ad| ad.url =~ url }
+                   else
+                     lambda { |ad| ad.url == url }
+                   end
+
+      return ads_with do |ad|
+        if comparitor.call(ad)
+          yield ad
+
+          true
+        end
+      end
     end
 
     #
-    # Selects the ads with the matching _direct_url_. The _direct_url_ may
-    # be either a String or a Regexp. If _block_ is given, each matching
-    # ad will be passed to the _block_.
+    # Selects the ads with the matching direct URL.
     #
-    #   sponsored.ads_with_direct_url(/\.com/) # => SponsoredLinks
+    # @param [String, Regexp] direct_url
+    #   The direct URL to search for.
     #
-    def ads_with_direct_url(direct_url,&block)
-      if direct_url.kind_of?(Regexp)
-        ads = ads_with { |ad| ad.direct_url =~ direct_url }
-      else
-        ads = ads_with { |ad| ad.direct_url == direct_url }
-      end
+    # @yield [ad]
+    #   Each matching ad will be passed to the given block.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   A sponsored ad with the matching direct URL.
+    #
+    # @return [Array, Enumerator]
+    #   The sponsored ads with the matching URL. If no block is given,
+    #   an Enumerator object will be returned.
+    #
+    # @example
+    #   sponsored.ads_with_direct_url(/\.com/)
+    #   # => SponsoredLinks
+    #
+    def ads_with_direct_url(direct_url)
+      return enum_for(:ads_with_direct_url,direct_url) unless block_given?
 
-      ads.each(&block) if block
-      return ads
+      comparitor = if direct_url.kind_of?(Regexp)
+                     lambda { |ad| ad.direct_url =~ direct_url }
+                   else
+                     lambda { |ad| ad.direct_url == direct_url }
+                   end
+
+      return ads_with do |ad|
+        if comparitor.call(ad)
+          yield ad
+
+          true
+        end
+      end
     end
 
     #
-    # Returns an Array containing the titles of the ads within the
-    # SponsoredLinks.
+    # Iterates over the titles of each ad.
     #
-    #   sponsored.titles # => [...]
+    # @yield [title]
+    #   The given block will be passed each title.
     #
-    def titles
-      map { |ad| ad.title }
+    # @yieldparam [String] title
+    #   A title of an ad.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    # @example
+    #   each_title { |title| puts title }
+    #
+    def each_title
+      unless block_given?
+        enum_for(:each_title)
+      else
+        each { |ad| yield ad.title }
+      end
     end
 
     #
-    # Returns an Array containing the URLs of the ads within the
-    # SponsoredLinks.
+    # Iterates over the URLs of each ad.
     #
-    #   sponsored.urls # => [...]
+    # @yield [url]
+    #   The given block will be passed each URL.
     #
-    def urls
-      map { |ad| ad.url }
+    # @yieldparam [URI::HTTP] url
+    #   An URL of an ad.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    # @example
+    #   each_url { |url| puts url }
+    #
+    def each_url
+      unless block_given?
+        enum_for(:each_url)
+      else
+        each { |ad| yield ad.url }
+      end
     end
 
     #
-    # Returns an Array containing the direct URLs of the ads within the
-    # SponsoredLinks.
+    # Iterates over the direct URLs of each ad.
     #
-    #   sponsored.direct_urls # => [...]
+    # @yield [direct_url]
+    #   The given block will be passed each direct URL.
     #
-    def direct_urls
-      map { |ad| ad.direct_url }
+    # @yieldparam [URI::HTTP] direct_url
+    #   A direct URL of an ad.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    # @example
+    #   each_direct_url { |url| puts url }
+    #
+    def each_direct_url
+      unless block_given?
+        enum_for(:each_direct_url)
+      else
+        each { |ad| yield ad.direct_url }
+      end
     end
 
     #
-    # Iterates over each ad's title within the SponsoredLinks, passing each to
-    # the given _block_.
+    # The titles for the ads.
     #
-    #   each_title { |title| puts title }
+    # @return [Array<String>]
+    #   The titles for the ads.
     #
-    def each_title(&block)
-      titles.each(&block)
+    # @example
+    #   sponsored.titles # => [...]
+    #
+    def titles
+      each_title.to_a
     end
 
     #
-    # Iterates over each ad's URL within the SponsoredLinks, passing each to
-    # the given _block_.
+    # The URLs for the ads.
     #
-    #   each_url { |url| puts url }
+    # @return [Array<URI::HTTP>]
+    #   The URLs for the ads.
     #
-    def each_url(&block)
-      urls.each(&block)
+    # @example
+    #   sponsored.urls # => [...]
+    #
+    def urls
+      each_url.to_a
     end
 
     #
-    # Iterates over each ad's direct URL within the SponsoredLinks, passing
-    # each to the given _block_.
+    # The direct URLs for the ads.
     #
-    #   each_direct_url { |url| puts url }
+    # @return [Array<URI::HTTP>]
+    #   The direct URLs for the ads.
     #
-    def each_direct_url(&block)
-      direct_urls.each(&block)
+    # @example
+    #   sponsored.direct_urls # => [...]
+    #
+    def direct_urls
+      each_direct_url.to_a
     end
 
     #
-    # Returns the titles of the ads that match the specified _block_.
+    # The titles of the selected ads.
     #
+    # @yield [ad]
+    #   The given block will be passed each ad to be selected.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   An ad to be selected.
+    #
+    # @return [Array<String>]
+    #   The titles of the selected ads.
+    #
+    # @example
     #   sponsored.titles_of { |ad| ad.url.include?('www') }
     #
     def titles_of(&block)
       ads_with(&block).titles
     end
 
     #
-    # Returns the URLs of the ads that match the specified _block_.
+    # The URLs of the selected ads.
     #
+    # @yield [ad]
+    #   The given block will be passed each ad to be selected.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   An ad to be selected.
+    #
+    # @return [Array<String>]
+    #   The URLs of the selected ads.
+    #
+    # @example
     #   sponsored.urls_of { |ad| ad.title =~ /buy these pants/ }
     #
     def urls_of(&block)
       ads_with(&block).urls
     end
 
     #
-    # Returns the direct URLs of the ads that match the specified _block_.
+    # The direct URLs of the selected ads.
     #
+    # @yield [ad]
+    #   The given block will be passed each ad to be selected.
+    #
+    # @yieldparam [SponsoredAd] ad
+    #   An ad to be selected.
+    #
+    # @return [Array<String>]
+    #   The direct URLs of the selected ads.
+    #
+    # @example
     #   sponsored.urls_of { |ad| ad.title =~ /buy these pants/ }
     #
     def direct_urls_of(&block)
       ads_with(&block).direct_urls
     end