bart_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: acf48065dee6a232f3d2696dd6ce3de6e6a28f95
+  data.tar.gz: 1d4aee5fe2c759ff55845523aa4acddd1b0344c9
+SHA512:
+  metadata.gz: 8229a8062b76851b6fd7a677a5f544d930a55667b5d8819ae399a181bc71d79593cf0d2299a959298de762838a3683cb2ae16d3c99693e0443e4bda8a6b37955
+  data.tar.gz: 5d0c905ef5ba65d12804295e19f3a3dbf2af8d00e0392ddb0635ebd966b0c3d2f60d7236c7967bd43043914494106c6011fce9a86615fa68ba38b3cb36cf7bb3

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Jon Egeland
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/bart_api/api.rb

@@ -0,0 +1,52 @@
+require 'memoist'
+
+module Bart
+  # A base class implementing common API operations
+  class API
+    include Connection
+
+    class << self
+      extend Memoist
+
+      # Include another API's functionality via a new method on this API.
+      # For example, `include_api :routes` would include the "Routes" API into
+      # the "Client" API, accessible as `Client#routes`.
+      def include_api name
+        klass = self.const_get(name.to_s.constantize)
+        define_method(name) do
+          klass.new
+        end
+        self.memoize name
+      end
+
+      # Require all the files given in `names` that exist in the given folder
+      def require_all folder, *libs
+        libs.each do |lib|
+          require_relative "#{File.join(folder, lib)}"
+        end
+      end
+
+      # Return a singleton instance of this API
+      def singleton
+        @singleton ||= self.new
+      end
+    end
+
+
+    # Perform a GET request over the connection to the given endpoint.
+    def get_request endpoint, opts={}, &block
+      connection.get endpoint, opts, &block
+    end
+
+    # Perform a POST request over the connection to the given endpoint.
+    def post_request endpoint, opts={}, &block
+      connection.post endpoint, opts, &block
+    end
+
+    # For APIs that extend Memoist, allow the user to call `refresh` as an
+    # alias for `flush_cache`.
+    def refresh
+      send(:flush_cache) if respond_to?(:flush_cache)
+    end
+  end
+end

data/lib/bart_api/client/estimates.rb

@@ -0,0 +1,38 @@
+module Bart
+  class Client::Estimates < API
+    RESOLUTION = 30 # seconds
+
+    def key stop_id, platform, direction
+      [stop_id, platform, direction]
+    end
+
+    # We need to memoize but never for longer than `RESOLUTION`, so rather than
+    # use Memoist this API maintains its own memo.
+    def get stop_id, platform: nil, direction: nil
+      @memo ||= {}
+      model, stored_at = @memo[[stop_id, platform, direction]]
+      return model if stored_at && 
+        Time.now - Bart.configuration.refresh_time < stored_at
+
+      parsed = get_request '/api/etd.aspx', query: { 
+        cmd: :etd, 
+        orig: stop_id,
+        plat: platform,
+        dir: direction
+      }.select { |_,v| v != nil }
+
+      parsed['root']['station'].tap do |station|
+        station['etd'] = [station['etd']].flatten
+        station['etd'].each do |etd|
+          etd['estimate'] = [etd['estimate']].flatten
+        end
+      end
+
+      model = Stop.new parsed['root']['station']
+      @memo[[stop_id, platform, direction]] = [model, Time.now]
+      model
+    end
+    alias_method :find, :get
+
+  end
+end

data/lib/bart_api/client/routes.rb

@@ -0,0 +1,21 @@
+module Bart
+  class Client::Routes < API
+    extend Memoist
+
+    # Return a list of all routes on the system.
+    def list
+      parsed = get_request '/api/route.aspx', query: { cmd: :routes }
+      parsed['root']['routes']['route'].map { |route| Route.new route }
+    end
+    memoize :list
+    alias_method :all, :list
+
+    # Return the route whose id matches the given id
+    def get id
+      parsed = get_request '/api/route.aspx', query: { cmd: :routeinfo, route: id }
+      Route.new parsed['root']['routes']['route']
+    end
+    memoize :get
+    alias_method :find, :get
+  end
+end

data/lib/bart_api/client/stops.rb

