lenex-parser 3.0.0

data/Rakefile

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+configure_test_task = lambda do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+Rake::TestTask.new(:test, &configure_test_task)
+
+namespace :test do
+  desc 'Run tests with coverage'
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task[:test].reenable
+    Rake::Task[:test].invoke
+  ensure
+    Rake::Task[:test].reenable
+    ENV.delete('COVERAGE')
+  end
+end
+
+RuboCop::RakeTask.new(:rubocop)
+
+YARD::Rake::YardocTask.new(:docs)
+
+desc 'Run full CI pipeline'
+task :ci do
+  Rake::Task['test:coverage'].invoke
+  Rake::Task[:rubocop].invoke
+  Rake::Task[:docs].invoke
+ensure
+  Rake::Task['test:coverage'].reenable
+  Rake::Task[:rubocop].reenable
+  Rake::Task[:docs].reenable
+end
+
+task default: :ci

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'lenex-parser'
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/lenex-parser.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/lenex/parser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lenex-parser'
+  spec.version       = Lenex::Parser::VERSION
+  spec.authors       = ['bigcurl']
+  spec.email         = ['maintheme@gmail.com']
+
+  spec.summary       = 'Streaming SAX parser for Lenex 3 swim files'
+  spec.description   = 'Streams Lenex v3 swim data without building a DOM.'
+  spec.homepage      = 'https://github.com/bigcurl/lenex-parser'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = spec.homepage
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.files = Dir.glob('lib/**/*') +
+               Dir.glob('bin/*') +
+               %w[README.md LICENSE lenex-parser.gemspec Rakefile .rubocop.yml .yardopts]
+  spec.files.uniq!
+  spec.files.reject! { |path| File.directory?(path) }
+
+  spec.bindir        = 'bin'
+  spec.executables   = Dir.children('bin').grep_v(/\A\./)
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency "nokogiri", "~> 1.14"
+  spec.add_runtime_dependency "rubyzip", "~> 2.3"
+end

