ratis 2.5.2.1

data/README.md

@@ -0,0 +1,157 @@
+# Ratis
+A Ruby wrapper for Trapeze Group's ATIS SOAP server.
+
+Goals:
+
+  - Wrap SOAP methods
+  - Provide an ActiveRecord like interface to queries
+  - Return object representations of SOAP responses
+  - Not encapulate any state (other than initial configuration)
+  - Try to catch erroneous queries before making a SOAP request
+  - Handle SOAP errors when they do occur
+  - Handle SOAP method versions changing
+
+Presently based on:
+
+**ATIS - SOAP Interface Specification Version 2.5.1, February 2012**
+
+Currently Supports Ruby `1.8.7` and `1.9.3`
+
+Gem installation
+-------------------
+  1. Ensure that an SSH identity with permission for the *authoritylabs* organisation on github is available to Bundler.
+  1. Include the gem in your Gemfile thus:
+
+        gem 'ratis', :git => 'git@github.com:authoritylabs/ratis.git'
+
+  1. Add the following (Valley Metro specific) configuration block.
+
+     This must happen before Ratis is `require`d (before `Rails::Initializer.run` in a Rails app).
+
+        require 'ratis/config'
+        Ratis.configure do |config|
+          config.endpoint = 'http://soap.valleymetro.org/cgi-bin-soap-web-new/soap.cgi'
+          config.namespace = 'PX_WEB'
+          config.proxy = 'http://localhost:8080'
+          config.timeout = 5
+        end
+
+     If Ratis is `require`d prior to this config being set you will get a `RuntimeError` informing you so.
+     If the provided `endpoint` is invalid an `ArgumentError: Invalid URL: bad URI` will be thrown, but only when a request is made.
+
+Gem usage
+-------------------
+
+### Classes
+All the classes are prefixed with `Atis`, such as:
+
+    AtisError, AtisItinerary, AtisLandmark, AtisModel, AtisNextBus, AtisRoute,...
+
+All `Atis` classes, with the exception of `AtisModel` and `AtisError` represent data structures returned by SOAP actions.
+
+If you know the SOAP action you want to use, and wish to see if it is implemented in Ratis, you can open a console and ask `AtisModel` to tell you `who_implements_soap_action`:
+
+    > AtisModel.who_implements_soap_action 'Getlandmarks'
+    => [AtisLandmark]
+
+### Queries
+By convention most provide either an `all` or `where` class method (following [Active Record's hash conditions syntax](http://guides.rubyonrails.org/active_record_querying.html#hash-conditions)), which will return an array of objects which wrap the response, e.g:
+
+    >> all_landmarks = AtisLandmark.where :type => :all
+    >> all_landmarks.count
+    => 1510
+    >> all_landmarks.first
+    => #<AtisLandmark:0x10d263190 @locality="N", @type="AIRPT", @location="4800 E. FALCON DR.", @verbose="FALCON FIELD AIRPORT">
+
+### Errors
+The `where` methods will try to sanity check your conditions before making a call to the SOAP server:
+
+    >> AtisLandmark.where({})
+    ArgumentError: You must provide a type
+
+    >> AtisLandmark.where :type => :all, :foo => 1
+    ArgumentError: Conditions not used by this class: [:foo]
+
+When something goes wrong with the SOAP transaction an `AtisError` will be raised:
+
+    >> AtisNextBus.where :stop_id => 123456
+    #<AtisError: #10222--Unknown stop>
+
+
+Development 
+-------------------
+
+### Installation
+ 1. Clone the repo
+ 1. `bundle install`
+
+### Usage
+
+ 1. For development Ratis is hard coded to use a local proxy server on port 8080:
+
+        ssh -i ~/.ssh/authoritylabs.pem -L 8080:localhost:3128 ubuntu@codingsanctum.com
+
+ 1. Run the test suite with `rake`
+ 1. Test it out with `irb -r config/valley_metro.rb -I lib/ -r rubygems -r ratis`
+
+### Extending
+
+The `AtisLandmark` class is a simple one to look at for reference, and will be referred to below:
+
+#### Testing
+
+You can see the spec for it in `spec/ratis/atis_landmark_spec.rb`, it uses helper methods defined in `spec/spec_helper.rb`:
+
+  1. `stub_atis_request` tells `Webmock` to stub a `POST` to the ATIS SOAP server, any request which hasn't been explicitly allowed will trigger an exception.
+
+  1. `atis_response` returns a string of the form returned in the body of a response from the ATIS SOAP server. It takes the SOAP action and version the response appears to be for, and a method specific response code and body.
+
+  Because the method specific response bodies are quite long, it is convenient to wrap them in a heredoc, thus:
+
+         atis_response 'Getlandmarks', '1.4', '0', <<-BODY
+           <Landmarks>
+           [snip]
+           </Landmarks>
+         BODY
+
+
+  1. `an_atis_request` returns a `Webmock` `a_request` object for a `POST` to the ATIS SOAP, which can be used like this:
+
+        an_atis_request.should have_been_made.times 1
+
+  1. `an_atis_request_for` is an `a_request` object for a specific SOAP action with specific parameters passed, which can be used like this:
+
+        an_atis_request_for('Getlandmarks', 'Type' => 'ALL').should have_been_made
+
+#### Implementing
+
+To ease interaction with the ATIS SOAP server the `AtisModel` module is available. Any class which makes requests to the server should:
+
+    require 'ratis/atis_model'
+    extend AtisModel
+
+You get the following:
+
+  1. `atis_request` should be used to make request to the ATIS SOAP server. It ensures the request is built in a way which the ATIS SOAP server expects, provides a version check against responses and returns a `Savon::Response`:
+
+        atis_request 'Getlandmarks', {'Type' => type}
+
+  The method and parameter names should be given as described by the ATIS SOAP Interface reference, with the first character uppercase and all others lowercase.
+
+  Now when a request for `Getlandmarks` is made the response's method version will be checked, and an `AtisError` will be thrown if it has not been declared. This ensures that a change on the SOAP server will not result in invalid response parsing by Ratis.
+
+  1. `all_conditions_used?` will raise an `ArgumentError` if the given hash is not empty. 
+
+  Convention in Ratis is to provide a `self.where(conditions)` method (following [Active Record's hash conditions syntax](http://guides.rubyonrails.org/active_record_querying.html#hash-conditions)). As each key in `conditions` is used it can be  `delete`d from `conditions`, then `all_conditions_used? conditions` can be called to ensure nothing unimplemented was passed to `where`.
+
+  It is also wise to raise an `ArgumentError` if an argument which is required isn't present in `conditions`.
+
+  Putting these steps together you get the following pattern:
+
+        type = conditions.delete(:type).to_s.upcase
+        raise ArgumentError.new('You must provide a type') if type.blank?
+        all_conditions_used? conditions
+
+  Following this pattern will provide a good deal of safety for someone using `where`, and eliminate potentially confusing SOAP errors.
+
+  1. `valid_latitude?` and `valid_longitude?` do range checks.

data/lib/ratis.rb

@@ -0,0 +1,49 @@
+require 'savon'
+
+require 'ratis/config'
+require 'ratis/core_ext'
+require 'ratis/closest_stop'
+require 'ratis/errors'
+require 'ratis/itinerary'
+require 'ratis/landmark'
+require 'ratis/landmark_category'
+require 'ratis/location'
+require 'ratis/next_bus'
+require 'ratis/point_2_point'
+require 'ratis/request'
+require 'ratis/route'
+require 'ratis/route_stops'
+require 'ratis/schedule'
+require 'ratis/schedule_group'
+require 'ratis/schedule_nearby'
+require 'ratis/schedule_trip'
+require 'ratis/service'
+require 'ratis/stop'
+require 'ratis/timetable'
+require 'ratis/walk'
+
+module Ratis
+
+  extend self
+
+  def configure
+    yield config
+  end
+
+  def config
+    @config ||= Config.new
+  end
+
+  def valid_latitude?(lat)
+    -90.0 <= lat.to_f and lat.to_f <= 90.0
+  end
+
+  def valid_longitude?(lon)
+    -180.0 <= lon.to_f and lon.to_f <= 180.0
+  end
+
+  def all_conditions_used?(conditions)
+    raise ArgumentError.new("Conditions not used by this class: #{conditions.keys.inspect}") unless conditions.empty?
+  end
+
+end

data/lib/ratis/closest_stop.rb

@@ -0,0 +1,43 @@
+module Ratis
+
+  class ClosestStop
+
+    def self.where(conditions)
+      latitude = conditions.delete :latitude
+      longitude = conditions.delete :longitude
+      location_text = conditions.delete :location_text
+      num_stops = conditions.delete :num_stops
+
+      raise ArgumentError.new('You must provide a longitude') unless longitude
+      raise ArgumentError.new('You must provide a latitude') unless latitude
+
+      Ratis.all_conditions_used? conditions
+
+      response = Request.get 'Closeststop',
+        {'Locationlat' => latitude, 'Locationlong' => longitude, 'Locationtext' => location_text, 'Numstops' => num_stops}
+
+      return [] unless response.success?
+
+      stops = response.to_hash[:closeststop_response][:stops][:stop].map do |s|
+        next if s[:description].blank?
+
+        stop = Stop.new
+        stop.walk_dist = s[:walkdist]
+        stop.description = s[:description]
+        stop.stop_id = s[:stopid]
+        stop.atis_stop_id = s[:atisstopid]
+        stop.latitude = s[:lat]
+        stop.longitude = s[:long]
+        stop.walk_dir = s[:walkdir]
+        stop.side = s[:side]
+        stop.heading = s[:heading]
+        stop.stop_position = s[:stopposition]
+        stop.route_dir = s[:routedirs][:routedir]
+        stop
+      end
+      stops.compact
+    end
+
+  end
+
+end

data/lib/ratis/config.rb

@@ -0,0 +1,21 @@
+module Ratis
+
+  class Config
+
+    attr_accessor :endpoint, :namespace, :proxy, :timeout
+
+    def valid?
+      return false if endpoint.nil? or namespace.nil?
+      return false if endpoint.empty? or namespace.empty?
+      true
+    end
+
+  private
+
+    def initialize
+      @timeout = 5
+    end
+
+  end
+
+end

data/lib/ratis/core_ext.rb

@@ -0,0 +1,35 @@
+class Hash
+
+  # Traverses the Hash for a given +path+ of Hash keys and returns
+  # the value as an Array. Defaults to return an empty Array in case the path does not
+  # exist or returns nil.
+  # Copied from Savon::SOAP::Response#to_array
+  def to_array(*path)
+    result = path.inject(self) do |memo, key|
+      return [] unless memo[key]
+      memo[key]
+    end
+
+    [result].compact.flatten(1)
+  end
+
+end
+
+class TrueClass
+  def y_or_n
+    'y'
+  end
+end
+
+class FalseClass
+  def y_or_n
+    'n'
+  end
+end
+
+class String
+  def y_or_n
+    raise ArgumentError.new 'Expecting y or n' unless ['y', 'n'].include? self.downcase
+    self
+  end
+end

data/lib/ratis/errors.rb

@@ -0,0 +1,70 @@
+module Ratis
+
+  class Error < StandardError
+
+    attr_accessor :fault_code, :fault_string
+
+    def initialize(savon_soap_fault = nil)
+      return if savon_soap_fault.nil? or savon_soap_fault.blank?
+      fault             = savon_soap_fault.to_hash[:fault]
+      code              = fault[:faultcode].scan(/\d+/).first
+      self.fault_code   = code.to_i if code
+      self.fault_string = fault[:faultstring]
+    end
+
+    def self.version_mismatch(method, version)
+      error = Errors.new
+      error.fault_string = "Unimplemented SOAP method #{ method } #{ version }"
+      error
+    end
+
+    def to_s
+      fault_string
+    end
+
+    def verbose_fault_string
+      case fault_string
+      when /10222|invalid Stopid/i
+        'Invalid STOP ID number. Please enter a valid five digit stop ID number'
+      when /20003|20046/
+        'No stops were found within the walking distance of the origin you specified'
+      when /20004|20047/
+        'No stops were found within the walking distance of the destination you specified'
+      when /20048/
+        'No stops were found within the walking distance of the destination or origin you specified'
+      when /20005/
+        'There is no service at this stop on the date and time specified'
+      when /20006/
+        'No services run at the date or time specified for your destination'
+      when /20007/
+        'No trips were found matching the criteria you specified'
+      when /20008/
+        'No services run at the date or time specified'
+      when /11085/
+        'Origin is within trivial distance of the destination'
+      when /15034/
+        'No runs available for the stop and times provided'
+      when /1007|no runs available/i
+        'There is no service at this stop on the date and time specified'
+      when /15035/
+        'The route you specified does not serve this stop at the date and time specified'
+      when /invalid Window|15030/i
+        'The minimum time range is one hour. Please adjust the start and/or end time and try again.'
+      when /invalid Location|20024/i
+        'Either the origin or destination could not be recognized by the server'
+      when /out of range/i
+        'The date you entered was out of range - please choose a valid date'
+      else
+        'The server could not handle your request at this time. Please try again later'
+      end
+    end
+  end
+
+  module Errors
+
+    class ConfigError < Error; end
+    class SoapError   < Error; end
+
+  end
+
+end

data/lib/ratis/itinerary.rb

@@ -0,0 +1,55 @@
+module Ratis
+
+  class Itinerary
+
+    attr_accessor :co2_auto, :co2_transit
+    attr_accessor :final_walk_dir, :legs
+    attr_accessor :reduced_fare, :regular_fare
+    attr_accessor :transit_time
+
+    def self.where(conditions)
+      date = conditions.delete :date
+      time = conditions.delete :time
+      minimize = conditions.delete(:minimize).to_s.upcase
+
+      origin_lat = conditions.delete(:origin_lat).to_f
+      origin_long = conditions.delete(:origin_long).to_f
+      destination_lat = conditions.delete(:destination_lat).to_f
+      destination_long = conditions.delete(:destination_long).to_f
+
+      raise ArgumentError.new('You must provide a date DD/MM/YYYY') unless DateTime.strptime(date, '%d/%m/%Y') rescue false
+      raise ArgumentError.new('You must provide a time as 24-hour HHMM') unless DateTime.strptime(time, '%H%M') rescue false
+      raise ArgumentError.new('You must provide a conditions of T|X|W to minimize') unless ['T', 'X', 'W'].include? minimize
+
+      raise ArgumentError.new('You must provide an origin latitude') unless Ratis.valid_latitude? origin_lat
+      raise ArgumentError.new('You must provide an origin longitude') unless Ratis.valid_longitude? origin_long
+      raise ArgumentError.new('You must provide an destination latitude') unless Ratis.valid_latitude? destination_lat
+      raise ArgumentError.new('You must provide an destination longitude') unless Ratis.valid_longitude? destination_long
+
+      Ratis.all_conditions_used? conditions
+
+      response = Request.get 'Plantrip',
+        'Date' => date, 'Time' => time, 'Minimize' => minimize,
+        'Originlat' => origin_lat, 'Originlong' => origin_long,
+        'Destinationlat' => destination_lat, 'Destinationlong' => destination_long
+
+      return [] unless response.success?
+
+      response.to_array(:plantrip_response, :itin).map do |itinerary|
+        atis_itinerary = Itinerary.new
+        atis_itinerary.co2_auto = itinerary[:co2auto].to_f
+        atis_itinerary.co2_transit = itinerary[:co2transit].to_f
+        atis_itinerary.final_walk_dir = itinerary[:finalwalkdir]
+        atis_itinerary.reduced_fare = itinerary[:reducedfare].to_f
+        atis_itinerary.regular_fare = itinerary[:regularfare].to_f
+        atis_itinerary.transit_time = itinerary[:transittime].to_i
+        atis_itinerary.legs = itinerary.to_array :legs, :leg
+
+        atis_itinerary
+      end
+
+    end
+
+  end
+
+end

data/lib/ratis/landmark.rb

@@ -0,0 +1,29 @@
+module Ratis
+
+  class Landmark
+
+    attr_accessor :type, :verbose, :location, :locality
+
+    def self.where(conditions)
+
+      type = conditions.delete(:type).to_s.upcase
+      raise ArgumentError.new('You must provide a type') if type.blank?
+      Ratis.all_conditions_used? conditions
+
+      response = Request.get 'Getlandmarks', {'Type' => type}
+      return [] unless response.success?
+
+      response.to_array(:getlandmarks_response, :landmarks, :landmark).map do |landmark|
+        atis_landmark = Landmark.new
+        atis_landmark.type = landmark[:type]
+        atis_landmark.verbose = landmark[:verbose]
+        atis_landmark.location = landmark[:location]
+        atis_landmark.locality = landmark[:locality]
+        atis_landmark
+      end
+
+    end
+
+  end
+
+end