rio_uk 1.0.0

data/README.md

@@ -0,0 +1,169 @@
+# RioUk
+
+A simple gem to pull the cinema and its performances from the [Rio Cinema website](https://riocinema.org.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rio_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rio_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 Savoy Systems' ticketing.
+Every page of it carries the whole programme as one line of JSON, every event
+on sale with every advertised performance, so one request to the what's on
+page reads it all. There is no lighter feed and no compression; the page is
+about 850 KB.
+
+### Cinema
+
+The Rio is one venue, keyed `rio`, the name of its Savoy site. The gem holds
+its details: the address from the website's footer and coordinates from
+OpenStreetMap. Cinema methods make no requests.
+
+``` ruby
+RioUk::Cinema.all
+#=> [<RioUk::Cinema ...>]
+
+cinema = RioUk::Cinema.new('rio')
+#=> <RioUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '107 Kingsland High Street',
+  extended_address: nil,
+  locality:         'London',
+  region:           nil,
+  postal_code:      'E8 2PB',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Rio Cinema'
+
+cinema.id
+#=> 'rio'
+
+cinema.latitude
+#=> 51.5496199
+
+cinema.url
+#=> 'https://riocinema.org.uk'
+```
+
+### 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
+RioUk::Performance.at('rio', from: Date.today, to: Date.today + 365)
+#=> [<RioUk::Performance ...>, <RioUk::Performance ...>, ...]
+
+performance = RioUk::Performance.at('rio').first
+#=> <RioUk::Performance ...>
+
+performance.film_name
+#=> 'Dao' # from "Black History Month:  Alain Gomis' DAO"
+
+performance.film_year
+#=> nil
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['q&a']
+
+performance.starting_at
+#=> 2026-11-01 13:30:00 UTC
+
+performance.booking_url
+#=> 'https://riocinema.org.uk/Rio.dll/Booking?Booking=TSelectItems.waSelectItemsPrompt.TcsWebMenuItem_0.TcsWebTab_0.TcsPerformance_2884892.TcsSection_1299'
+
+performance.cinema_name
+#=> 'Rio Cinema'
+
+performance.cinema_id
+#=> 'rio'
+```
+
+Booking links open Savoy's ticket selection for the performance. A few special
+events sell through a partner, such as the Japanese Film Club, and link there.
+Sold out performances are listed with no booking link.
+
+Variants come from the Rio's performance flags and from titles: `baby` (Carers
++ Baby), `senior` (Classic Matinee, for the over 60s), `kids` (Family Flicks
+and Hackney Children's Film Fest), `subtitled` (Hard of Hearing), `q&a`,
+`relaxed`, `35mm`, `70mm` and `sing_along`. Pink Palace, Rio Forever, special
+event and no ads flags are not variants.
+
+Film years come from the listing's year, or a year in the title. Double bills
+('1974 / 1976') and programmes ('Various') have none.
+
+Only films are kept: events whose type names a film or feature and that have a
+director or a year. Gigs and parties listed as films, such as 'Velcro Flats
+presents POZI', have neither.
+
+Titles are cleaned up. The Rio writes the film in capitals and everything else
+in mixed case:
+
+- Strands, clubs, festivals and presenters before a colon go: 'Pink Palace: A
+  SINGLE MAN', 'JAPANESE FILM CLUB: YOUR NAME', 'Loose Willis presents: THE
+  DEVILS'.
+- A mixed case prefix before a film in capitals goes: 'Category H: MALATESTA’S
+  CARNIVAL OF BLOOD + FINAL DESTINATION 3'.
+- Mixed case extras after a film in capitals go: 'PAN'S LABYRINTH on 35mm',
+  'WE, THE HATED (Just Stop Oil doc) + Q&A', '... with Smut Press'.
+- A director's name in front goes: "Alain Gomis' DAO" becomes 'Dao'.
+- Capitals become title case: 'SHAUN THE SHEEP: THE BEAST OF MOSSY BOTTOM'
+  becomes 'Shaun the Sheep: The Beast of Mossy Bottom'. Words with digits,
+  Roman numerals and words without vowels, such as 'M3GAN', 'II' and 'RRR',
+  keep their capitals.
+- Event cinema names stay and are standardised: 'NT Live: HAMLET' becomes
+  'National Theatre Live: Hamlet', 'RBO 2026-27: SWAN LAKE' becomes 'Royal
+  Ballet and Opera: Swan Lake'.
+
+Double bills keep both films: 'Flesh Gordon + Gums'.
+
+## Tests
+
+```sh
+bundle exec rake                # unit tests against fixtures
+LIVE=1 bundle exec rake live    # live riocinema.org.uk
+```
+
+The fixture in `test/fixtures` is the what's on page, trimmed to its programme
+of a few events with short synopses. `test/support/api_shapes.rb` describes
+the JSON 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/rio_uk/cinema.rb

@@ -0,0 +1,99 @@
+module RioUk
+  # The object representing the Rio Cinema in Dalston, London
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's id, 'rio'
+
+    # The Rio is one venue. Its id is the name of its Savoy site, as in
+    # riocinema.org.uk/Rio.dll.
+    VENUES = {
+      'rio' => {
+        name: 'Rio Cinema', street_address: '107 Kingsland High Street', locality: 'London',
+        postal_code: 'E8 2PB', latitude: 51.5496199, longitude: -0.0755805
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    URL = 'https://riocinema.org.uk'.freeze
+
+    # Constructor
+    # @param [String] id the cinema's id, 'rio' or 'Rio'
+    # @return [RioUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.downcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<RioUk::Cinema>] the one cinema
+    # @example
+    #   RioUk::Cinema.all
+    #   #=> [<RioUk::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 = RioUk::Cinema.new('rio')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '107 Kingsland High Street',
+    #         extended_address: nil,
+    #         locality:         'London',
+    #         region:           nil,
+    #         postal_code:      'E8 2PB',
+    #         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
+    #   RioUk::Cinema.new('rio').name
+    #   #=> 'Rio Cinema'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's website
+    # @return [String]
+    # @example
+    #   RioUk::Cinema.new('rio').url
+    #   #=> 'https://riocinema.org.uk'
+    def url
+      venue.empty? ? '' : URL
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/rio_uk/internal/http.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module RioUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to riocinema.org.uk
+    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 "Rio 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/rio_uk/internal/parser/event.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RioUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads one Savoy event, a film or other listing with its performances
+      class Event
+        # TypeDescription of films, e.g. 'Film' or 'Main Feature'. Other
+        # types are live events.
+        FILM_TYPE = /\b(?:film|feature)s?\b/i
+
+        # The Rio's performance flags and the variants they mean. PP (Pink
+        # Palace), RF (Rio Forever), SP (special event) and NoAds are strands
+        # and promises, not variants.
+        FLAGS = {
+          'CB' => 'baby',      # Carers + Baby
+          'CM' => 'senior',    # Classic Matinee, for the over 60s
+          'FF' => 'kids',      # Family Flicks
+          'HC' => 'kids',      # Hackney Children's Film Fest
+          'HoH' => 'subtitled', # Hard of Hearing
+          'QA' => 'q&a',
+          'RS' => 'relaxed'
+        }.freeze
+
+        TITLE_VARIANTS = {
+          /\b35mm\b/i => '35mm',
+          /\b70mm\b/i => '70mm',
+          /\bQ\s?[&+]\s?A\b/i => 'q&a',
+          /\bSing[- ]?A[- ]?Long\b/i => 'sing_along'
+        }.freeze
+
+        YES = 'Y'
+        THREE_D = /\b3D\b/i
+        YEAR = /\A\d{4}\z/
+        TIME_ZONE = 'Europe/London'
+
+        # @param [Hash] event one of the website's Savoy events
+        def initialize(event)
+          @event = event
+        end
+
+        # Films have a director or a year. Gigs and parties listed as films
+        # have neither.
+        # @return [Boolean]
+        def film?
+          @event['TypeDescription'].to_s.match?(FILM_TYPE) && !(director.empty? && year_field.empty?)
+        end
+
+        # @param [Range<Date>] dates listings dates to keep
+        # @return [Array<Hash>] options for RioUk::Performance.new
+        def performances(dates)
+          @event.fetch('Performances', []).filter_map do |performance|
+            date = Date.iso8601(performance.fetch('StartDate'))
+            attributes(performance, date) if dates.cover?(date)
+          end
+        end
+
+        private
+
+        def attributes(performance, date)
+          starting_at = starting_at(performance, date)
+          {
+            booking_url: booking_url(performance),
+            dimension: [title, format].any? { |text| text.match?(THREE_D) } ? '3d' : '2d',
+            festival: Cinebase::Festival.from_title(title, year: starting_at.year),
+            film_name: film_name,
+            film_year: film_year,
+            starting_at: starting_at,
+            variant: variant(performance)
+          }
+        end
+
+        def booking_url(performance)
+          if performance['IsSoldOut'] == YES || !performance['IsOpenForSale']
+            nil
+          else
+            Website.url(performance.fetch('URL'))
+          end
+        end
+
+        def director
+          @event['Director'].to_s.strip
+        end
+
+        def film_name
+          @film_name ||= TitleSanitizer.new(title, director: director, strands: strands).sanitized
+        end
+
+        # Double bills give two years, e.g. '1974 / 1976', and programmes of
+        # shorts 'Various'
+        def film_year
+          year_field.match?(YEAR) ? year_field.to_i : Cinebase::TitleSanitizer.film_year(title)
+        end
+
+        def format
+          @event.fetch('Tags', []).map { |tag| tag['Format'].to_s }.join(' ')
+        end
+
+        # Times are London time, e.g. '1830'
+        def starting_at(performance, date)
+          hour, minute = performance.fetch('StartTime').unpack('a2a2').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 strands
+          @event.fetch('Seasons', []).map { |season| CGI.unescapeHTML(season['SeasonName'].to_s) }
+        end
+
+        def title
+          @title ||= CGI.unescapeHTML(@event.fetch('Title')).squeeze(' ').strip
+        end
+
+        def variant(performance)
+          from_flags = FLAGS.filter_map { |flag, variant| variant if performance[flag] == YES }
+          from_title = TITLE_VARIANTS.filter_map { |pattern, variant| variant if title.match?(pattern) }
+          (from_flags + from_title).uniq
+        end
+
+        def year_field
+          @event['Year'].to_s.strip
+        end
+      end
+    end
+  end
+end

data/lib/rio_uk/internal/title_sanitizer.rb

@@ -0,0 +1,116 @@
+module RioUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles. The Rio writes the film in
+    # capitals and its strand, presenter and extras in mixed case, e.g.
+    # 'Little White Lies: PAN'S LABYRINTH on 35mm'.
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # Event cinema names to keep in front of the film
+      EVENT_CINEMA = /\A(?:NT Live|National Theatre Live|RBO|Royal Ballet|Met Opera|Exhibition on Screen)\b[^:]*:\s*/i
+      # A strand or presenter that names a club, festival or presenter
+      PRESENTER = /\b(?:club|fest|festival|kino|presents?)\b/i
+      SMALL_WORDS = %w(a an and as at but by for from in nor of on or the to v vs via with).freeze
+      # Lone Roman numerals, e.g. 'II', stay in capitals
+      ROMAN = /\A(?=[IVXLC])C{0,3}(?:XC|XL|L?X{0,3})(?:IX|IV|V?I{0,3})\z/
+      VOWEL = /[AEIOUYÀ-ÖØ-Ý]/
+      # The first two-letter word, which says whether the title is in capitals
+      FIRST_WORD = /[\p{L}\p{N}'’-]*\p{L}[\p{L}\p{N}'’-]*\p{L}[\p{L}\p{N}'’-]*/
+
+      # Constructor
+      # @param [String] title a film title, without HTML entities
+      # @param [String] director the event's director, whose name some
+      #   titles lead with, e.g. "Alain Gomis' DAO"
+      # @param [Array<String>] strands the event's season names, e.g.
+      #   'Pink Palace'
+      # @return [RioUk::Internal::TitleSanitizer]
+      def initialize(title, director: '', strands: [])
+        super(title)
+        @director = director
+        @strands = strands
+      end
+
+      # sanitized and standardized title
+      # @return [String] sanitised title
+      def sanitized
+        @sanitized ||= begin
+          listed = without_director(title.squeeze(' ').strip)
+          event_cinema = listed[EVENT_CINEMA].to_s
+          film = without_strand(listed.delete_prefix(event_cinema))
+          film = titlecase(leading_capitals(film)) if capitals?(film)
+          film = remove.reduce(event_cinema + film) { |text, pattern| text.gsub(pattern, '') }
+          replace.reduce(film) { |text, (pattern, prefix)| text.gsub(pattern) { prefix + $1 } }.squeeze(' ').strip
+        end
+      end
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [/[\s:,+-]+\z/] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A(?:NT|National Theatre) Live:\s*(.*)/i              => 'National Theatre Live: ',
+          /\ARBO (?:Cinema Season )?20\d{2}-\d{2}:\s*(.*)/i      => 'Royal Ballet and Opera: ',
+          /\AExhibition on Screen:\s*(.*)/i                      => 'Exhibition on Screen: '
+        }.merge(COMMON_REPLACE)
+      end
+
+      def capitals?(text)
+        word = text[FIRST_WORD]
+        !word.nil? && !word.match?(/\p{Ll}/)
+      end
+
+      # Mixed case words after the film are extras, e.g. 'on 35mm'
+      def leading_capitals(text)
+        text.split(' ').take_while { |word| !word.match?(/\p{Ll}/) }.join(' ')
+      end
+
+      def without_director(text)
+        if @director.empty?
+          text
+        else
+          text.sub(/#{Regexp.escape(@director)}['’]s?\s+(?=\S)/i, '')
+        end
+      end
+
+      # The first prefix before a colon goes when it is one of the event's
+      # strands, names a club, festival or presenter, or is in mixed case in
+      # front of a film in capitals
+      def without_strand(text)
+        prefix, film = text.split(/:\s+/, 2)
+        if film.nil?
+          text.sub(/\A.+?\s+presents\s+/i, '')
+        elsif strand?(prefix) || prefix.match?(PRESENTER) || (prefix.match?(/\p{Ll}/) && capitals?(film))
+          film
+        else
+          text
+        end
+      end
+
+      def strand?(prefix)
+        @strands.any? { |strand| prefix.downcase.start_with?(strand.downcase) }
+      end
+
+      # Words start with a capital, except small words inside the title
+      def titlecase(text)
+        text.gsub(/[\p{L}\p{N}'’]+/) do |word|
+          titlecase_word(word, first: $`.match?(/\A[^\p{L}\p{N}]*\z|[:(–-]\s*\z/))
+        end
+      end
+
+      def titlecase_word(word, first:)
+        if !first && SMALL_WORDS.include?(word.downcase)
+          word.downcase
+        elsif word.match?(/\p{N}|\p{Ll}/) || word.length < 2 || word.match?(ROMAN) || !word.match?(VOWEL)
+          word
+        else
+          word.capitalize
+        end
+      end
+    end
+  end
+end

data/lib/rio_uk/internal/website.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RioUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads the Rio Cinema's website, run on Savoy Systems' ticketing. No
+    # token is needed.
+    class Website
+      include Http
+
+      WHATS_ON = 'https://riocinema.org.uk/Rio.dll/WhatsOn'
+      # Savoy pages carry the whole programme as one line of JSON
+      EVENTS = /^var Events =\s*(\{.*\})\s*$/
+
+      # Every event on sale with every advertised performance, however far
+      # ahead, including sold out ones
+      # @return [Array<Hash>] Savoy events, each with its 'Performances'
+      def events
+        JSON.parse(get(WHATS_ON)[EVENTS, 1] || '{}').fetch('Events', [])
+      end
+
+      # @param [String] path a Savoy link relative to the what's on page,
+      #   e.g. 'Booking?Booking=...'
+      # @return [String] the absolute url
+      def self.url(path)
+        URI.join(WHATS_ON, path).to_s
+      end
+    end
+  end
+end

data/lib/rio_uk/performance.rb

@@ -0,0 +1,66 @@
+module RioUk
+  # A single screening of a film on the Rio 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
+
+    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 id, 'rio'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<RioUk::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
+        events = RioUk::Internal::Website.new.events.map { |event| RioUk::Internal::Parser::Event.new(event) }
+        performances = events.select(&:film?).flat_map { |event| event.performances(from..to) }.map do |attributes|
+          new(attributes.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, baby, kids, q&a, relaxed, senior,
+    #   subtitled ...)
+    #   @return <Array[String]>
+  end
+end

data/lib/rio_uk/version.rb

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

data/lib/rio_uk.rb

@@ -0,0 +1,18 @@
+require 'cgi/escape'
+require 'json'
+
+require 'cinebase'
+
+require_relative './rio_uk/version'
+
+require_relative './rio_uk/internal/http'
+require_relative './rio_uk/internal/website'
+require_relative './rio_uk/internal/title_sanitizer'
+require_relative './rio_uk/internal/parser/event'
+
+require_relative './rio_uk/cinema'
+require_relative './rio_uk/performance'
+
+# rio_uk gem
+module RioUk
+end