ratebeer 0.0.4b → 0.0.5a

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7c2006d937effedd123240471363f0ab74b490b1
-  data.tar.gz: 16cb0a3c415564220941eb88435cf27df46f5a2b
+  metadata.gz: d001c76b26d45e168769fddcb3c69dcea3711479
+  data.tar.gz: 27390f84bc7f8272b893b1169e3d0e90bab1510d
 SHA512:
-  metadata.gz: 029cf0b3964cf721c20a031e5c6f1fa8114f10ee38a4cc36f5a0a3e573e58131bd8657b6ac639c54380ebb746254df2cd8eeff84582e225164b1eab3bf38b36e
-  data.tar.gz: e4a8efdb59630749439da12eb0a07abe43262c4e82a7c24a840455215996dbbaf2d16dad0ebc490b8ad666decc17db91c45bbb414727a4d4d4145bec8cf3d9d6
+  metadata.gz: 07e2009a0bc96bf6afb208345c0c0167a62de3969fd0a209b3428b63abf0572d3265611e15ad7f81d8742dbe00900bf601ef4fdf600fb74a2d76f494649ea9e6
+  data.tar.gz: d7a0c63bdc4bf43aa3050dd4fb022c6b6ab4ca7bbd55b2f48bac575e1e0cbcf38120e615492afb22d87710a80b2e24d55e8e5cbdc8bfdb5ed14f495d7d8224dd

data/Gemfile

@@ -1,13 +1,13 @@
-source "https://rubygems.org"
-ruby "2.3.0"
+source 'https://rubygems.org'
+ruby '2.3.0'
 
 gemspec
 
-gem "i18n"
-gem "nokogiri"
+gem 'i18n'
+gem 'nokogiri'
 
 group :test do
-  gem "rspec"
-  gem "rake"
-  gem "codeclimate-test-reporter"
+  gem 'rspec'
+  gem 'rake'
+  gem 'codeclimate-test-reporter'
 end

data/Gemfile.lock

@@ -1,36 +1,39 @@
 PATH
   remote: .
   specs:
