ldbws 1.0.0

data/lib/ldbws/request/get_service_details.rb

@@ -0,0 +1,29 @@
+require "ldbws/request/base"
+
+require "ldbws/response_types/service_details"
+
+module Ldbws::Request
+  # Returns details about a particular service. Corresponds to +GetServiceDetailsResponse+ in the LDBWS schema.
+  #
+  # === Parameters
+  # service_id:: the ID of the service (required)
+  class GetServiceDetails < Base
+    # :nodoc:
+    SCHEMA = Dry::Schema.Params do
+      required(:service_id).filled(:string)
+    end
+
+    # :nodoc:
+    RESULT_XPATH = "GetServiceDetailsResult"
+
+    # :nodoc:
+    RESULT_TYPE = Ldbws::ResponseTypes::ServiceDetails
+
+    # :nodoc:
+    def to_soap_params
+      {
+        serviceID: @params[:service_id],
+      }
+    end
+  end
+end

data/lib/ldbws/request/get_station_board.rb

@@ -0,0 +1,60 @@
+require "ldbws/request/base"
+
+require "ldbws/response_types/station_board"
+
+module Ldbws::Request
+  # Returns an arrival or departure board for a given station. Corresponds to +GetStationBoardRequest+ in the LDBWS
+  # schema.
+  #
+  # === Parameters
+  # crs:: the CRS code for the station (required)
+  # num_rows:: the number of services to include (optional)
+  # filter_crs:: a CRS code for a station to filter arrivals from/departures to (optional)
+  # filter_type:: either ‘to’ or ‘from’ (optional)
+  # time_offset:: the offset from the current time—in minutes—to return departure information (optional).
+  # time_window:: how far into the future—relative to +:time_offset+—to return service information for (optional).
+  class GetStationBoard < Base
+    # :nodoc:
+    SCHEMA = Dry::Schema.Params do
+      required(:crs).filled(Types::Crs)
+      optional(:num_rows).filled(:integer)
+      optional(:filter_crs).filled(Types::Crs)
+      optional(:filter_type).filled(Types::FilterType)
+      optional(:time_offset).filled(:integer)
+      optional(:time_window).filled(:integer)
+    end
+
+    # :nodoc:
+    RESULT_XPATH = "GetStationBoardResult"
+
+    # :nodoc:
+    RESULT_TYPE = Ldbws::ResponseTypes::StationBoard
+
+    # :nodoc:
+    def to_soap_params
+      @params.tap do |params|
+        # CRSes should always be upcased
+        params[:crs].upcase!
+        params[:filter_crs].upcase! if params[:filter_crs]
+
+        # filter type isn’t needed if we’re not filtering
+        params.delete(:filter_type) unless params[:filter_crs]
+      end
+    end
+  end
+
+  # Returns an arrival or departure board for a given station with full service details. Corresponds to
+  # +GetStationBoardWithDetailsRequest+ in the LDBWS schema.
+  #
+  # === Parameters
+  # crs:: the CRS code for the station (required)
+  # num_rows:: the number of services to include (optional)
+  # filter_crs:: a CRS code for a station to filter arrivals from/departures to (optional)
+  # filter_type:: either ‘to’ or ‘from’ (optional)
+  # time_offset:: the offset from the current time—in minutes—to return departure information (optional).
+  # time_window:: how far into the future—relative to +:time_offset+—to return service information for (optional).
+  class GetStationBoardWithDetails < GetStationBoard
+    # :nodoc:
+    RESULT_TYPE = Ldbws::ResponseTypes::StationBoardWithDetails
+  end
+end

data/lib/ldbws/response_types/base.rb

@@ -0,0 +1,34 @@
+require "ldbws/utils"
+
+require "ldbws/response_types/parsing_functions"
+
+# This module defines specific response types that map 1:1 with corresponding types in the LDBWS service schema. Sadly
+# these are not especially well-documented.
+#
+# A lot of the Ruby side here works using a DSL to programatically define how XML nodes should be converted into Ruby
+# objects: this is defined in {ParsingFunctions}.
+module Ldbws::ResponseTypes # :nodoc:
+  # \Base class which defines most of the functionality required by subclasses.
+  class Base # :nodoc:
+    include ParsingFunctions
+
+    def method_missing(prop)
+      @props.fetch(prop)
+    end
+
+    def to_h
+      @props.to_h do |k, v|
+        [
+          k,
+          Ldbws::Utils.deep_hashify_value(v),
+        ]
+      end
+    end
+
+    private
+
+    def initialize(props)
+      @props = props
+    end
+  end
+end

