cta_redux 0.2.0 → 0.3.1

data/lib/cta_redux/customer_alerts.rb

@@ -1,12 +1,15 @@
 module CTA
   class CustomerAlerts
+    @cache_responses = true
 
     # Returns the connection object we use to talk to the CustomerAlerts API
     def self.connection
       @connection ||= Faraday.new do |faraday|
         faraday.url_prefix = 'http://www.transitchicago.com/api/1.0/'
         faraday.use CTA::CustomerAlerts::Parser, !!@debug
-        faraday.response :caching, SimpleCache.new(Hash.new)
+        if @cache_responses
+          faraday.response :caching, (@cache || SimpleCache.new(Hash.new))
+        end
         faraday.adapter Faraday.default_adapter
       end
     end
@@ -93,5 +96,38 @@ module CTA
       @debug = debug
       @connection = nil
     end
+
+    # Returns whether or not cta_redux is caching responses
+    # @return [true, false]
+    def self.cache_responses
+      @cache_responses
+    end
+
+    # Sets whether or not cta_redux is caching responses
+    # @param [true, false] should_cache
+    def self.cache_responses=(should_cache)
+      @cache_responses = should_cache
+      @connection = nil
+    end
+
+    # Returns the underlying cache object caching responses (if we're actually caching responses)
+    # @return [Object]
+    def self.cache
+      if self.cache_responses
+        # This is ugly
+        @cache || self.connection.builder.handlers.find { |x| x == FaradayMiddleware::Caching }.instance_variable_get(:@args).first
+      else
+        nil
+      end
+    end
+
+    # Sets the underlying cache object caching responses. Any object can be used that responds to #read, #write, and #fetch
+    # @note Setting the cache object resets the connection. If you're using the default SimpleCache strategy (built-in 60
+    #  second caching), then it will also *clear* the cache.
+    # @param [Object] cache
+    def self.cache=(cache)
+      @cache = cache
+      @connection = nil
+    end
   end
 end

data/lib/cta_redux/faraday_middleware/simple_cache.rb

@@ -1,3 +1,5 @@
+# A simplistic in-process cache.
+# Used internally by cta_redux and caches responses for 60 seconds.
 class SimpleCache
   def initialize(cache)
     @cache = cache

data/lib/cta_redux/models/agency.rb

@@ -1,4 +1,26 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#agency_txt___Field_Definitions agency.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:agency_name, :agency_url, :agency_timezone, :agency_lang, :agency_phone, :agency_fare_url]
   class Agency < Sequel::Model(:agency)
+    # @!method agency_name
+    #  @return [String]
+    # @!method agency_url
+    #  @return [String]
+    # @!method agency_timezone
+    #  @return [String]
+    # @!method agency_lang
+    #  @return [String]
+    # @!method agency_phone
+    #  @return [String]
+    # @!method agency_fare_url
+    #  @return [String]
+    alias_method :name, :agency_name
+    alias_method :url, :agency_url
+    alias_method :timezone, :agency_timezone
+    alias_method :language, :agency_lang
+    alias_method :phone, :agency_phone
+    alias_method :fare_url, :agency_fare_url
   end
 end

data/lib/cta_redux/models/bus.rb

@@ -1,32 +1,111 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}, inherited from {CTA::Trip}
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#trips_txt___Field_Definitions trips.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:route_id, :service_id, :trip_id, :direction_id, :block_id, :shape_id, :direction, :wheelchair_accessible, :schd_trip_id]
   class Bus < CTA::Trip
+    # @return [Live] the {Live} data associated with this {CTA::Bus}, if available.
+    # @note a {CTA::Bus} will only contain live data when augmented with an {API::Response}
+    attr_accessor :live
+
+    # @!method route_id
+    #  @return [String]
+    # @!method service_id
+    #  @return [Integer]
+    # @!method trip_id
+    #  @return [Integer]
+    # @!method direction_id
+    #  @return [Integer]
+    # @!method block_id
+    #  @return [Integer]
+    # @!method shape_id
+    #  @return [Integer]
+    # @!method direction
+    #  @return [String]
+    # @!method wheelchair_accessible
+    #  @return [true,false]
+    # @!method schd_trip_id
+    #  @return [String]
+    alias_method :id, :route_id
+    alias_method :scheduled_trip_id, :schd_trip_id
+    alias_method :run, :schd_trip_id
+
+    # Returns predictions for this {CTA::Bus}. Accepts all options for {CTA::BusTracker.predictions!}, and will merge in
+    # it's own vehicle_id or route_id if present.
+    # @param [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :vehicles Vehicles to predict. Not available with :routes
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes to predict. Not available with :vehicles
+    # @option options [Array<String>, Array<Integer>, String, Integer] :stops Stops along a route to predict. Required with :routes
+    # @option options [String, Integer] :limit Maximum number of predictions to return.
+    # @return [CTA::BusTracker::PredictionsResponse]
+    # @example
+    #   predictions!(:stops => 15895)
+    #   predictions!(:limit => 1)
     def predictions!(options = {})
       opts = (self.vehicle_id ? { :vehicles => self.vehicle_id } : { :routes => self.route_id })
