matsadler-tube 0.1.0

data/lib/line.rb

@@ -0,0 +1,72 @@
+module Tube # :nodoc:
+  
+  # Models the data gathered on a tube line from the tfl.gov.uk "Live travel
+  # news" page.
+  # 
+  class Line
+    attr_reader :id
+    attr_accessor :status, :problem, :message, :name
+    alias_method :problem?, :problem
+    
+    # :call-seq: Line.new(id, status, problem=false, message=nil, name=nil)
+    # 
+    # Create a new Line. If name is ommited it will be set to id.
+    # 
+    def initialize( id, status, problem=false, message=nil, name=nil )
+      @id = id
+      @status = status
+      @problem = problem
+      @message = message
+      @name = name || @id
+    end
+    
+    # :call-seq: line.to_hash -> hash
+    # 
+    # Returns a hash representation of the object.
+    #  {"id" => "central", "status" => "Good service", "problem" => false,
+    #  "message" => nil, "name" => "Central"}
+    # 
+    # 
+    def to_hash
+      instance_variables.inject( {} ) do |memo, var|
+        memo.merge( {var[1..-1] => instance_variable_get( var )} )
+      end
+    end
+    
+    # :call-seq: line.to_json -> string
+    # 
+    # Returns a string of JSON representing the object.
+    #  '{"id":"central", "status":"Good service", "problem":false,
+    #  "message":null, "name":"Central"}'
+    # 
+    def to_json( *args )
+      to_hash.to_json( *args )
+    end
+    
+    # :call-seq: line.to_xml -> string
+    # line.to_xml(false) -> rexml_document.
+    # 
+    # Returns a string of XML representing the object.
+    #  <line>
+    #    <id>central</id>
+    #    <status>Good service</status>
+    #    <problem>false</problem>
+    #    <message/>
+    #    <name>Central</name>
+    #  </line>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "line" )
+      instance_variables.each do |var|
+        el = root.add_element( var[1..-1] )
+        el.add_text( instance_variable_get( var ).to_s )
+      end
+      if as_string then doc.to_s else doc end
+    end
+    
+  end
+end

data/lib/line_group.rb

@@ -0,0 +1,28 @@
+module Tube # :nodoc:
+  
+  # Really just an array with an appropriate #to_xml method.
+  # 
+  class LineGroup < Array
+    
+    # :call-seq: line_group.to_xml -> string
+    # line_group.to_xml(false) -> rexml_document.
+    # 
+    # Returns a string of XML representing the object.
+    #  <lines>
+    #    contents of the array as xml...
+    #  </lines>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "lines" )
+      each do |e|
+        root.add_element( e.to_xml( false ) )
+      end
+      if as_string then doc.to_s else doc end
+    end
+    
+  end
+end

data/lib/station.rb

@@ -0,0 +1,61 @@
+module Tube # :nodoc:
+  
+  # Models the data gathered on a tube station from the tfl.gov.uk "Live travel
+  # news" page.
+  # 
+  class Station
+    attr_reader :name
+    attr_accessor :message
+    
+    # :call-seq: Station.new(name, message=nil)
+    # 
+    # Create a new Station.
+    # 
+    def initialize( name, message=nil )
+      @name = name
+      @message = message
+    end
+    
+    # :call-seq: station.to_hash -> hash
+    # 
+    # Returns a hash representation of the object.
+    #  {"name" => "Bank", "message" => "Undergoing escalator refurbishment."}
+    # 
+    def to_hash
+      instance_variables.inject( {} ) do |memo, var|
+        memo.merge( {var[1..-1] => instance_variable_get( var )} )
+      end
+    end
+    
+    # :call-seq: station.to_json -> string
+    # 
+    # Returns a string of JSON representing the object.
+    #  '{"name":"Bank", "message":"Undergoing escalator refurbishment."}'
+    # 
+    def to_json( *args )
+      to_hash.to_json( *args )
+    end
+    
+    # :call-seq: station.to_xml -> string
+    # station.to_xml(false) -> rexml_document.
+    # 
+    # Returns a string of XML representing the object.
+    #  <station>
+    #    <name>Bank</name>
+    #    <message>Undergoing escalator refurbishment.</message>
+    #  </station>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "station" )
+      instance_variables.each do |var|
+        root.add_element( var[1..-1] ).add_text( instance_variable_get( var ) )
+      end
+      if as_string then doc.to_s else doc end
+    end
+    
+  end
+end

