gtfs-reader 0.2.2

data/lib/gtfs_reader/config/column.rb

@@ -0,0 +1,72 @@
+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 [String] :alias an alternative name for this column. Many
+      #  column names are needlessly prefixed with their filename:
+      #  +Stop.stop_name+ could be aliased to +Stop.name+ for example.
+      #@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,
+          alias: nil
+        }.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 [String,nil] this column's name's alias, if there is one
+      def alias
+        @opts[:alias]
+      end
+
+      #@return [Boolean]
+      def parser?
+        parser != IDENTITY_PARSER
+      end
+
+      def to_s
+        opts = @opts.collect 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,208 @@
+require_relative '../feed_definition'
+
+module GtfsReader
+  module Config
+    module Defaults
+      FEED_DEFINITION = FeedDefinition.new.tap do |feed|
+        feed.instance_exec do
+          file :agency, required: true do
+            prefix :agency do
+              col :name,     required: true
+              col :url,      required: true
+              col :timezone, required: true
+              col :id,                       unique: true
+              col :lang
+              col :phone
+              col :fare_url
+            end
+          end
+
+          file :stops, required: true do
+            prefix :stop do
+              col :id,       required: true, unique: true
+              col :code
+              col :name,     required: true
+              col :desc
+              col :lat,      required: true
+              col :lon,      required: true
+              col :url
+              col :timezone
+            end
+
+            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
+            prefix :route do
+              col :id,         required: true, unique: true
+              col :short_name, required: true
+              col :long_name,  required: true
+              col :desc
+              col :type,       required: true,
+                &output_map(   :unknown,
+                                   tram: ?0,
+                                 subway: ?1,
+                                   rail: ?2,
+                                    bus: ?3,
+                                  ferry: ?4,
+                              cable_car: ?5,
+                                gondola: ?6,
+                              funicular: ?7 )
+              col :url
+              col :color
+              col :text_color
+            end
+
+            col :agency_id
+          end
+
+          file :trips, required: true do
+            prefix :trip do
+              col :id,         required: true, unique: true
+              col :headsign
+              col :short_name
+              col :long_name
+            end
+
+            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
+
+            prefix :stop do
+              col :id,       required: true
+              col :sequence, required: true
+              col :headsign
+            end
+
+            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
+            prefix :shape do
+              col :id,            required: true
+              col :pt_lat,        required: true
+              col :pt_lon,        required: true
+              col :pt_sequence,   required: true
+              col :dist_traveled
+            end
+          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
+            prefix :scope do
+              col :publisher_name, required: true
+              col :publisher_url,  required: true
+              col :lang,           required: true
+              col :start_date
+              col :end_date
+              col :version
+            end
+          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,111 @@
+require_relative 'column'
+require_relative 'prefixed_column_setter'
+
+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 || {})
+        @aliases = {}
+      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)
+        name = @aliases[name] if @aliases.key? name
+
+        if @columns.key? name
+          @columns[name].parser &block if block_given?
+          return @columns[name]
+        end
+
+        (@columns[name] = Column.new name, args.first, &block).tap do |col|
+          @aliases[col.alias] = name if col.alias
+        end
+      end
+
+      # Starts a new block within which any defined columns will have the given
+      # +sym+ prefixed to its name (joined with an underscore). Also, the
+      # defined name given within the block will be aliased to the column.
+      #@param sym the prefix to prefixed to each column within the block
+      #
+      #@example Create a column +route_name+ with the alias +name+
+      #  prefix( :route ) { name }
+      def prefix(sym, &blk)
+        PrefixedColumnSetter.new(self, sym.to_s).instance_exec &blk
+      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