-      puts opts
       CTA::BusTracker.predictions!(options.merge(opts))
     end
 
-    def live!(position, predictions = [])
-      class << self
-        attr_reader :lat, :lon, :vehicle_id, :heading, :pattern_id, :pattern_distance, :route, :delayed, :speed, :predictions
-      end
+    class Live
+      # @return [Float] The latitude of the {CTA::Bus}.
+      attr_reader :lat
+      # @return [Float] The longitude of the {CTA::Bus}.
+      attr_reader :lon
+      # @return [Integer] The vehicle_id of the {CTA::Bus}.
+      attr_reader :vehicle_id
+      # @return [Integer] The heading of the {CTA::Bus}.
+      attr_reader :heading
+      # @return [Integer] The pattern the {CTA::Bus} is following.
+      attr_reader :pattern_id
+      # @return [Integer] The distance into the pattern the {CTA::Bus} is following.
+      attr_reader :pattern_distance
+      # @return [CTA::Route] The {CTA::Route} the {CTA::Bus} is operating.
+      attr_reader :route
+      # @return [true,false] True if the {CTA::Bus} is considered to be delayed.
+      attr_reader :delayed
+      # @return [Integer] Last reported speed of the {CTA::Bus}, in mph.
+      attr_reader :speed
+      # @return [Array<Prediction>] Predictions for this {CTA::Bus}.
+      attr_reader :predictions
 
-      @lat = position["lat"].to_f
-      @lon = position["lon"].to_f
-      @heading = position["hdg"].to_i
-      @vehicle_id = position["vid"].to_i
-      @pattern_id = position["pid"].to_i
-      @pattern_distance = position["pdist"].to_i
-      @route = CTA::Route.where(:route_id => position["rt"]).first
-      @delayed = (position["dly"] == "true")
-      @speed = position["spd"].to_i
+      def initialize(position, predictions = [])
+        @lat = position["lat"].to_f
+        @lon = position["lon"].to_f
+        @heading = position["hdg"].to_i
+        @vehicle_id = position["vid"].to_i
+        @pattern_id = position["pid"].to_i
+        @pattern_distance = position["pdist"].to_i
+        @route = CTA::Route.where(:route_id => position["rt"]).first
+        @delayed = (position["dly"] == "true")
+        @speed = position["spd"].to_i
 
-      @predictions = Array.wrap(predictions).map { |p| Prediction.new(p) }
+        @predictions = Array.wrap(predictions).map { |p| Prediction.new(p) }
+      end
     end
 
     class Prediction
-      attr_reader :type, :stop, :distance, :route, :direction, :destination,
-                  :prediction_generated_at, :arrival_time, :delayed, :minutes, :seconds
+      # @return [String] The type of prediction, either *A*rrival or *D*eparture
+      attr_reader :type
+      # @return [CTA::Stop] The {CTA::Stop} for this prediction
+      attr_reader :stop
+      # @return [Integer] The distance remaining until the bus arrives
+      attr_reader :distance
+      # @return [CTA::Route] The {CTA::Route} associated with this prediction
+      attr_reader :route
+      # @return [Direction] The {Direction} associated with this prediction
+      attr_reader :direction
+      # @return [String] The headsign of the bus (final destination, *not* expressed as {CTA::Stop})
+      attr_reader :headsign
+      # @return [DateTime] The time this {Prediction} was generated on the BusTime servers
+      attr_reader :prediction_generated_at
+      # @return [DateTime] The time this bus is predicted to arrive or depart
+      attr_reader :arrival_time
+      # @return [true, false] True if this bus is considered to be delayed
+      attr_reader :delayed
+      # @return [Integer] The number of minutes until this bus arrives or departs
+      attr_reader :minutes
+      # @return [Integer] The number of seconds until this bus arrives or departs
+      attr_reader :seconds
 
       def initialize(data)
         @type = data["typ"]
