wtw_uk 1.0.0

data/README.md

@@ -0,0 +1,160 @@
+# WtwUk
+
+A simple gem to pull cinemas and performances from the [WTW Cinemas website](https://wtwcinemas.co.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'wtw_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wtw_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 years,
+subtitle, preview, autism friendly, Q&A and film club markers, and naming
+National Theatre Live, Royal Ballet and Opera and Exhibition on Screen
+screenings in full.
+
+No token or setup is needed. WTW's WordPress website runs Jacro's cinema
+plugin, with a subsite for each venue. Tickets are sold through TapOS,
+behind each venue's own booking pages.
+
+### Cinema
+
+The gem holds WTW's four Cornish venues, keyed by the TapOS site code in
+their booking pages: subsites and Jacro cinema ids from the home page,
+addresses from each venue's page footer and coordinates from OpenStreetMap.
+Cinema methods make no requests.
+
+``` ruby
+WtwUk::Cinema.all
+#=> [<WtwUk::Cinema ...>, <WtwUk::Cinema ...>, ...]
+
+cinema = WtwUk::Cinema.new('PLATRU')
+#=> <WtwUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '69 Lemon Street',
+  extended_address: nil,
+  locality:         'Truro',
+  region:           'Cornwall',
+  postal_code:      'TR1 2PN',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'WTW Cinemas'
+
+cinema.full_name
+#=> 'WTW Cinemas Truro'
+
+cinema.id
+#=> 'PLATRU'
+
+cinema.latitude
+#=> 50.261851
+
+cinema.url
+#=> 'https://wtwcinemas.co.uk/truro/'
+```
+
+| id | name |
+| --- | --- |
+| `WTWNEW` | Newquay (Lighthouse Cinema) |
+| `FILAUS` | St Austell (White River Cinema) |
+| `PLATRU` | Truro (The Plaza) |
+| `REGWAD` | Wadebridge (The Regal) |
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. The what's on page's
+'All Shows' request lists every showtime the venue has on sale, so any range
+is one request.
+
+``` ruby
+WtwUk::Performance.at('PLATRU', from: Date.today, to: Date.today + 2)
+#=> [<WtwUk::Performance ...>, <WtwUk::Performance ...>, ...]
+
+performance = WtwUk::Performance.at('PLATRU').first
+#=> <WtwUk::Performance ...>
+
+performance.film_name
+#=> 'Heart of the Beast' # from 'Heart of the Beast (with subtitles)'
+
+performance.film_year
+#=> nil # from the title, e.g. 1971 for 'The Devils (1971)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['senior', 'subtitled']
+
+performance.subtitled?
+#=> true
+
+performance.festival
+#=> nil
+
+performance.starting_at
+#=> 2026-11-12 11:15:00 UTC
+
+performance.booking_url
+#=> 'https://wtwcinemas.co.uk/truro/booknow/122882/'
+
+performance.cinema_name
+#=> 'Truro'
+
+performance.cinema_id
+#=> 'PLATRU'
+```
+
+Booking links go to the venue's booking page, which holds the TapOS seat
+selection. Showtimes already passed today have no booking link.
+
+Variants come from each showtime's classes and the title: `arts` (event
+cinema: theatre, opera, ballet, musicals, concerts and exhibitions), `q&a`,
+`relaxed` (autism friendly), `senior` (Silver Screen) and `subtitled`. Many
+screenings offer audio description headsets or caption glasses, so neither
+is a variant. Laser projection, strobe warnings and ticket offers are not
+variants either.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live wtwcinemas.co.uk
+```
+
+The fixture in `test/fixtures` is Truro's programme, trimmed to a few films
+with shortened descriptions. `test/support/api_shapes.rb` describes the
+markup the gem reads. The unit suite checks the fixture against it and the
+live suite checks every venue's real programme, held only in memory, along
+with the venue list and each venue's TapOS code. When the markup changes,
+update the shape first, then the fixture.
+
+## 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/wtw_uk/cinema.rb

@@ -0,0 +1,130 @@
+module WtwUk
+  # The object representing a cinema on the WTW Cinemas website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the venue's TapOS site code, e.g. 'PLATRU'
+
+    # Each venue is a subsite, and its programme request names it by Jacro
+    # cinema id. Neither page names the TapOS site code its booking pages
+    # use, and no page gives coordinates, so the gem holds the venues: names,
+    # subsites and cinema ids from the quick booking menu, codes from booking
+    # pages, addresses from venue page footers and coordinates from
+    # OpenStreetMap.
+    VENUES = {
+      'WTWNEW' => {
+        name: 'Newquay', path: 'newquay', location: '5', street_address: 'King Street', locality: 'Newquay',
+        region: 'Cornwall', postal_code: 'TR7 1AA', latitude: 50.4136279, longitude: -5.0873384
+      },
+      'FILAUS' => {
+        name: 'St Austell', path: 'st-austell', location: '1', street_address: 'White River Place',
+        locality: 'St Austell', region: 'Cornwall', postal_code: 'PL25 5AZ', latitude: 50.3376527,
+        longitude: -4.7948318
+      },
+      'PLATRU' => {
+        name: 'Truro', path: 'truro', location: '2', street_address: '69 Lemon Street', locality: 'Truro',
+        region: 'Cornwall', postal_code: 'TR1 2PN', latitude: 50.261851, longitude: -5.0523149
+      },
+      'REGWAD' => {
+        name: 'Wadebridge', path: 'wadebridge', location: '3', street_address: 'The Platt', locality: 'Wadebridge',
+        region: 'Cornwall', postal_code: 'PL27 7AD', latitude: 50.5152411, longitude: -4.8361756
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    WEBSITE = 'https://wtwcinemas.co.uk'.freeze
+
+    # Constructor
+    # @param [String] id the venue's TapOS site code, e.g. 'PLATRU' or 'platru'
+    # @return [WtwUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.upcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<WtwUk::Cinema>]
+    # @example
+    #   WtwUk::Cinema.all
+    #   #=> [<WtwUk::Cinema>, <WtwUk::Cinema>, ...]
+    def self.all
+      VENUES.keys.map { |id| new(id) }
+    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 = WtwUk::Cinema.new('PLATRU')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '69 Lemon Street',
+    #         extended_address: nil,
+    #         locality:         'Truro',
+    #         region:           'Cornwall',
+    #         postal_code:      'TR1 2PN',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      ADDRESS_PARTS.to_h { |part| [part, venue[part]] }.merge(country_name: 'United Kingdom')
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'WTW Cinemas'
+    def brand
+      'WTW Cinemas'.freeze
+    end
+
+    # @return [Float, nil]
+    def latitude
+      venue[:latitude]
+    end
+
+    # Jacro's cinema id for the venue
+    # @return [String, nil]
+    # @api private
+    def location
+      venue[:location]
+    end
+
+    # @return [Float, nil]
+    def longitude
+      venue[:longitude]
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   WtwUk::Cinema.new('FILAUS').name
+    #   #=> 'St Austell'
+    def name
+      venue[:name].to_s
+    end
+
+    # The venue's subsite on the WTW Cinemas website
+    # @return [String, nil]
+    # @api private
+    def path
+      venue[:path]
+    end
+
+    # The url of the cinema's pages on the WTW Cinemas website
+    # @return [String]
+    # @example
+    #   WtwUk::Cinema.new('PLATRU').url
+    #   #=> 'https://wtwcinemas.co.uk/truro/'
+    def url
+      path ? "#{WEBSITE}/#{path}/" : ''
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/wtw_uk/internal/http.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module WtwUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to wtwcinemas.co.uk
+    module Http
+      RETRIES = 2
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      private
+
+      def post(url, form)
+        uri = URI(url)
+        request = Net::HTTP::Post.new(uri)
+        request.set_form_data(form)
+        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 "WTW Cinemas HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/wtw_uk/internal/parser/programme.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module WtwUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads a venue's whole programme: a block for each film, with its
+      # showtimes in order under date headings such as
+      # '<strong>Wednesday </strong>16 December 2026'
+      class Programme
+        FILM = '<div class="poster-case '
+        TITLE = %r{<span class="poster-title">([^<]*)</span>}
+        DATE = %r{dateshow"><strong>[^<]*</strong>\s*(\d{1,2} [A-Z][a-z]+ \d{4})\s*</span>}
+        SHOWTIME = %r{<div class="singlefilmperfs ([^"]*)">(.*?)<input type="hidden" class="perfcat_message"}m
+
+        # @param [String] html a venue's programme
+        def initialize(html)
+          @html = html
+        end
+
+        # @return [Array<WtwUk::Internal::Parser::Showtime>] every showtime,
+        #   including those already passed today
+        def showtimes
+          @html.split(FILM).drop(1).flat_map do |markup|
+            title = markup[TITLE, 1]
+            title ? film_showtimes(CGI.unescapeHTML(title), markup) : []
+          end
+        end
+
+        private
+
+        def film_showtimes(title, markup)
+          date = nil
+          markup.scan(/#{DATE}|#{SHOWTIME}/o).filter_map do |day, classes, perf|
+            if day
+              date = Date.strptime(day, '%d %B %Y')
+              nil
+            elsif date
+              Showtime.new(perf, title: title, date: date, classes: classes)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wtw_uk/internal/parser/showtime.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module WtwUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses one showtime from a venue's programme into performance
+      # attributes
+      class Showtime
+        # Showtime classes and the variants they mean. Others, such as
+        # 'audio-des' and 'ccap' (headsets and caption glasses on offer),
+        # 'sub-titles' (also on every opera), 'laser', 'strobe-lgt' and
+        # 'percatediscountedscreening' (cheap tickets), are not variants.
+        CLASSES = {
+          'aslive' => 'arts',
+          'aut' => 'relaxed',
+          'percateeventcinemascreening' => 'arts',
+          'sil' => 'senior',
+          'subtitled' => 'subtitled'
+        }.freeze
+
+        # Event cinema classes are missing from some showtimes
+        TITLE_VARIANTS = {
+          /\b(?:Exhibition On Screen|National Theatre Live|NT Live|Royal Ballet (?:&|and) Opera|Live On Stage)\b/i =>
+            'arts',
+          /\s-\sThe Play\z/i => 'arts',
+          /\bQ&A\b/i => 'q&a',
+          /\bsubtitle[ds]\b/i => 'subtitled'
+        }.freeze
+
+        THREE_D_CLASS = 'icon-3d'
+        THREE_D = /\b3D\b/i
+        START = %r{Start time:<span>(\d{1,2}):(\d{2})</span>}
+        BOOKING = %r{href="(https://wtwcinemas\.co\.uk/[a-z-]+/booknow/\d+)/?"}
+        # Venues differ over hyphens and en dashes in the same title
+        EN_DASH = ' – '
+        LANGUAGE = /\((#{Cinebase::TitleSanitizer::LANGUAGES.join('|')})\)/i
+        TIME_ZONE = 'Europe/London'
+
+        # @return [Date] the local date of the showtime
+        attr_reader :date
+
+        # @param [String] markup the showtime's markup
+        # @param [String] title the film's title as listed
+        # @param [Date] date from the showtime's date heading
+        # @param [String] classes the showtime's class attribute
+        def initialize(markup, title:, date:, classes:)
+          @markup = markup
+          @title = title.gsub(EN_DASH, ' - ').strip
+          @date = date
+          @classes = classes.downcase.split
+        end
+
+        # @return [Hash] options for WtwUk::Performance.new
+        def to_hash
+          {
+            booking_url: booking_url,
+            dimension: @classes.include?(THREE_D_CLASS) || @title.match?(THREE_D) ? '3d' : '2d',
+            festival: Cinebase::Festival.from_title(@title, year: @date.year),
+            film_name: TitleSanitizer.new(@title).sanitized,
+            film_year: Cinebase::TitleSanitizer.film_year(@title),
+            language: @title[LANGUAGE, 1],
+            starting_at: starting_at,
+            variant: variant
+          }
+        end
+
+        private
+
+        # Showtimes already passed have no link
+        def booking_url
+          url = @markup[BOOKING, 1]
+          url && "#{url}/"
+        end
+
+        def starting_at
+          hour, minute = @markup.match(START).captures.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
+
+        def variant
+          from_title = TITLE_VARIANTS.filter_map { |pattern, variant| variant if @title.match?(pattern) }
+          (@classes.filter_map { |name| CLASSES[name] } + from_title).uniq
+        end
+      end
+    end
+  end
+end

data/lib/wtw_uk/internal/title_sanitizer.rb

@@ -0,0 +1,38 @@
+module WtwUk
+  # 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 [WtwUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\ASee It First\s+-\s+/i,                                     # preview
+          /\s*-\s*Pat's [^-]+\z/,                                       # Truro's film club strands
+          /\s+(?:-\s+)?(?:Subtitled and )?Autism Friendly Screening\z/i, # relaxed screening
+          /\s+(?:inc\.?|plus)\s+(?:[\w-]+\s+)*Q&A\z/i                   # Q&A add-on
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A(.*) - Royal Ballet (?:&|and) Opera \d{2}-\d{2} Season\z/i => 'Royal Ballet and Opera: ',
+          /\A(.*) - Exhibition On Screen\z/i                             => 'Exhibition on Screen: ',
+          /\ANT Live: (.*)/                                              => 'National Theatre Live: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/wtw_uk/internal/website.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WtwUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads WTW's WordPress website, built on Jacro's cinema plugin, with a
+    # subsite for each venue. No token is needed.
+    class Website
+      include Http
+
+      HOME = 'https://wtwcinemas.co.uk'
+      # The what's on page's request when a date is chosen
+      ACTION = 'jacro_filter_result'
+      # The 'All Shows' date, which lists every showtime on sale
+      ALL_DATES = 'moredates'
+      FILM_TYPE = 'Now Showing'
+
+      # @param [String] path the venue's subsite, e.g. 'truro'
+      # @param [String] location Jacro's cinema id for the venue, e.g. '2'
+      # @return [String] every film the venue has on sale, each with every
+      #   showtime under date headings, however far ahead
+      def programme(path, location)
+        form = { 'action' => ACTION, 'film_date' => ALL_DATES, 'film_type' => FILM_TYPE, 'cinema_id' => location }
+        JSON.parse(post("#{HOME}/#{path}/wp-admin/admin-ajax.php", form)).fetch('html', '').to_s
+      end
+    end
+  end
+end

data/lib/wtw_uk/performance.rb

@@ -0,0 +1,67 @@
+module WtwUk
+  # A single screening of a film on the WTW Cinemas website
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String, nil] the booking URL on the cinema website
+    # @!attribute [r] cinema_name
+    #   @return [String] the cinema name
+    # @!attribute [r] cinema_id
+    #   @return [String] the cinema id
+    # @!attribute [r] dimension
+    #   @return [String] 2d or 3d
+    # @!attribute [r] film_name
+    #   @return [String] the film name
+
+    # @!method initialize(options)
+    #   @param [Hash] options options hash
+    #   @option options [String] :booking_url (nil) buying url for the screening
+    #   @option options [String] :cinema_name name of the cinema
+    #   @option options [String] :cinema_id website id of the cinema
+    #   @option options [String] :dimension ('2d') dimension of the screening
+    #   @option options [Cinebase::Festival] :festival (nil) festival edition
+    #   @option options [String] :film_name name of the film
+    #   @option options [Integer] :film_year (nil) year from the film's title
+    #   @option options [String] :language (nil) audio language, e.g. 'Hindi'
+    #   @option options [Time] :starting_at listed start time of the performance
+
+    TIME_ZONE = 'Europe/London'.freeze
+
+    # Performances within an inclusive range of showing dates, from one
+    # request: the venue's programme holds every advertised date.
+    # @param [String] cinema_id the venue's TapOS site code, e.g. 'PLATRU'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<WtwUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: TZInfo::Timezone.get(TIME_ZONE).now.to_date,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      if cinema.name.empty?
+        []
+      else
+        html = WtwUk::Internal::Website.new.programme(cinema.path, cinema.location)
+        showtimes = WtwUk::Internal::Parser::Programme.new(html).showtimes
+        performances = showtimes.select { |showtime| (from..to).cover?(showtime.date) }.map do |showtime|
+          new(showtime.to_hash.merge(cinema_id: cinema.id, cinema_name: cinema.name))
+        end
+        performances.sort_by(&:starting_at)
+      end
+    end
+
+    # @!method showing_on
+    #   The date of the screening
+    #   @return [Date]
+
+    # @!method starting_at
+    #   UTC time of the screening
+    #   @return [Time]
+
+    # @!method variant
+    #   The kinds of screening (arts, q&a, relaxed, senior, subtitled)
+    #   @return <Array[String]>
+  end
+end

data/lib/wtw_uk/version.rb

@@ -0,0 +1,6 @@
+# Ruby interface for https://wtwcinemas.co.uk
+# @version 1.0.0
+module WtwUk
+  # Gem version
+  VERSION = '1.0.0'.freeze
+end

data/lib/wtw_uk.rb

@@ -0,0 +1,19 @@
+require 'cgi/escape'
+require 'json'
+
+require 'cinebase'
+
+require_relative './wtw_uk/version'
+
+require_relative './wtw_uk/internal/http'
+require_relative './wtw_uk/internal/website'
+require_relative './wtw_uk/internal/title_sanitizer'
+require_relative './wtw_uk/internal/parser/showtime'
+require_relative './wtw_uk/internal/parser/programme'
+
+require_relative './wtw_uk/cinema'
+require_relative './wtw_uk/performance'
+
+# wtw_uk gem
+module WtwUk
+end