odeon_uk 1.1.2 → 1.1.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MTZjMGMzNjQxNzUwZjUxZTE2OWY3NDRiNjY5ZmIxNWM0NjFjZjZiZg==
+    NDQxYWI5ZWRlNDQ1YThkYjc2NzU5MWJlNTA5ZTM3MGQyMzE3ZDVhOA==
   data.tar.gz: !binary |-
-    N2Y2MGY0NWRmYjBiZDEwYjU2ZGJiYWI4ODVlMjg3YmM5YWFkMWYxYQ==
+    ZGRjMjg4Y2M5YTMxZDU5MWQ2ZDIxZTUyMDAyODk3ZWFlZDcwODdmOA==
 SHA512:
   metadata.gz: !binary |-
-    NzA0MzM5ZTc2ZjI4ZjBiNTI3MTQzY2NiZTRkZTE4MjM0NzE4NDE0ZGRkNWFi
-    YWUxMDA5NTA4ZTUyNGYwYjIyZTdjZTMxM2QyY2M0MWVjNzI0MjBjOTYwZjY5
-    OTYxOGZjOTQ1MTk4NTY2NzVlZWY0NjBhYWY1YzQ0ODI3ZWNkZWE=
+    YjQ0ZGEzOTAwNzczOWVkZmY1NjkzODYyYThiMWQ4NGYxNjMzOWUxOGEzYzAw
+    YzQwYzE3YzQ4ZmJhZWU2MTdmMWI2ZjZmMjUxZDQ0OTA1MWY5N2VkMDVlZjMz
+    ZjNlYzdjOTdhNzk2M2NmYWMzYmIwZTVhMjBkODcyMTJkYTEyOTc=
   data.tar.gz: !binary |-
-    YWYxZTY5NmQyZmJiMzhkMDY2ZDhhNGFmYWVmYzE3ZjIwM2U0NmFiZGYzZmQ0
-    NDZmMjFkMWE1Y2YzNmFiZDg2YmViNDQ0Zjg1ODA1ODYyODkyYmI2NTE0MWZk
-    MDMxMjg0NDFjNzRlNDllODA1ZTRiNmE0YzViMTQ0ZjE4OWE4NDk=
+    NjdmNWExNzI5NWJhYTg4YjQzOTdkMTRkYjQ5ZjVjNzMyOTM2YWM3NTY5M2Vk
+    ZmNhYTVmZTdhMmZhNWU1M2JjZTRiYzA4YWMzZDFhY2Q5MzYyMTZmNWIxMTlk
+    YjYyODFjMWNiNzZlZWQ2OWQxMjRhZGUyOTM2OWQ3MGU1OTJmMTQ=

data/lib/odeon_uk/cinema.rb

@@ -1,24 +1,23 @@
 module OdeonUk
 
-  # Public: The object representing a cinema on the Odeon UK website
+  # The object representing a cinema on the Odeon UK website
   class Cinema
 
-    # Public: Returns the String brand of the cinema #=> 'Odeon'
+    # @return [String] the brand of the cinema
     attr_reader :brand
-    # Public: Returns the Integer id of the cinema on teh odeon website
+    # @return [Integer] the numeric id of the cinema on the Odeon website
     attr_reader :id
-    # Public: Returns the String name of the cinema
+    # @return [String] the name of the cinema
     attr_reader :name
-    # Public: Returns the String slug of the cinema
+    # @return [String] the slug of the cinema
     attr_reader :slug
-    # Public: Returns the String url of the cinema's page on odeon.co.uk
+    # @return [String] the url of the cinema on the Odeon website
     attr_reader :url
 
-    # Public: Initialize a cinema
-    #
-    # id   - Integer/String of the cinema on the odeon website
-    # name - String of cinema name
-    # url  - String of cinema url on the odeon website
+    # @param [Integer, String] id cinema id
+    # @param [String] name cinema name
+    # @param [String] url url on Odeon website
+    # @return [OdeonUk::Cinema]
     def initialize(id, name, url)
       @brand = 'Odeon'
       @id    = id.to_i
@@ -27,31 +26,23 @@ module OdeonUk
       @url   = (url[0] == '/') ? "http://www.odeon.co.uk#{url}" : url
     end
 