data/lib/lenex/document/serializer.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Lenex
+  class Document
+    # Serialises a {Lenex::Document} into Lenex XML.
+    class Serializer
+      ROOT_ELEMENT = 'LENEX'
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Generates a Lenex XML document from the provided {Lenex::Document}.
+      #
+      # @return [String] UTF-8 encoded Lenex XML
+      def to_xml
+        lenex = document.build_lenex
+
+        Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+          write_lenex(xml, lenex)
+        end.to_xml
+      end
+
+      def self.singular_element(container_name)
+        return container_name unless container_name.end_with?('S')
+        return container_name[0..-2] if container_name.end_with?('SS')
+
+        container_name.sub(/IES\z/, 'Y').sub(/S\z/, '')
+      end
+
+      private
+
+      attr_reader :document
+
+      def write_lenex(xml, lenex)
+        attributes = { 'version' => lenex.version }
+        revision = lenex.revision
+        attributes['revision'] = revision if present?(revision)
+
+        xml.send(ROOT_ELEMENT, attributes) do
+          NodeSerializer.write(xml, 'CONSTRUCTOR', lenex.constructor)
+          write_collection(xml, 'MEETS', lenex.meets)
+          write_collection(xml, 'RECORDLISTS', lenex.record_lists)
+          write_collection(xml, 'TIMESTANDARDLISTS', lenex.time_standard_lists)
+        end
+      end
+
+      def write_collection(xml, container_name, collection)
+        return if collection.empty?
+
+        item_name = self.class.singular_element(container_name)
+        xml.send(container_name) do
+          collection.each do |item|
+            NodeSerializer.write(xml, item_name, item)
+          end
+        end
+      end
+
+      def present?(value)
+        !(value.nil? || value.to_s.strip.empty?)
+      end
+
+      # Serialises Lenex object model instances using their attribute maps.
+      class NodeSerializer
+        def self.write(xml, element_name, object)
+          return if object.nil?
+
+          raise ArgumentError, "Cannot serialise #{object.class} with #{name}" if object.is_a?(Hash)
+
+          new(xml, element_name, object).write
+        end
+
+        def self.attribute_map_for(klass)
+          attribute_cache[klass] ||= build_attribute_map(klass)
+        end
+
+        def self.attribute_cache
+          @attribute_cache ||= {}
+        end
+        private_class_method :attribute_cache
+
+        def self.build_attribute_map(klass)
+          return {} unless klass.const_defined?(:ATTRIBUTES, false)
+
+          attributes = klass.const_get(:ATTRIBUTES)
+          attributes.each_with_object({}) do |(attribute_name, definition), mapping|
+            key = definition.is_a?(Hash) ? definition.fetch(:key) : definition
+            mapping[key.to_sym] = attribute_name
+          end
+        end
+        private_class_method :build_attribute_map
+
+        def initialize(xml, element_name, object)
+          @xml = xml
+          @element_name = element_name
+          @object = object
+        end
+
+        def write
+          attributes = collect_attributes
+          children = collect_children
+
+          return emit_empty_element(attributes) if children.empty?
+
+          emit_nested_element(attributes, children)
+        end
+
+        def write_child(name, value)
+          return write_array_child(name, value) if value.is_a?(Array)
+
+          self.class.write(xml, element_name_for(name), value)
+        end
+
+        private
+
+        attr_reader :xml, :element_name, :object
+
+        def collect_attributes
+          attribute_map = self.class.attribute_map_for(object.class)
+
+          attribute_map.each_with_object({}) do |(key, xml_name), collected|
+            value = fetch_attribute_value(key)
+            next if value.nil?
+
+            collected[xml_name] = value.to_s
+          end
+        end
+
+        def fetch_attribute_value(key)
+          object.public_send(key)
+        rescue NoMethodError
+          nil
+        end
+
+        def collect_children
+          object.instance_variables.each_with_object({}) do |ivar, collected|
+            next if attribute_instance_variables.include?(ivar.to_s)
+
+            value = object.instance_variable_get(ivar)
+            next if skip_child_value?(value)
+
+            collected[ivar_name(ivar)] = value
+          end
+        end
+
+        def attribute_instance_variables
+          self.class.attribute_map_for(object.class).keys.map { |key| "@#{key}" }
+        end
+
+        def ivar_name(ivar)
+          ivar.to_s.delete_prefix('@').to_sym
+        end
+
+        def element_name_for(name)
+          name.to_s.delete('_').upcase
+        end
+
+        def emit_empty_element(attributes)
+          xml.send(element_name, attributes)
+        end
+
+        def emit_nested_element(attributes, children)
+          xml.send(element_name, attributes) do
+            children.each do |name, value|
+              write_child(name, value)
+            end
+          end
+        end
+
+        def write_array_child(name, values)
+          return if values.empty?
+
+          container_name = element_name_for(name)
+          item_name = Serializer.singular_element(container_name)
+
+          xml.send(container_name) do
+            values.each do |value|
+              self.class.write(xml, item_name, value)
+            end
+          end
+        end
+
+        def skip_child_value?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+      end
+    end
+  end
+end

