princecharles_uk 1.0.0

data/README.md

@@ -0,0 +1,173 @@
+# PrincecharlesUk
+
+A simple gem to pull the cinema and its performances from the [Prince Charles Cinema website](https://princecharlescinema.com) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'princecharles_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install princecharles_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.
+
+No token or setup is needed. The website runs on WordPress with Jacro's
+cinema plugin, and tickets are sold through Jacro's TapOS. Its what's on page
+lists every film on sale with every advertised showtime, months ahead, so one
+request reads the whole programme.
+
+### Cinema
+
+The Prince Charles Cinema has one venue, keyed by its Jacro site code,
+`PRILON`. The gem holds its details: the address from the website's location
+page and coordinates from OpenStreetMap. Cinema methods make no requests.
+
+``` ruby
+PrincecharlesUk::Cinema.all
+#=> [<PrincecharlesUk::Cinema ...>]
+
+cinema = PrincecharlesUk::Cinema.new('PRILON')
+#=> <PrincecharlesUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '7 Leicester Place',
+  extended_address: nil,
+  locality:         'London',
+  region:           nil,
+  postal_code:      'WC2H 7BY',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Prince Charles Cinema'
+
+cinema.id
+#=> 'PRILON'
+
+cinema.latitude
+#=> 51.5114907
+
+cinema.url
+#=> 'https://princecharlescinema.com'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. Any range is one
+request.
+
+``` ruby
+PrincecharlesUk::Performance.at('PRILON', from: Date.today, to: Date.today + 365)
+#=> [<PrincecharlesUk::Performance ...>, <PrincecharlesUk::Performance ...>, ...]
+
+performance = PrincecharlesUk::Performance.at('PRILON', from: Date.today, to: Date.today + 365).last
+#=> <PrincecharlesUk::Performance ...>
+
+performance.film_name
+#=> 'The Rocky Horror Picture Show' # from '... : Sing Along'
+
+performance.film_year
+#=> 1975
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['sing_along']
+
+performance.subtitled?
+#=> false
+
+performance.festival
+#=> nil
+
+performance.starting_at
+#=> 2027-06-25 19:30:00 UTC
+
+performance.booking_url
+#=> 'https://princecharlescinema.com/prince-charles-cinema/booknow/31628659/'
+
+performance.cinema_name
+#=> 'Prince Charles Cinema'
+
+performance.cinema_id
+#=> 'PRILON'
+```
+
+Booking links are the website's own booking pages, which hold the TapOS seat
+selection. Sold out screenings are listed with no booking link.
+
+Date headings such as 'Friday 25th June' give no year. The gem takes the year
+in which that date falls on that weekday.
+
+Variants come from each showtime's tags and from titles: `35mm`, `70mm`,
+`subtitled` (SUB and HOH, hard of hearing, screenings), `q&a`, `sing_along`
+and `arts` (films with a live score). 4K, £1 member tickets, introductions,
+previews and final shows are not variants.
+
+Film years come from a year in the title, such as 'Godzilla (1954)' or
+'The Mummy [1999]', or else from the listing. Placeholder years before 1888,
+which the listing gives to some events such as 'Mystery Movie', are dropped.
+
+Titles are cleaned up:
+
+- Original titles, cuts and notes in square brackets go: 'Rashomon [Rashômon]'
+  becomes 'Rashomon', 'The New World [Extended Cut]' becomes 'The New World'.
+- A final parenthesis goes: 'Daisies (Sedmikrásky)' becomes 'Daisies', and
+  'Ten Years of Monkey Tennis (with Peter Serafinowicz)' loses its guest.
+- Anniversaries, restorations and touring prints go: 'Amelie - 25th
+  Anniversary', 'Wake in Fright - 4K Restoration', 'Short Cuts : 35mm Roadshow
+  Tour'.
+- Sing-along names go: 'The Rocky Horror Picture Show: Sing Along' and
+  'Sing-A-Long-A Rocky Horror Picture Show'.
+- Q&A add-ons go: 'Dead Souls + Alex Cox Q&A' becomes 'Dead Souls'.
+- Presenters go: 'Funeral Parade presents "The Long Day Closes"' becomes 'The
+  Long Day Closes'.
+- Spaced colons close up: '2001 : A Space Odyssey' becomes '2001: A Space
+  Odyssey'.
+
+Director's and final cuts named after a colon keep their names. Double bills,
+marathons and all-nighters keep the cinema's names, such as 'Studio Ghibli
+All-Nighter' and 'Evangelion: Death (True)² + The End of Evangelion: Double
+Feature'.
+
+## Tests
+
+```sh
+bundle exec rake                # unit tests against fixtures
+LIVE=1 bundle exec rake live    # live princecharlescinema.com
+```
+
+The fixture in `test/fixtures` is the what's on page, trimmed to a few films
+with shortened descriptions and no posters. `test/support/api_shapes.rb`
+describes the markup the gem reads. The unit suite checks the fixture against
+it and the live suite checks the real page, held only in memory. When the page
+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/princecharles_uk/cinema.rb

@@ -0,0 +1,100 @@
+module PrincecharlesUk
+  # The object representing the Prince Charles Cinema, London
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's Jacro site code, 'PRILON'
+
+    # The cinema has one venue. Its Jacro site code names it in ticketing
+    # links. The address is from the website's location page, coordinates
+    # from OpenStreetMap.
+    VENUES = {
+      'PRILON' => {
+        name: 'Prince Charles Cinema', street_address: '7 Leicester Place', locality: 'London',
+        postal_code: 'WC2H 7BY', latitude: 51.5114907, longitude: -0.1302137
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    URL = 'https://princecharlescinema.com'.freeze
+
+    # Constructor
+    # @param [String] id the cinema's Jacro site code, 'PRILON' or 'prilon'
+    # @return [PrincecharlesUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.upcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<PrincecharlesUk::Cinema>] the one cinema
+    # @example
+    #   PrincecharlesUk::Cinema.all
+    #   #=> [<PrincecharlesUk::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 = PrincecharlesUk::Cinema.new('PRILON')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '7 Leicester Place',
+    #         extended_address: nil,
+    #         locality:         'London',
+    #         region:           nil,
+    #         postal_code:      'WC2H 7BY',
+    #         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 'Independent'
+    def brand
+      'Independent'.freeze
+    end
+
+    # @return [Float, nil]
+    def latitude
+      venue[:latitude]
+    end
+
+    # @return [Float, nil]
+    def longitude
+      venue[:longitude]
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   PrincecharlesUk::Cinema.new('PRILON').name
+    #   #=> 'Prince Charles Cinema'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's website
+    # @return [String]
+    # @example
+    #   PrincecharlesUk::Cinema.new('PRILON').url
+    #   #=> 'https://princecharlescinema.com'
+    def url
+      venue.empty? ? '' : URL
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/princecharles_uk/internal/http.rb

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

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module PrincecharlesUk
+  # @api private
+  module Internal
+    module Parser
+      # One showtime from the what's on page
+      Showing = Data.define(:title, :year, :date, :starting_at, :tags, :booking_url)
+
+      # Parses the what's on page: one block per film, each with its
+      # showtimes under date headings such as 'Friday 25th June'
+      class WhatsOn
+        FILM = /<div class="jacro-event movie-tabs row/
+        TITLE = /class="liveeventtitle"[^>]*>([^<]+)</
+        # The first detail is the film's year when the listing gives one
+        DETAILS = %r{<div class="running-time">\s*<span>([^<]*)</span>}
+        YEAR = /\A\d{4}\z/
+        SHOWTIMES = %r{<ul class="performance-list-items">(.*?)</ul>}m
+        HEADING_OR_SHOWTIME = %r{<div class="heading">([^<]+)</div>|<li class="([^"]*)">(.*?)</li>}m
+        HEADING = /\A(\w+) (\d{1,2})(?:st|nd|rd|th) (\w+)\z/
+        TIME = %r{<span class="time">\s*(\d{1,2}):(\d{2})\s*([ap]m)\s*</span>}i
+        # Sold out showtimes have no link
+        BOOKING = %r{href="(https://princecharlescinema\.com/[\w-]+/booknow/\d+)/?"}
+        TIME_ZONE = 'Europe/London'
+        HOURS_TO_NOON = 12
+
+        # @param [String] html the what's on page
+        # @param [Date] today in London, to place headings, which give no
+        #   year, in the right year
+        def initialize(html, today:)
+          @html = html
+          @today = today
+        end
+
+        # @return [Array<PrincecharlesUk::Internal::Parser::Showing>]
+        def showings
+          @html.split(FILM).drop(1).flat_map { |film| film_showings(film) }
+        end
+
+        private
+
+        def film_showings(film)
+          title = CGI.unescapeHTML(film[TITLE, 1].to_s).strip
+          year = film[DETAILS, 1].to_s.strip
+          year = year.match?(YEAR) ? year.to_i : nil
+          date = nil
+          film[SHOWTIMES, 1].to_s.scan(HEADING_OR_SHOWTIME).filter_map do |heading, tags, showtime|
+            if heading
+              date = date(heading.strip)
+              nil
+            elsif date && showtime.match?(TIME)
+              showing(title, year, date, tags, showtime)
+            end
+          end
+        end
+
+        def showing(title, year, date, tags, showtime)
+          Showing.new(
+            title: title,
+            year: year,
+            date: date,
+            starting_at: starting_at(date, showtime),
+            tags: tags.split,
+            booking_url: booking_url(showtime)
+          )
+        end
+
+        def booking_url(showtime)
+          url = showtime[BOOKING, 1]
+          url ? "#{url}/" : nil
+        end
+
+        # The year whose date falls on the heading's weekday, or failing
+        # that the first on or after today
+        def date(heading)
+          weekday, day, name = heading.match(HEADING)&.captures
+          month = name && Date::MONTHNAMES.index(name)
+          if month
+            dates = (@today.year - 1..@today.year + 1).filter_map do |year|
+              Date.new(year, month, day.to_i) if Date.valid_date?(year, month, day.to_i)
+            end
+            dates.find { |date| Date::DAYNAMES[date.wday] == weekday } || dates.find { |date| date >= @today }
+          end
+        end
+
+        def starting_at(date, showtime)
+          hour, minute, meridiem = showtime.match(TIME).captures
+          hour = hour.to_i % HOURS_TO_NOON
+          hour += HOURS_TO_NOON if meridiem.casecmp?('pm')
+          local = Time.utc(date.year, date.month, date.day, hour, minute.to_i)
+          TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+        end
+      end
+    end
+  end
+end

data/lib/princecharles_uk/internal/title_sanitizer.rb

@@ -0,0 +1,41 @@
+module PrincecharlesUk
+  # 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 [PrincecharlesUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\A.+?\s+presents\s+/i,                        # presenter, e.g. 'Funeral Parade presents'
+          /\ASing-A-Long-A\s+/i,                         # sing-along prefix
+          /:\s*Sing[- ]?A[- ]?Long\z/i,                  # sing-along suffix
+          /\s+-\s+\d+(?:st|nd|rd|th) Anniversary\z/i,    # anniversary re-release
+          /\s+-\s+4K Restoration\z/i,                    # restoration
+          /\s*:\s*35mm Roadshow Tour\z/i,                # touring print
+          /\s*\[[^\]]*\]\z/,                             # original title, cut or year, e.g. '[Rashômon]'
+          /\s*\([^)]*\)\z/                               # original title, guest or year, e.g. '(Sedmikrásky)'
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A"(.*)"\z/  => '', # quotes left by a presenter
+          /\s+:\s+(.*)/ => ': ' # spaced colon, e.g. '2001 : A Space Odyssey'
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/princecharles_uk/internal/website.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PrincecharlesUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads the Prince Charles Cinema's WordPress website, built on Jacro's
+    # cinema plugin. No token is needed.
+    class Website
+      include Http
+
+      WHATS_ON = 'https://princecharlescinema.com/whats-on/'
+
+      # @return [String] every film on sale with every advertised showtime,
+      #   however far ahead, including sold out ones
+      def whats_on
+        get(WHATS_ON)
+      end
+    end
+  end
+end

data/lib/princecharles_uk/performance.rb

@@ -0,0 +1,129 @@
+module PrincecharlesUk
+  # A single screening of a film on the Prince Charles Cinema website
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String, nil] the booking URL, nil when sold out
+    # @!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 of the film
+    #   @option options [Time] :starting_at listed start time of the performance
+
+    # Showtime tags and the variants they mean. HOH (hard of hearing)
+    # screenings are subtitled. Others, such as '4k', '1-mem' (£1 member
+    # tickets), 'intro', 'preview' and 'final-show', are not variants.
+    TAGS = {
+      '35mm' => '35mm',
+      '70mm' => '70mm',
+      'hoh' => 'subtitled',
+      'live-score' => 'arts',
+      'q-a' => 'q&a',
+      'sing-along' => 'sing_along',
+      'sub' => 'subtitled'
+    }.freeze
+
+    # Variants some titles name without a tag
+    TITLE_VARIANTS = {
+      /\b35mm\b/i => '35mm',
+      /\b70mm\b/i => '70mm',
+      /\bQ&A\b/i => 'q&a',
+      /\bSing[- ]?A[- ]?Long\b/i => 'sing_along'
+    }.freeze
+
+    THREE_D = /\b3D\b/i
+    # Bracketed years in titles, such as 'The Mummy [1999]'
+    TITLE_YEAR = /[(\[](1[89]\d{2}|20\d{2})[)\]]\s*\z/
+    # Listings give placeholder years to some events, e.g. 1878
+    FIRST_FILM_YEAR = 1888
+    TIME_ZONE = 'Europe/London'.freeze
+
+    # Performances within an inclusive range of showing dates, from one
+    # request: the what's on page holds every advertised date.
+    # @param [String] cinema_id the cinema's Jacro site code, 'PRILON'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<PrincecharlesUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: today,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      if cinema.name.empty?
+        []
+      else
+        performances = showings.select { |showing| (from..to).cover?(showing.date) }.map do |showing|
+          new(attributes(showing).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 (35mm, 70mm, q&a, sing_along, subtitled ...)
+    #   @return <Array[String]>
+
+    def self.today
+      TZInfo::Timezone.get(TIME_ZONE).now.to_date
+    end
+    private_class_method :today
+
+    def self.showings
+      html = PrincecharlesUk::Internal::Website.new.whats_on
+      PrincecharlesUk::Internal::Parser::WhatsOn.new(html, today: today).showings
+    end
+    private_class_method :showings
+
+    def self.attributes(showing)
+      title = showing.title
+      {
+        booking_url: showing.booking_url,
+        dimension: [title, *showing.tags].any? { |text| text.match?(THREE_D) } ? '3d' : '2d',
+        festival: Cinebase::Festival.from_title(title, year: showing.date.year),
+        film_name: PrincecharlesUk::Internal::TitleSanitizer.new(title).sanitized,
+        film_year: film_year(showing),
+        starting_at: showing.starting_at,
+        variant: variant(showing)
+      }
+    end
+    private_class_method :attributes
+
+    # A year in the title first, as it picks out one version of a film
+    def self.film_year(showing)
+      year = showing.title[TITLE_YEAR, 1]&.to_i || showing.year
+      year if year && year >= FIRST_FILM_YEAR
+    end
+    private_class_method :film_year
+
+    def self.variant(showing)
+      from_tags = showing.tags.filter_map { |tag| TAGS[tag] }
+      from_title = TITLE_VARIANTS.filter_map { |pattern, variant| variant if showing.title.match?(pattern) }
+      (from_tags + from_title).uniq
+    end
+    private_class_method :variant
+  end
+end

data/lib/princecharles_uk/version.rb

@@ -0,0 +1,6 @@
+# Ruby interface for https://princecharlescinema.com
+# @version 1.0.0
+module PrincecharlesUk
+  # Gem version
+  VERSION = '1.0.0'.freeze
+end

data/lib/princecharles_uk.rb

@@ -0,0 +1,17 @@
+require 'cgi/escape'
+
+require 'cinebase'
+
+require_relative './princecharles_uk/version'
+
+require_relative './princecharles_uk/internal/http'
+require_relative './princecharles_uk/internal/website'
+require_relative './princecharles_uk/internal/title_sanitizer'
+require_relative './princecharles_uk/internal/parser/whats_on'
+
+require_relative './princecharles_uk/cinema'
+require_relative './princecharles_uk/performance'
+
+# princecharles_uk gem
+module PrincecharlesUk
+end