ldbws 1.0.2 → 1.0.4

data/doc/js/search_ranker.js

@@ -0,0 +1,239 @@
+/**
+ * Aliki Search Implementation
+ *
+ * Search algorithm with the following priorities:
+ * 1. Exact full_name match always wins (for namespace/method queries)
+ * 2. Exact name match gets high priority
+ * 3. Match types:
+ *    - Namespace queries (::) and method queries (# or .) match against full_name
+ *    - Regular queries match against unqualified name
+ *    - Prefix (10000) > substring (5000) > fuzzy (1000)
+ * 4. First character determines type priority:
+ *    - Starts with lowercase: methods first
+ *    - Starts with uppercase: classes/modules/constants first
+ * 5. Within same type priority:
+ *    - Unqualified match > qualified match
+ *    - Shorter name > longer name
+ * 6. Class methods > instance methods
+ * 7. Result limit: 30
+ * 8. Minimum query length: 1 character
+ */
+
+var MAX_RESULTS = 30;
+var MIN_QUERY_LENGTH = 1;
+
+/*
+ * Scoring constants - organized in tiers where each tier dominates lower tiers.
+ * This ensures match type always beats type priority, etc.
+ *
+ * Tier 0: Exact matches (immediate return)
+ * Tier 1: Match type (prefix > substring > fuzzy)
+ * Tier 2: Exact name bonus
+ * Tier 3: Type priority (method vs class based on query case)
+ * Tier 4: Minor bonuses (top-level, class method, name length)
+ */
+var SCORE_EXACT_FULL_NAME = 1000000;  // Tier 0: Query exactly matches full_name
+var SCORE_MATCH_PREFIX    = 10000;    // Tier 1: Query is prefix of name
+var SCORE_MATCH_SUBSTRING = 5000;     // Tier 1: Query is substring of name
+var SCORE_MATCH_FUZZY     = 1000;     // Tier 1: Query chars appear in order
+var SCORE_EXACT_NAME      = 500;      // Tier 2: Name exactly equals query
+var SCORE_TYPE_PRIORITY   = 100;      // Tier 3: Preferred type (method/class)
+var SCORE_TOP_LEVEL       = 50;       // Tier 4: Top-level over namespaced
+var SCORE_CLASS_METHOD    = 10;       // Tier 4: Class method over instance method
+
+/**
+ * Check if all characters in query appear in order in target
+ * e.g., "addalias" fuzzy matches "add_foo_alias"
+ */
+function fuzzyMatch(target, query) {
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    ti = target.indexOf(query[qi], ti);
+    if (ti === -1) return false;
+    ti++;
+  }
+  return true;
+}
+
+/**
+ * Parse and normalize a search query
+ * @param {string} query - The raw search query
+ * @returns {Object} Parsed query with normalized form and flags
+ */
+function parseQuery(query) {
+  // Lowercase for case-insensitive matching (so "hash" finds both Hash class and #hash methods)
+  var normalized = query.toLowerCase();
+  var isNamespaceQuery = query.includes('::');
+  var isMethodQuery = query.includes('#') || query.includes('.');
+
+  // Normalize . to :: (RDoc uses :: for class methods in full_name)
+  if (query.includes('.')) {
+    normalized = normalized.replace(/\./g, '::');
+  }
+
+  return {
+    original: query,
+    normalized: normalized,
+    isNamespaceQuery: isNamespaceQuery,
+    isMethodQuery: isMethodQuery,
+    // Namespace and method queries match against full_name instead of name
+    matchesFullName: isNamespaceQuery || isMethodQuery,
+    // If query starts with lowercase, prioritize methods; otherwise prioritize classes/modules/constants
+    prioritizeMethod: !/^[A-Z]/.test(query)
+  };
+}
+
+/**
+ * Main search function
+ * @param {string} query - The search query
+ * @param {Array} index - The search index to search in
+ * @returns {Array} Array of matching entries, sorted by relevance
+ */
+function search(query, index) {
+  if (!query || query.length < MIN_QUERY_LENGTH) {
+    return [];
+  }
+
+  var q = parseQuery(query);
+  var results = [];
+
+  for (var i = 0; i < index.length; i++) {
+    var entry = index[i];
+    var score = computeScore(entry, q);
+
+    if (score !== null) {
+      results.push({ entry: entry, score: score });
+    }
+  }
+
+  results.sort(function(a, b) {
+    return b.score - a.score;
+  });
+
+  return results.slice(0, MAX_RESULTS).map(function(r) {
+    return r.entry;
+  });
+}
+
+/**
+ * Compute the relevance score for an entry
+ * @param {Object} entry - The search index entry
+ * @param {Object} q - Parsed query from parseQuery()
+ * @returns {number|null} Score or null if no match
+ */
+function computeScore(entry, q) {
+  var name = entry.name;
+  var fullName = entry.full_name;
+  var type = entry.type;
+
+  var nameLower = name.toLowerCase();
+  var fullNameLower = fullName.toLowerCase();
+
+  // Exact full_name match (e.g., "Array#filter" matches Array#filter)
+  if (q.matchesFullName && fullNameLower === q.normalized) {
+    return SCORE_EXACT_FULL_NAME;
+  }
+
+  var matchScore = 0;
+  var target = q.matchesFullName ? fullNameLower : nameLower;
+
+  if (target.startsWith(q.normalized)) {
+    matchScore = SCORE_MATCH_PREFIX;     // Prefix (e.g., "Arr" matches "Array")
+  } else if (target.includes(q.normalized)) {
+    matchScore = SCORE_MATCH_SUBSTRING;  // Substring (e.g., "ray" matches "Array")
+  } else if (fuzzyMatch(target, q.normalized)) {
+    matchScore = SCORE_MATCH_FUZZY;      // Fuzzy (e.g., "addalias" matches "add_foo_alias")
+  } else {
+    return null;
+  }
+
+  var score = matchScore;
+  var isMethod = (type === 'instance_method' || type === 'class_method');
+
+  if (q.prioritizeMethod ? isMethod : !isMethod) {
+    score += SCORE_TYPE_PRIORITY;
+  }
+
+  if (type === 'class_method') score += SCORE_CLASS_METHOD;
+  if (name === fullName) score += SCORE_TOP_LEVEL;  // Top-level (Hash) > namespaced (Foo::Hash)
+  if (nameLower === q.normalized) score += SCORE_EXACT_NAME;  // Exact name match
+  score -= name.length;
+
+  return score;
+}
+
+/**
+ * SearchRanker class for compatibility with the Search UI
+ * Provides ready() and find() interface
+ */
+function SearchRanker(index) {
+  this.index = index;
+  this.handlers = [];
+}
+
+SearchRanker.prototype.ready = function(fn) {
+  this.handlers.push(fn);
+};
+
+SearchRanker.prototype.find = function(query) {
+  var q = parseQuery(query);
+  var rawResults = search(query, this.index);
+  var results = rawResults.map(function(entry) {
+    return formatResult(entry, q);
+  });
+
+  var _this = this;
+  this.handlers.forEach(function(fn) {
+    fn.call(_this, results, true);
+  });
+};
+
+/**
+ * Format a search result entry for display
+ */
+function formatResult(entry, q) {
+  var result = {
+    title: highlightMatch(entry.full_name, q),
+    path: entry.path,
+    type: entry.type
+  };
+
+  if (entry.snippet) {
+    result.snippet = entry.snippet;
+  }
+
+  return result;
+}
+
+/**
+ * Add highlight markers (\u0001 and \u0002) to matching portions of text
+ * @param {string} text - The text to highlight
+ * @param {Object} q - Parsed query from parseQuery()
+ */
+function highlightMatch(text, q) {
+  if (!text || !q) return text;
+
+  var textLower = text.toLowerCase();
+  var query = q.normalized;
+
+  // Try contiguous match first (prefix or substring)
+  var matchIndex = textLower.indexOf(query);
+  if (matchIndex !== -1) {
+    return text.substring(0, matchIndex) +
+      '\u0001' + text.substring(matchIndex, matchIndex + query.length) + '\u0002' +
+      text.substring(matchIndex + query.length);
+  }
+
+  // Fall back to fuzzy highlight (highlight each matched character)
+  var result = '';
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    var charIndex = textLower.indexOf(query[qi], ti);
+    if (charIndex === -1) return text;
+    result += text.substring(ti, charIndex);
+    result += '\u0001' + text[charIndex] + '\u0002';
+    ti = charIndex + 1;
+  }
+  result += text.substring(ti);
+  return result;
+}