data/lib/ldbws/response_types/calling_point.rb

@@ -0,0 +1,40 @@
+require "ldbws/response_types/base"
+require "ldbws/response_types/formation"
+
+module Ldbws::ResponseTypes
+  # Represents a calling point in the LDBWS.
+  #
+  # === Properties
+  # location_name:: the name of the station
+  # crs:: the CRS of the station
+  # st:: the scheduled time (as a Time object)
+  # et:: the expected time (as a String)
+  # at:: the actual time (as a string)
+  # cancelled::
+  # length::
+  # detatch_front::
+  # formation:: information about the formation of the train
+  # adhoc_alerts::
+  # cancel_reason::
+  # delay_reason::
+  # affected_by_diversion::
+  # reroute_delay::
+  # affected_by::
+  class CallingPoint < Base
+    property :location_name, String
+    property :crs, String
+    property :st, Time
+    property :et, String
+    property :at, String
+    property :cancelled, Boolean, selector: "isCancelled"
+    property :length, Integer
+    property :detatch_front, Boolean, default: false
+    property :formation, Formation
+    collection :adhoc_alerts, "adhocAlertText", String
+    property :cancel_reason, String
+    property :delay_reason, String
+    property :affected_by_diversion, Boolean, default: false
+    property :reroute_delay, Integer, default: 0
+    property :affected_by, String
+  end
+end

data/lib/ldbws/response_types/departures_board.rb

@@ -0,0 +1,39 @@
+require "ldbws/response_types/base"
+require "ldbws/response_types/station_board"
+
+module Ldbws::ResponseTypes
+  # Represents an item on a departure board.
+  #
+  # === Properties
+  # crs:: the CRS for the item
+  # service:: a ServiceItem[rdoc-ref:ServiceItem] representing this service.
+  class DepartureItem < Base
+    property :crs, String, selector: "@crs"
+    property :service, ServiceItem
+  end
+
+  # Represents an item on a departure board with additional details.
+  #
+  # === Properties
+  # crs:: the CRS for the item
+  # service:: a ServiceItemWithCallingPoints[rdoc-ref:ServiceItemWithCallingPoints] representing this service.
+  class DepartureItemWithDetails < Base
+    property :crs, String, selector: "@crs"
+    property :service, ServiceItemWithCallingPoints
+  end
+
+  # Represents a departures board.
+  #
+  # === Properties
+  # departures:: a list of departures[rdoc-ref:DepartureItem].
+  class DeparturesBoard < BaseStationBoard
+    collection :departures, "destination", DepartureItem
+  end
+
+  # Represents a departures board with additional details.
+  # === Properties
+  # departures:: a list of departures[rdoc-ref:DepartureItemWithDetails].
+  class DeparturesBoardWithDetails < BaseStationBoard
+    collection :departures, "destination", DepartureItemWithDetails
+  end
+end

data/lib/ldbws/response_types/formation.rb

@@ -0,0 +1,49 @@
+require "ldbws/response_types/base"
+
+module Ldbws::ResponseTypes
+  # The loading category of a train
+  #
+  # === Properties
+  # code::
+  # colour::
+  # image::
+  class LoadingCategory < Base
+    property :code, String
+    property :colour, String
+    property :image, String
+  end
+
+  # The availability of an individual toilet on a train
+  #
+  # === Properties
+  # type:: the type of toilet
+  # status:: whether the toilet is in- or out of service
+  class ToiletAvailability < Base
+    property :type, String, selector: "."
+    property :status, String, selector: "@status", default: "InService"
+  end
+
+  # Information about an individual coach in the train.
+  #
+  # === Properties
+  # number:: the coach number or identifier
+  # class:: the class of the coach—usually ‘standard’ or ‘first’
+  # toilet:: information about {toilets}[rdoc-ref:ToiletAvailability] in the carriage
+  # loading:: the loading of the carriage, as a percentage from 0–100.
+  class Coach < Base
+    property :number, String, selector: "@number"
+    property :class, String, selector: "coachClass"
+    property :toilet, ToiletAvailability
+    property :loading, Integer
+  end
+
+  # Information about the formation of a train
+  #
+  # === Properties
+  # loading_category:: how heavily-loaded the train is. Provided as as LoadingCategory
+  # coaches:: descriptions of each of the {carriages}[rdoc-ref:Coach] in the train
+  class Formation < Base
+    property :loading_category, LoadingCategory
+    collection :coaches, "coach", Coach
+  end
+end