@@ -0,0 +1,21 @@
+module Bart
+  class Client::Stops < API
+    extend Memoist
+
+    # Return a list of all stops on the system.
+    def list
+      parsed = get_request '/api/stn.aspx', query: { cmd: :stns }
+      parsed['root']['stations']['station'].map { |stop| Stop.new stop }
+    end
+    memoize :list
+    alias_method :all, :list
+
+    # Return the route whose id matches the given id
+    def get id
+      parsed = get_request '/api/stn.aspx', query: { cmd: :stninfo, orig: id }
+      Stop.new parsed['root']['stations']['station']
+    end
+    memoize :get
+    alias_method :find, :get
+  end
+end

data/lib/bart_api/client.rb

@@ -0,0 +1,14 @@
+require 'memoist'
+
+module Bart
+  class Client < API
+    extend Memoist
+
+    require_all 'client', 'routes', 'stops', 'estimates'
+
+    include_api :routes
+    include_api :stops
+    include_api :estimates
+  end
+end
+

data/lib/bart_api/configuration.rb

@@ -0,0 +1,49 @@
+module Bart
+  class Configuration
+    # The version of the BART system
+    attr_accessor :version
+    # The base URL of the BART system
+    attr_accessor :base_uri
+    # The adapter to use for network communication
+    attr_accessor :adapter
+    # The output stream to which debug information should be written
+    attr_accessor :debug_output
+    # The key used to make requests, defaulting to BART's public key.
+    attr_accessor :api_key
+    # The number of seconds real-time results are cached for.
+    attr_accessor :refresh_time
+
+    # The defaults to use for any configuration options that are not provided
+    DEFAULT_CONFIGURATION = {
+      adapter: :httparty,
+      debug_output: false,
+      base_uri: 'http://api.bart.gov',
+      refresh_time: 30,
+      api_key: 'MW9S-E7SL-26DU-VV8V'
+    }
+
+    # The options required when configuring a BART instance
+    REQUIRED_CONFIGURATION = [
+      :base_uri,
+      :api_key,
+      :refresh_time
+    ]
+
+    def initialize
+      # Apply the default set of configurations before anything else to ensure
+      # all options are initialized.
+      DEFAULT_CONFIGURATION.each do |name, value|
+        send("#{name}=", value)
+      end
+    end
+
+    # Ensure that all required configurations have been given a value. Returns
+    # true if all required configuration options have been set.
+    def validate!
+      REQUIRED_CONFIGURATION.each do |name|
+        raise "`#{name}` is a required configuration option, but was not given a value." if send("#{name}").nil?
+      end
+      true
+    end
+  end
+end

data/lib/bart_api/connection.rb

@@ -0,0 +1,23 @@
+module Bart
+  module Connection
+    extend self
+
+    # Return the connection adapter instance
+    def connection
+      @connection ||= adapter.new(Bart.configuration)
+    end
+
+    # Return the class of the adapter to use for the connection
+    def adapter
+      @@adapters[Bart.configuration.adapter]
+    end
+
+    # Register a new class that can be used as a connection adapter
+    def register_adapter name, klass
+      (@@adapters ||= {})[name] = klass
+    end
+  end
+end
+
+# Include the adapters that come packaged with the gem
+require_relative 'connection_adapters/httparty_adapter.rb'

data/lib/bart_api/connection_adapters/httparty_adapter.rb

@@ -0,0 +1,35 @@
+require 'httparty'
+require 'json'
+
+# A Connection adapter using HTTParty as the network transport
+module Bart
+  module Connection
+    class HTTPartyAdapter
+      include HTTParty
+
+      def initialize config
+        self.class.base_uri config.base_uri
+        # Write debug information to the configured output stream
+        self.class.debug_output config.debug_output
+        @config = config
+      end
+
+      def defaults
+        { 
+          query: { key: @config.api_key }
+        }
+      end
+
+      def get endpoint, opts={}, &block
+        self.class.get(endpoint, defaults.deep_merge(opts), &block).parsed_response
+      end
+
+      def post endpoint, opts={}, &block
+        self.class.post(endpoint, defaults.deep_merge(opts), &block).parsed_response
+      end
+    end
+
+    register_adapter :httparty, HTTPartyAdapter
+  end
+end
+

data/lib/bart_api/core_ext/float.rb

@@ -0,0 +1,5 @@
+class Float
+  def self.new numeric
+    numeric.to_f if numeric.respond_to? :to_f
+  end
+end

data/lib/bart_api/core_ext/hash.rb