data/doc/js/theme-toggle.js

@@ -0,0 +1,112 @@
+(function() {
+  'use strict';
+
+  const STORAGE_KEY = 'rdoc-theme';
+  const THEME_LIGHT = 'light';
+  const THEME_DARK = 'dark';
+
+  /**
+   * Get the user's theme preference
+   * Priority: localStorage > system preference > light (default)
+   */
+  function getThemePreference() {
+    // Check localStorage first
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === THEME_LIGHT || stored === THEME_DARK) {
+      return stored;
+    }
+
+    // Check system preference
+    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      return THEME_DARK;
+    }
+
+    return THEME_LIGHT;
+  }
+
+  /**
+   * Apply theme to document
+   */
+  function applyTheme(theme) {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem(STORAGE_KEY, theme);
+
+    // Update toggle button icon
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      const icon = toggleBtn.querySelector('.theme-toggle-icon');
+      if (icon) {
+        icon.textContent = theme === THEME_DARK ? '☀️' : '🌙';
+      }
+      toggleBtn.setAttribute('aria-label',
+        theme === THEME_DARK ? 'Switch to light mode' : 'Switch to dark mode'
+      );
+    }
+  }
+
+  /**
+   * Toggle between light and dark themes
+   */
+  function toggleTheme() {
+    const currentTheme = document.documentElement.getAttribute('data-theme') || THEME_LIGHT;
+    const newTheme = currentTheme === THEME_LIGHT ? THEME_DARK : THEME_LIGHT;
+    applyTheme(newTheme);
+
+    // Announce to screen readers
+    announceThemeChange(newTheme);
+  }
+
+  /**
+   * Announce theme change to screen readers
+   */
+  function announceThemeChange(theme) {
+    const announcement = document.createElement('div');
+    announcement.setAttribute('role', 'status');
+    announcement.setAttribute('aria-live', 'polite');
+    announcement.className = 'sr-only';
+    announcement.textContent = `Switched to ${theme} mode`;
+    document.body.appendChild(announcement);
+
+    // Remove after announcement
+    setTimeout(() => {
+      document.body.removeChild(announcement);
+    }, 1000);
+  }
+
+  /**
+   * Initialize theme on page load
+   */
+  function initTheme() {
+    // Apply theme immediately to prevent flash
+    const theme = getThemePreference();
+    applyTheme(theme);
+
+    // Set up toggle button listener
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      toggleBtn.addEventListener('click', toggleTheme);
+    }
+
+    // Listen for system theme changes
+    if (window.matchMedia) {
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+        // Only auto-switch if user hasn't manually set a preference
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (!stored) {
+          applyTheme(e.matches ? THEME_DARK : THEME_LIGHT);
+        }
+      });
+    }
+  }
+
+  // Initialize immediately (before DOMContentLoaded to prevent flash)
+  if (document.readyState === 'loading') {
+    // Apply theme as early as possible
+    const theme = getThemePreference();
+    document.documentElement.setAttribute('data-theme', theme);
+
+    document.addEventListener('DOMContentLoaded', initTheme);
+  } else {
+    initTheme();
+  }
+})();