-    # Public: Return basic cinema information for all Odeon cinemas
-    #
-    # Examples
-    #
+    # Return basic cinema information for all cinemas
+    # @return [Array<OdeonUk::Cinema>]
+    # @example
     #   OdeonUk::Cinema.all
-    #   # => [<OdeonUk::Cinema brand="Odeon" name="Odeon Tunbridge Wells" slug="odeon-tunbridge-wells" id=23 url="...">, #=> <OdeonUk::Cinema brand="Odeon" name="Odeon Brighton" slug="odeon-brighton" chain_id="71" url="...">, ...]
-    #
-    # Returns an array of hashes of cinema information.
+    #   #=> [<OdeonUk::Cinema brand="Odeon" name="Odeon Tunbridge Wells" slug="odeon-tunbridge-wells" id=23 url="...">, #=> <OdeonUk::Cinema brand="Odeon" name="Odeon Brighton" slug="odeon-brighton" chain_id="71" url="...">, ...]
     def self.all
       cinema_links.map do |link|
         new_from_link link
       end
     end
 
-    # Public: Return single cinema information for an Odeon cinema
-    #
-    # id_string - a string/int representing the cinema id
-    #             of the format '32'/32 as used on the odeon.co.uk website
-    #
-    # Examples
-    #
+    # Find a single cinema
+    # @param [Integer, String] id the cinema id of the format 71/'71' as used on the odeon.co.uk website
+    # @return [OdeonUk::Cinema, nil]
+    # @example
     #   OdeonUk::Cinema.find('71')
-    #   # => <OdeonUk::Cinema brand="Odeon" name="Brighton" slug="brighton" id=71 url="...">
-    #
-    # Returns an Odeon::Cinema or nil if none was found
+    #   #=> <OdeonUk::Cinema brand="Odeon" name="Brighton" slug="brighton" id=71 url="...">
     def self.find(id)
       id = id.to_i
       return nil unless id > 0
@@ -59,18 +50,12 @@ module OdeonUk
       all.select { |cinema| cinema.id == id }[0]
     end
 
-    # Public: Returns adress hash of an Odeon cinema
-    #
-    # Examples
-    #
+    # Address of the cinema
+    # @return [Hash] of different address parts
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.adr
-    #   # => { street_address: 'Kingswest',
-    #          locality: 'Brighton',
-    #          postal_code: 'BN1 2RE',
-    #          country_name: 'United Kingdom' }
-    #
-    # Returns an array of strings or nil
+    #   #=> { street_address: 'Kingswest', locality: 'Brighton', postal_code: 'BN1 2RE', country_name: 'United Kingdom' }
     def adr
       {
         street_address: street_address,
@@ -80,15 +65,12 @@ module OdeonUk
       }
     end
 
-    # Public: Returns films for an Odeon cinema
-    #
-    # Examples
-    #
+    # Films with showings scheduled at this cinema
+    # @return [Array<OdeonUk::Film>]
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.films
-    #   # => [<OdeonUk::Film name="Iron Man 3">, <OdeonUk::Film name="Star Trek Into Darkness">]
-    #
-    # Returns an array of Odeon::Film objects
+    #   #=> [<OdeonUk::Film name="Iron Man 3">, <OdeonUk::Film name="Star Trek Into Darkness">]
     def films
       film_nodes.map do |node|
         parser = OdeonUk::Internal::FilmWithScreeningsParser.new node.to_s
@@ -96,42 +78,33 @@ module OdeonUk
       end.uniq
     end
 
-    # Public: Returns the locality (town) of an Odeon cinema
-    #
-    # Examples
-    #
+    # The locality (town) of the cinema
+    # @return [String]
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.locality
-    #   # => 'Brighton'
-    #
-    # Returns a String
+    #   #=> 'Brighton'
     def locality
       address_node.text.match(/\w+(\s\w+){0,}\s+(\w+(\s\w+){0,})/)[2]
     end
 
 
-    # Public: Returns the postal code of an Odeon cinema
-    #
-    # Examples
-    #
+    # Post code of the cinema
+    # @return [String]
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.postal_code
-    #   # => 'BN1 2RE'
-    #
-    # Returns a String
+    #   #=> 'BN1 2RE'
     def postal_code
       address_node.text.match(/[A-Z]{1,2}\d{1,2}[A-Z]?\s\d{1,2}[A-Z]{1,2}/)[0]
     end
 