+    ratebeer (0.0.5)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    codeclimate-test-reporter (0.4.8)
+    codeclimate-test-reporter (0.6.0)
       simplecov (>= 0.7.1, < 1.0.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
     i18n (0.7.0)
-    json (1.8.3)
-    mini_portile (0.6.2)
-    nokogiri (1.6.6.2)
-      mini_portile (~> 0.6.0)
-    rake (10.4.2)
-    rspec (3.3.0)
-      rspec-core (~> 3.3.0)
-      rspec-expectations (~> 3.3.0)
-      rspec-mocks (~> 3.3.0)
-    rspec-core (3.3.2)
-      rspec-support (~> 3.3.0)
-    rspec-expectations (3.3.1)
+    json (2.0.1)
+    mini_portile2 (2.1.0)
+    nokogiri (1.6.8)
+      mini_portile2 (~> 2.1.0)
+      pkg-config (~> 1.1.7)
+    pkg-config (1.1.7)
+    rake (11.2.2)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.1)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-mocks (3.3.2)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-support (3.3.0)
-    simplecov (0.10.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    simplecov (0.12.0)
       docile (~> 1.1.0)
-      json (~> 1.8)
+      json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
 
@@ -45,5 +48,8 @@ DEPENDENCIES
   ratebeer!
   rspec
 
+RUBY VERSION
+   ruby 2.3.0p0
+
 BUNDLED WITH
-   1.11.2
+   1.12.5

data/lib/ratebeer/beer.rb

@@ -0,0 +1,156 @@
+require_relative "brewery"
+require_relative "review"
+require_relative "style"
+require_relative "scraping"
+require_relative "urls"
+
+module RateBeer
+  class Beer
+    # Each key represents an item of data accessible for each beer, and defines
+    # dynamically a series of methods for accessing this data.
+    #
+    def self.data_keys
+      [:name,
+       :brewery, 
+       :style, 
+       :glassware, 
+       :availability, 
+       :abv, 
+       :calories, 
+       :description,
+       :retired,
+       :rating]
+    end
+
+    include RateBeer::Scraping
+    include RateBeer::URLs
+
+    # Create RateBeer::Beer instance.
+    #
+    # Requires the RateBeer ID# for the beer in question.
+    #
+    # @param [Integer, String] id ID# of beer to retrieve
+    # @param [String] name Name of the beer to which ID# relates if known
+    # @param [hash] options Options hash for entity created
+    #
+    def initialize(id, name: nil, **options)
+      super
+    end
+
+    # Return reviews of this beer.
+    #
+    def reviews(order: :most_recent, limit: 10)
+      Review.retrieve(self, order: order, limit: limit)
+    end
+
+    private
+
+    # Retrieve details about this beer from the website.
+    #
+    # This method stores the retrieved details in instance variables
+    # of the beer instance.
+    #
+    def retrieve_details
+      doc      = noko_doc(URI.join(BASE_URL, beer_url(id)))
+      root     = doc.css('#container table').first
+      info_tbl = root.css('table').first 
+
+      @name = doc.css("h1")
+                 .text
+                 .strip
+      @name = fix_characters(@name)
+      raise PageNotFoundError.new("Beer not found - #{id}") if name.empty?
+
+      # If this beer is an alias, change ID to that of "proper" beer and
+      # retrieve details of the proper beer instead.
+      alias_pattern = /Also known as(.|\n)*Proceed to the aliased beer\.{3}/
+      if root.css('tr')[1].css('div div').text =~ alias_pattern
+        alias_node = root.css('tr')[1]
+                         .css('div div')
+                         .css('a')
+                         .first
+        alias_name = alias_node.text
+        alias_id   = alias_node['href'].split('/').last.to_i
+        @id = alias_id
+        retrieve_details
+        return nil
+      end
+
+      @brewery = info_tbl.css('td')[1]
+                         .css('div')
+                         .first
+                         .css('a')
+                         .map { |a| [:id, 
+                                     :name].zip([a['href'].split('/')
+                                                          .last
+                                                          .to_i, a.text]).to_h }.first
+      @brewery = Brewery.new(@brewery[:id], name: fix_characters(@brewery[:name]))
+      @style = info_tbl.css('td')[1]
+                       .css('div')
+                       .first
+                       .css('a')
+                       .select { |a| a['href'] =~ /beerstyles/ }
+                       .map { |a| [:id, 
+                                   :name].zip([a['href'].split('/')
+                                                        .last
+                                                        .to_i, a.text]).to_h }.first
+      @style = Style.new(@style[:id], name: fix_characters(@style[:name]))
+      @glassware = info_tbl.css('td')[1]
+                          .css('div')[1]
+                          .css('a')
+                          .map { |a| [:id, 
+                                      :name].zip([a['href'].split('GWID=')
+                                                           .last
+                                                           .to_i, a.text]).to_h }.first
+      misc = info_tbl.next_element
+                     .first_element_child
+                     .children 
+                     .map(&:text)
+                     .flat_map { |x| x.gsub(nbsp, ' ').strip.split(':') }
+                     .map(&:strip)
+                     .reject(&:empty?)
+                     .each_slice(2)
+                     .map { |(k, v)| [symbolize_text(k),
+                                      v.to_f.zero? ? v : v.to_f] }
+                     .to_h
+      @abv      = misc[:abv]
+      @calories = misc[:est_calories]
+      @rating   = [:overall, 
+                   :style].zip(info_tbl.css('div')
+                          .select { |d| d['title'] =~ /This figure/ }
+                          .map    { |d| d['title'].split(':').first.to_f }).to_h
+      @rating.merge!({ ratings:       misc[:ratings], 
+                       weighted_avg:  misc[:weighted_avg],
+                       mean:          misc[:mean] })
+      @availability  = info_tbl.css('td')[1]
+                               .css('table')
+                               .css('td')
+                               .children
+                               .children
+                               .map(&:text)
+                               .reject(&:empty?)
+                               .each_slice(2)
+                               .to_a
+                               .tap { |a| a.last.unshift('distribution') }
+                               .map { |(k, v)| [k =~ /bottl/ ?  
+                                                :bottling : 
+                                                symbolize_text(k), v] }
+                               .to_h
+      @availability.merge!({ seasonal: misc[:seasonal] })
+      @description  = info_tbl.next_element
+                              .next_element
+                              .children
+                              .children
+                              .map(&:text)
+                              .map(&:strip)
+                              .drop(1)
+                              .reject(&:empty?)
+                              .join("\n")
+      @description = fix_characters(@description)
+      @retired = !(root.css('span.beertitle2') && 
+                   root.css('span.beertitle2').text =~ /RETIRED/).nil?
+
+      nil
+    end
+  end
+end

data/lib/ratebeer/brewery.rb

@@ -0,0 +1,167 @@
+require_relative "scraping"
+require_relative "urls"
+
+module RateBeer
+  class Brewery
+    # Each key represents an item of data accessible for each beer, and defines
+    # dynamically a series of methods for accessing this data.
+    #
+    def self.data_keys
+      [:name,
+       :type,
+       :address,
+       :telephone,
+       :beers]
+    end
+
+    include RateBeer::Scraping
+    include RateBeer::URLs
+
+    attr_reader :established, :location
+
+    # Create RateBeer::Brewery instance.
+    #
+    # Requires the RateBeer ID# for the brewery in question. Optionally accepts
+    # a name parameter where the name is already known.
+    # 
+    # @param [Integer, String] id ID# for the brewery
+    # @param [String] name The name of the specified brewery
+    # @param [hash] options Options hash for entity created
+    #
+    def initialize(id, name: nil, **options)
+      super
+      if options
+        @established = options[:established]
+        @location    = options[:location]
+        @type        = options[:type]
+        @status      = options[:status]
+      end
+    end
+
+    private
+
+    # Retrieve details about this brewery from the website.
+    #
+    # This method stores the retrieved details in instance variables
+    # of the brewery instance.
+    #
+    def retrieve_details
+      @doc  = noko_doc(URI.join(BASE_URL, brewery_url(id)))
+
+      brewery_info = retrieve_brewery_info
+
+      @beers = []
+      if pagination?(@doc)
+        (1..page_count(@doc)).flat_map do |page_no|
+          @doc = noko_doc(URI.join(BASE_URL, brewery_url(id), "0/", "#{page_no}/"))
+          retrieve_brewery_beers
+        end
+      else
+        retrieve_brewery_beers
+      end
+      nil
+    end
+
+    # Scrape brewery info from Nokogiri Doc for brewery page
+    #
+    def retrieve_brewery_info
+      root = @doc.css('#container table').first
+      contact_node = root.css('td').first
+
+      @name = fix_characters(root.css('h1').first.text)
+      raise PageNotFoundError.new("Brewery not found - #{id}") if @name.empty?
+
+      @type = root.css('span.beerfoot')
+                  .select { |x| x.text =~ /Type: .*/ }
+                  .first
+                  .text
+                  .strip
+                  .split("Type: ")
+                  .last
+                  .split(/\s{2,}/)
+                  .first
+      @address = root.css('div[itemprop="address"] b span')
+                     .map { |elem| key = case elem.attributes['itemprop'].value
+                                         when 'streetAddress' then :street
+                                         when 'addressLocality' then :city
+                                         when 'addressRegion' then :state
+                                         when 'addressCountry' then :country
+                                         when 'postalCode' then :postcode
+                                         else raise "unrecognised attribute"
+                                         end
+                                   [key, elem.text.strip] }
+                     .to_h
+
+      @telephone = root.css('span[itemprop="telephone"]').first && 
+                   root.css('span[itemprop="telephone"]').first.text
+
+    end
+
+    # Scrape beer details from Nokogiri Doc for brewery page
+    #
+    def retrieve_brewery_beers
+      location, brewer = nil  # Variables used in the map below
+      root = @doc.css('table.maintable.nohover').first
+      @beers += root.css('tr').drop(1).map do |row|
+        if row.text =~ /^Brewed at (?<location>.+?)(?: by\/for (?<brewer>.+))?$/
+          location = Regexp.last_match['location']
+          brewer   = Regexp.last_match['brewer']
+          nil
+        else
+          process_beer_row(row, location, brewer)
+        end
+      end.reject(&:nil?)
+    end
+
+    # Process a row of data representing one beer brewed by/at a brewery.
+    #
+    # @param [Nokogiri::XML::Element] row HTML TR row wrapped as a Nokogiri
+    #   element
+    # @param [String] location the location at which a brewery's beer is brewed
+    #   where this location differs from the brewery's regular brewsite/venue
+    # @param [String] brewer the client for whom this brewery brewed the beer,
+    #   where the brewery is brewing for a different company/brewery
+    # @return [RateBeer::Beer] a beer object representing the scraped beer, 
+    #   containing scraped attributes
+    #
+    def process_beer_row(row, location=nil, brewer=nil)
+      # Attributes stored in each table row, with indices representing their
+      # position in each row
+      attributes = { name:            0,
+                     abv:             2,
+                     avg_rating:      3,
+                     overall_rating:  4,
+                     style_rating:    5,
+                     num_ratings:     6 }
+
+      beer = attributes.reduce({}) do |beer_hash, (attr, i)| 
+        val = row.css('td')[i].text.gsub(nbsp, ' ').strip rescue nil
+        case attr
+        when :name
+          fix_characters(val)
+        when :abv, :avg_rating
+          val = val.to_f
+        when :overall_rating, :style_rating, :num_ratings
+          val = val.to_i
+        end
+        beer_hash[attr] = val
+        beer_hash
+      end
+      beer[:url] = row.css('td').first.css('a').first['href']
+      id = beer[:url].split('/').last.to_i
+
+      # Apply additional location and brewer information if scraped
+      beer[:brewed_at]     = location unless location.nil?
+      beer[:brewed_by_for] = brewer unless brewer.nil?
+
+      # Transform ratings into correct format
+      beer[:rating] = { overall: beer[:overall_rating], 
+                        style: beer[:style_rating],
+                        ratings: beer[:num_ratings],
+                        weighted_avg: beer[:avg_rating] }
+
+      # Create beer instance from scraped data
+      Beer.new(id, beer)
+    end
+  end
+end

data/lib/ratebeer/country.rb

@@ -0,0 +1,9 @@
+require_relative 'location'
+
+module RateBeer
+  class Country < Location
+    def initialize(id, name: nil)
+      super(id, location_type: :country, name: name)
+    end
+  end
+end

data/lib/ratebeer/location.rb

@@ -0,0 +1,104 @@
+require_relative "brewery"
+require_relative "style"
+require_relative "urls"
+
+module RateBeer
+  class Location
+    # Keys for fields scraped on RateBeer
+    def self.data_keys
+      [:name,
+       :num_breweries,
+       :breweries]
+    end
+
+    include RateBeer::Scraping
+    include RateBeer::URLs
+
+    # Initialize a RateBeer::Location instance.
+    #
+    # Locations may be either Regions or Countries. This must be specified to
+    # the constructor.
+    #
+    # @param [Integer] id ID# for this location
+    # @param [Symbol] location_type Symbol representing either country or region
+    # @param [String] name Name of this location
+    #
+    def initialize(id, location_type: nil, name: nil, **options)
+      super
+      if location_type.nil? || !([:country, :region].include?(location_type))
+        raise ArgumentError.new("location_type must be supplied and must be "\
+                                "either country or region")
+      end
+      @location_type = location_type
+    end
+
+    private
+
+    # Retrive details about this location from the website.
+    #
+    # This method stores the retrived details in instance variables
+    # of the location instance.
+    #
+    def retrieve_details
+      doc          = noko_doc(url)
+      heading      = doc.css('.col-lg-9').first
+      brewery_info = doc.css('#tabs table')
+
+      @name = heading.at_css('h1')
+                     .text
+                     .split('Breweries')
+                     .first
+                     .strip
+      if @name == "n/a" || @name == "RateBeer Robot Oops!"
+        raise PageNotFoundError.new("#{self.class.name} not found - #{id}")
+      end
+
+      @num_breweries = heading.at_css('li.active')
+                              .text
+                              .scan(/Active \((\d*)\)/)
+                              .first
+                              .first
+                              .to_i
+
+      @breweries = brewery_info.flat_map.with_index do |tbl, i|
+        status = i == 0 ? 'Active' : 'Out of Business'
+
+        tbl.css('tr').drop(1).flat_map do |row|
+          cells = row.css('td')
+          next if cells.empty?
+          id       = cells[0].at_css('a')['href'].split('/').last.to_i
+          name     = cells[0].text.split('-').first.strip
+          location = cells[0].text
+                             .split('-')
+                             .last
+                             .sub('(Out of Business)', '')
+                             .strip
+          type = cells[1].text.strip
+          established = status == 'Active' ? cells[3].text.to_i : nil
+          Brewery.new(id,
+                      name:        name,
+                      location:    location,
+                      type:        type,
+                      established: established,
+                      status:      status)
+        end
+      end
+      nil
+    end
+
+    # Return URL for page containing information on this location.
+    #
+    # Result depends on whether this is a country or a region.
+    #
+    def url
+      @url ||= case @location_type
+               when :country
+                 URI.join(BASE_URL, country_url(id))
+               when :region
+                 URI.join(BASE_URL, region_url(id))
+               else
+                 raise "invalid location type: #{@location_type.to_s}"
+               end
+    end
+  end
+end

data/lib/ratebeer/region.rb

@@ -0,0 +1,9 @@
+require_relative 'location'
+
+module RateBeer
+  class Region < Location
+    def initialize(id, name: nil)
+      super(id, location_type: :region, name: name)
+    end
+  end
+end

data/lib/ratebeer/review.rb

@@ -0,0 +1,157 @@
+require_relative "beer"
+require_relative "scraping"
+require_relative "urls"
+
+module RateBeer
+  # The Review class contains reviews of Beers posted to RateBeer.com. It
+  # also provides some scraping functionality for obtaining reviews.
+  #
+  class Review
+    extend RateBeer::URLs
+
+    class << self
+      attr_reader :review_limit
+      attr_reader :review_order
+    
+      # Calculate the number of pages of reviews to retrieve.
+      #
+      # Ten reviews appear on a page, so this method calculates the number of
+      # pages on this basis.
+      #
+      # @param [Integer] limit The number of reviews to be retrieved
+      # @return [Integer] Number of pages to be retrieved for number of reviews
+      #
+      def num_pages(limit)
+        (limit / 10.0).ceil
+      end
+
+      # Determine the URL suffix required for a particular sort order.
+      #
+      # @param [Symbol] order The desired sorting order
+      # @return [String] The URL suffix required to obtain reviews sorted in
+      #   the desired order
+      #
+      def url_suffix(order)
+        options = [:most_recent, :top_raters, :highest_score]
+        unless options.include?(order)
+          raise ArgumentError.new("unknown ordering: #{order}") 
+        end
+
+        case order 
+        when :most_recent
+          "1"
+        when :top_raters
+          "2"
+        when :highest_score
+          "3"
+        end
+      end
+
+      # Retrieve all reviews for a given beer.
+      #
+      # @param [Integer, RateBeer::Beer] beer The beer for which to download
+      #   reviews
+      # @param [Symbol] order The order by which to list reviews
+      # @param [Integer] limit The number of reviews to retrieve
+      # @return [Array<RateBeer::Review>] A list of all reviews for the passed
+      #   beer, up to the review_limit
+      #
+      def retrieve(beer, order: :most_recent, limit: 10)
+        if beer.is_a?(RateBeer::Beer)
+          beer_id = beer.id
+        elsif beer.is_a?(Integer)
+          beer_id = beer
+          beer    = RateBeer::Beer.new(beer)
+        else
+          raise "unknown beer value: #{beer}"
+        end
+
+        reviews = num_pages(limit).times.flat_map do |page_number|
+          url = URI.join(BASE_URL, review_url(beer_id, url_suffix(order), page_number))
+          doc = RateBeer::Scraping.noko_doc(url)
+          root = doc.css("#container table table")[3]
+
+          # All reviews are contained within the sole cell in the sole row of
+          # the selected table. Each review consists of rating information, 
+          # details of the reviewer, and the text of the review itself.
+          #
+          # The components are contained within div, small, div tags 
+          # respectively. We need to scrape these specifically.
+          root.css('td')
+              .children
+              .select { |x| x.name == 'div' || x.name == 'small' }
+              .map(&:text)
+              .reject { |x| x.empty? || x.include?("googleFillSlot") }
+              .each_slice(3).map do |(rating_data, reviewer_data, review)|
+                rating_pattern   = /^(?<total>\d+(\.\d+)?).+
+                                    AROMA\s(?<aroma>\d+\/10).+
+                                    APPEARANCE\s(?<appearance>\d+\/5).+
+                                    TASTE\s(?<taste>\d+\/10).+
+                                    PALATE\s(?<palate>\d+\/5).+
+                                    OVERALL\s(?<overall>\d+\/20)$/x
+                reviewer_pattern = /^(?<name>.+)\s\((?<rank>\d+\))\s-\s?
+                                     (?<location>.+)?\s?-\s
+                                     (?<date>.+)$/x
+                rating_breakdown_match = rating_data.match(rating_pattern)
+                rating_breakdown = {}
+                reviewer = reviewer_data.gsub(RateBeer::Scraping.nbsp, ' ').match(reviewer_pattern)
+                [:overall, :aroma, :appearance, :taste, :palate].each { |k|
+                  rating_breakdown[k] = Rational(rating_breakdown_match[k])
+                }
+                rating = rating_breakdown_match[:total].to_f
+                self.new({ beer:              beer,
+                           reviewer:          reviewer[:name],
+                           reviewer_rank:     reviewer[:rank],
+                           location:          reviewer[:location].strip,
+                           date:              Date.parse(reviewer[:date]),
+                           rating:            rating,
+                           rating_breakdown:  rating_breakdown,
+                           comment:           review })
+          end
+        end
+        reviews.take(limit)
+      end
+    end
+    
+    attr_reader :beer
+    attr_reader :reviewer
+    attr_reader :reviewer_rank
+    attr_reader :location
+    attr_reader :date 
+    attr_reader :rating
+    attr_reader :rating_breakdown
+    attr_reader :comment
+
+    def initialize(**options)
+      @beer = if options[:beer].is_a?(RateBeer::Beer)
+                options[:beer]
+              elsif options[:beer].is_a?(Integer)
+                RateBeer::Beer.new(options[:beer])
+              else
+                raise ArgumentError.new("incorrect beer parameter: #{options[:beer]}")
+              end
+      [:reviewer, :reviewer_rank, :location, :date, 
+       :rating, :rating_breakdown, :comment].each do |param|
+        if options[param].nil?
+          raise ArgumentError.new("#{param.to_s} parameter required")
+        end
+        instance_variable_set("@#{param.to_s}", options[param])
+      end
+    end
+
+    def inspect
+      var = "#<Review of #{self.beer} - #{@reviewer} on #{@date}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def ==(other_review)
+      self.reviewer == other_review.reviewer && 
+        self.date == other_review.date && 
+        self.beer == other_review.beer &&
+        self.comment == other_review.comment
+    end
+  end
+end

data/lib/ratebeer/scraping.rb

@@ -0,0 +1,150 @@
+require 'net/http'
+require 'nokogiri'
+require 'open-uri'
+
+module RateBeer
+
+  # The Scraping module contains a series of methods to assist with scraping
+  # pages from RateBeer.com, and dealing with the results.
+  module Scraping
+
+    class PageNotFoundError < StandardError; end
+
+    attr_reader :id
+
+    # Run method on inclusion in class.
+    def self.included(base)
+      base.data_keys.each do |attr|
+        define_method(attr) do
+          unless instance_variable_defined?("@#{attr}")
+            retrieve_details
+          end
+          instance_variable_get("@#{attr}")
+        end
+      end
+    end
+
+    # Create RateBeer::Scraper instance.
+    #
+    # Requires an ID#, and optionally accepts a name and options parameters.
+    #
+    # @param [Integer, String] id ID# of the entity which is to be retrieved
+    # @param [String] name Name of the entity to which ID# relates if known
+    # @param [hash] options Options hash for entity created
+    #
+    def initialize(id, name: nil, **options)
+      @id   = id
+      @name = name unless name.nil?
+      options.each do |k, v|
+        instance_variable_set("@#{k.to_s}", v)
+      end
+    end
+
+    def inspect
+      val = "#<#{self.class} ##{@id}"
+      val << " - #{@name}" if instance_variable_defined?("@name")
+      val << ">"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def ==(other_entity)
+      other_entity.is_a?(self.class) && id == other_entity.id
+    end
+
+    def url
+      @url ||= if respond_to?("#{demodularized_class_name.downcase}_url", id)
+                 send("#{demodularized_class_name.downcase}_url", id)
+               end
+    end
+
+    # Return full details of the scraped entity in a Hash.
+    #
+    def full_details
+      data = self.class
+                 .data_keys
+                 .map { |k| [k, send("#{k}")] }
+                 .to_h
+      { id:   id,
+        url:  url }.merge(data)
+    end
+
+    # Determine if data is paginated, or not.
+    #
+    # @param [Nokogiri::Doc] doc Nokogiri document to test for pagination
+    # @return [Boolean] true, if paginated, else false
+    #
+    def pagination?(doc)
+      !page_count(doc).nil?
+    end
+
+    # Determine the number of pages in a document.
+    #
+    # @param [Nokogiri::Doc] doc Nokogiri document to test for pagination
+    # @return [Integer] Number of pages in the document
+    #
+    def page_count(doc)
+      doc.at_css('.pagination') && doc.at_css('.pagination')
+                                      .css('b')
+                                      .map(&:text)
+                                      .map(&:to_i)
+                                      .max
+    end
+
+    # Create Nokogiri doc from url.
+    #
+    def noko_doc(url)
+      begin
+        Nokogiri::HTML(open(url).read)
+      rescue OpenURI::HTTPError => msg
+        raise PageNotFoundError.new("Page not found - #{url}")
+      end
+    end
+
+    module_function :noko_doc
+
+    # Emulate &nbsp; character for stripping, substitution, etc.
+    #
+    def nbsp
+      Nokogiri::HTML("&nbsp;").text
+    end
+
+    module_function :nbsp
+
+    # Convert text keys to symbols
+    #
+    def symbolize_text(text)
+      text.downcase.gsub(' ', '_').gsub('.', '').to_sym
+    end
+    
+    # Fix characters in string scraped from website.
+    #
+    # This method substitutes problematic characters found in
+    # strings scraped from RateBeer.com
+    #
+    def fix_characters(string)
+      characters = { nbsp     => " ",
+                     "\u0093" => "ž",
+                     "\u0092" => "'",
+                     "\u0096" => "–",
+                     / {2,}/ => " " }
+      characters.each { |c, r| string.gsub!(c, r) }
+      string.strip
+    end 
+
+    # Make POST request to RateBeer form. Return a Nokogiri doc.
+    #
+    def post_request(url, params)
+      res = Net::HTTP.post_form(url, params)
+      Nokogiri::HTML(res.body)
+    end
+
+    private
+
+    def demodularized_class_name
+      self.class.name.split("::").last
+    end
+  end
+end

data/lib/ratebeer/search.rb

@@ -0,0 +1,224 @@
+require "i18n"
+require_relative "beer"
+require_relative "brewery"
+require_relative "scraping"
+require_relative "urls"
+
+module RateBeer
+  
+  # Stop I18N from enforcing locale, to avoid error message
+  I18n.enforce_available_locales = false
+
+  # This class provides functionality for searching RateBeer.com for a
+  # specific beer or brewery.
+  #
+  class Search
+    # Keys for fields scraped on RateBeer
+    def self.data_keys
+      [:query,
+       :beers,
+       :breweries]
+    end
+
+    include RateBeer::Scraping
+    include RateBeer::URLs
+
+    class << self
+      # Create method which generates new search instance and immediately runs
+      # a search.
+      #
+      def search(query)
+        s = self.new(query)
+        { beers:      s.beers,
+          breweries:  s.breweries }
+      end
+    end
+
+    attr_reader :query
+
+    # Create a RateBeer::Search instance.
+    #
+    # @param [String] query Term to use to search RateBeer
+    #
+    def initialize(query)
+      self.query = query
+    end
+
+    # Setter for query instance variable.
+    #
+    def query=(qry)
+      clear_cached_data
+      @query = fix_query_param(qry)
+    end
+
+    def inspect
+      num_beers = @beers && @beers.count || 0
+      num_breweries = @breweries && @breweries.count || 0
+      val = "#<#{self.class} - #{@query}"
+      val << " - #{num_beers} beers / #{num_breweries} breweries" if @beers || @breweries
+      val << ">"
+    end
+
+    # Search RateBeer for beers, brewers, etc.
+    #
+    # The search results page contains a series of tables each of which has the
+    # "results" class, containing data of matching brewers, beers, and places
+    # in that order. Only brewers and beers are extracted.
+    #
+    # @return [Hash] Results of the search, broken into breweries and beers,
+    #                with the attributes of these results contained therein.
+    #
+    def run_search
+      @beers, @breweries = nil
+      doc                = post_request(URI.join(BASE_URL, SEARCH_URL), post_params)
+      tables             = doc.css('h2').map(&:text).zip(doc.css('table'))
+      beers, breweries   = nil
+      tables.each do |(heading, table)|
+        case heading
+        when 'brewers'
+          @breweries = process_breweries_table(table)
+        when 'beers'
+          @beers = process_beers_table(table)
+        end
+      end
+
+      # RateBeer is inconsistent with searching for IPAs. If IPA is in the name
+      # of the beer, replace IPA with India Pale Ale, and add the additional 
+      # results to these results.
+      if query.downcase.include?(" ipa")
+        alt_query = query.downcase.gsub(" ipa", " india pale ale")
+        extra_beers = self.class.new(alt_query).run_search.beers
+        @beers = ((@beers || []) + (extra_beers || [])).uniq
+      end
+      return self
+    end
+
+    alias retrieve_details run_search
+
+    private
+
+    # Generate parameters to use in POST request.
+    #
+    def post_params
+      { "BeerName" => @query }
+    end
+
+    # Process breweries table returned in search.
+    #
+    # The breweries table (if returned) consists of a series of rows each
+    # containing two cells: the first is the name (and hyperlink) to the
+    # brewery; and the second is the full location of the brewery.
+    #
+    # @param [Nokogiri::XML::Element] table An HTML table containing breweries
+    #   information
+    # @return [Hash{Symbol, String}] Brewery data, including name, location,
+    #   url and ID
+    #
+    def process_breweries_table(table)
+      table.css('tr').map do |row|
+        result = [:id, :name, :location, :url].zip([nil]).to_h
+        result[:name], result[:location] = row.element_children.map { |x| 
+          fix_characters(x.text) 
+        }
+        result[:url] = row.at_css('a')['href']
+        result[:id]  = result[:url].split('/').last.to_i
+        Brewery.new(result[:id], name: result[:name])
+      end
+    end
+
+    # Process beers table returned in search.
+    #
+    # The beers table (if returned) consists of a series of rows each of which
+    # contains five cells: the first is the name (and hyperlink) to the beer;
+    # the second and third relate to features of the RateBeer.com site, and are
+    # ignored; the fourth provides the rating of the beer (if any); and the
+    # fifth contains the number of ratings submitted for this beer.
+    #
+    # The first row in the table contains headings, and is disregarded.
+    #
+    # @param [Nokogiri::XML::Element] table An HTML table containing beers
+    #   information
+    # @return [Hash{Symbol, String}] Beer data, including name, score, rating,
+    #   url and ID
+    #
+    def process_beers_table(table)
+      table.css('tr').drop(1).map do |row|
+        result = [:id, :name, :score, :ratings, :url].zip([nil]).to_h
+        content = row.element_children.map { |x| fix_characters(x.text) }
+        result[:name]    = content.first
+        result[:score], result[:ratings] = content.values_at(3, 4)
+                                                  .map { |n| 
+          n.nil? || n.empty? ? nil : n.to_i 
+        }
+        result[:url] = row.at_css('a')['href']
+        result[:id]  = result[:url].split('/').last.to_i
+        Beer.new(result[:id], name: result[:name])
+      end
+    end
+
+    # Amend search query string for better results
+    #
+    # RateBeer is a little finicky about finding search results. It does not
+    # provide results on abbreviations, and a passed query including special
+    # characters will return no hits. Often searching using a generic term such
+    # as Co, Brewers, Brewery, etc. will not return any results. This method
+    # strips out such generic terms from a query.
+    #
+    # This method attempts to deal with these issues.
+    #
+    # @param [String] query Raw query parameter
+    # @return [String] Query parameter amended to improve results
+    #
+    def fix_query_param(query)
+      query = strip_generic_terms(query)
+      query = substitute_known_terms(query)
+      I18n.transliterate(query)
+    end
+
+    # Strip defined generic terms from query.
+    #
+    # This method removes all generic terms which may refer to a brewery, but
+    # which may not appear in the brewery's proper name, e.g. brewers.
+    #
+    # @param [String] query Raw query parameter
+    # @return [String] Query parameter with generics stripped out
+    #
+    def strip_generic_terms(query)
+      generic_words = ["Brew",
+                       "Brewers", 
+                       "Brewery",
+                       "Brewing",
+                       "Brewhouse",
+                       "Company",
+                       "Co\.?",
+                       "Inc\.?",
+                       "Ltd\.?",
+                       "Limited"]
+      generic_words.map! { |w| /(^| )#{w}( |$)/i }
+      generic_words.each { |w| query.gsub!(w, " ") }
+      query.strip
+    end
+
+    # Substitute known problematic terms in query.
+    #
+    # This method will replace terms which are known to cause problems in the
+    # search with different terms which do not cause the same problem.
+    #
+    # @param [String] query Raw query parameter
+    # @return [String] Query parameter with terms substituted
+    #
+    def substitute_known_terms(query)
+      # List of problem terms - key can be a string or regexp
+      problem_terms = { "six°north" => "Six Degrees North",
+                        /[\/:]/     => " " }
+      problem_terms.each { |term, substitute| query.gsub!(term, substitute) }
+      query.strip
+    end 
+
+    # Clear cached search data.
+    #
+    def clear_cached_data
+      ["@beers", "@breweries"].each { |v| remove_instance_variable(v) if instance_variable_defined?(v) }
+    end
+  end
+end

data/lib/ratebeer/style.rb

@@ -0,0 +1,104 @@
+require_relative 'beer'
+require_relative 'scraping'
+require_relative 'urls'
+
+module RateBeer
+  class Style
+    # Each key represents an item of data accessible for each beer, and defines
+    # dynamically a series of methods for accessing this data.
+    #
+    def self.data_keys
+      [:name,
+       :description,
+       :glassware,
+       :beers]
+    end
+
+    include RateBeer::Scraping
+    include RateBeer::URLs
+
+    attr_accessor :category
+
+    class << self
+      include RateBeer::URLs
+
+      # Scrape all styles.
+      #
+      # RateBeer provides a styles landing page, with links through to info on 
+      # each style listed thereon. This method scrapes style info with links 
+      # to the more detailed pages.
+      #
+      # @param [Boolean] hidden_styles Flag for whether to include hidden 
+      #   styles.
+      # @return [Array<RateBeer::Style>] List of styles with links etc. to 
+      #   detailed pages
+      #
+      def all_styles(include_hidden=false)
+        doc  = Scraping.noko_doc(URI.join(BASE_URL, '/beerstyles/'))
+        root = doc.at_css('div.container-fluid table')
+
+        categories = root.css('.groupname').map(&:text)
+        style_node = root.css('.styleGroup')
+
+        styles = style_node.flat_map.with_index do |list, i|
+          list.css('a').map do |x| 
+            category = categories[i]
+            Style.new(x['href'].split('/').last.to_i, name: x.text).tap { |s| 
+              s.category = category 
+            }
+          end
+        end
+        if include_hidden
+          styles += hidden_styles
+        else
+          styles
+        end
+      end
+      
+      # Scrape hidden style information
+      #
+      # RateBeer has a number of styles not accessible from the "beerstyles" 
+      # landing page. This method scrapes these.
+      #
+      # @return [Array<Hash>] List of hidden styles
+      #
+      def hidden_styles
+        hidden_ids = [40, 41, 57, 59, 66, 67, 68, 69, 70, 
+                      75, 83, 99, 104, 106, 116, 119, 120]
+        hidden_ids.map do |id|
+          Style.new(id)
+        end
+      end
+    end
+
+    private
+
+    # Retrieve details about this style from the website.
+    #
+    # This method stores the retrieved details in instance variables of
+    # this style instance.
+    #
+    def retrieve_details
+      doc       = noko_doc(URI.join(BASE_URL, style_url(id)))
+      root      = doc.at_css('.container-fluid')
+      beer_list = noko_doc(URI.join(BASE_URL, style_beers_url(id)))
+
+      if !root.nil?
+        @name = root.at_css('h1').text.strip
+      else
+        raise PageNotFoundError.new("style not found - ##{id}")
+      end
+
+      @description = root.at_css('#styleDescription').text
+      @glassware   = root.css('.glassblurb').map { |x| x.text.strip }
+
+      @beers = beer_list.css('tr').drop(1).map do |row|
+        cells = row.css('td')
+        url   = cells[1].at_css('a')['href']
+        [cells[0].text.to_i, Beer.new(url.split('/').last, 
+                                      name: fix_characters(cells[1].text))]
+      end.to_h
+      nil
+    end
+  end
+end

data/lib/ratebeer/urls.rb

@@ -0,0 +1,54 @@
+module RateBeer
+
+  # This module contains URLs or URL patterns for use throughout the Gem.
+  #
+  module URLs
+    BASE_URL   = "http://www.ratebeer.com"
+    SEARCH_URL = "/findbeer.asp"
+
+    # Return URL to info page for beer with id
+    #
+    def beer_url(id)
+      "/beer/a/#{id}/"
+    end
+
+    # Return URL to page containing reviews for a given beer
+    #
+    def review_url(beer_id, sort_suffix, page_number)
+      "/beer/a/#{beer_id}/#{sort_suffix}/#{page_number}/"
+    end
+
+    # Return URL to info page for brewery with id
+    #
+    def brewery_url(id)
+      "/brewers/a/#{id}/"
+    end
+
+    # Return URL to info page for country with id
+    def country_url(id)
+      "/breweries/a/0/#{id}/"
+    end
+
+    # Return URL to info page for region with id
+    def region_url(id)
+      "/breweries/a/#{id}/0/"
+    end
+
+    # Return URL to info page for style with id
+    def style_url(id)
+      "/beerstyles/a/#{id}/"
+    end
+
+    # Return URL to beers list page for style with id
+    def style_beers_url(id)
+      "/ajax/top-beer-by-style.asp?style=#{id}"
+    end
+
+    [:beer_url, 
+     :brewery_url,
+     :country_url, 
+     :region_url,
+     :style_url,
+     :style_beers_url].each { |m| module_function m }
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ratebeer
 version: !ruby/object:Gem::Version
-  version: 0.0.4b
+  version: 0.0.5a
 platform: ruby
 authors:
 - Dan Meakin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-03 00:00:00.000000000 Z
+date: 2016-07-16 00:00:00.000000000 Z
 dependencies: []
 description: RateBeer provides a way to access beer & brewery data from RateBeer.com.
 email: dan@danmeakin.com
@@ -23,6 +23,16 @@ files:
 - Rakefile
 - bin/ratebeer
 - lib/ratebeer.rb
+- lib/ratebeer/beer.rb
+- lib/ratebeer/brewery.rb
+- lib/ratebeer/country.rb
+- lib/ratebeer/location.rb
+- lib/ratebeer/region.rb
+- lib/ratebeer/review.rb
+- lib/ratebeer/scraping.rb
+- lib/ratebeer/search.rb
+- lib/ratebeer/style.rb
+- lib/ratebeer/urls.rb
 - spec/lib/ratebeer/beer_spec.rb
 - spec/lib/ratebeer/brewery_spec.rb
 - spec/lib/ratebeer/country_spec.rb