@@ -0,0 +1,11 @@
+class Hash
+  def deep_merge hash
+    self.merge hash do |k, a, b| 
+      if a.respond_to? :merge and b.respond_to? :merge
+        a.merge b
+      else
+        b
+      end
+    end
+  end
+end

data/lib/bart_api/core_ext/integer.rb

@@ -0,0 +1,5 @@
+class Integer
+  def self.new numeric
+    numeric.to_i if numeric.respond_to? :to_i
+  end
+end

data/lib/bart_api/core_ext/string.rb

@@ -0,0 +1,21 @@
+class String
+  def underscore
+    self.dup.underscore!
+  end unless method_defined? :underscore
+
+  def underscore!
+    self.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+    self.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+    self.tr_s!('- ', '_')
+    self.downcase!
+    self
+  end unless method_defined? :underscore!
+
+  def titleize
+    self.tr_s('- ', '_').split('_').map(&:capitalize).join(' ')
+  end unless method_defined? :titleize
+
+  def constantize
+    self.tr_s('- ', '_').split('_').map(&:capitalize).join
+  end unless method_defined? :constantize
+end

data/lib/bart_api/models/arrival.rb

@@ -0,0 +1,13 @@
+module Bart
+  class Arrival < Model
+    attribute :minutes
+    attribute :platform, type: Integer
+    attribute :direction
+    attribute :length, type: Integer
+    alias_method :train_length, :length
+    attribute :color
+    attribute :hexcolor
+    attribute :bikeflag, type: Integer
+    attribute :delay, type: Integer
+  end
+end

data/lib/bart_api/models/destination.rb

@@ -0,0 +1,15 @@
+module Bart
+  class Destination < Model
+    attribute :destination
+    alias_method :name, :destination
+    attribute :abbreviation
+    alias_method :abbr, :abbreviation
+
+    attribute :limited, type: Integer
+    attribute :estimate, type: Bart::Arrival, array: true
+    alias_method :arrivals, :estimate
+
+    primary_attribute :abbr
+  end
+end
+

data/lib/bart_api/models/route.rb

@@ -0,0 +1,21 @@
+module Bart
+  class Route < Model
+    attribute :name
+    attribute :abbr
+    attribute :route_id
+    attribute :number, type: Integer
+    alias_method :id, :number
+    attribute :hexcolor
+    attribute :color
+
+    attribute :origin
+    attribute :destination
+    attribute :holidays
+    attribute :num_stns
+    attribute :direction
+    
+    attribute :config
+
+    primary_attribute :id
+  end
+end

data/lib/bart_api/models/stop.rb

@@ -0,0 +1,40 @@
+module Bart
+  class Stop < Model
+    # Identity
+    attribute :name
+    attribute :abbr
+    attribute :link
+
+    # Location
+    attribute :gtfs_latitude, type: Float
+    alias_method :latitude, :gtfs_latitude
+    attribute :gtfs_longitude, type: Float
+    alias_method :longitude, :gtfs_longitude
+    attribute :address
+    attribute :city
+    attribute :county
+    attribute :state
+    attribute :zipcode
+
+    # Associations
+    attribute :north_routes
+    attribute :south_routes
+    attribute :north_platforms
+    attribute :south_platforms
+
+    # Prose metadata
+    attribute :platform_info
+    attribute :intro
+    attribute :cross_street
+    attribute :food
+    attribute :shopping
+    attribute :attraction
+
+    # Estimates from the `etd` endpoint
+    attribute :etd, type: Bart::Destination, array: true
+    alias_method :estimates, :etd
+
+    primary_attribute :abbr
+    alias_method :id, :abbr
+  end
+end

data/lib/bart_api/models.rb

