gtfs_reader 1.0.0

data/lib/gtfs_reader/bulk_feed_handler.rb

@@ -0,0 +1,94 @@
+module GtfsReader
+  class BulkFeedHandler
+    def initialize(bulk_size, args=[], &block)
+      @bulk_size = bulk_size
+      @callbacks = {}
+      BulkFeedHandlerDsl.new(self).instance_exec *args, &block
+    end
+
+    def handler?(filename)
+      @callbacks.key? filename
+    end
+
+    def handle_file(filename, reader)
+      unless @callbacks.key? filename
+        Log.warn { "No handler registered for #{filename.to_s.red}.txt" }
+        return
+      end
+
+      calls = callbacks filename
+      calls[:before].call if calls.key? :before
+      read_row = calls[:read]
+
+      values = []
+      total = bulk_count = 0
+      cols = reader.col_names
+      reader.each do |row|
+        values << (read_row ? read_row.call(row) : row)
+        bulk_count += 1
+
+        if bulk_count == @bulk_size
+          total += bulk_count
+          calls[:bulk].call values, bulk_count, total, cols
+          bulk_count = 0
+          values = []
+        end
+      end
+
+      unless bulk_count == 0
+        calls[:bulk].call values, bulk_count, (total + bulk_count), cols
+      end
+      nil
+    end
+
+    def create_callback(kind, filename, block)
+      Log.debug do
+        kind_str = kind.to_s.center(:before.to_s.length).magenta
+        "create callback (#{kind_str}) #{filename.to_s.red}"
+      end
+      callbacks(filename)[kind] = block
+    end
+
+    def callback?(kind, filename)
+      @callbacks.key? filename and @callbacks[filename].key? kind
+    end
+
+    private
+
+    def callbacks(filename)
+      @callbacks[filename] ||= {}
+    end
+  end
+
+  class BulkFeedHandlerDsl
+    def initialize(feed_handler)
+      @feed_handler = feed_handler
+    end
+
+    def method_missing(filename, *args, &block)
+      BulkDsl.new(@feed_handler, filename).instance_exec &block
+
+      unless @feed_handler.callback? :bulk, filename
+        raise HandlerMissingError, "No bulk block for #{filename}"
+      end
+    end
+  end
+
+  class BulkDsl
+    def initialize(feed_handler, filename)
+      @feed_handler, @filename = feed_handler, filename
+    end
+
+    def before(&block)
+      @feed_handler.create_callback :before, @filename, block
+    end
+
+    def read(&block)
+      @feed_handler.create_callback :read, @filename, block
+    end
+
+    def bulk(&block)
+      @feed_handler.create_callback :bulk, @filename, block
+    end
+  end
+end

data/lib/gtfs_reader/config/column.rb

@@ -0,0 +1,60 @@
+module GtfsReader
+  module Config
+    # Defines a single column in a {FileDefinition file}.
+    class Column
+      # A "parser" which simply returns its input. Used by default
+      IDENTITY_PARSER = ->(arg) { arg }
+
+      attr_reader :name
+
+      #@param name [String] the name of the column
+      #@option opts [Boolean] :required (false) If this column is required to
+      #  appear in the given file
+      #@option opts [Boolean] :unique (false) if values in this column need to be
+      #  unique among all rows in the file.
+      def initialize(name, opts={}, &parser)
+        @name = name
+        @parser = block_given? ? parser : IDENTITY_PARSER
+
+        @opts = { required: false, unique: false }.merge ( opts || {} )
+      end
+
+      def parser(&block)
+        @parser = block if block_given?
+        @parser
+      end
+
+      #@return [Boolean] if this column is required to appear in the file
+      def required?
+        @opts[:required]
+      end
+
+      #@return [Boolean] if values in this column need to be unique among all rows
+      #  in the file.
+      def unique?
+        @opts[:unique]
+      end
+
+      #@return [Boolean]
+      def parser?
+        parser != IDENTITY_PARSER
+      end
+
+      def to_s
+        opts = @opts.map do |key,value|
+          case value
+            when true then key
+            when false,nil then nil
+            else "#{key}=#{value}"
+          end
+        end.reject &:nil?
+
+        opts << 'has_parser' if parser?
+
+        str = name.to_s
+        str << ": #{opts.join ', '}" unless opts.empty?
+        "[#{str}]"
+      end
+    end
+  end
+end

data/lib/gtfs_reader/config/defaults/gtfs_feed_definition.rb

