reel_uk 1.0.0

data/README.md

@@ -0,0 +1,171 @@
+# ReelUk
+
+A simple gem to pull cinemas and performances from the [Reel Cinemas website](https://reel-cinemas.co.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'reel_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install reel_uk
+
+## Usage
+
+The gem conforms to the API set down in the `cinebase` gem, [andycroll/cinebase](https://github.com/andycroll/cinebase), which provides a lot of useful base vocabulary and repetitive code for this series of cinema focussed gems.
+
+Performance titles are sanitized as much as possible, removing subtitled, 3D
+and premium screen copies, preview prefixes, anniversaries and years, and
+naming National Theatre Live and Royal Ballet and Opera screenings in full.
+
+No token or setup is needed. Reel is moving from Admit One's A1Web website,
+`reelcinemas.co.uk`, to a WordPress website, `reel-cinemas.co.uk`, built on
+Jacro's cinema plugin with TapOS ticketing. Most venues have moved. The cinema
+menu on the new home page links each venue's pages on whichever website it
+uses, and the gem reads each venue from there: the new website itself, or the
+old one through cinebase's shared `Cinebase::A1web` support. A venue that
+moves keeps its id, its path on both websites.
+
+### Cinema
+
+The venue list is cached for an hour. Reading it takes one request for the home
+page. Venue pages give one-line addresses and no coordinates, so the gem holds
+them: addresses from the page footers and coordinates from OpenStreetMap,
+apart from Burnley's, which is not mapped and comes from its postcode.
+
+``` ruby
+ReelUk::Cinema.all
+#=> [<ReelUk::Cinema ...>, <ReelUk::Cinema ...>, ...]
+
+cinema = ReelUk::Cinema.new('borehamwood')
+#=> <ReelUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'Metropolis Centre',
+  extended_address: '84 Shenley Road',
+  locality:         'Borehamwood',
+  region:           'Hertfordshire',
+  postal_code:      'WD6 1EH',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Reel'
+
+cinema.full_name
+#=> 'Reel Borehamwood'
+
+cinema.id
+#=> 'borehamwood'
+
+cinema.latitude
+#=> 51.6549265
+
+cinema.url
+#=> 'https://reel-cinemas.co.uk/borehamwood'
+
+cinema.a1web?
+#=> false # true for venues still on reelcinemas.co.uk
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. It always reads every
+advertised date.
+
+On the WordPress website the what's on page covers three weeks and the coming
+soon page shows only a film's first few showtimes. The gem reads both, then
+asks the quick booking menu for every showtime of each film on either page:
+three requests and one more for each film, about forty for a venue, which
+takes half a minute. On the old A1Web website the what's on page holds every
+date, so it is one request.
+
+``` ruby
+ReelUk::Performance.at('chorley', from: Date.today, to: Date.today + 2)
+#=> [<ReelUk::Performance ...>, <ReelUk::Performance ...>, ...]
+
+performance = ReelUk::Performance.at('chorley').detect(&:subtitled?)
+#=> <ReelUk::Performance ...>
+
+performance.film_name
+#=> 'Wicker' # from 'Wicker - Subtitled Screening'
+
+performance.film_year
+#=> nil # from the title, e.g. 1981 for 'The Evil Dead (1981)'
+
+performance.language
+#=> nil # e.g. 'Hindi' from 'Ramayana: Rise of a Legend: 3D (Hindi)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['subtitled']
+
+performance.subtitled?
+#=> true
+
+performance.starting_at
+#=> 2026-11-03 17:15:00 UTC
+
+performance.booking_url
+#=> 'https://reel-cinemas.co.uk/chorley/booknow/34324/'
+
+performance.cinema_name
+#=> 'Chorley'
+
+performance.cinema_id
+#=> 'chorley'
+```
+
+Booking links on the WordPress website open the TapOS booking for the
+showtime in the venue's pages. Venues on the old website link to their Admit
+One ticketing site, such as
+`https://reelhull.admit-one.co.uk/tickets/?perfCode=34037`, which redirects to
+seat selection; the old website's own booking links only work in a browser
+that has just visited the venue's pages.
+
+Variants are `arts` (event cinema, from A1Web's 'Event Cinema' heading or, on
+the WordPress website, from titles such as 'RBO' and 'NT Live'), `baby`,
+`imax`, `kids`, `relaxed`, `senior` and `subtitled`. Showtime labels such as
+'Senior' are only on the WordPress website's what's on page, so showtimes
+beyond its three weeks have none until they come into range. 'Movie Madness'
+marks cheap tickets and is not a variant.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live reel-cinemas.co.uk and reelcinemas.co.uk, several minutes
+```
+
+Fixtures in `test/fixtures` are captured from both websites and trimmed: the
+home page's cinema menu, Chorley's quick booking menu, what's on page and
+coming soon page with a few films on a few dates, the quick booking menu's
+showtimes for three films, and Hull's A1Web what's on page with a few films on
+a few dates. `test/support/api_shapes.rb` describes the parts of the pages the
+gem reads. The unit suite checks the fixtures against it and the live suite
+checks real responses, held only in memory. When the websites change, update
+the shape first, then the fixtures.
+
+## Releasing
+
+Bump the version, merge, then run the **Release Gem** workflow in GitHub
+Actions. It runs the tests, tags the version and publishes the gem through
+RubyGems trusted publishing.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/reel_uk/cinema.rb

@@ -0,0 +1,201 @@
+module ReelUk
+  # The object representing a cinema on the Reel Cinemas website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the venue's path on the website, e.g. 'chorley'
+
+    # Worker processes outlive a day's listings, so refetch the venue list
+    CACHE_SECONDS = 3600
+
+    # Most venues have moved to Reel's WordPress website. The rest are still
+    # on its old Admit One A1Web website, which the cinema menu links.
+    VENUE = %r{<option value="(https://(?:reel-cinemas|reelcinemas)\.co\.uk/([a-z-]+))/?">([^<]+)</option>}
+    A1WEB_HOST = 'reelcinemas.co.uk'
+    A1WEB_WEBSITE = 'https://reelcinemas.co.uk'
+    # Menu names such as 'Fareham - Hampshire' add the county
+    COUNTY = /\s+-\s+.*\z/
+
+    # Venue pages give one-line addresses and no coordinates. Addresses come
+    # from those page footers, coordinates from OpenStreetMap, apart from
+    # Burnley's, from its postcode.
+    LOCATIONS = {
+      'bishop-auckland' => {
+        street_address: 'Bishop Auckland Retail and Leisure Park', locality: 'Bishop Auckland',
+        postal_code: 'DL14 9AA', latitude: 54.6383991, longitude: -1.6885187
+      },
+      'blackburn' => {
+        street_address: 'Nab Lane', locality: 'Blackburn', region: 'Lancashire', postal_code: 'BB2 1LN',
+        latitude: 53.7483439, longitude: -2.4868526
+      },
+      'borehamwood' => {
+        street_address: 'Metropolis Centre', extended_address: '84 Shenley Road', locality: 'Borehamwood',
+        region: 'Hertfordshire', postal_code: 'WD6 1EH', latitude: 51.6549265, longitude: -0.2747628
+      },
+      'bridgnorth' => {
+        street_address: 'Whitburn Street', locality: 'Bridgnorth', region: 'Shropshire', postal_code: 'WV16 4QP',
+        latitude: 52.535652, longitude: -2.4222158
+      },
+      'burnley' => {
+        street_address: 'Unit 1, Pioneer Place', extended_address: 'Curzon Street', locality: 'Burnley',
+        postal_code: 'BB11 1FB', latitude: 53.791753, longitude: -2.245629
+      },
+      'chippenham' => {
+        street_address: 'Marshfield Road', locality: 'Chippenham', region: 'Wiltshire', postal_code: 'SN15 1JR',
+        latitude: 51.4618773, longitude: -2.1207797
+      },
+      'chorley' => {
+        street_address: 'Unit 6, Market Walk Extension', extended_address: 'Union Street', locality: 'Chorley',
+        postal_code: 'PR7 1FD', latitude: 53.6539814, longitude: -2.628561
+      },
+      'fareham-hampshire' => {
+        street_address: '3 Vannes Parade', extended_address: 'Market Quay', locality: 'Fareham',
+        region: 'Hampshire', postal_code: 'PO16 0BX', latitude: 50.8519189, longitude: -1.1784328
+      },
+      'farnham-surrey' => {
+        street_address: '8 Old Market Place', locality: 'Farnham', region: 'Surrey', postal_code: 'GU9 7SF',
+        latitude: 51.2154964, longitude: -0.7948056
+      },
+      'hull' => {
+        street_address: 'St Stephens Shopping Centre', extended_address: '110 Ferensway', locality: 'Hull',
+        region: 'North Humberside', postal_code: 'HU2 8LN', latitude: 53.7450491, longitude: -0.3474325
+      },
+      'morecambe' => {
+        street_address: 'Central Drive', locality: 'Morecambe', postal_code: 'LA4 4DW',
+        latitude: 54.0707779, longitude: -2.8743043
+      },
+      'port-talbot' => {
+        street_address: 'Hollywood Park', locality: 'Port Talbot', postal_code: 'SA12 6QW',
+        latitude: 51.5926478, longitude: -3.8123333
+      },
+      'quinton' => {
+        street_address: 'Hagley Road West', locality: 'Halesowen', region: 'West Midlands', postal_code: 'B62 9AS',
+        latitude: 52.4625982, longitude: -2.0141104
+      },
+      'rochdale' => {
+        street_address: 'Unit 22, Rochdale Riverside', extended_address: 'Riverside Walk', locality: 'Rochdale',
+        postal_code: 'OL16 1BE', latitude: 53.6178417, longitude: -2.1558455
+      },
+      'wakefield' => {
+        street_address: 'Unit 104-107, The Ridings Shopping Centre', extended_address: 'Almshouse Lane',
+        locality: 'Wakefield', postal_code: 'WF1 1DS', latitude: 53.6816652, longitude: -1.4960074
+      },
+      'widnes' => {
+        street_address: 'Unit 4, Venture Fields', extended_address: 'Earle Road', locality: 'Widnes',
+        region: 'Cheshire', postal_code: 'WA8 0GY', latitude: 53.3624648, longitude: -2.723302
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+
+    # Constructor
+    # @param [String] id the venue's path on the website, e.g. 'chorley'
+    # @return [ReelUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.downcase
+    end
+
+    # Return basic cinema information for all cinemas, from the cinema menu
+    # on the home page
+    # @return [Array<ReelUk::Cinema>]
+    # @example
+    #   ReelUk::Cinema.all
+    #   #=> [<ReelUk::Cinema>, <ReelUk::Cinema>, ...]
+    def self.all
+      venues_hash.keys.map { |id| new(id) }
+    end
+
+    # @return [Cinebase::A1web::Client] for venues still on the old website
+    def self.a1web_client
+      Cinebase::A1web::Client.new(base_url: A1WEB_WEBSITE)
+    end
+
+    # @!method address
+    #   Address of the cinema
+    #   @return [Hash] of different address parts
+    #   @see #adr
+
+    # Address of the cinema
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = ReelUk::Cinema.new('borehamwood')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   'Metropolis Centre',
+    #         extended_address: '84 Shenley Road',
+    #         locality:         'Borehamwood',
+    #         region:           'Hertfordshire',
+    #         postal_code:      'WD6 1EH',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      ADDRESS_PARTS.to_h { |part| [part, location[part]] }.merge(country_name: 'United Kingdom')
+    end
+
+    # @return [Boolean] whether the venue is still on the old A1Web website
+    def a1web?
+      URI(url).host == A1WEB_HOST
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Reel'
+    def brand
+      'Reel'.freeze
+    end
+
+    # @return [Float, nil]
+    def latitude
+      location[:latitude]
+    end
+
+    # @return [Float, nil]
+    def longitude
+      location[:longitude]
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   ReelUk::Cinema.new('fareham-hampshire').name
+    #   #=> 'Fareham'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's pages on the Reel website
+    # @return [String]
+    # @example
+    #   ReelUk::Cinema.new('chorley').url
+    #   #=> 'https://reel-cinemas.co.uk/chorley'
+    #   ReelUk::Cinema.new('hull').url
+    #   #=> 'https://reelcinemas.co.uk/hull'
+    def url
+      venue[:url].to_s
+    end
+
+    # @api private
+    def self.venues_hash
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      if @venues_hash.nil? || now - @fetched_at > CACHE_SECONDS
+        @fetched_at = now
+        html = ReelUk::Internal::Website.new.home
+        @venues_hash = html.scan(VENUE).to_h do |url, id, name|
+          [id, { url: url, name: CGI.unescapeHTML(name).sub(COUNTY, '').strip }]
+        end
+      end
+      @venues_hash
+    end
+    private_class_method :venues_hash
+
+    private
+
+    def location
+      LOCATIONS.fetch(id, {})
+    end
+
+    def venue
+      self.class.send(:venues_hash).fetch(id, {})
+    end
+  end
+end

data/lib/reel_uk/internal/http.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ReelUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to reel-cinemas.co.uk
+    module Http
+      RETRIES = 2
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      private
+
+      def get(url)
+        perform(Net::HTTP::Get.new(URI(url)))
+      end
+
+      def post(url, form)
+        post = Net::HTTP::Post.new(URI(url))
+        post.set_form_data(form)
+        perform(post)
+      end
+
+      def perform(request)
+        uri = request.uri
+        attempts = 0
+        begin
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
+            http.request(request)
+          end
+        rescue *TRANSIENT_ERRORS
+          attempts += 1
+          raise if attempts > RETRIES
+
+          sleep(attempts)
+          retry
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Reel HTTP error #{response.code} from #{uri.host}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/reel_uk/internal/listings.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ReelUk
+  # @api private
+  module Internal
+    # Every showtime a venue on Reel's WordPress website has on sale. The
+    # what's on page covers three weeks and the coming soon page only a
+    # film's first few showtimes, so the quick booking menu's request for
+    # each film on either page fills in the rest, one request per film.
+    # Labels such as 'Senior' are only on the what's on page.
+    class Listings
+      LOCATION = /attr_loc="(\d+)"/
+
+      # @param [String] venue_url e.g. 'https://reel-cinemas.co.uk/chorley'
+      # @param [ReelUk::Internal::Website] website
+      def initialize(venue_url, website: Website.new)
+        @venue_url = venue_url
+        @website = website
+      end
+
+      # @return [Array<Cinebase::A1web::Showing>] each showtime once
+      def showings
+        whats_on = Parser::WhatsOn.new(@website.whats_on(@venue_url), venue_url: @venue_url)
+        films = Parser::ComingSoon.new(@website.coming_soon(@venue_url)).films.merge(whats_on.films)
+        (whats_on.showings + scheduled(films)).uniq(&:booking_url)
+      end
+
+      private
+
+      # Without a location id, only the what's on page's showtimes are known
+      def scheduled(films)
+        location = @website.venue(@venue_url)[LOCATION, 1]
+        if location
+          films.flat_map do |film_id, title|
+            html = @website.showtimes(film_id, location)
+            Parser::Showtimes.new(html, film_id: film_id, title: title, venue_url: @venue_url).showings
+          end
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/reel_uk/internal/parser/coming_soon.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ReelUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads the films on a venue's coming soon page, which shows only
+      # their first few showtimes
+      class ComingSoon
+        FILM_BLOCK = '<div class="grid-column">'
+        FILM = %r{<h2><a href="[^"]*/film/(\d+)/[^"]*">(.*?)</a></h2>}m
+        BOOKABLE = %r{/booknow/\d+}
+
+        # @param [String] html a coming soon page
+        def initialize(html)
+          @html = html
+        end
+
+        # @return [Hash{String => String}] titles by Jacro film id, for films
+        #   with showtimes on sale
+        def films
+          @html.split(FILM_BLOCK).drop(1).filter_map do |markup|
+            film = markup.match(FILM)
+            [film[1], CGI.unescapeHTML(film[2]).strip] if film && markup.match?(BOOKABLE)
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/reel_uk/internal/parser/showtimes.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ReelUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads the quick booking menu's options for one film at one venue,
+      # such as '16 Dec 2026 @ 09:30', which name every showtime on sale
+      class Showtimes
+        OPTION = %r{<option value="[^"]*/booknow/(\d+)/?">(\d{1,2} [A-Z][a-z]{2} \d{4}) @ (\d{1,2}):(\d{2})</option>}
+        TIME_ZONE = 'Europe/London'
+
+        # @param [String] html the menu's options
+        # @param [String] film_id Jacro's film id
+        # @param [String] title the film's title
+        # @param [String] venue_url e.g. 'https://reel-cinemas.co.uk/chorley'
+        def initialize(html, film_id:, title:, venue_url:)
+          @html = html
+          @film_id = film_id
+          @title = title
+          @venue_url = venue_url
+        end
+
+        # Options link through a 'reel-chorley' path that redirects, so
+        # booking links take the what's on page's form
+        # @return [Array<Cinebase::A1web::Showing>] without tags
+        def showings
+          @html.scan(OPTION).map do |booking_id, day, hour, minute|
+            date = Date.strptime(day, '%d %b %Y')
+            Cinebase::A1web::Showing.new(
+              film_id: @film_id, title: @title, date: date, starting_at: starting_at(date, hour, minute),
+              booking_url: "#{@venue_url}/booknow/#{booking_id}/", tags: []
+            )
+          end
+        end
+
+        private
+
+        def starting_at(date, hour, minute)
+          local = Time.utc(date.year, date.month, date.day, hour.to_i, minute.to_i)
+          TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+        end
+      end
+    end
+  end
+end

data/lib/reel_uk/internal/parser/whats_on.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ReelUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads the films and showtimes on a venue's what's on page, which
+      # covers the next three weeks. Each film has a block for each date,
+      # with every showtime twice, for large and small screens.
+      class WhatsOn
+        BLOCK = /<div class="nowshowing_film_box_outer[^"]*?nowshowingslider_(\d{8})">/
+        FILM = %r{<h2><a href="[^"]*/film/(\d+)/[^"]*">(.*?)</a></h2>}m
+        SHOWTIME = %r{
+          <a\shref="[^"]*/booknow/(\d+)/?"[^>]*>\s*(\d{1,2}:\d{2})\s*</a>
+          (?:<div\sclass="show_time_label">([^<]*)</div>)?
+        }x
+        TIME_ZONE = 'Europe/London'
+
+        # @param [String] html a what's on page
+        # @param [String] venue_url e.g. 'https://reel-cinemas.co.uk/chorley'
+        def initialize(html, venue_url:)
+          @html = html
+          @venue_url = venue_url
+        end
+
+        # @return [Hash{String => String}] titles by Jacro film id
+        def films
+          blocks.to_h { |_date, film_id, title, _markup| [film_id, title] }
+        end
+
+        # @return [Array<Cinebase::A1web::Showing>] each showtime once, with
+        #   labels such as 'Senior' as tags
+        def showings
+          all = blocks.flat_map do |date, film_id, title, markup|
+            markup.scan(SHOWTIME).map do |booking_id, time, label|
+              Cinebase::A1web::Showing.new(
+                film_id: film_id, title: title, date: date, starting_at: starting_at(date, time),
+                booking_url: "#{@venue_url}/booknow/#{booking_id}/", tags: [label].compact
+              )
+            end
+          end
+          all.uniq(&:booking_url)
+        end
+
+        private
+
+        def blocks
+          @blocks ||= @html.split(BLOCK).drop(1).each_slice(2).filter_map do |key, markup|
+            film = markup.to_s.match(FILM)
+            [Date.strptime(key, '%Y%m%d'), film[1], CGI.unescapeHTML(film[2]).strip, markup] if film
+          end
+        end
+
+        def starting_at(date, time)
+          hour, minute = time.split(':').map(&:to_i)
+          local = Time.utc(date.year, date.month, date.day, hour, minute)
+          TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+        end
+      end
+    end
+  end
+end

data/lib/reel_uk/internal/title_sanitizer.rb

@@ -0,0 +1,37 @@
+module ReelUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [ReelUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s+-\s+Subtitled(?: Screening)?\z/i, # subtitled copy
+          /(?::|\s+-)?\s+3D\b/i,                # 3D copy, e.g. ': 3D' or ' - 3D'
+          /\s+I Infinity Vision\z/i,            # premium screen copy
+          /\ASee It First\s+-\s+/i              # preview
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\ANT Live: (.*)/                       => 'National Theatre Live: ',
+          /\ARBO 20\d{2}-(?:20)?\d{2}: (.*)/      => 'Royal Ballet and Opera: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end