data/doc/table_of_contents.html

@@ -34,9 +34,8 @@
     <a href="README_md.html">README</a>
 
     <ul>
-      <li><a href="README_md.html#label-ldbws-ruby">ldbws-ruby</a>
-      <li><a href="README_md.html#label-HOWTO">HOWTO</a>
-      <li><a href="README_md.html#label-A+note+about+rate+limiting">A note about rate limiting</a>
+      <li><a href="README_md.html#label-ldbws">ldbws</a>
+      <li><a href="README_md.html#label-Installation-2Fusage">Installation/usage</a>
       <li><a href="README_md.html#label-Error-handling">Error-handling</a>
       <li><a href="README_md.html#label-Ldbws-3A-3ARequest-3A-3AParamValidationError"><code>Ldbws::Request::ParamValidationError</code></a>
       <li><a href="README_md.html#label-Ldbws-3A-3ARequestError"><code>Ldbws::RequestError</code></a>

data/ldbws.gemspec

@@ -14,12 +14,13 @@ Gem::Specification.new do |spec|
 
   spec.version = Ldbws::VERSION
   spec.files = `git ls-files`.split($\)
+  spec.required_ruby_version = ">= 3.3"
 
-  spec.add_dependency "dry-schema", "~> 1.13"
-  spec.add_dependency "faraday", "~> 2.7"
-  spec.add_dependency "nokogiri", "~> 1.14"
+  spec.add_dependency "dry-schema", "~> 1.16"
+  spec.add_dependency "faraday", "~> 2.15"
+  spec.add_dependency "nokogiri", "~> 1.19"
 