@@ -0,0 +1,190 @@
+require_relative '../feed_definition'
+
+# This default config file creates a [FeedDefinition] that matches the one
+# specified by Google. You can use this definition in most cases. A custom
+# definition will only be required if you need to parse a feed that differs in
+# some critical way (Remember that these feeds are not always created by
+# technically-proficient people).
+# See https://developers.google.com/transit/gtfs/reference
+module GtfsReader
+  module Config
+    module Defaults
+      FEED_DEFINITION = FeedDefinition.new.tap do |feed|
+        feed.instance_exec do
+          file :agency, required: true do
+            col :agency_name,     required: true
+            col :agency_url,      required: true
+            col :agency_timezone, required: true
+            col :agency_id,                       unique: true
+            col :agency_lang
+            col :agency_phone
+            col :agency_fare_url
+          end
+
+          file :stops, required: true do
+            col :stop_id,       required: true, unique: true
+            col :stop_code
+            col :stop_name,     required: true
+            col :stop_desc
+            col :stop_lat,      required: true
+            col :stop_lon,      required: true
+            col :stop_url
+            col :stop_timezone
+            col :zone_id
+            col :location_type, &output_map( :stop, station: ?1 )
+            col :parent_station
+
+            col :wheelchair_boarding do |val|
+              if parent_station
+                case val
+                when ?2 then :no
+                when ?1 then :yes
+                else :inherit
+                end
+              else
+                case val
+                when ?2 then :no_vehicles
+                when ?1 then :some_vehicles
+                else :unknown
+                end
+              end
+            end
+          end
+
+          file :routes, required: true do
+            col :route_id,         required: true, unique: true
+            col :route_short_name, required: true
+            col :route_long_name,  required: true
+            col :route_desc
+            col :route_type,       required: true,
+                &output_map(   :unknown,
+                               tram: ?0,
+                               subway: ?1,
+                               rail: ?2,
+                               bus: ?3,
+                               ferry: ?4,
+                               cable_car: ?5,
+                               gondola: ?6,
+                               funicular: ?7 )
+            col :route_url
+            col :route_color
+            col :route_text_color
+            col :agency_id
+          end
+
+          file :trips, required: true do
+            col :trip_id,               required: true, unique: true
+            col :trip_headsign
+            col :trip_short_name
+            col :trip_long_name
+            col :route_id,              required: true
+            col :service_id,            required: true
+            col :direction_id,          &output_map( primary: ?0, opposite: ?1 )
+            col :block_id
+            col :shape_id
+            col :wheelchair_accessible, &output_map( :unknown, yes: ?1, no: ?2 )
+            col :bikes_allowed,         &output_map( :unknown, yes: ?1, no: ?2 )
+          end
+
+          file :stop_times, required: true do
+            col :trip_id,        required: true
+            col :arrival_time,   required: true
+            col :departure_time, required: true
+            col :stop_id,        required: true
+            col :stop_sequence,  required: true
+            col :stop_headsign
+
+            col :pickup_type,
+              &output_map(    :regular,
+                                  none: ?1,
+                          phone_agency: ?2,
+                coordinate_with_driver: ?3 )
+
+            col :drop_off_type,
+              &output_map(    :regular,
+                                  none: ?1,
+                          phone_agency: ?2,
+                coordinate_with_driver: ?3 )
+
+            col :shape_dist_traveled
+          end
+
+          file :calendar, required: true do
+            col :service_id, required: true, unique: true
+            col :monday,     required: true, &output_map( yes: ?1, no: ?0 )
+            col :tuesday,    required: true, &output_map( yes: ?1, no: ?0 )
+            col :wednesday,  required: true, &output_map( yes: ?1, no: ?0 )
+            col :thursday,   required: true, &output_map( yes: ?1, no: ?0 )
+            col :friday,     required: true, &output_map( yes: ?1, no: ?0 )
+            col :saturday,   required: true, &output_map( yes: ?1, no: ?0 )
+            col :sunday,     required: true, &output_map( yes: ?1, no: ?0 )
+            col :start_date
+            col :end_date
+          end
+
+          file :calendar_dates do
+            col :service_id,     required: true
+            col :date,           required: true
+            col :exception_type, required: true,
+              &output_map( added: ?1, removed: ?2 )
+          end
+
+          file :fare_attributes do
+            col :fare_id,        required: true, unique: true
+            col :price,          required: true
+            col :currency_type,  required: true
+            col :payment_method, required: true,
+              &output_map( on_board: 0, before: 1 )
+            col :transfers,      required: true,
+              &output_map( :unlimited, none: 0, once: 1, twice: 2 )
+            col :transfer_duration
+          end
+
+          file :fare_rules do
+            col :fare_id,        required: true
+            col :route_id
+            col :origin_id
+            col :destination_id
+            col :contains_id
+          end
+
+          file :shapes do
+            col :shape_id,            required: true
+            col :shape_pt_lat,        required: true
+            col :shape_pt_lon,        required: true
+            col :shape_pt_sequence,   required: true
+            col :shape_dist_traveled
+          end
+
+          file :frequencies do
+            col :trip_id,      required: true
+            col :start_time,   required: true
+            col :end_time,     required: true
+            col :headway_secs, required: true
+            col :exact_times,  &output_map( :inexact, exact: 1 )
+          end
+
+          file :transfers do
+            col :from_stop_id,      required: true
+            col :to_stop_id,        required: true
+            col :transfer_type,     required: true,
+              &output_map( :recommended,
+                         timed_transfer: 1,
+                  minimum_time_required: 2,
+                             impossible: 3 )
+            col :min_transfer_time
+          end
+
+          file :feed_info do
+            col :feed_publisher_name, required: true
+            col :feed_publisher_url,  required: true
+            col :feed_lang,           required: true
+            col :feed_start_date
+            col :feed_end_date
+            col :feed_version
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gtfs_reader/config/feed_definition.rb