data/lib/lenex/document.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'document/serializer'
+
+module Lenex
+  # Document models the <LENEX> root element of a Lenex file.
+  # It exposes the constructor metadata and the collections that hang off the
+  # root node so the parser can populate the object graph incrementally.
+  class Document
+    # Container for constructor metadata coming from the <LENEX> element.
+    #
+    # The metadata is stored as a symbol-keyed hash so callers can merge values
+    # that originate from XML attributes or nested elements.
+    class ConstructorMetadata
+      # @return [Hash{Symbol => Object}] symbol-keyed constructor attributes
+      attr_reader :attributes
+
+      # @param attributes [Hash{Symbol,String => Object}] initial metadata values
+      def initialize(attributes = {})
+        @attributes = {}
+        merge!(attributes)
+      end
+
+      # Returns the value stored for the provided key.
+      #
+      # @param key [Symbol, String]
+      # @return [Object, nil]
+      def [](key)
+        @attributes[key.to_sym]
+      end
+
+      # Stores a value for the provided key.
+      #
+      # @param key [Symbol, String]
+      # @param value [Object]
+      # @return [Object] the assigned value
+      def []=(key, value)
+        @attributes[key.to_sym] = value
+      end
+
+      # Merges the provided hash into the stored attributes.
+      #
+      # Keys are normalized to symbols to provide consistent access semantics.
+      #
+      # @param new_attributes [Hash{Symbol,String => Object}]
+      # @return [ConstructorMetadata] self
+      def merge!(new_attributes)
+        new_attributes.each do |key, value|
+          @attributes[key.to_sym] = value
+        end
+        self
+      end
+
+      # @return [Hash{Symbol => Object}] a shallow copy of the stored attributes
+      def to_h
+        @attributes.dup
+      end
+    end
+
+    # @!attribute [r] constructor_metadata
+    #   @return [ConstructorMetadata] constructor metadata captured from the LENEX root
+    # @!attribute [r] meets
+    #   @return [Array<Object>] collection of parsed meets associated with the document
+    # @!attribute [r] record_lists
+    #   @return [Array<Object>] record lists extracted from the document
+    # @!attribute [r] time_standard_lists
+    #   @return [Array<Object>] time standard lists associated with the document
+    attr_reader :constructor_metadata, :meets, :record_lists, :time_standard_lists
+    attr_accessor :version, :revision
+    attr_writer :constructor
+
+    # @param constructor [ConstructorMetadata]
+    # @param collections [Hash{Symbol => Array<Object>}] pre-populated associations keyed by
+    #   :meets, :record_lists, and :time_standard_lists
+    def initialize(constructor: ConstructorMetadata.new,
+                   collections: {},
+                   version: nil,
+                   revision: nil)
+      @constructor_metadata = constructor
+      @constructor = nil
+      @meets = Array(collections.fetch(:meets, []))
+      @record_lists = Array(collections.fetch(:record_lists, []))
+      @time_standard_lists = Array(collections.fetch(:time_standard_lists, []))
+      @version = version
+      @revision = revision
+    end
+
+    # @return [ConstructorMetadata, Lenex::Parser::Objects::Constructor]
+    def constructor
+      @constructor || @constructor_metadata
+    end
+
+    # Adds a meet to the document.
+    #
+    # @param meet [Object]
+    # @return [Object] the provided meet
+    def add_meet(meet)
+      @meets << meet
+      meet
+    end
+
+    # Adds a record list to the document.
+    #
+    # @param record_list [Object]
+    # @return [Object] the provided record list
+    def add_record_list(record_list)
+      @record_lists << record_list
+      record_list
+    end
+
+    # Adds a time standard list to the document.
+    #
+    # @param time_standard_list [Object]
+    # @return [Object] the provided time standard list
+    def add_time_standard_list(time_standard_list)
+      @time_standard_lists << time_standard_list
+      time_standard_list
+    end
+
+    # Builds a Lenex object from the accumulated SAX state.
+    #
+    # @return [Lenex::Parser::Objects::Lenex]
+    def build_lenex
+      ensure_constructor_present!
+
+      Lenex::Parser::Objects::Lenex.new(
+        version: resolved_version,
+        revision: @revision,
+        constructor: @constructor,
+        collections: collections_payload
+      )
+    end
+
+    # Serialises the document into Lenex XML.
+    #
+    # @return [String]
+    def to_xml
+      Serializer.new(self).to_xml
+    end
+
+    private
+
+    def ensure_constructor_present!
+      return if @constructor
+
+      raise Lenex::Parser::ParseError, 'CONSTRUCTOR element is required'
+    end
+
+    def resolved_version
+      return @version unless @version.nil? || @version.strip.empty?
+
+      raise Lenex::Parser::ParseError, 'LENEX version attribute is required'
+    end
+
+    def collections_payload
+      {
+        meets: @meets,
+        record_lists: @record_lists,
+        time_standard_lists: @time_standard_lists
+      }
+    end
+  end
+end