data/lib/ldbws/response_types/parsing_functions.rb

@@ -0,0 +1,177 @@
+module Ldbws::ResponseTypes # :nodoc:
+  # Provides a DSL-type interface for easily defining the conversion from XML to PORO.
+  #
+  # It does this through the provision of two methods: {#property}, which defines a single property of a specified type,
+  # and {#collection} which defines a list of the same.
+  #
+  # Thus, given some XML like:
+  #
+  #   <foo>text</foo>
+  #   <bar>
+  #     <value>one</value>
+  #     <value>two</value>
+  #     <value>three</value>
+  #   </bar>
+  #
+  # Your DSL would look something like:
+  #
+  #   property :foo, String
+  #   collection :bar, "Value", String
+  #
+  # === Nested parsing
+  #
+  # Both [#property] and [#collection] take a class that is used to convert from the XML value to Ruby. This can be
+  # any normal Ruby class that response to either +#new+ or +#parse+ (like [Date]).
+  # Additionally, this can be another class implementing this module, in which case the #from_xml method is used.
+  module ParsingFunctions # :nodoc:
+    def self.included(base)
+      base.extend(ClassFunctions)
+    end
+
+    module ClassFunctions # :nodoc:
+      # Creates an object from an XML node.
+      #
+      # === Parameters
+      # xml_node:: the {XML node}[rdoc-ref:Nokogiri:XML::Node] to parse
+      def from_xml(xml_node)
+        raise "Oh no" if properties.empty?
+
+        props = properties.dup.map do |key, defn|
+          # look for the node, and return the default if we can’t find it
+          found = xml_node.xpath("./#{defn[:selector]}")
+          next [key, defn[:default]] unless found.any?
+
+          [
+            key,
+            if defn[:collection]
+              found.map { |node| parse_property(node, defn) }.compact
+            else
+              parse_property(found.first, defn)
+            end,
+          ]
+        end.to_h
+
+        new(props)
+      end
+
+      protected
+
+      # Defines a single property to be parsed from the XML.
+      #
+      # === Examples
+      #
+      # Given the structure
+      #
+      #   <foo>text content</foo>
+      #   <bar>3.1415</bar>
+      #   <blah>Some more content</blah>
+      #
+      # and
+      #
+      #   property :foo, String
+      #   property :bar, Float
+      #   property :baz, String, selctor: "blah" # selects the value from <blah>, but stores it as `:baz`
+      #
+      # === Parameters
+      # key:: the name of the property. This us used to select the node in XML unless `:selector` is specified.
+      # klass:: the Ruby class to use when parsing the value.
+      # selector:: an optional XPath selector. If not specified, a snake_case version of `:key` is used instead.
+      # default:: an optional default value for the property if the specified XML node cannot be found.
+      def property(key, klass, selector: nil, default: nil)
+        selector ||= Ldbws::Utils.to_snake_case(key.to_s)
+
+        @_properties ||= {}
+        @_properties[key] = {
+          key: key,
+          selector: selector,
+          klass: klass,
+          default: default,
+          collection: false,
+        }
+      end
+
+      # Defines an array of a single type to be parsed from the XML.
+      #
+      # === Examples
+      #
+      # Given the structure
+      #
+      #   <foo>
+      #     <value>…</value>
+      #     <value>…</value>
+      #   </foo>
+      #
+      # and
+      #
+      #   property :foo, "value", String
+      #   property :bar, "value", String, selector: "foo" # selects the same as above, just aliased as :bar
+      #
+      # === Parameters
+      # key:: the name of the property. This us used to select the node in XML unless +:selector+ is specified.
+      # option_selector:: a selector for the ‘child’ node that contains the additional value
+      # klass:: the Ruby class to use when parsing the value.
+      # selector:: an optional XPath selector to use when getting the ‘root’ node. If left unspecified, a +snake_case+
+      #            version of +:key+ is used.
+      # default:: an optional default value, if the specified XML node cannot be found.
+      def collection(key, option_selector, klass, selector: nil, default: [])
+        selector ||= Ldbws::Utils.to_snake_case(key.to_s)
+
+        @_properties ||= {}
+        @_properties[key] = {
+          key: key,
+          selector: "#{selector}/#{option_selector}",
+          klass: klass,
+          default: default,
+          collection: true,
+        }
+      end
+
+      # Used by #inherited to copy properties from parents to children
+      def properties=(props) # :nodoc:
+        @_properties = props
+      end
+
+      private
+
+      # Returns the properties
+      def properties
+        @_properties
+      end
+
+      def inherited(sub)
+        sub.properties = @_properties.dup
+      end
+
+      def parse_property(xml_node, definition)
+        return definition[:default] if xml_node.children.empty?
+
+        klass = definition[:klass]
+        content = xml_node.content
+
+        if klass.respond_to?(:parse)
+          klass.parse(content)
+        elsif klass.respond_to?(:from_xml)
+          klass.from_xml(xml_node)
+        elsif klass.respond_to?(:new)
+          klass.new(content)
+        else
+          content
+        end
+      end
+    end
+  end
+
+  # Provides a Boolean type for use with the DSL.
+  class Boolean # :nodoc:
+    def self.parse(value)
+      value.downcase == "true"
+    end
+  end
+
+  # Provides a self-stripping string for use with the DSL.
+  class StrippedString # :nodoc:
+    def self.parse(value)
+      value.strip
+    end
+  end
+end