@@ -0,0 +1,55 @@
+require_relative 'file_definition'
+
+module GtfsReader
+  module Config
+    # Describes a GTFS feed and the {FileDefinition files} it is expected to
+    # provide.
+    class FeedDefinition
+      def initialize
+        @file_definition = {}
+      end
+
+      #@return [Array<FileDefinition>] All of the defined files.
+      def files
+        @file_definition.values
+      end
+
+      def required_files
+        files.select &:required?
+      end
+
+      def optional_files
+        files.reject &:required?
+      end
+
+      #@overload file(name, *args, &block)
+      #  Defines a new file in the feed.
+      #
+      #  @param name [String] the name of this file within the feed. This name
+      #    should not include a file extension (like +.txt+)
+      #  @param args [Array] the first argument is used as a +Hash+ of options
+      #    to create the new file definition
+      #  @param block [Proc] this block is +instance_eval+ed on the new
+      #    {FileDefinition file}
+      #  @return [FileDefinition] the newly created file
+      #
+      #@overload file(name)
+      #  @param name [String] the name of the file to return
+      #  @return [FileDefinition] the previously created file with the given name
+      #@see FileDefinition
+      def file(name, *args, &block)
+        return @file_definition[name] unless block_given?
+
+        definition_for!( name, args.first ).tap do |d|
+          d.instance_exec &block if block
+        end
+      end
+
+      private
+
+      def definition_for!(name, opts)
+        @file_definition[name] ||= FileDefinition.new( name, opts )
+      end
+    end
+  end
+end

data/lib/gtfs_reader/config/file_definition.rb

@@ -0,0 +1,94 @@
+require_relative 'column'
+
+module GtfsReader
+  module Config
+    # Describes a single file in a {FeedDefinition GTFS feed}.
+    class FileDefinition
+      attr_reader :name
+
+      #@param name [String] The name of the file within the feed.
+      #@option opts [Boolean] :required (false)
+      #  If this file is required to be in the feed.
+      def initialize(name, opts={})
+        @name, @columns = name, {}
+        @opts = { required: false }.merge (opts || {})
+      end
+
+      #@return [Boolean] If this file is required to be in the feed.
+      def required?
+        @opts[:required]
+      end
+
+      #@return [String] The filename of this file within the GTFS feed.
+      def filename
+        "#{name}.txt"
+      end
+
+      #@return [Column] The column with the given name
+      def [](name)
+        @columns[name]
+      end
+
+      def columns
+        @columns.values
+      end
+
+      #@return [Array<Column>] The columns required to appear in this file.
+      def required_columns
+        columns.select &:required?
+      end
+
+      #@return [Array<Column>] The columns not required to appear in this file.
+      def optional_columns
+        columns.reject &:required?
+      end
+
+      #@return [Array<Column>] The columns which cannot have two rows with the
+      #  same value.
+      def unique_columns
+        columns.select &:unique?
+      end
+
+      # Creates a column with the given name.
+      #
+      #@param name [String] The name of the column to define.
+      #@param args [Array] The first element of this args list is used as a
+      #  +Hash+ of options to create the new column with.
+      #@param block [Proc] An optional block used to parse the values of this
+      #  column on each row.
+      #@yieldparam input [String] The value of this column for a particular row.
+      #@yieldreturn Any kind of object.
+      #@return [Column] The newly created column.
+      def col(name, *args, &block)
+        if @columns.key? name
+          @columns[name].parser &block if block_given?
+          return @columns[name]
+        end
+
+        @columns[name] = Column.new name, args.first, &block
+      end
+
+      # Creates an input-output proc to convert column values from one form to
+      # another.
+      #
+      # Many parser procs simply map a set of known values to another set of
+      # known values. This helper creates such a proc from a given hash and
+      # optional default.
+      #
+      #@param default [] The value to return if there is no mapping for a given
+      #  input.
+      #@param reverse_map [Hash] A map of returns values to their input values.
+      #  This is in reverse because it looks better, like a list of labels:
+      #  +{bus: 3, ferry: 4}+
+      def output_map(default=nil, reverse_map)
+        if reverse_map.values.uniq.length != reverse_map.values.length
+          raise FileDefinitionError, "Duplicate values given: #{reverse_map}"
+        end
+
+        map = default.nil? ? {} : Hash.new( default )
+        reverse_map.each { |k,v| map[v] = k }
+        map.method( :[] ).to_proc
+      end
+    end
+  end
+end