data/lib/station_group.rb

@@ -0,0 +1,65 @@
+module Tube # :nodoc:
+  
+  # Really just an array that can have a name, plus appropriate #to_json and
+  # #to_xml methods.
+  # 
+  class StationGroup < Array
+    attr_reader :name
+    
+    # :call-seq: StationGroup.new(name, size=0, obj=nil)
+    # StationGroup.new(name, array)
+    # StationGroup.new(name, size) {|index| block }
+    # 
+    # See Array.new.
+    # 
+    def initialize( name, *args )
+      @name = name
+      super( *args )
+    end
+    
+    # :call-seq: station_group.to_hash -> hash
+    # 
+    # Returns a hash representation of the object. Also calls #to_hash on its
+    # contents.
+    #  {"Closed stations" => [array contents...]}
+    # 
+    def to_hash
+      {@name => to_a.map {|e| e.to_hash}}
+    end
+    
+    # :call-seq: station_group.to_json -> string
+    # 
+    # Returns a string of JSON representing the object.
+    #  '{"Closed stations":[array contents...]}'
+    # 
+    def to_json( *args )
+      to_hash.to_json( *args )
+    end
+    
+    # :call-seq: station_group.to_xml -> string
+    # station_group.to_xml(false) -> rexml_document.
+    # 
+    # Returns a string of XML representing the object.
+    #  <station_group>
+    #    <name>Closed stations</name>
+    #    <stations>
+    #      contents of the array as xml...
+    #    </stations>
+    #  </station_group>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "station_group" )
+      root.add_element( "name" ).add_text( name )
+      stations = root.add_element( "stations" )
+      each do |e|
+        stations.add_element( e.to_xml( false ) )
+      end
+      if as_string then doc.to_s else doc end
+    end
+    
+  end
+end

data/lib/station_group_group.rb

@@ -0,0 +1,62 @@
+module Tube # :nodoc:
+  
+  # Really just an array with appropriate #to_json and #to_xml methods.
+  # 
+  class StationGroupGroup < Array
+    
+    # :call-seq: station_group_group.to_hash -> hash
+    # 
+    # Returns a hash representation of the object.
+    # Calls #to_hash on its contents (which should be station groups) and then
+    # merges those hashes. The end results should look something like:
+    #  {"Closed stations" => [station group contents...],
+    #  "Station maintenance" => [station group contents...]}
+    # 
+    def to_hash
+      inject( {} ) do |memo, e|
+        memo.merge( e.to_hash )
+      end
+    end
+    
+    # :call-seq: station_group_group.to_json -> string
+    # 
+    # Returns a string of JSON representing the object.
+    #  '{"Closed stations": [station group contents...],
+    #  "Station maintenance": [station group contents...]}'
+    # 
+    def to_json( *args )
+      to_hash.to_json( *args )
+    end
+    
+    # :call-seq: station_group_group.to_xml -> string
+    # station_group_group.to_xml(false) -> rexml_document.
+    # 
+    # Returns a string of XML representing the object.
+    #  <station_groups>
+    #    <station_group>
+    #      <name>Closed stations</name>
+    #      <stations>
+    #        contents of the station group as xml...
+    #      </stations>
+    #    </station_group>
+    #    <station_group>
+    #      <name>Station maintenance</name>
+    #      <stations>
+    #        contents of the station group as xml...
+    #      </stations>
+    #    </station_group>
+    #  </station_groups>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "station_groups" )
+      each do |e|
+        root.add_element( e.to_xml( false ) )
+      end
+      if as_string then doc.to_s else doc end
+    end
+  end
+end

data/lib/status.rb