-    # Public: Returns screenings for an Odeon cinema
-    #
-    # Examples
-    #
+    # All planned screenings
+    # @return [Array<OdeonUk::Screening>]
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.screenings
-    #   # => [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
-    #
-    # Returns an array of Odeon::Screening objects
+    #   #=> [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
     def screenings
       film_nodes.map do |node|
         parser = OdeonUk::Internal::FilmWithScreeningsParser.new node.to_s
@@ -143,31 +116,27 @@ module OdeonUk
       end.flatten
     end
 
-    # Public: Returns screenings for particular film at an Odeon cinema
-    #
-    # Examples
-    #
+    # Screenings for particular film
+    # @param [OdeonUk::Film, String] film a film object or title of the film
+    # @return [Array<Odeon::Screening>]
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
-    #   cinema.screenings_of 'Iron Man 3'
-    #   # => [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
-    #   cinema.screenings_of <OdeonUk::Film name="Iron Man 3">
-    #   # => [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
-    #
-    # Returns an array of Odeon::Screening objects
+    #   cinema.screenings_of('Iron Man 3')
+    #   #=> [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
+    #   iron_man_3 = OdeonUk::Film.new "Iron Man 3"
+    #   cinema.screenings_of(iron_man_3)
+    #   #=> [<OdeonUk::Screening film_name="Iron Man 3" cinema_name="Brighton" when="..." varient="...">, <OdeonUk::Screening ...>]
     def screenings_of film
       film_name = (film.is_a?(OdeonUk::Film) ? film.name : film)
       screenings.select { |s| s.film_name == film_name }
     end
 
-    # Public: Returns the street adress of an Odeon cinema
-    #
-    # Examples
-    #
+    # The street adress of the cinema
+    # @return a String
+    # @example
     #   cinema = OdeonUk::Cinema.find('71')
     #   cinema.street_address
-    #   # => 'Kingswest'
-    #
-    # Returns a String
+    #   #=> 'Kingswest'
     def street_address
       address_node.text.match(/\A\s+(\w+(\s\w+){0,})/)[1]
     end

data/lib/odeon_uk/film.rb

@@ -1,50 +1,45 @@
 module OdeonUk
 
-  # Public: The object representing a film on the Odeon UK website
+  # The object representing a film on the Odeon UK website
   class Film
     include Comparable
 
-    # Public: Returns the String name of the film
+    # @return [String] the name of the film
     attr_reader :name
-    # Public: Returns the String slug of the film
+    # @return [String] the normalized slug derived from the film name
     attr_reader :slug
 
-    # Public: Initialize a screening
-    #
-    # name - String of the film name
+    # @param [String] name the film name
+    # @return [OdeonUk::Film]
     def initialize(name)
       @name = name
       @slug = name.downcase.gsub(/[^0-9a-z ]/,'').gsub(/\s+/, '-')
     end
 
-    # Public: Allows sort on objects
+    # Allows sort on objects
+    # @param [OdeonUk::Film] other another film object
+    # @return [Integer] -1, 0 or 1
     def <=> other
       self.slug <=> other.slug
     end
 
-    # Public: Check an object is the same as another object.
-    #
-    # True if both objects are the same exact object, or if they are of the same
-    # type and share an equal slug
-    #
-    # Guided by http://woss.name/2011/01/20/equality-comparison-and-ordering-in-ruby/
-    #
-    # object - object to be compared
-    #
-    # Returns Boolean
+    # Check an object is the same as another object.
+    # @param [OdeonUk::Film] other another film
+    # @return [Boolean] True if both objects are the same exact object, or if
+    #   they are of the same type and share an equal slug
+    # @note Guided by http://woss.name/2011/01/20/equality-comparison-and-ordering-in-ruby/
     def eql? other
       self.class == other.class && self == other
     end
 
-    # Public: generates hash of slug in order to allow two records of the same
-    # type and id to work with something like:
+    # Generates hash of slug in order to allow two records of the same type and
+    # id to work with something like:
     #
     #   [ Film.new('ABC'), Film.new('DEF') ] & [ Film.new('DEF'), Film.new('GHI') ]
     #   #=> [ Film.new('DEF') ]
     #