@@ -34,7 +113,7 @@ module CTA
         @distance = data["dstp"].to_i
         @route = CTA::Route.where(:route_id => data["rt"]).first
         @direction = CTA::BusTracker::Direction.new(data["rtdir"])
-        @destination = data["des"]
+        @headsign = data["des"]
         @prediction_generated_at = DateTime.parse(data["tmstmp"])
         @arrival_time = DateTime.parse(data["prdtm"])
         @seconds = @arrival_time.to_time - @prediction_generated_at.to_time

data/lib/cta_redux/models/calendar.rb

@@ -1,7 +1,35 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#calendar_txt___Field_Definitions calendar.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:service_id, :monday, :tuesday, :wednesday, :thursday, :friday, :saturday, :sunday, :start_date, :end_date]
   class Calendar < Sequel::Model(:calendar)
     set_primary_key :service_id
 
+    # @!method service_id
+    #   @return [String]
+    # @!method monday
+    #   @return [true,false]
+    # @!method tuesday
+    #   @return [true,false]
+    # @!method wednesday
+    #   @return [true,false]
+    # @!method thursday
+    #   @return [true,false]
+    # @!method friday
+    #   @return [true,false]
+    # @!method saturday
+    #   @return [true,false]
+    # @!method sunday
+    #   @return [true,false]
+    # @!method start_date
+    #   @return [Date]
+    # @!method end_date
+    #   @return [Date]
+
+    # @!method trips
+    #   A {CTA::Calendar} defines a time period during which multiple {CTA::Trip}s may or may not be active.
+    #   @return [Array<CTA::Trip>] All trips associated with this service
     one_to_many :trips, :key => :service_id
   end
 end

data/lib/cta_redux/models/route.rb

@@ -1,9 +1,50 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#routes_txt___Field_Definitions routes.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:route_id, :route_short_name, :route_long_name, :route_type, :route_url, :route_color, :route_text_color]
   class Route < Sequel::Model
+    # @return [Live] the {Live} data associated with this {CTA::Route}, if available.
+    # @note a {CTA::Route} will only contain live data when augmented with an {API::Response}
+    attr_accessor :live
     set_primary_key :route_id
 
+    # @!method trips
+    #   A {CTA::Route} may be associated with multiple trips ("runs").
+    #   @return [Array<CTA::Trip>] All trips associated with this route
     one_to_many :trips, :key => :route_id
 
+    # @!method route_id
+    #  @return [String]
+    # @!method route_short_name
+    #  @return [String]
+    # @!method route_long_name
+    #  @return [String]
+    # @!method route_type
+    #  @return [Integer]
+    # @!method route_url
+    #  @return [String]
+    # @!method route_color
+    #  @return [String]
+    # @!method route_text_color
+    #  @return [String]
+    alias_method :id, :route_id
+    alias_method :name, :route_short_name
+    alias_method :short_name, :route_short_name
+    alias_method :long_name, :route_long_name
+    alias_method :type, :route_type
+    alias_method :url, :route_url
+    alias_method :color, :route_color
+    alias_method :text_color, :route_text_color
+
+    # Overrides the default "find by primary key" method in {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+    # Allows you to specify a human-friendly {CTA::Train} name. If you supply something that doesn't look like an "L" route, it's passed
+    # to the default [] method on Sequel::Model.
+    # @return [CTA::Route] The route requested
+    # @example
+    #   CTA::Route[:brown] #=> equivalent to calling CTA::Route["Brn"]
+    #   CTA::Route["Brown"] #=> equivalent to calling CTA::Route["Brn"]
+    #   CTA::Route["8"] #=> equivalent to calling CTA::Route["8"]
     def self.[](*args)
       potential_route = args.first.downcase.to_sym
       if CTA::Train::FRIENDLY_L_ROUTES.has_key?(potential_route)
@@ -13,8 +54,13 @@ module CTA
       end
     end
 
+    # Returns a {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Dataset.html Sequel::Dataset} that corresponds to stops associated
+    # with this {CTA::Route}
+    # @return [Sequel::Dataset]
+    # @example
+    #   CTA::Route["brown"].stops.first #=> #<CTA::Stop...
+    #   CTA::Route["brown"].stops.all   #=> [#<CTA::Stop..., #<CTA::Stop...]
     def stops