data/lib/lenex/parser/objects/age_date.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    module Objects
+      # Value object representing an AGEDATE element.
+      class AgeDate
+        ATTRIBUTES = {
+          'type' => { key: :type, required: true },
+          'value' => { key: :value, required: false }
+        }.freeze
+
+        ATTRIBUTE_KEYS = ATTRIBUTES.values.map { |definition| definition[:key] }.freeze
+        private_constant :ATTRIBUTE_KEYS
+
+        ATTRIBUTE_KEYS.each { |attribute| attr_reader attribute }
+
+        def initialize(**attributes)
+          ATTRIBUTES.each_value do |definition|
+            key = definition[:key]
+            instance_variable_set(:"@#{key}", attributes[key])
+          end
+        end
+
+        def self.from_xml(element)
+          raise ::Lenex::Parser::ParseError, 'AGEDATE element is required' unless element
+
+          attributes = extract_attributes(element)
+
+          new(**attributes)
+        end
+
+        def self.extract_attributes(element)
+          ATTRIBUTES.each_with_object({}) do |(attribute_name, definition), collected|
+            value = element.attribute(attribute_name)&.value
+            ensure_required_attribute!(attribute_name, definition, value)
+            collected[definition[:key]] = value if value
+          end
+        end
+        private_class_method :extract_attributes
+
+        def self.ensure_required_attribute!(attribute_name, definition, value)
+          return unless definition[:required]
+          return unless value.nil? || value.strip.empty?
+
+          message = "AGEDATE #{attribute_name} attribute is required"
+          raise ::Lenex::Parser::ParseError, message
+        end
+        private_class_method :ensure_required_attribute!
+      end
+    end
+  end
+end

data/lib/lenex/parser/objects/age_group.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    module Objects
+      # Value object representing an AGEGROUP element.
+      class AgeGroup
+        ATTRIBUTES = {
+          'agegroupid' => { key: :age_group_id, required: true },
+          'agemax' => { key: :age_max, required: true },
+          'agemin' => { key: :age_min, required: true },
+          'calculate' => { key: :calculate, required: false },
+          'gender' => { key: :gender, required: false },
+          'handicap' => { key: :handicap, required: false },
+          'levelmax' => { key: :level_max, required: false },
+          'levelmin' => { key: :level_min, required: false },
+          'levels' => { key: :levels, required: false },
+          'name' => { key: :name, required: false }
+        }.freeze
+
+        ATTRIBUTE_KEYS = ATTRIBUTES.values.map { |definition| definition[:key] }.freeze
+        private_constant :ATTRIBUTE_KEYS
+
+        ATTRIBUTE_KEYS.each { |attribute| attr_reader attribute }
+        attr_reader :rankings
+
+        def initialize(rankings: [], **attributes)
+          ATTRIBUTES.each_value do |definition|
+            key = definition[:key]
+            instance_variable_set(:"@#{key}", attributes[key])
+          end
+          @rankings = Array(rankings)
+        end
+
+        def self.from_xml(element)
+          raise ::Lenex::Parser::ParseError, 'AGEGROUP element is required' unless element
+
+          attributes = extract_attributes(element)
+
+          rankings = extract_rankings(element.at_xpath('RANKINGS'))
+
+          new(**attributes, rankings:)
+        end
+
+        def self.extract_attributes(element)
+          ATTRIBUTES.each_with_object({}) do |(attribute_name, definition), collected|
+            value = element.attribute(attribute_name)&.value
+            ensure_required_attribute!(element, attribute_name, definition, value)
+            collected[definition[:key]] = value if value
+          end
+        end
+        private_class_method :extract_attributes
+
+        def self.ensure_required_attribute!(element, attribute_name, definition, value)
+          return unless definition[:required]
+          return if optional_age_group_id_without_reference?(element, attribute_name)
+          return unless value.nil? || value.strip.empty?
+
+          message = "AGEGROUP #{attribute_name} attribute is required"
+          raise ::Lenex::Parser::ParseError, message
+        end
+        private_class_method :ensure_required_attribute!
+
+        def self.optional_age_group_id_without_reference?(element, attribute_name)
+          return false unless attribute_name == 'agegroupid'
+
+          parent = element.respond_to?(:parent) ? element.parent : nil
+          ALLOWED_PARENTS_WITHOUT_ID.include?(parent&.name)
+        end
+        private_class_method :optional_age_group_id_without_reference?
+
+        ALLOWED_PARENTS_WITHOUT_ID = %w[TIMESTANDARDLIST RECORDLIST].freeze
+        private_constant :ALLOWED_PARENTS_WITHOUT_ID
+
+        def self.extract_rankings(collection_element)
+          return [] unless collection_element
+
+          collection_element.xpath('RANKING').map do |ranking_element|
+            Ranking.from_xml(ranking_element)
+          end
+        end
+        private_class_method :extract_rankings
+      end
+    end
+  end
+end