data/lib/ldbws/response_types/service_details.rb

@@ -0,0 +1,69 @@
+require "ldbws/response_types/base"
+require "ldbws/response_types/formation"
+
+module Ldbws::ResponseTypes
+  # Represents details about a service in LDBWS.
+  #
+  # === Properties
+  # generatedAt::
+  # service_type::
+  # location_name::
+  # crs::
+  # operator::
+  # operator_code::
+  # rsid::
+  # cancelled::
+  # cancel_reason::
+  # delay_reason::
+  # overdue_message::
+  # length::
+  # detach_front::
+  # reverse_formation::
+  # platform::
+  # sta:: the scheduled arrival time as a Time object.
+  # eta:: the estimated arrival time, as a string
+  # ata:: the actual arrival time, as a string
+  # std:: the scheduled departure time as a Time object
+  # etd:: the estimated departure time, as a string
+  # atd:: the actual departure time, as a String
+  # diverted_via::
+  # diversion_reason::
+  # adhoc_alerts::
+  # formation:: information about the formation of the train
+  # previous_calling_points::
+  # subsequent_calling_points::
+  class ServiceDetails < Base
+    # from rtti_2017-10-01_ldb_types.xsd // BaseServiceDetails
+    property :generated_at, DateTime
+    property :service_type, String
+    property :location_name, String
+    property :crs, String
+    property :operator, String
+    property :operator_code, String
+    property :rsid, String
+    property :cancelled, Boolean, selector: "isCancelled", default: false
+    property :cancel_reason, String
+    property :delay_reason, String
+    property :overdue_message, String
+    property :length, Integer
+    property :detach_front, Boolean, default: false
+    property :reverse_formation, Boolean, selector: "isReverseFormation", default: false
+    property :platform, String
+    property :sta, Time
+    property :eta, String
+    property :ata, String
+    property :std, Time
+    property :etd, String
+    property :atd, String
+
+    # From rtti_2021-11-01_ldb_types.xsd // BaseServiceDetails
+    property :diverted_via, String
+    property :diversion_reason, String
+
+    # From rtti_2021-11-01_ldb_types.xsd // ServiceDetails
+    collection :adhoc_alerts, "adhocAlertText", String
+    property :formation, Formation
+    collection :previous_calling_points, "callingPointList/callingPoint", CallingPoint
+    collection :subsequent_calling_points, "callingPointList/callingPoint", CallingPoint
+  end
+end