-  spec.add_development_dependency "rdoc", "~> 6.5.0"
-  spec.add_development_dependency "rspec", "~> 3.11"
-  spec.add_development_dependency "rufo", "~> 0.13.0"
+  spec.add_development_dependency "rdoc", "~> 8.1"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rufo", "~> 0.18"
 end

data/lib/ldbws/request/base.rb

@@ -12,9 +12,6 @@ module Ldbws::Request # :nodoc:
 
     # A CRS code (eg ‘WAT’ for London Waterloo). These are not exhaustively validated.
     Crs = String.constrained(size: 3)
-
-    # A specific type used when filtering by CRS.
-    FilterType = String.enum("to", "from")
   end
 
   # \Base request type used whem querying LDBWS: provides basic functionality that can be overridden on a per-subclass

data/lib/ldbws/request/get_departures_board.rb

@@ -14,8 +14,10 @@ module Ldbws::Request
   class GetDeparturesBoard < Base
     # :nodoc:
     SCHEMA = Dry::Schema.Params do
+      config.validate_keys = true
+
       required(:crs).filled(Types::Crs)
-      required(:filter_list).array(Types::Crs, min_size?: 1)
+      required(:filter_list).value(array[Types::Crs], min_size?: 1)
       optional(:time_offset).filled(:integer)
       optional(:time_window).filled(:integer)
     end
@@ -26,6 +28,8 @@ module Ldbws::Request
     # :nodoc:
     RESULT_TYPE = Ldbws::ResponseTypes::DeparturesBoard
 
+    protected
+
     # :nodoc:
     def to_soap_params
       @params.tap do |params|

data/lib/ldbws/request/get_service_details.rb

@@ -10,6 +10,8 @@ module Ldbws::Request
   class GetServiceDetails < Base
     # :nodoc:
     SCHEMA = Dry::Schema.Params do
+      config.validate_keys = true
+
       required(:service_id).filled(:string)
     end
 
@@ -19,10 +21,12 @@ module Ldbws::Request
     # :nodoc:
     RESULT_TYPE = Ldbws::ResponseTypes::ServiceDetails
 
+    protected
+
     # :nodoc:
     def to_soap_params
       {
-        serviceID: @params[:service_id],
+        serviceID: @params[:service_id].upcase,
       }
     end
   end

data/lib/ldbws/request/get_station_board.rb

@@ -16,10 +16,12 @@ module Ldbws::Request
   class GetStationBoard < Base
     # :nodoc:
     SCHEMA = Dry::Schema.Params do
+      config.validate_keys = true
+
       required(:crs).filled(Types::Crs)
       optional(:num_rows).filled(:integer)
       optional(:filter_crs).filled(Types::Crs)
-      optional(:filter_type).filled(Types::FilterType)
+      optional(:filter_type).filled(Types::String.enum("to", "from"))
       optional(:time_offset).filled(:integer)
       optional(:time_window).filled(:integer)
     end
@@ -30,12 +32,23 @@ module Ldbws::Request
     # :nodoc:
     RESULT_TYPE = Ldbws::ResponseTypes::StationBoard
 
+    def initialize(args)
+      # there doesn’t seem to be a nice way of getting Dry::Types to do a case-insensitive enum, so instead we’ll do
+      # some manual case-coersion here
+      args[:filter_type].downcase! if args[:filter_type]
+
+      super(args)
+    end
+
+    protected
+
     # :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]
+        params[:filter_type].downcase! if params[:filter_type]
 
         # filter type isn’t needed if we’re not filtering
         params.delete(:filter_type) unless params[:filter_crs]

data/lib/ldbws/response_types/calling_point.rb

@@ -12,7 +12,7 @@ module Ldbws::ResponseTypes
   # at:: the actual time (as a string)
   # cancelled::
   # length::
-  # detatch_front::
+  # detach_front::
   # formation:: information about the formation of the train
   # adhoc_alerts::
   # cancel_reason::
@@ -28,7 +28,7 @@ module Ldbws::ResponseTypes
     property :at, String
     property :cancelled, Boolean, selector: "isCancelled"
     property :length, Integer
-    property :detatch_front, Boolean, default: false
+    property :detach_front, Boolean, default: false
     property :formation, Formation
     collection :adhoc_alerts, "adhocAlertText", String
     property :cancel_reason, String

data/lib/ldbws/response_types/station_board.rb

@@ -18,6 +18,12 @@ module Ldbws::ResponseTypes
     collection :nrcc_messages, "message", StrippedString
     property :platform_available, Boolean, default: false
     property :are_services_available, Boolean, default: true
