routing 0.0.2

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.navteq_host
+.yardoc
+.rspec
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+**/.DS_Store
+.DS_Store

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gemspec
+
+gem "awesome_print"
+gem "yard"
+gem "redcarpet"
+gem "guard-rspec"

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2, :all_on_start => true, :all_after_pass => true  do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 flinc AG
+
+MIT License
+
+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/README.md

@@ -0,0 +1,54 @@
+# Routing
+
+Provides a generic interface for routing services that can by used to calculate directions between geolocations.
+
+It aims to make parsing and use-case specific data handling easy trough an extendable middleware stack (think of rack middleware for your routing service).
+
+## Usage
+
+```ruby
+start = Routing::GeoPoint.new(:lat => 49, :lng => 9)
+destination = Routing::GeoPoint.new(:lat => 48, :lng => 8.9)
+
+route = Routing.new.calculate(start, destination)
+```
+
+### Middleware
+
+```ruby
+routing = Routing.new do |r|
+  r.use MyMiddleware.new
+  r.use MyRoutingCache.new
+end
+
+route = routing.calculate(start, destination)
+```
+
+### Custom Adapters
+
+```ruby
+routing = Routing.new(MyAdapter.new)
+route = routing.calculate(start, destination)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'routing'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install routing
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new('spec')
+
+YARD::Rake::YardocTask.new
+
+task :default => :spec

data/lib/routing.rb

@@ -0,0 +1,77 @@
+require "routing/version"
+
+# The {Routing} class is the main entry point for the library.
+class Routing
+
+  autoload :Adapter,    "routing/adapter"
+  autoload :GeoPoint,   "routing/geo_point"
+  autoload :Middleware, "routing/middleware"
+  autoload :Parser,     "routing/parser"
+
+  class << self
+
+    # Sets the default adapter/routing service.
+    #
+    # @return [Object] Default adapter.
+    attr_writer :default_adapter
+
+    # The default adapter/routing service that is used, if no one is specified.
+    # Currently this is {Routing::Adapter::Navteq}.
+    #
+    # @return [Object] Current default adapter.
+    def default_adapter
+      @default_adapter ||= Routing::Adapter::Navteq.new
+    end
+
+  end
+
+  attr_accessor :middlewares
+
+  # Creates a new instance of the routing class
+  #
+  # @param [Object] adapter Adapter for the routing service that should be used, defaults to {Routing::Adapter::Navteq}.
+  def initialize(adapter = self.class.default_adapter)
+    @adapter = adapter
+    @middlewares = []
+
+    yield(self) if block_given?
+  end
+
+  # Calculates a route for the passed {GeoPoint}s.
+  # These will be passed through the middleware stack and will
+  # finally be given to the configured adapter which calculates a route out of it.
+  #
+  # @param [Array<GeoPoint>] geo_points
+  #   An array of geo points to calculate a route of.
+  #
+  # @return [Array<GeoPoint>]
+  #   An array of geo points that represent the calculated route.
+  def calculate(*geo_points)
+    calculate_with_stack(geo_points.flatten, middlewares + [@adapter])
+  end
+
+  # Adds an object to the middleware stack.
+  #
+  # @param [Routing::Middleware] middleware The middleware to append to the stack.
+  #
+  # @return [Array<Routing::Middleware>] Updated list of used middlewares.
+  def use(middleware)
+    @middlewares << middleware
+  end
+
+  private
+
+  # Helper method that will iterate through the middleware stack.
+  #
+  # @param [Array<GeoPoint>] geo_points
+  #   The array of geo points to be passed to the middleware.
+  #
+  # @param [Routing::Middleware] stack
+  #   The remaining stack of middlewares to iterate through.
+  def calculate_with_stack(geo_points, stack)
+    stack.shift.calculate(geo_points) do |gp|
+      calculate_with_stack(gp, stack)
+    end
+  end
+
+end

data/lib/routing/adapter.rb

@@ -0,0 +1,22 @@
+class Routing
+
+  # The {Routing::Adapter} namespace holds classes that are responsible to accept an
+  # array of {Routing::GeoPoint}s and calculate a route based on these positions.
+  #
+  # Most commonly they will get the calculated route from a webservice and will create a compatible
+  # return value by using a matching {Routing::Parser}.
+  #
+  # The end-point of the middleware stack is always the chosen adapter of a {Routing} instance which has to return the
+  # calculated route in form of {Routing::GeoPoint} objects again.
+  #
+  # Creating your own adapter:
+  # To connect your own routing service, you can easily implement your own adapter.
+  # The only requirements are an instance method called *calculate* that will take an Array of {Routing::GeoPoint}s
+  # as only parameters and will return an Array of {Routing::GeoPoint}s when the calculation is done.
+  module Adapter
+
+    autoload :Navteq, "routing/adapter/navteq"
+    autoload :Test, "routing/adapter/test"
+
+  end
+end

data/lib/routing/adapter/navteq.rb

@@ -0,0 +1,83 @@
+require 'time'
+require 'faraday'
+
+class Routing
+  module Adapter
+
+    # Adapter for a NAVTEQ LBSP Routing Service v6 server.
+    # It passes the {GeoPoint}s to the routing service and will return another
+    # Array of {GeoPoint}s, representing the calculated route.
+    class Navteq
+
+      ATTR_ACCESSIBLE = [ :host, :default_params ]
+
+      def initialize(options = {})
+        options.each do |attribute, value|
+          send("#{attribute}=", value) if ATTR_ACCESSIBLE.include?(attribute)
+        end
+      end
+
+      def calculate(geo_points)
+        parse get(geo_points)
+      end
+
+      def get(geo_points)
+        params = default_params.merge geo_points_to_params(geo_points)
+
+        response = connection.get do |request|
+          request.url(service_path)
+          request.params = params
+        end
+
+        response.body
+      end
+
+      attr_writer :host
+
+      def host
+        @host
+      end
+
+      def parse(response)
+        ::Routing::Parser::NavteqSimple.new(response).to_geo_points
+      end
+
+      attr_writer :default_params
+
+      def default_params
+        @default_params || {
+          departure:          Time.now.utc.iso8601,
+          mode0:              "fastest;car",
+          language:           "de_DE",
+          legattributes:      "all,-links",
+          maneuverattributes: "position,travelTime,length,time"
+        }
+      end
+
+      protected
+
+      # The path on the server to the routing service.
+      # This is determined by the server and should not be changed.
+      #
+      # @returns [String]
+      #   Path to the routing service.
+      def service_path
+        "/routing/6.2/calculateroute.json"
+      end
+
+      def geo_points_to_params(geo_points)
+        Hash[geo_points.each_with_index.map { |point, i| [ "waypoint#{i}", "geo!#{point.lat},#{point.lng}" ] }]
+      end
+
+      def connection
+        @connection ||= Faraday.new(:url => host) do |builder|
+          builder.request  :url_encoded
+          builder.response :logger
+          builder.adapter  :net_http
+        end
+      end
+
+    end
+
+  end
+end

data/lib/routing/adapter/test.rb

@@ -0,0 +1,24 @@
+class Routing
+  module Adapter
+
+    # Simple test adapter, that returns an array of {GeoPoint}s
+    # with values which are based on the ones it recieved.
+    class Test
+
+      def calculate(geo_points)
+        geo_points.collect do |point|
+          GeoPoint.new(
+            :lat => point.lat,
+            :lng => point.lng,
+            :original_lat => point.lat,
+            :original_lng => point.lng,
+            :relative_time => 100,
+            :distance => 100,
+            :waypoint => true
+          )
+        end
+      end
+    end
+
+  end
+end

data/lib/routing/geo_point.rb

@@ -0,0 +1,34 @@
+class Routing
+
+  # A {GeoPoint} object is a very simple representation of a geospatial point
+  # that is part of a route or can be used as base to create one.
+  #
+  # It holds the most basic textual and geospatial information that is necessary
+  # to describe a section of a route.
+  #
+  # The complete roundtrip from a {Routing} object through the {Routing::Middleware} to a
+  # {Routing::Adapter} and back uses arrays of {GeoPoint} objects as arguments.
+  #
+  # Depending on your very own use-case, you can either extend the {GeoPoint} class or
+  # use another class that mimicks the behavior of {GeoPoint}.
+  # In fact, this is just a container class which is no hard requirement in general.
+  # If you decide to roll your own {Adapter}, {Parser} and maybe {Middleware},
+  # you could replace the class completely
+  class GeoPoint < Struct.new(:lat, :lng, :original_lat, :original_lng, :relative_time, :distance, :waypoint, :type)
+
+    # Creates a new GeoPoint instance.
+    #
+    # @param [Hash] attributes
+    #   Automatically sets values for the attributes that match the keys of the hash.
+    def initialize(attributes = {})
+      attributes.each do |attribute, value|
+        self[attribute] = value if members.include?(attribute)
+      end
+    end
+
+    def waypoint?
+      !!waypoint
+    end
+
+  end
+end

data/lib/routing/middleware.rb

@@ -0,0 +1,29 @@
+class Routing
+  # An abstract middleware class to illustrate how you can build your own.
+  #
+  # @abstract
+  class Middleware
+
+    # The only method your own middleware has to implement to work.
+    #
+    # @param [Array<GeoPoint>] geo_points
+    #   The array of {GeoPoint}s that should be routed.
+    #
+    # @yield [Array<GeoPoint>]
+    #   Passes the geo_points on to the next middleware in the stack.
+    #   Please note, that you _always_ have to call yield in order to make
+    #   the middleware stack proceed.
+    #
+    #   If you will return a value before yielding, you will cancel the rest of the middleware stack.
+    #
+    # @return [Array<GeoPoint>]
+    #   The array of {GeoPoint}s after they have been routed.
+    def calculate(geo_points)
+      # manipulate geo points before routing here
+      yield(geo_points) # hand control to the next middleware in the stack
+      # manipulate geo points after routing here
+    end
+
+  end
+
+end

data/lib/routing/parser.rb

@@ -0,0 +1,26 @@
+class Routing
+  # The {Routing::Parser} namespace holds classes that are used to parse the
+  # response of a specific routing service.
+  #
+  # They are used by the matching adapters {Routing::Adapter} to create the array of {Routing::GeoPoint} objects
+  # to pass into the middleware.
+  module Parser
+
+    autoload :NavteqSimple, "routing/parser/navteq_simple"
+
+    # This error is thrown by the parsers if a calculated waypoint can't be matched
+    # to one of the initial passed geo points that were routed.
+    #
+    # The reason why this is important is that most routing services have a "snap-to-route"
+    # algorithm that will manipulate the coordinates of a passed geo point by moving it to
+    # the next routeable position.
+    # A parser should be able to determine which geo point of the response belongs to which geo point of the
+    # request. Otherwise this error will be thrown.
+    class NoMatchingMappedPositionFound < StandardError
+    end
+
+    class RoutingFailed < StandardError
+    end
+
+  end
+end

data/lib/routing/parser/navteq_simple.rb

@@ -0,0 +1,112 @@
+class Routing
+  module Parser
+
+    # A very simple parser implementation for a NAVTEQ LBSP Routing Service v6.
+    # It converts the json response of the routing service to an Array of {GeoPoint}s.
+    class NavteqSimple
+
+      # Creates a new instance of the parser.
+      #
+      # @param [String] response
+      #  A json response string of a NAVTEQ routing server.
+      def initialize(response)
+        response = JSON.parse(response)
+        check_for_error(response)
+
+        @route = response["Response"]["Route"].first
+        @overall_covered_distance  = 0
+        @overall_relative_time = 0
+
+        self
+      end
+
+      # Converts the server response in an Array of {GeoPoint}s
+      #
+      # @return [Array<GeoPoint>]
+      #   List of {GeoPoint}s that represent the calculated route.
+      def to_geo_points
+        legs = @route["Leg"]
+        geo_points = legs.map { |leg| parse_leg(leg) }.flatten
+
+        # At last we add the destination point
+        geo_points << parse_maneuver(legs.last["Maneuver"].last, waypoint: true)
+        geo_points
+      end
+
+      private
+
+      # Parses is single leg of the route including all its maneuvers.
+      #
+      # @param [Hash] leg
+      #   The route leg to parse.
+      #
+      # @return [Array<GeoPoint>]
+      #   List of {GeoPoint}s that represent the passed Leg.
+      def parse_leg(leg)
+        # Skip the last maneuver as it is the same as the first one
+        # of the next maneuver.
+        # For the last leg we parse the last maneuver right at the end
+        maneuvers = leg["Maneuver"][0...-1]
+        maneuvers.map do |maneuver|
+          parse_maneuver(maneuver, :waypoint => (maneuver == maneuvers.first))
+        end
+      end
+
+      # Parses is single maneuver of a route leg.
+      #
+      # @param [Hash] maneuver
+      #   The maneuver to parse.
+      #
+      # @param [Hash] attributes
+      #   Additional attributes that should be set on the returned {GeoPoint}.
+      #
+      # @return [GeoPoint]
+      #   A {GeoPoint} that represents the passed maneuver.
+      def parse_maneuver(maneuver, attributes = {})
+        geo_point = ::Routing::GeoPoint.new attributes.merge({
+          lat: maneuver["Position"]["Latitude"],
+          lng: maneuver["Position"]["Longitude"],
+          relative_time: @overall_relative_time,
+          distance: @overall_covered_distance
+        })
+
+        @overall_relative_time += maneuver["TravelTime"].to_i
+        @overall_covered_distance += maneuver["Length"].to_i
+
+        search_original_position(geo_point) if geo_point.waypoint?
+
+        geo_point
+      end
+
+      # Matches a parsed {GeoPoint} of the route response
+      # with the (unmapped) position of the
+      # corresponding {GeoPoint} of the request.
+      #
+      # @param [GeoPoint] geo_point
+      #   Point of the response to find the initial position for.
+      #
+      # @return [GeoPoint]
+      #   The passed in {GeoPoint}, enriched with the information about the original position in the request.
+      #
+      # @raise [NoMatchingMappedPositionFound] If no matching original position is found.
+      def search_original_position(geo_point)
+        matching_waypoint = @route["Waypoint"].detect do |waypoint|
+          waypoint["MappedPosition"]["Latitude"]  == geo_point.lat && 
+          waypoint["MappedPosition"]["Longitude"] == geo_point.lng
+        end or raise NoMatchingMappedPositionFound
+
+        geo_point.original_lat = matching_waypoint["OriginalPosition"]["Latitude"]
+        geo_point.original_lng = matching_waypoint["OriginalPosition"]["Longitude"]
+
+        geo_point
+      end
+
+      def check_for_error(response)
+        if error = response['Error']
+          raise Routing::Parser::RoutingFailed.new("#{error['type']}(#{error['subtype']}) - #{error['Details']}")
+        end
+      end
+
+    end
+  end
+end