data/lib/ldbws/response_types/service_item.rb

@@ -0,0 +1,77 @@
+require "ldbws/response_types/base"
+require "ldbws/response_types/calling_point"
+require "ldbws/response_types/formation"
+
+module Ldbws::ResponseTypes
+  # Represents a location in LDBWS.
+  #
+  # === Properties
+  # name::
+  # crs::
+  # via::
+  class Location < Base
+    property :name, String, selector: "locationName"
+    property :crs, String
+    property :via, String
+  end
+
+  # Represents a service item in LDBWS.
+  #
+  # === Properties
+  # sta:: the scheduled arrival time as a Time object
+  # eta:: the estimated arrival time as a string
+  # std:: the scheduled departure time as a Time object
+  # etd:: the estimated departure time as a string
+  # platform::
+  # operator::
+  # operator_code::
+  # circular_route::
+  # cancelled::
+  # service_type::
+  # length::
+  # detatch_front::
+  # reverse_formation::
+  # cancel_reason::
+  # delay_reason::
+  # service_id::
+  # adhoc_alerts::
+  # origin::
+  # destination::
+  # formation:: information about the formation of the train
+  class ServiceItem < Base
+    property :sta, Time
+    property :eta, String
+    property :std, Time
+    property :etd, String
+    property :platform, String
+    property :operator, String
+    property :operator_code, String
+    property :circular_route, Boolean, default: false, selector: "isCircularRoute"
+    property :cancelled, Boolean, default: false, selector: "isCancelled"
+    property :service_type, String
+    property :length, Integer
+    property :detach_front, Boolean, default: false
+    property :reverse_formation, Boolean, default: false, selector: "isReverseFormation"
+    property :cancel_reason, String
+    property :delay_reason, String
+    property :service_id, String, selector: "serviceID"
+    collection :adhoc_alerts, "adhocAlertText", String
+    collection :origin, "location", Location
+    collection :destination, "location", Location
+
+    # rtti_2021-11-01_ldb_types.xsd
+    property :formation, Formation
+  end
+
+  # Represents a service item with additional details in LDBWS: extends ServiceItem.
+  #
+  # === Properties
+  # As ServiceItem, and additionally:
+  #
+  # previous_calling_points::
+  # subsequent_calling_points::
+  class ServiceItemWithCallingPoints < ServiceItem
+    collection :previous_calling_points, "callingPointList/callingPoint", CallingPoint
+    collection :subsequent_calling_points, "callingPointList/callingPoint", CallingPoint
+  end
+end

data/lib/ldbws/response_types/station_board.rb

@@ -0,0 +1,50 @@
+require "ldbws/response_types/base"
+require "ldbws/response_types/service_item"
+
+module Ldbws::ResponseTypes
+  # \Base station board information. This does not directly correspond to a type in LDBWS.
+  #
+  # === Properties
+  # generated_at::
+  # location_name::
+  # crs::
+  # nrcc_messages::
+  # platform_available::
+  # are_services_available::
+  class BaseStationBoard < Base
+    property :generated_at, DateTime
+    property :location_name, String
+    property :crs, String
+    collection :nrcc_messages, "message", StrippedString
+    property :platform_available, Boolean, default: false
+    property :are_services_available, Boolean, default: true
+  end
+
+  # Represents a station arrival/departure board in LDBWS.
+  #
+  # === Properties
+  # As BaseStationBoard, and additionally:
+  #
+  # train_services::
+  # bus_services::
+  # ferry_services::
+  class StationBoard < BaseStationBoard
+    collection :train_services, "service", ServiceItem
+    collection :bus_services, "service", ServiceItem
+    collection :ferry_services, "service", ServiceItem
+  end
+
+  # Represents a station arrival/departure board with additional details in LDBWS.
+  #
+  # === Properties
+  # As BaseStationBoard, and additionally:
+  #
+  # train_services::
+  # bus_services::
+  # ferry_services::
+  class StationBoardWithDetails < BaseStationBoard
+    collection :train_services, "service", ServiceItemWithCallingPoints
+    collection :bus_services, "service", ServiceItemWithCallingPoints
+    collection :ferry_services, "service", ServiceItemWithCallingPoints
+  end
+end