-      # Gosh, I wish SQLite could do "SELECT DISTINCT ON..."
       CTA::Stop.with_sql(<<-SQL)
         SELECT s.*
         FROM stops s
@@ -27,14 +73,9 @@ module CTA
       SQL
     end
 
-    def live!(vehicles)
-      class << self
-        attr_reader :vehicles
-      end
-
-      @vehicles = vehicles
-    end
-
+    # Returns predictions for this specific {CTA::Route}. Accepts all optiosn of either
+    # {CTA::BusTracker.predictions!} or {CTA::TrainTracker.predictions!}, depending on the type of this {CTA::Route}
+    # @return [CTA::BusTracker::PredictionsResponse, CTA::TrainTracker::ArrivalsResponse]
     def predictions!(options = {})
       if CTA::Train::L_ROUTES.keys.include?(self.route_id.downcase)
         CTA::TrainTracker.predictions!(options.merge({:route => self.route_id.downcase}))
@@ -43,6 +84,14 @@ module CTA
       end
     end
 
+    # Returns the position and next station of all trains in service for this route.
+    # @note Raises an exception when called on a {CTA::Bus} route, because the BusTracker API has nothing like the
+    #  TrainTracker locations call
+    # @param [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes for which to return positions
+    # @return [CTA::TrainTracker::LocationsResponse]
+    # @example
+    #    locations!(:route => [:red, :blue])
     def locations!(options = {})
       if CTA::Train::L_ROUTES.keys.include?(self.route_id.downcase)
         CTA::TrainTracker.locations!(options.merge({:routes => self.route_id.downcase}))
@@ -51,12 +100,25 @@ module CTA
       end
     end
 
+    # Returns an overview of system status for this route
+    # @return [CTA::CustomerAlerts::RouteStatusResponse]
     def status!
       CTA::CustomerAlerts.status!(:routes => self.route_id).routes.first
     end
 
+    # Returns alerts for this route
+    # @return [CTA::CustomerAlerts::AlertsResponse]
     def alerts!
       CTA::CustomerAlerts.alerts!(:route => self.route_id).alerts
     end
+
+    class Live
+      # @return [Array<CTA::Bus>, Array<CTA::Train>] The live vehicles associated with this route
+      attr_reader :vehicles
+
+      def initialize(vehicles)
+        @vehicles = vehicles
+      end
+    end
   end
 end

data/lib/cta_redux/models/shape.rb

@@ -1,4 +1,24 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#shapes_txt___Field_Definitions routes.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:shape_id, :shape_pt_lat, :shape_pt_lon, :shape_pt_sequence, :shape_dist_traveled]
   class Shape < Sequel::Model
+    # @!method shape_id
+    #  @return [Integer]
+    # @!method shape_pt_lat
+    #  @return [Float]
+    # @!method shape_pt_lon
+    #  @return [Float]
+    # @!method shape_pt_sequence
+    #  @return [Integer]
+    # @!method shape_dist_traveled
+    #  @return [Integer]
+    alias_method :id, :shape_id
+    alias_method :lat, :shape_pt_lat
+    alias_method :lon, :shape_pt_lon
+    alias_method :sequence, :shape_pt_sequence
+    alias_method :distance, :shape_dist_traveled
+    alias_method :distance_traveled, :shape_dist_traveled
   end
 end

data/lib/cta_redux/models/stop.rb

@@ -1,15 +1,71 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#stops_txt___Field_Definitions stops.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:stop_id, :stop_code, :stop_name, :stop_desc, :stop_lat, :stop_lon, :location_type, :parent_station, :wheelchair_boarding]
   class Stop < Sequel::Model
     set_primary_key :stop_id
 
+    # @!method child_stops
+    #   Stops can have a hierarchical relationship. The CTA designates certain stops as "parent stops" which contain "child stops"
+    #   A great example of this is an 'L' station - the station itself will be a parent stop, but each platform will be a child stop.
+    #   @return [Array<CTA::Stop>] Child {CTA::Stop}s of this stop
     one_to_many :child_stops, :class => self, :key => :parent_station
+    # @!method parent_stop
+    #   Stops can have a hierarchical relationship. The CTA designates certain stops as "parent stops" which contain "child stops"
+    #   A great example of this is an 'L' station - the station itself will be a parent stop, but each platform will be a child stop.
+    #   @return [CTA::Stop] Parent {CTA::Stop} of this stop
     many_to_one :parent_stop, :class => self, :key => :parent_station
 