@@ -0,0 +1,317 @@
+module Tube # :nodoc:
+  
+  # Models the status of the London Underground network as displayed on
+  # http://www.tfl.gov.uk/tfl/livetravelnews/realtime/tube/default.html.
+  # 
+  # It is a very thin abstraction over the tfl website, as a result the access
+  # to data on stations is somewhat different to lines due to the differing
+  # presentation.
+  # However it is very dynamic, for example should the East London line return
+  # it will show up in the lines array automatically.
+  # 
+  # ==Example Usage
+  #  require 'tube/status'
+  #  
+  #  status = Tube::Status.get
+  #  
+  #  broken_lines = status.lines.select {|line| line.problem?}
+  #  broken_lines.collect {|line| line.name}
+  #  #=> ["Circle", "District", "Jubilee", "Metropolitan", "Northern"]
+  #  
+  #  status.line(:circle).message
+  #  #=> "Saturday 7 and Sunday 8 March, suspended."
+  #  
+  #  closed_stations = status.station_group(:closed)
+  #  closed_stations.collect {|station| station.name}
+  #  #=> ["Blackfriars", "Hatton Cross"]
+  #  
+  #  status.find_station("hatton").message
+  #  #=> "Saturday 7 and Sunday 8 March, closed."
+  #  
+  #  status.updated.strftime("%I:%M%p")
+  #  #=> "04:56PM"
+  #  
+  #  status.reload
+  #  status.updated.strftime("%I:%M%p")
+  #  #=> "05:00PM"
+  # 
+  # ==Converting to JSON and XML
+  # All objects come complete with #to_json and #to_xml methods. These depend
+  # upon the ruby json and REXML libraries.
+  # 
+  # ===XML
+  #  status.line(:central).to_xml
+  #  #=> "<line><id>central</id><status>Good service</status>
+  #      <problem>false</problem><message/><name>Central</name></line>"
+  # 
+  # ===JSON
+  #  status.line(:central).to_json
+  #  #=> '{"id":"central", "status":"Good service", "problem":false,
+  #      "message":null, "name":"Central"}'
+  # 
+  class Status
+    attr_reader :updated, :lines, :station_groups
+    
+    # :call-seq: Status.get -> status
+    # Status.new -> status
+    # 
+    # Request and parse the status of the London Underground network from the
+    # tfl.gov.uk "Live travel news" page.
+    # 
+    def initialize( url=
+        "http://www.tfl.gov.uk/tfl/livetravelnews/realtime/tube/default.html" )
+      
+      @url = url
+      reload
+    end
+    
+    class << self
+      alias get new
+    end
+    
+    # :call-seq: status.reload -> status
+    # 
+    # Re-request the latest status and reload all data.
+    # 
+    def reload
+      doc = Hpricot( open( @url ) )
+      
+      time_el = doc.at( "div#service-board" ).previous_sibling.children.first
+      time_text = time_el.inner_text.match( /(\d?\d:\d\d(a|p)m)/ )[0]
+      time_zone = if is_bst? then "+0100" else "+0000" end
+      @updated = Time.parse( "#{time_text} #{time_zone}" )
+      
+      lines = doc.search( "dl#lines dt" ).map do |el|
+        id = el.attributes["class"]
+        name = el.inner_text.strip
+        
+        status = el.next_sibling
+        if status_el = status.at( "h3" )
+          status_text = status_el.inner_text.strip
+          message = format_messages( status.search( "div.message p" ) )
+        else
+          status_text = status.inner_text.strip
+        end
+        problem = status.attributes["class"] == "problem"
+        
+        Line.new( id, status_text, problem, message, name )
+      end
+      @lines = LineGroup.new( lines )
+      
+      @station_groups = StationGroupGroup.new
+      doc.search( "dl#stations dt" ).each do |el|
+        station_group = StationGroup.new( el.inner_text.strip )
+        while el = el.next_sibling
+          if el.to_html =~ /^<dd/ && name_el = el.at( "h3" )
+            name = name_el.inner_text.strip
+            message = format_messages( el.search( "div.message p" ) )
+            station = Station.new( name, message )
+            station_group.push( station )
+          elsif el.to_html =~ /^<dt/
+            break
+          end
+        end
+        @station_groups.push( station_group )
+      end
+      
+      self
+    end
+    
+    # :call-seq: status.line(string) -> line or nil
+    # status.line(symbol) -> line or nil
+    # status.line(regexp) -> line or nil
+    # 
+    # Get a single Line object. Passing a string will do a fuzzy match on the
+    # line id, a symbol will have to match the line id exactly.
+    # 
+    #  status.line(:hammersmithandcity)   #=>\
+    #<Tube::Line:0x1163964 @id="hammersmithandcity", @name="H'smith & City"...
+    #  status.line("waterloo")            #=>\
+    #<Tube::Line:0x113d700 @id="waterlooandcity", @name="Waterloo & City"...
+    #  status.line("east london")         #=>     nil # no longer exists
+    # 
+    def line( name )
+      if name.is_a?( String )
+        name = name.gsub( /\s/, "" )
+        name.gsub!( /&/, "and" )
+        name.gsub!( /'/, ".+" )
+        name = Regexp.new( name, true )
+      elsif name.is_a?( Symbol )
+        name = /^#{name}$/
+      end
+      @lines.detect {|line| line.id =~ name}
+    end
+    
+    # :call-seq: status.find_station(string) -> station or nil
+    # status.find_station(symbol) -> station or nil
+    # status.find_station(regexp) -> station or nil
+    # 
+    # Get a single Station object. See #find_stations for more details. If more
+    # than one station is found the one with the shortest name will be returned.
+    # 
+    def find_station( name )
+      results = find_stations( name )
+      
+      if results.length == 1
+        results.first
+      else
+        results.sort do |a,b|
+          a.name.gsub(/\(.+\)/, "").length <=> b.name.gsub(/\(.+\)/, "").length
+        end.first
+      end
+    end
+    
+    # :call-seq: status.find_stations(string) -> array
+    # status.find_stations(symbol) -> array
+    # status.find_stations(regexp) -> array
+    # status.find_stations(array) -> array
+    # status.find_stations -> array
+    # 
+    # Get all Station objects matching the argument. Passing a string will do a
+    # fuzzy match on the station name, a symbol will have to match the station
+    # name exactly, an array will return all matches (without duplicates) for
+    # the contents of the array.
+    # 
+    # With no arguments simply returns all stations.
+    # 
+    #  status.find_stations("acton")     \
+    #=> [#<Tube::Station:0x110d7e4 @message="Closed.", @name="East Acton">]
+    #  status.find_stations(:Bank)            #=> [] # No problems at Bank
+    #  status.find_stations("tower bridge")   #=> [] # No station by that name
+    # 
+    def find_stations( name=nil )
+      stations = @station_groups.flatten
+      
+      case name
+      when String
+        # this could be simplified once I'm more confident about the format of
+        # station names
+        name = name.gsub( /\s/, "\\s*" )
+        name.gsub!( /(and|&)/, "(and|&)" )
+        name = Regexp.new( name, true )
+        stations = stations.select {|station| station.name =~ name}
+      when Regexp
+        stations = stations.select {|station| station.name =~ name}
+      when Symbol
+        stations = stations.select {|station| station.name == name.to_s}
+      when Array
+        stations = name.map {|n| search_stations( n )}.flatten.uniq
+      when nil
+        stations
+      end
+    end
+    
+    # :call-seq: status.station_group(string) -> station_group or nil
+    # status.station_group(symbol) -> station_group or nil
+    # status.station_group(regexp) -> station_group or nil
+    # 
+    # Get a single StationGroup object. Both string and symbol are fuzzy
+    # matches.
+    # 
+    # It appears the two groups are "Closed stations" and "Station maintenance"
+    # 
+    #  status.station_group(:closed)        #=> [stations...]
+    #  status.station_group(:maintenance)   #=> [stations...]
+    # 
+    def station_group( name )
+      if name.is_a?( String ) || name.is_a?( Symbol )
+        name = Regexp.new( name.to_s, true )
+      end
+      @station_groups.detect {|group| group.name =~ name}
+    end
+    
+    # :call-seq: status.to_hash -> hash
+    # 
+    # Returns a hash representation of the object.
+    #  {"stations" => {station groups...},
+    #  "lines" => [lines...],
+    #  "updated" => Fri Feb 13 23:31:30 +0000 2009}
+    # 
+    def to_hash
+      {"updated" => updated,
+        "lines" => lines.map {|e| e.to_hash},
+        "stations" => station_groups.to_hash}
+    end
+    
+    # :call-seq: status.to_json -> string
+    # 
+    # Returns a string of JSON representing the object.
+    #  '{"stations":{stations...},
+    #  "lines":[lines...],
+    #  "updated":"Fri Feb 13 23:31:30 +0000 2009"}'
+    # 
+    def to_json( *args )
+      to_hash.to_json( *args )
+    end
+    
+    # :call-seq: status.to_xml -> string
+    # status.to_xml(false) -> rexml_document
+    # 
+    # Returns a string of XML representing the object.
+    #  <status>
+    #    <updated>Fri Feb 13 23:31:30 +0000 2009</updated>
+    #    lines as xml...
+    #    station_groups as xml...
+    #  </status>
+    # 
+    # Alternately pass false as the only argument to get an instance of
+    # REXML::Document.
+    # 
+    def to_xml( as_string=true )
+      doc = REXML::Document.new
+      root = doc.add_element( "status" )
+      root.add_element( "updated" ).add_text( updated.to_s )
+      root.add_element( lines.to_xml( false ) )
+      root.add_element( station_groups.to_xml( false ) )
+      if as_string then doc.to_s else doc end
+    end
+    
+    private
+    
+    # :call-seq: format_messages(messages) -> string
+    # 
+    # Takes an array of elements, strips those elements of elements they contain
+    # and returns only the text within the root elements.
+    #  <p>Suspended. Rail replacement bus services operate.</p>
+    #  <p>Service A: ...</p>
+    #  <p><a href="/transform">See how we are transforming the Tube</a></p>
+    # becomes
+    #  Suspended. Rail replacement bus services operate.
+    #  Service A: ...
+    # 
+    def format_messages( messages )
+      text_messages = messages.map do |message|
+        if message.children
+          message.children.select {|child| child.text?}.join( " " )
+        end
+      end.compact
+      text_messages.reject! {|m| m.empty?}
+      text_messages.map {|m| m.gsub( /\s+/, " " ).strip}.join( "\n" )
+    end
+    
+    # :call-seq: is_bst? -> bool
+    # 
+    # Is British Summer Time currently in effect.
+    # 
+    def is_bst?
+      bst_start = last_sunday_of_preceding_month( "april" )
+      bst_end = last_sunday_of_preceding_month( "november" )
+      
+      one_hour = 3600
+      bst_start = Time.gm(bst_start.year, bst_start.month) + one_hour
+      bst_end = Time.gm(bst_end.year, bst_end.month) + one_hour
+      
+      (bst_start..bst_end).include?(Time.now.getgm)
+    end
+    
+    # :call-seq: last_sunday_of_preceding_month(month_name) -> date
+    # 
+    def last_sunday_of_preceding_month( month_name )
+      start_of_preceding_month = Date.parse( month_name )
+      week_day = start_of_preceding_month.wday
+      distance_from_sunday = if week_day == 0 then 7 else week_day end
+      start_of_preceding_month - distance_from_sunday
+    end
+    
+  end
+end

data/lib/tube.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'hpricot'
+require 'open-uri'
+require 'time'
+require 'json'
+require 'rexml/document'
+
+require 'line'
+require 'station'
+require 'line_group'
+require 'station_group'
+require 'station_group_group'
+require 'status'

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: matsadler-tube
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mat Sadler
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-24 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.8.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A simple Ruby library to access the status of the London Underground network.
+email: mat@sourcetagsandcodes.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/line.rb
+- lib/line_group.rb
+- lib/station.rb
+- lib/station_group.rb
+- lib/station_group_group.rb
+- lib/status.rb
+- lib/tube.rb
+has_rdoc: true
+homepage: http://github.com/matsadler/tube
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Tube
+- --main
+- Tube::Status
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A simple Ruby library to access the status of the London Underground network.
+test_files: []
+