@@ -0,0 +1,89 @@
+require 'set'
+
+module Bart
+  class Model
+    extend Forwardable
+
+    class << self
+      # Define a new attribute of the model.
+      # If `type` is given, a new instance of `type` will be created whenever
+      # this attribute is assigned a value. This allows creation of nested
+      # objects from a simple Hash.
+      # If `type` is given and `array` is true, the value given to this
+      # attribute will be interpreted as an array and a new instance of `type`
+      # will be created for each entry in the array
+      # It `type` is given, and the value given to this attribute is nil, no
+      # new instance of `type` will be created. Instead, the value will remain
+      # nil, as an instance of NilClass.
+      def attribute name, type: nil, array: false
+        attributes << [name, type]
+        attr_reader name
+        # Use a custom writer method to allow typed attributes to be
+        # instantiated properly.
+        define_method "#{name}=" do |value|
+          # Only do type conversion if the type is specified and the value is
+          # not nil.
+          if type and !value.nil?
+            # Lookup is done on Bart to ensure that Model subclasses are
+            # searched first, falling back to other types (Numeric, Hash, etc.)
+            # if no Model subclass is found.
+            klass = Bart.const_get(type.to_s)
+            value = array ? value.map{ |v| klass.new(v) } : klass.new(value)
+          end
+          instance_variable_set("@#{name}", value)
+        end
+      end
+
+      # The list of attributes defined on the model
+      def attributes
+        @attributes ||= Set.new
+      end
+
+      # The attribute of the model that can be used to uniquely identify an
+      # instance from any other. The primary attribute should also be set
+      # with `attribute <name>`.
+      attr_accessor :identifier
+      def primary_attribute name
+        @identifier = name
+      end
+
+      # Define one or more delegated methods on the model, passing them to the
+      # given attribute.
+      def delegate *names, to:
+        names.each do |name|
+          def_delegator to, name
+        end
+      end
+    end
+
+    # Initialize a model instance with any given attributes assigned
+    def initialize args={}
+      assign(args)
+    end
+
+    # Mass assign a group of attributes. Attribute names will be automatically
+    # be converted to snake_case for consistency.
+    def assign args={}
+      args.each do |_name, value|
+        public_send("#{_name.underscore}=", value) if respond_to? "#{_name.underscore}="
+      end
+    end
+
+    # The value of the primary attribute on this model
+    def identifier
+      send(self.class.identifier)
+    end
+
+    # Assume that two Model objects are the same if their primary attributes
+    # have the same value
+    def == o
+      identifier == o.identifier
+    end
+  end
+end
+
+# Include all model subclasses
+require_relative 'models/route'
+require_relative 'models/arrival'
+require_relative 'models/destination'
+require_relative 'models/stop'

data/lib/bart_api/version.rb

@@ -0,0 +1,3 @@
+module Bart
+  VERSION = "1.0.0"
+end

data/lib/bart_api.rb

@@ -0,0 +1,35 @@
+require_relative 'bart_api/core_ext/string'
+require_relative 'bart_api/core_ext/hash'
+require_relative 'bart_api/core_ext/float'
+require_relative 'bart_api/core_ext/integer'
+
+require_relative 'bart_api/version'
+require_relative 'bart_api/configuration'
+require_relative 'bart_api/connection'
+require_relative 'bart_api/models'
+require_relative 'bart_api/api'
+require_relative 'bart_api/client'
+
+module Bart
+  class << self
+    # Alias for `Bart::Client.new`
+    def new
+      Client.new
+    end
+
+    # The current client configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Allow users to set configuration options via a block. By default, the
+    # configuration will be validated after the block returns. This will raise
+    # an exception if any required configurations are not provided. This
+    # behavior can be skipped by passing `validate: false` as a parameter.
+    def configure validate: true
+      yield configuration
+      configuration.validate! if validate
+      configuration
+    end
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: bart_api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Elliott Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: memoist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: A Ruby client for the BART real-time transit API.
+email: code@elliottwillia.ms
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+files:
+- LICENSE
+- lib/bart_api.rb
+- lib/bart_api/api.rb
+- lib/bart_api/client.rb
+- lib/bart_api/client/estimates.rb
+- lib/bart_api/client/routes.rb
+- lib/bart_api/client/stops.rb
+- lib/bart_api/configuration.rb
+- lib/bart_api/connection.rb
+- lib/bart_api/connection_adapters/httparty_adapter.rb
+- lib/bart_api/core_ext/float.rb
+- lib/bart_api/core_ext/hash.rb
+- lib/bart_api/core_ext/integer.rb
+- lib/bart_api/core_ext/string.rb
+- lib/bart_api/models.rb
+- lib/bart_api/models/arrival.rb
+- lib/bart_api/models/destination.rb
+- lib/bart_api/models/route.rb
+- lib/bart_api/models/stop.rb
+- lib/bart_api/version.rb
+homepage: http://github.com/propershark/bart_api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.9
+signing_key: 
+specification_version: 4
+summary: A Ruby client for the BART real-time transit API.
+test_files: []