+    # @!method transfers_from
+    #   GTFS defines a {CTA::Transfer} object, that describes where customers may transfer lines.
+    #   This method defines which {CTA::Stop} customers may transfer *from* at this {CTA::Stop}.
+    #   By then introspecting on {CTA::Route}s attached to these stops, you can find the transfer points between routes at this stop.
+    #   @return [Array<CTA::Stop>] All {CTA::Stop}s from which a customer may transfer at this stop
     one_to_many :transfers_from, :class => 'CTA::Transfer', :key => :from_stop_id
+    # @!method transfers_to
+    #   GTFS defines a {CTA::Transfer} object, that describes where customers may transfer lines.
+    #   This method defines which {CTA::Stop} customers may transfer *to* at {CTA::Stop}.
+    #   By then introspecting on {CTA::Route}s attached to these stops, you can find the transfer points between routes at this stop.
+    #   @return [Array<CTA::Stop>] All {CTA::Stop}s to which a customer may transfer at this stop
     one_to_many :transfers_to, :class => 'CTA::Transfer', :key => :to_stop_id
 
+    # @!method trips
+    #   A {CTA::Route} may be related to many trips, through {CTA::StopTime} objects
+    #   @return [Array<CTA::Trip>] The trips that will at some point use this {CTA::Stop}
     many_to_many :trips, :left_key => :stop_id, :right_key => :trip_id, :join_table => :stop_times
 
+    # @!method stop_id
+    #  @return [Integer]
+    # @!method stop_code
+    #  @return [Integer]
+    # @!method stop_name
+    #  @return [String]
+    # @!method stop_desc
+    #  @return [String]
+    # @!method stop_lat
+    #  @return [Float]
+    # @!method stop_lon
+    #  @return [Float]
+    # @!method location_type
+    #  @return [Integer]
+    # @!method parent_station
+    #  @return [Integer]
+    # @!method wheelchair_boarding
+    #  @return [true, false]
+    alias_method :id, :stop_id
+    alias_method :code, :stop_code
+    alias_method :name, :stop_name
+    alias_method :description, :stop_desc
+    alias_method :lat, :stop_lat
+    alias_method :lon, :stop_lon
+
+    # Returns a {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Dataset.html Sequel::Dataset} that corresponds to all routes
+    # associated with this {CTA::Stop} at some point
+    # @return [Sequel::Dataset] All routes associated with this stop
+    # @example
+    #   CTA::Stop.first.routes.first #=> #<CTA::Route...
+    #   CTA::Stop.first.routes.all   #=> [#<CTA::Route..., #<CTA::Route...]
     def routes
       CTA::Route.with_sql(<<-SQL)
         SELECT r.*
@@ -23,6 +79,7 @@ module CTA
       SQL
     end
 
+    # Internal method.
     # Some CTA routes are seasonal, and are missing from the GTFS feed.
     # However, the API still returns that info. So, we create a dummy CTA::Stop
     # to fill in the gaps. I've emailed CTA developer support for clarification.
@@ -41,6 +98,13 @@ module CTA
       stop
     end
 
+    # The type of this stop. CTA partitions all stops on the numeric stop_id. It's unclear why the CTA does this,
+    # but the TrainTracker API seems to separate out parent stations and stations in their requests, which complicates
+    # following the GTFS spec to the letter. Additionally, because GTFS has no concept of differentiating stops based
+    # on the type of vehicle expected to service that stop, the numerical ID can also differentiate a bus stop from a rail stop.
+    # Bottom line? The CTA's APIs and GTFS itself is really confusing, and the actual reasons why this method exists
+    # are unclear. You should just be able to rely on it.
+    # @return [:bus, :rail, :parent_station]
     def stop_type
       if self.stop_id < 30000
         :bus
@@ -51,6 +115,10 @@ module CTA
       end
     end
 
+    # Returns predictions for this {CTA::Stop}. Accepts all options for {CTA::BusTracker.predictions!} or {CTA::TrainTracker.predictions!},
+    # and will merge in # it's own stop/station/parent_station ID as needed.
+    # @params [Hash] options
+    # @return [CTA::BusTracker::PredictionsResponse, CTA::TrainTracker::ArrivalsResponse]
     def predictions!(options = {})
       if self.stop_type == :bus
         CTA::BusTracker.predictions!(options.merge({:stops => self.stop_id}))