-    # Guided by http://woss.name/2011/01/20/equality-comparison-and-ordering-in-ruby/
-    #
-    # Returns an Integer hash of the slug
+    # @return [Integer] hash of slug
+    # @note Guided by http://woss.name/2011/01/20/equality-comparison-and-ordering-in-ruby/
     def hash
       self.slug.hash
     end

data/lib/odeon_uk/internal/film_with_screenings_parser.rb

@@ -1,12 +1,19 @@
 module OdeonUk
+
+  # Internal utility classes: Do not use
+  # @api private
   module Internal
-    # Private: An object to parse a film HTML snippet
+
+    # Parses a chunk of HTML to derive movie showing data
     class FilmWithScreeningsParser
 
+      # @param [String] film_html a chunk of html
       def initialize(film_html)
         @nokogiri_html = Nokogiri::HTML(film_html)
       end
 
+      # The film name
+      # @return [String]
       def film_name
         name = @nokogiri_html.css('.presentation-info h4 a').children.first.to_s
 
@@ -34,6 +41,13 @@ module OdeonUk
         name = name.gsub /\s+\z/, '' # remove trailing spaces
       end
 
+      # Showings
+      # @return [Hash]
+      # @example
+      #   {
+      #     "2D" => [[Time.utc, 'http://www...'], [Time.utc, 'http://www...']],
+      #     "3D" => [[Time.utc, 'http://www...']]
+      #   }
       def showings
         tz = TZInfo::Timezone.get('Europe/London')
         @nokogiri_html.css('.times-all.accordion-group').inject({}) do |result, varient_node|

data/lib/odeon_uk/screening.rb

@@ -1,34 +1,32 @@
 module OdeonUk
 
-  # Public: The object representing a screening of a film on the Odeon UK website
+  # The object representing a single screening of a film on the Odeon UK website
   class Screening
 
-    # Public: Returns the booking URL on the cinema website
+    # @return [String] the booking URL on the cinema website
     attr_reader :booking_url
-    # Public: Returns the String name of the cinema
+    # @return [String] the cinema name
     attr_reader :cinema_name
-    # Public: Returns the String name of the film
+    # @return [String] the film name
     attr_reader :film_name
-    # Public: Returns the Time of the screening
+    # @return [Time] the UTC time of the screening
     attr_reader :when
-    # Public: Returns the Type of screening (3d, baby, kids, live)
+    # @return [String] the type of screening (2D, 3D, IMAX...)
     attr_reader :varient
 
-    # Public: Initialize a screening
-    #
-    # film_name   - String of the film name
-    # cinema_name - String of the cinema name on the Odeon website
-    # time        - Time representing the time of the screening (24 hour clock)
-    # varient     - String representing the type of showing (e.g. 3d/baby/live)
+    # @param [String] film_name the film name
+    # @param [String] the cinema name
+    # @param [Time] time datetime of the screening (UTC preferred)
+    # @param [String] booking_url direct link to the booking page for this screening
+    # @param [String] varient the type of showing (e.g. 3d/baby/live)
     def initialize(film_name, cinema_name, time, booking_url=nil, varient=nil)
       @cinema_name, @film_name, @varient = cinema_name, film_name, varient
       @booking_url = booking_url
       @when = time.utc? ? time : TZInfo::Timezone.get('Europe/London').local_to_utc(time)
     end
 
-    # Public: The Date of the screening
-    #
-    # Returns a Date
+    # The date of the screening
+    # @return [Date]
     def date
       @when.to_date
     end

data/lib/odeon_uk/version.rb

@@ -1,3 +1,6 @@
+# Ruby interface for http://www.odeon.co.uk
+# @version 1.1.3
 module OdeonUk
-  VERSION = "1.1.2"
+  # Gem version
+  VERSION = "1.1.3"
 end

data/lib/odeon_uk.rb

@@ -13,5 +13,4 @@ require_relative './odeon_uk/film'
 require_relative './odeon_uk/screening'
 
 module OdeonUk
-  # Your code goes here...
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: odeon_uk
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
 platform: ruby
 authors:
 - Andy Croll
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-06 00:00:00.000000000 Z
+date: 2013-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake