wmata 0.1.0 → 0.2.0

data/README.rdoc

@@ -1,6 +1,38 @@
 = wmata
 
-Description goes here.
+Jeremy McAnally - Intridea
+
+A nice little gem for accessing the WMATA data API (http://developer.wmata.com).
+
+== Installing / Getting Started
+
+First, install the gem...
+
+    gem install wmata
+    
+...or use your Git clone.  It's up to you. :)
+
+Next, mosey on over to http://developer.wmata.com and get yourself a developer account.  Create an application (it can just be named "test" or whatever for now) and get your API key.  You'll need to provide your API key for any API work you'll be doing.
+
+To get started using the gem, require it (of course), and then set your API key:
+
+    WMATA.api_key = "ab7bce7ba8e08ccca9ce80ab890eb8a9dd"
+    
+Now you're ready to rock and roll!
+
+== Usage
+
+The gem's functionality is primarily oriented around the +WMATA+ module.  For example, to get all the rail lines available, you'd do this:
+
+    WMATA.lines
+    
+This will give you an array of +Line+ objects to manipulate.  So, you could do something like this:
+
+    WMATA.lines.first.incidents
+    
+This code would give you an array of +Incident+ objects that you can manipulate.  Essentially, its usage boils down to a simple maxim: most of the fetching logic should be accessed through the +WMATA+ module or the domain objects returned from methods called on methods called on +WMATA+.  You can call the fetching logic directly (e.g., +Line.get_all+), but it's smarter to use the public API. 
+
+For detailed information about what methods are available, see the documentation for +WMATA+ and each individual resource class.
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/resources/elevator_incident.rb

@@ -1,23 +1,48 @@
 module WMATA
+  # A class representing service incidents in elevators (e.g., an elevator is busted
+  # going between the two floors of the station).
+  #
+  # Available attribute methods:
+  #
+  # * +display_order+ - Display priority
+  # * +date_out_of_service+ - Date when elevator/escalator was switched off.
+  # * +date_updated+ - Time when the information was last received.
+  # * +location_description+ - Location of elevator/escalator.
+  # * +station_code+ - Code of the station affected by the escalator/elevator incident.
+  # * +station_name+ - Name of the station affected by the escalator/elevator incident.
+  # * +symptom_code+ - ID of the reason why elevator/escalator was switched off.
+  # * +symptom_description+ - Information why elevator/escalator was switched off.
+  # * +time_out_of_service+ - Number of minutes the elevator has been out of service until last update of data.
+  # * +unit_name+ - ID of the affected elevator/escalator.
+  # * +unit_status+ - Can be "C" or "O": O means Out of service (has open issues) and C  means Operational (open issues were closed).
+  # * +unit_type+ - "ESCALATOR" or "ELEVATOR"
+  #
   class ElevatorIncident < Resource
     service "Incidents"
     endpoint "ElevatorIncidents"
     
+    # Get the incidents by station; provide either a +Station+ instance
+    # or a station code as the argument.
     def self.get_by_station(affected_station)
       @incidents ||= get_all
       @incidents.select {|i| i.station_code == affected_station.to_s }.pop
     end
     
+    # Get the station affected by the problem.
     def affected_station
       Station.get(@attrs['StationCode'])
     end
 
     alias_method :station, :affected_station
     
+    # Get a +Time+ object representing the time the elevator went out of 
+    # service.
     def date_out_of_service
       Time.parse(@attrs['DateOutOfServ'])
     end
     
+    # Get a +Time+ object representing the last time this API data entry
+    # was updated.
     def date_updated
       Time.parse(@attrs['DateUpdated'])
     end

data/lib/resources/line.rb

@@ -1,48 +1,80 @@
 module WMATA
+  # A resource class representing a rail line.
+  #
+  # Available attribute methods:
+  #
+  # * +display_name+ - The public name (color) of the line.
+  # * +start_station_code+ - The code associated with the first station on the line.
+  # * +end_station_code+ - The code associated with the last station on the line.
+  # * +internal_destination1+ - Some trains can start/finish their trips not only at the first/last station, but at intermediate stations along the line.
+  # * +internal_destination2+ - See +internal_destination+.
+  #
   class Line < Resource
     service "Rail"
     endpoint "JLines"
     
+    SYMBOL_TO_LINES_MAP = {
+      :red => "RD",
+      :blue => "BL",
+      :orange => "OR", 
+      :green => "GR", 
+      :yellow => "YE"
+    }
+    
     class <<self
       alias_method :get_all_without_memoize, :get_all
         
-      # Memoize this since (a) there's no way to ask for just one line and
+      # NOTE: We memoize this since (a) there's no way to ask for just one line and
       # (b) they're unlikely to change while we're doing a request.
       def get_all(params)
         @lines ||= get_all_without_memoize(params)
       end
+      
+      def symbol_to_line_code(symbol)
+        SYMBOL_TO_LINES_MAP[symbol]
+      end
     end
     
+    # Get the first station on this line.
     def start_station
       @start_station ||= Station.get(@attrs['StartStationCode'])
     end
     
+    # Get the last station on this line.
     def end_station
       @end_station ||= Station.get(@attrs['EndStationCode'])
     end
     
+    # Get all internal destinations (some lines "end" or "begin" at more than
+    # one station).
     def internal_destinations
       [@attrs['InternalDestination1'], @attrs['InternalDestination2']].compact.map do |s| 
         Station.get(s)
       end
     end
     
+    # Get all rail incidents on this line.
     def rail_incidents
       @incidents ||= RailIncident.get_by_line(self)
     end
     
     alias_method :incidents, :rail_incidents
     
+    # Get all the stations on this line ordered by the route.
     def route
       Station.get_on_line(code)
     end
     
     alias_method :stations, :route
     
+    # Get a specific line, identified by line code (e.g., "RD") or a +Symbol+
+    # string name (e.g., +:red+).
     def get(code)
+      code = Line.symbol_to_line_code(code) if code.is_a?(Symbol)
       get_all.select {|l| l.code == code}.pop
     end
     
+    # Returns the line's code (also available as +line_code+).
     def code
       @attrs['LineCode']
     end

data/lib/resources/path_segment.rb

@@ -1,18 +1,37 @@
 module WMATA
+  # A resource class representing a segment in a path between two stations.
+  #
+  # Available attribute methods:
+  #
+  # * +station_code+ - The ID code for an individual station.
+  # * +station_name+ - The name of the Station.
+  # * +line_code+ - The ID (color) of the Line associated with the path.
+  # * +seq_num+ - The sequence of the station in the path.
+  # * +distance_to_previous+ - Distance in feet from the previous station in the path.
+  #
   class PathSegment < Resource
     service "Rail"
     endpoint "JPath"
     
+    # Return the +Station+ instance representing the station on
+    # this segment of the path.
     def station
       @station ||= Station.get(@attrs['StationCode'])
     end
     
+    # Returns the +Line+ instance for the line this segment falls on.
     def line
       @line ||= Line.get(@attrs['LineCode'])
     end
     
+    # The position this +PathSegment+ is in the overall path.
     def index
       @attrs['SeqNum']
     end
+    
+    # The distance to the previous station in the path.
+    def distance_to_previous
+      @attrs['DistanceToPrev']
+    end
   end
 end

data/lib/resources/prediction.rb

@@ -1,28 +1,59 @@
 module WMATA
+  # A resource class representing train arrival prediction information.
+  #
+  # Available attribute methods:
+  #
+  # * +car+ - Number of cars in a particular train (usually 6 or 8).
+  # * +destination_code+ - The ID of destination station.
+  # * +destination_name+ - The name of destination station.
+  # * +group+ - Track number (1 or 2).
+  # * +line+ - ID of the metro line.
+  # * +location_code+ - ID of the station where the train is arriving.
+  # * +location_name+ - The name of the station where the train is arriving.
+  # * +arrival_status+ - The minutes to train arrival. Can be +:boarding+, +:arrived+, or positive number.
+  #
   class Prediction < Resource
     service "StationPrediction"
     
+    # Get train arrival prediction information for a given station; can
+    # be a station code as a string or a +Station+ instance.
     def self.predict_for(station_code)
-      url = WMATA.base_url % [service, "GetPrediction/#{station_code}", ""]
+      url = WMATA.base_url % [service, "GetPrediction/#{station_code.to_s}", ""]
       HTTParty.get(url).first.last.map {|values| new(values) }
     end
     
+    # Get the arriving station this prediction applies to.
     def location
       @location ||= Station.get(@attrs['LocationCode'])
     end
     
     alias_method :station, :location
     
+    # Get the destination of the train for this prediction.
     def destination
       @destination ||= Station.get(@attrs['DestinationCode'])
     end
     
+    # Get the line code the line this prediction's station is on.
     def line_code
       @attrs['Line']
     end
     
+    # Get the +Line+ instance for this prediction's station's line.
     def line
       @line ||= Line.get(@attrs['Line'])
     end
+    
+    # Get the arrival status of the train.  Can be +:boarding+, +:arrived+, or 
+    # the number of minutes until the train will arrive.
+    def arrival_status
+      if @attrs['Min'] == "BRD"
+        :boarding
+      elsif @attrs['Min'] == "ARR"
+        :arrived
+      else
+        @attrs['Min'].to_i
+      end
+    end
   end
 end

data/lib/resources/rail_incident.rb

@@ -1,23 +1,52 @@
 module WMATA
+  # A resource class representing a rail incident (e.g., garbage on the rails delaying a train).
+  #
+  # Available attribute methods:
+  #
+  # * +incident_id+ - ID of the nicident
+  # * +incident_type+ - Type of the nicident
+  # * +date_updated+ - Date and time where information was updated.
+  # * +delay_severity+ - Severity of delay (if any). Can be +:minor+, +:major+, or +:medium+.
+  # * +description+ - Description what happened.
+  # * +emergency_text+ - Some text for emergency (if any).
+  # * +start_location_full_name+ - Station where delay starts.
+  # * +end_location_full_name+ - Station where delay ends.
+  # * +passenger_delay+ - Delay in minutes.
+  #
   class RailIncident < Resource
     service "Incidents"
     endpoint "Incidents"
 
+    # Get all rail incidents by the line; can be a line code string or
+    # a +Line+ instance.
     def self.get_by_line(line)
       @incidents ||= get_all
       @incidents.select {|i| i.line_codes_affected.include?(line.to_s)}
     end
     
+    # Get a +Time+ object representing the last time this API data entry
+    # was updated.
     def date_updated
       Time.parse(@attrs['DateUpdated'])
     end
     
+    # Get an array of the line codes affected by this incident.
     def line_codes_affected
       @attrs['LinesAffected'].split(";").reject {|s| s.empty? || s.nil?}
     end
     
+    # Get +Line+ instances for the lines affected by this incident.
     def lines_affected
-      @lines_affected = line_codes_affected.map {|l| Line.get(l)}
+      @lines_affected = line_codes_affected.map {|l| Line.get(l.strip)}
+    end
+    
+    # ID of the incident.
+    def incident_id
+      @attrs['IncidentID']
+    end
+    
+    def delay_severity
+      @attrs['DelaySeverity'].to_s.downcase.to_sym
     end
   end
 end

data/lib/resources/station.rb

@@ -1,46 +1,83 @@
 module WMATA
+  # Resource class representing a station in the metro system.
+  #
+  # Available attribute methods:
+  #
+  # * +code - The code associated with a specific station.
+  # * +name - The name of the station.
+  # * +lat+ - The latitude of the station.
+  # * +lon+ - The longitude of the station.
+  #
+  StationTogether2 - Unused.
   class Station < Resource
     service "Rail"
     endpoint "JStations"
     
-    SYMBOL_TO_LINES_MAP = {
-      :red => "RD",
-      :blue => "BL",
-      :orange => "OR", 
-      :green => "GR", 
-      :yellow => "YE"
-    }
-    
+    # Get all stations on a given line; argument can be a +Line+ instance, a string
+    # line code, or a symbol name (e.g., +:red+).
     def self.get_on_line(line)
-      line = SYMBOL_TO_LINES_MAP[line] if line.is_a?(Symbol)
+      line = Line.symbol_to_line_code(line) if line.is_a?(Symbol)
       get_all("LineCode" => line.to_s)
     end
     
+    # Get a specific station by its code.
     def self.get(code)
       url = WMATA.base_url % [service, "JStationInfo", to_query_string("StationCode" => code)]
       new(HTTParty.get(url))
     end
     
+    # Get all possible codes for this station (some stations are in together with another so
+    # they are technically identified by two station codes).
     def codes
       [@attrs['Code'], @attrs['StationTogether1'], @attrs['StationTogether2']].compact
     end
     
+    # Get the line codes for this station (some stations serve more than one line).
     def line_codes
       [@attrs['LineCode1'], @attrs['LineCode2'], @attrs['LineCode3'], @attrs['LineCode4']].compact
     end
     
+    # Get +Line+ instances for the lines serviced by this station.
     def lines
       @lines ||= line_codes.map {|l| Line.get(l)}
     end
     
+    # Get train arrival predictions for this station.
     def predictions
       @predictions ||= Prediction.predict_for(self)
     end
     
+    # Get all elevator incidents affecting this station.
     def elevator_incidents
       @elevator_incidents ||= ElevatorIncident.get_by_station(self)
     end
     
+    # Build a path from this station to another identified by its code or as a 
+    # +Station+ instance.
+    def path_to(to)
+      WMATA.build_path(self, to)
+    end
+    
+    # Build a path from this station to another station identified by its code
+    # or as a +Station+ instance.
+    def path_from(from)
+      WMATA.build_path(from, self)
+    end
+    
+    def latitude
+      @attrs['Lat']
+    end
+    
+    def longitude
+      @attrs['Lon']
+    end
+    
+    def coordinates
+      [latitude, longitude]
+    end
+    
+    alias_method :coords, :coordinates
+    
     def to_s
       @attrs['Code']
     end

data/lib/resources/station_entrance.rb

@@ -1,14 +1,40 @@
 module WMATA
+  # A resource class representing a station entrance (even if it's just an elevator).
+  #
+  # Available attribute methods:
+  #
+  # * +id+ - ID of the entrance.
+  # * +name+ - The name of the entrance.
+  # * +description+ - A description of the entrance.
+  # * +lat+ - The entrance's latitude.
+  # * +lon+ - The entrance's longitude.
+  #
   class StationEntrance < Resource
     service "Rail"
     endpoint "JStationEntrances"
     
+    # Get station codes that this entrance serves.
     def station_codes
       [@attrs['StationCode1'], @attrs['StationCode2']].compact
     end
     
+    # Get the +Station+ instance for this entrance.
     def station
       @station ||= Station.get(station_codes.first)
     end
+    
+    def latitude
+      @attrs['Lat']
+    end
+    
+    def longitude
+      @attrs['Lon']
+    end
+    
+    def coordinates
+      [latitude, longitude]
+    end
+    
+    alias_method :coords, :coordinates
   end
 end

data/lib/wmata.rb

@@ -18,45 +18,105 @@ module WMATA
   
   class <<self
     attr_accessor :api_key
-        
+    
+    # Get the base URL based on the API key given.  Used in 
+    # nearly every method that contacts the remote API.
     def base_url
       BASE_URL.dup % ["%s", "%s", @api_key, "%s"]    
     end
     
+    # Get all rail lines.
+    #
+    #    WMATA.lines.map {|l| l.code}
+    #    # => ["RD", "BL", "GR", "OR", "YE"]
+    #
     def lines
       Line.get_all
     end
     
+    # Get all stations.
+    #
+    #     WMATA.stations.map {|s| s.name }
+    #     # => ["McPherson Square", "Metro Center", ...]
+    #
     def stations
       Station.get_all
     end
     
+    # Get a specific station by code.
+    #
+    #     WMATA.station("C02")
+    #     # => #<Station:0x1205aee8 "McPherson Square">
+    #
     def station(code)
       Station.get(code)
     end
     
+    # Get an array of stations on a particular line.  Can be called
+    # with a line code (e.g., RD) or a symbol for the line name
+    # (e.g., +:red+).
+    #
+    #     WMATA.stations_on_line(:red)
+    #     # => [#<Station:0x0702aca8>, ...]
+    #
     def stations_on_line(code)
       Station.get_on_line(code)
     end
     
+    # Get station predictions (i.e., train arrival information seen on
+    # station terminals) for a specific station; if no station
+    # code is provided, it will get predictions for all stations.
+    #
+    #     predictions = WMATA.predict_for("C02")
+    #     # => [#<Prediction:0x1205aee8 ...>, ...]
+    #     puts "#{predictions.first.location_name} => #{predictions.first.destination_name}"
+    #     # McPherson Square => Metro Center
+    #
     def predict_for(station="All")
       Prediction.predict_for(station)
     end
     
+    alias_method :get_predictions, :predict_for
+    
+    # Get an array of rail incidents for all lines; use the +incidents+ method
+    # on +Line+ to get them for a specific line or the same method.
+    #
+    #     WMATA.rail_incidents.map {|i| i.description}
+    #     # => ["Friendship Heights is closed...", ...]
+    #
     def rail_incidents
       RailIncident.get_all
     end
     
     alias_method :incidents, :rail_incidents
     
+    # Get an array of elevator incidents for all lines; use the +elevator_incidents+ 
+    # method on +Station+ to get them for a specific station.
+    #
+    #     WMATA.elevator_incidents.map {|i| i.symptom_code}
+    #     # => ["1419", ...]
+    #
     def elevator_incidents
       ElevatorIncident.get_all
     end
     
+    # Map a path between two stations, identified by their station codes; returns an 
+    # array of stations ordered by the path.  You can also provide +Station+ instances
+    # and get a path between them.
+    #
+    #     WMATA.build_path("C02", "A01")
+    #     # => [#<Station:0x0702aca8>, ...]
+    #
     def build_path(from, to)
       PathSegment.get_all("FromStationCode" => from, "ToStationCode" => to)
     end
     
+    # Find entrances near a given latitude and longitude within a given radius (in meters).  
+    # If no geolocation information is given, all entrances are returned.
+    #
+    #     WMATA.entrances(:lat => 28.82083, :lon => 88.9239423, :radius => 2000)
+    #     # => [#<StationEntrance:0x0702aca8>, ...]
+    #
     def entrances(from={})
       params = {:lat => 0, :lon => 0, :radius => 500}.merge(from)
       StationEntrance.get_all(params)

data/wmata.gemspec

@@ -0,0 +1,75 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{wmata}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jeremy McAnally"]
+  s.date = %q{2010-08-17}
+  s.description = %q{A gem for accessing the WMATA API}
+  s.email = %q{jeremymcanally@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/resource.rb",
+     "lib/resources/elevator_incident.rb",
+     "lib/resources/line.rb",
+     "lib/resources/path_segment.rb",
+     "lib/resources/prediction.rb",
+     "lib/resources/rail_incident.rb",
+     "lib/resources/station.rb",
+     "lib/resources/station_entrance.rb",
+     "lib/wmata.rb",
+     "test/helper.rb",
+     "test/test_elevator_incident.rb",
+     "test/test_line.rb",
+     "test/test_path_segment.rb",
+     "test/test_prediction.rb",
+     "test/test_rail_incident.rb",
+     "test/test_resource.rb",
+     "test/test_station.rb",
+     "test/test_station_entrance.rb",
+     "test/test_wmata.rb",
+     "wmata.gemspec"
+  ]
+  s.homepage = %q{http://github.com/jm/wmata}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A gem for the WMATA API}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_elevator_incident.rb",
+     "test/test_line.rb",
+     "test/test_path_segment.rb",
+     "test/test_prediction.rb",
+     "test/test_rail_incident.rb",
+     "test/test_resource.rb",
+     "test/test_station.rb",
+     "test/test_station_entrance.rb",
+     "test/test_wmata.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jeremy McAnally
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-16 00:00:00 -04:00
+date: 2010-08-17 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -53,6 +53,7 @@ files:
 - test/test_station.rb
 - test/test_station_entrance.rb
 - test/test_wmata.rb
+- wmata.gemspec
 has_rdoc: true
 homepage: http://github.com/jm/wmata
 licenses: []