+
+    # Returns a combined list of all services (train, bus, and ferry), ordered by scheduled time of departure or
+    # arrival.
+    def all_services
+      (train_services + bus_services + ferry_services).sort_by { |s| s.std || s.sta }
+    end
   end
 
   # Represents a station arrival/departure board in LDBWS.

data/lib/ldbws/service.rb

@@ -202,17 +202,15 @@ module Ldbws
     end
 
     def perform_soap_request(action, body)
-      uri = URI(SERVICE_URI)
-
       conn = Faraday.new(
-        url: "#{uri.scheme}://#{uri.host}",
+        url: "#{SERVICE_URI.scheme}://#{SERVICE_URI.host}",
         headers: {
           'Content-Type': "text/xml",
           'SOAPAction': action,
         },
       )
 
-      conn.post(uri.path, body).body
+      conn.post(SERVICE_URI.path, body).body
     end
 
     def extract_error(xml)

data/lib/ldbws/version.rb

@@ -1,4 +1,4 @@
 module Ldbws
   # The current gem version.
-  VERSION = "1.0.2"
+  VERSION = "1.0.4"
 end

data/spec/helpers/request_helper.rb

@@ -0,0 +1,27 @@
+require "nokogiri"
+
+module RequestHelper
+  def expect_ok(params)
+    ret = nil
+    expect { ret = subject.new(params) }.not_to raise_error
+    ret
+  end
+
+  def expect_error(params, field, message)
+    expect { subject.new(params) }.to raise_error do |err|
+      expect(err).to be_a(Ldbws::Request::ParamValidationError)
+
+      messages = err.messages
+      expect(messages[field]).not_to be_nil
+      expect(messages[field].to_s).to include(message)
+    end
+  end
+
+  def to_soap_str(params)
+    Nokogiri::XML::Builder.new do |xml|
+      xml.Request { # This node is entirely arbitrary
+        subject.new(params).to_soap(xml)
+      }
+    end.to_xml
+  end
+end

data/spec/request/get_departures_board_spec.rb

@@ -0,0 +1,55 @@
+require "spec_helper"
+require "helpers/request_helper"
+
+describe Ldbws::Request::GetDeparturesBoard do
+  include RequestHelper
+
+  let(:subject) { Ldbws::Request::GetDeparturesBoard }
+
+  context :validation do
+    context :crs do
+      it "requires a CRS" do
+        expect_error({}, :crs, "is missing")
+      end
+
+      it "enforces the length requirement" do
+        expect_error({ crs: "x" }, :crs, "length must be 3")
+        expect_error({ crs: "xxxx" }, :crs, "length must be 3")
+      end
+    end
+
+    context :filter_list do
+      it "requires at least one to be specified" do
+        expect_error({}, :filter_list, "is missing")
+
+        expect_error({ filter_list: [] }, :filter_list, "cannot be less than 1")
+      end
+
+      it "enforces the length requirement" do
+        expect_error({ filter_list: ["x"] }, :filter_list, "length must be 3")
+        expect_error({ filter_list: ["xxxx"] }, :filter_list, "length must be 3")
+      end
+
+      it "works with something that looks like a CRS (inexhaustive validation)" do
+        expect_ok(crs: "xxx", filter_list: %w{ abc def })
+      end
+    end
+  end
+
+  context :to_soap do
+    it "upcases the CRS field" do
+      soap = to_soap_str(crs: "cdf", filter_list: %w{ pad pmh swa })
+
+      expect(soap).to include("<crs>CDF</crs>")
+    end
+
+    it "correctly encodes the filterList field" do
+      soap = to_soap_str(crs: "cdf", filter_list: %w{ pad pmh swa })
+
+      # strip newlines and indents to make matching easier
+      soap.gsub!(/\n\s*/, "")
+
+      expect(soap).to include("<filterList><crs>PAD</crs><crs>PMH</crs><crs>SWA</crs></filterList>")
+    end
+  end
+end

data/spec/request/get_service_details_spec.rb

@@ -0,0 +1,16 @@
+require "spec_helper"
+require "helpers/request_helper"
+
+describe Ldbws::Request::GetServiceDetails do
+  include RequestHelper
+
+  let (:subject) { Ldbws::Request::GetServiceDetails }
+
+  context :to_soap do
+    it "upcases the service ID" do
+      soap = to_soap_str(service_id: "1234567crdfcen_")
+
+      expect(soap).to include("<serviceID>1234567CRDFCEN_</serviceID>")
+    end
+  end
+end