data/lib/lenex/parser/objects/athlete.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    module Objects
+      # Value object representing an ATHLETE element.
+      class Athlete
+        ATTRIBUTES = {
+          'athleteid' => { key: :athlete_id, required: true },
+          'birthdate' => { key: :birthdate, required: true },
+          'firstname' => { key: :first_name, required: true },
+          'firstname.en' => { key: :first_name_en, required: false },
+          'gender' => { key: :gender, required: true },
+          'lastname' => { key: :last_name, required: true },
+          'lastname.en' => { key: :last_name_en, required: false },
+          'level' => { key: :level, required: false },
+          'license' => { key: :license, required: false },
+          'license_dbs' => { key: :license_dbs, required: false },
+          'license_dsv' => { key: :license_dsv, required: false },
+          'license_ipc' => { key: :license_ipc, required: false },
+          'nameprefix' => { key: :name_prefix, required: false },
+          'nation' => { key: :nation, required: false },
+          'passport' => { key: :passport, required: false },
+          'status' => { key: :status, required: false },
+          'swrid' => { key: :swrid, required: false }
+        }.freeze
+
+        ATTRIBUTE_KEYS = ATTRIBUTES.values.map { |definition| definition[:key] }.freeze
+        private_constant :ATTRIBUTE_KEYS
+
+        ATTRIBUTE_KEYS.each { |attribute| attr_reader attribute }
+        attr_reader :handicap, :entries, :results
+
+        def initialize(handicap: nil, entries: [], results: [], **attributes)
+          ATTRIBUTES.each_value do |definition|
+            key = definition[:key]
+            instance_variable_set(:"@#{key}", attributes[key])
+          end
+          @handicap = handicap
+          @entries = Array(entries)
+          @results = Array(results)
+        end
+
+        def self.from_xml(element)
+          raise ::Lenex::Parser::ParseError, 'ATHLETE element is required' unless element
+
+          attributes = extract_attributes(element)
+          handicap = Handicap.from_xml(element.at_xpath('HANDICAP'))
+          entries = extract_entries(element.at_xpath('ENTRIES'))
+          results = extract_results(element.at_xpath('RESULTS'))
+
+          new(**attributes, handicap:, entries:, results:)
+        end
+
+        def self.extract_attributes(element)
+          ATTRIBUTES.each_with_object({}) do |(attribute_name, definition), collected|
+            value = element.attribute(attribute_name)&.value
+            ensure_required_attribute!(attribute_name, definition, value)
+            collected[definition[:key]] = value if value
+          end
+        end
+        private_class_method :extract_attributes
+
+        def self.ensure_required_attribute!(attribute_name, definition, value)
+          return unless definition[:required]
+          return unless value.nil? || value.strip.empty?
+
+          message = "ATHLETE #{attribute_name} attribute is required"
+          raise ::Lenex::Parser::ParseError, message
+        end
+        private_class_method :ensure_required_attribute!
+
+        def self.extract_entries(collection_element)
+          return [] unless collection_element
+
+          collection_element.xpath('ENTRY').map do |entry_element|
+            Entry.from_xml(entry_element)
+          end
+        end
+        private_class_method :extract_entries
+
+        def self.extract_results(collection_element)
+          return [] unless collection_element
+
+          collection_element.xpath('RESULT').map do |result_element|
+            Result.from_xml(result_element)
+          end
+        end
+        private_class_method :extract_results
+      end
+    end
+  end
+end