lenex-parser 3.0.0

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    module Objects
+      # Value object representing a TIMESTANDARDLIST element.
+      class TimeStandardList
+        ATTRIBUTES = {
+          'course' => { key: :course, required: true },
+          'gender' => { key: :gender, required: true },
+          'handicap' => { key: :handicap, required: false },
+          'name' => { key: :name, required: true },
+          'timestandardlistid' => { key: :time_standard_list_id, required: true },
+          'type' => { key: :type, 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 :age_group, :time_standards
+
+        def initialize(age_group: nil, time_standards: [], **attributes)
+          ATTRIBUTES.each_value do |definition|
+            key = definition[:key]
+            instance_variable_set(:"@#{key}", attributes[key])
+          end
+          @age_group = age_group
+          @time_standards = Array(time_standards)
+        end
+
+        def self.from_xml(element)
+          raise ::Lenex::Parser::ParseError, 'TIMESTANDARDLIST element is required' unless element
+
+          attributes = extract_attributes(element)
+          ensure_required_attributes!(attributes)
+
+          age_group = age_group_from(element.at_xpath('AGEGROUP'))
+          time_standards = extract_time_standards(element.at_xpath('TIMESTANDARDS'))
+
+          new(**attributes, age_group:, time_standards:)
+        end
+
+        def self.extract_attributes(element)
+          ATTRIBUTES.each_with_object({}) do |(attribute_name, definition), collected|
+            value = element.attribute(attribute_name)&.value
+            collected[definition[:key]] = value if value
+          end
+        end
+        private_class_method :extract_attributes
+
+        def self.ensure_required_attributes!(attributes)
+          REQUIRED_ATTRIBUTE_KEYS.each do |key|
+            value = attributes[key]
+            next unless value.nil? || value.strip.empty?
+
+            message = "TIMESTANDARDLIST #{ATTRIBUTE_NAME_FOR.fetch(key)} attribute is required"
+            raise ::Lenex::Parser::ParseError, message
+          end
+        end
+        private_class_method :ensure_required_attributes!
+
+        REQUIRED_ATTRIBUTE_KEYS = %i[
+          course
+          gender
+          name
+          time_standard_list_id
+        ].freeze
+        private_constant :REQUIRED_ATTRIBUTE_KEYS
+
+        ATTRIBUTE_NAME_FOR = ATTRIBUTES.each_with_object({}) do |attribute, mapping|
+          attribute_name, definition = attribute
+          mapping[definition[:key]] = attribute_name
+        end.freeze
+        private_constant :ATTRIBUTE_NAME_FOR
+
+        def self.age_group_from(element)
+          return unless element
+
+          AgeGroup.from_xml(element)
+        end
+        private_class_method :age_group_from
+
+        def self.extract_time_standards(collection_element)
+          unless collection_element
+            message = 'TIMESTANDARDLIST TIMESTANDARDS element is required'
+            raise ::Lenex::Parser::ParseError, message
+          end
+
+          collection_element.xpath('TIMESTANDARD').map do |time_standard_element|
+            TimeStandard.from_xml(time_standard_element)
+          end
+        end
+        private_class_method :extract_time_standards
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    module Objects
+      # Value object representing a TIMESTANDARDREF element.
+      class TimeStandardRef
+        ATTRIBUTES = {
+          'timestandardlistid' => { key: :time_standard_list_id, required: true },
+          'marker' => { key: :marker, 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 :fee
+
+        def initialize(fee: nil, **attributes)
+          ATTRIBUTES.each_value do |definition|
+            key = definition[:key]
+            instance_variable_set(:"@#{key}", attributes[key])
+          end
+          @fee = fee
+        end
+
+        def self.from_xml(element)
+          raise ::Lenex::Parser::ParseError, 'TIMESTANDARDREF element is required' unless element
+
+          attributes = extract_attributes(element)
+          fee = fee_from(element.at_xpath('FEE'))
+
+          new(**attributes, fee:)
+        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 = "TIMESTANDARDREF #{attribute_name} attribute is required"
+          raise ::Lenex::Parser::ParseError, message
+        end
+        private_class_method :ensure_required_attribute!
+
+        def self.fee_from(element)
+          return unless element
+
+          Fee.from_xml(element)
+        end
+        private_class_method :fee_from
+      end
+    end
+  end
+end

data/lib/lenex/parser/objects.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    # Namespace for parser value objects.
+    module Objects
+    end
+  end
+end
+
+require_relative 'objects/age_date'
+require_relative 'objects/age_group'
+require_relative 'objects/athlete'
+require_relative 'objects/bank'
+require_relative 'objects/club'
+require_relative 'objects/contact'
+require_relative 'objects/constructor'
+require_relative 'objects/entry'
+require_relative 'objects/entry_schedule'
+require_relative 'objects/event'
+require_relative 'objects/facility'
+require_relative 'objects/fee'
+require_relative 'objects/fee_schedule'
+require_relative 'objects/handicap'
+require_relative 'objects/heat'
+require_relative 'objects/host_club'
+require_relative 'objects/judge'
+require_relative 'objects/lenex'
+require_relative 'objects/meet'
+require_relative 'objects/meet_info'
+require_relative 'objects/official'
+require_relative 'objects/organizer'
+require_relative 'objects/point_table'
+require_relative 'objects/pool'
+require_relative 'objects/qualify'
+require_relative 'objects/ranking'
+require_relative 'objects/record'
+require_relative 'objects/record_athlete'
+require_relative 'objects/record_list'
+require_relative 'objects/record_relay'
+require_relative 'objects/record_relay_position'
+require_relative 'objects/relay'
+require_relative 'objects/relay_entry'
+require_relative 'objects/relay_position'
+require_relative 'objects/relay_result'
+require_relative 'objects/result'
+require_relative 'objects/session'
+require_relative 'objects/split'
+require_relative 'objects/swim_style'
+require_relative 'objects/time_standard'
+require_relative 'objects/time_standard_list'
+require_relative 'objects/time_standard_ref'

data/lib/lenex/parser/sax/document_handler.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'nokogiri'
+
+module Lenex
+  module Parser
+    module Sax
+      # SAX document handler that streams Lenex XML into a {Lenex::Document}.
+      class DocumentHandler < Nokogiri::XML::SAX::Document
+        CAPTURED_ELEMENTS = {
+          'CONSTRUCTOR' => lambda do |element, document|
+            document.constructor = Objects::Constructor.from_xml(element)
+          end,
+          'MEET' => lambda do |element, document|
+            document.add_meet(Objects::Meet.from_xml(element))
+          end,
+          'RECORDLIST' => lambda do |element, document|
+            document.add_record_list(Objects::RecordList.from_xml(element))
+          end,
+          'TIMESTANDARDLIST' => lambda do |element, document|
+            document.add_time_standard_list(Objects::TimeStandardList.from_xml(element))
+          end
+        }.freeze
+
+        def initialize(document)
+          super()
+          @document = document
+          @capture = nil
+          @root_encountered = false
+        end
+
+        def start_document
+          @capture = nil
+          @root_encountered = false
+        end
+
+        def start_element(name, attrs = [])
+          handle_root(name, attrs)
+          append_start_tag(name, attrs)
+          start_capture(name, attrs) if CAPTURED_ELEMENTS.key?(name)
+        end
+
+        def characters(string)
+          append_text(string)
+        end
+
+        def cdata_block(string)
+          append_cdata(string)
+        end
+
+        def end_element(name)
+          finalize_capture(name)
+        end
+
+        def end_document
+          ensure_root_present!
+        end
+
+        private
+
+        attr_reader :document
+
+        def handle_root(name, attrs)
+          return if @root_encountered
+
+          raise ParseError, 'Root element must be LENEX' unless name == 'LENEX'
+
+          @root_encountered = true
+          attributes = attributes_from(attrs)
+          version = attributes['version']
+
+          if version.nil? || version.strip.empty?
+            raise ParseError, 'LENEX version attribute is required'
+          end
+
+          document.version = version
+          document.revision = attributes['revision'] if attributes.key?('revision')
+        end
+
+        def append_start_tag(name, attrs)
+          @capture&.start_tag(name, attrs)
+        end
+
+        def append_text(string)
+          return if string.nil? || string.empty?
+
+          @capture&.append_text(string)
+        end
+
+        def append_cdata(string)
+          return if string.nil?
+
+          @capture&.append_cdata(string)
+        end
+
+        def start_capture(name, attrs)
+          return if @capture
+
+          @capture = Capture.new(name)
+          @capture.start_tag(name, attrs)
+        end
+
+        def finalize_capture(name)
+          return unless @capture
+
+          @capture.end_tag(name)
+          return unless @capture.complete?
+
+          emit_capture(@capture)
+          @capture = nil
+        end
+
+        def ensure_root_present!
+          return if @root_encountered
+
+          raise ParseError, 'Root element must be LENEX'
+        end
+
+        def emit_capture(capture)
+          element = Nokogiri::XML::Document.parse(capture.to_xml) do |config|
+            config.strict.noblanks
+          end.root
+
+          handler = CAPTURED_ELEMENTS.fetch(capture.name)
+          handler.call(element, document)
+        end
+
+        def attributes_from(attrs)
+          attrs.each_with_object({}) do |(key, value), collected|
+            collected[key] = value
+          end
+        end
+
+        # Simple builder for captured subtrees.
+        class Capture
+          attr_reader :name
+
+          def initialize(name)
+            @name = name
+            @buffer = +''
+            @depth = 0
+          end
+
+          def start_tag(name, attrs)
+            @buffer << '<' << name
+            attrs.each do |attr_name, attr_value|
+              @buffer << ' ' << attr_name << '="' << escape_attribute(attr_value) << '"'
+            end
+            @buffer << '>'
+            @depth += 1
+          end
+
+          def end_tag(name)
+            @buffer << '</' << name << '>'
+            @depth -= 1
+          end
+
+          def append_text(string)
+            @buffer << CGI.escapeHTML(string)
+          end
+
+          def append_cdata(string)
+            @buffer << '<![CDATA[' << string << ']]>'
+          end
+
+          def complete?
+            @depth.zero?
+          end
+
+          def to_xml
+            @buffer
+          end
+
+          private
+
+          def escape_attribute(value)
+            CGI.escapeHTML(value.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lenex/parser/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Lenex
+  module Parser
+    # Current version of the lenex-parser gem.
+    VERSION = '3.0.0'
+  end
+end

data/lib/lenex/parser/zip_source.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Lenex
+  module Parser
+    # Utility helpers for reading XML payloads embedded in ZIP archives.
+    module ZipSource
+      extend self
+
+      SIGNATURE = "PK\x03\x04".b
+      INSTALL_MESSAGE = 'ZIP archives require the rubyzip gem. ' \
+                        'Install it with `gem install rubyzip` and try again.'
+      MISSING_XML_MESSAGE = 'Lenex archive does not contain a .lef or .xml payload'
+
+      def extract(io)
+        ensure_rubyzip!
+
+        payload = xml_payload_from(io)
+        return build_io(payload) if payload
+
+        raise Lenex::Parser::Error, MISSING_XML_MESSAGE
+      rescue Zip::Error => e
+        raise Lenex::Parser::Error, "Unable to read Lenex archive: #{e.message}"
+      ensure
+        reset_io(io)
+      end
+
+      private
+
+      def ensure_rubyzip!
+        require 'zip'
+      rescue LoadError
+        raise Lenex::Parser::Error, INSTALL_MESSAGE
+      end
+
+      def xml_payload_from(io)
+        reset_io(io)
+        payload = read_with_input_stream(io)
+        return payload if payload
+
+        reset_io(io)
+        read_with_file(io)
+      end
+
+      def read_with_input_stream(io)
+        Zip::InputStream.open(io) do |zip|
+          while (entry = zip.get_next_entry)
+            next unless xml_entry?(entry)
+
+            return zip.read
+          end
+        end
+        nil
+      end
+
+      def read_with_file(io)
+        data = buffered_zip_data(io)
+        return if data.empty?
+
+        Zip::File.open_buffer(data) do |zip|
+          zip.each do |entry|
+            next unless xml_entry?(entry)
+
+            return entry.get_input_stream.read
+          end
+        end
+        nil
+      end
+
+      def buffered_zip_data(io)
+        raw_data = io.read
+        return '' if raw_data.nil? || raw_data.empty?
+
+        raw_data.dup.tap { |buffer| buffer.force_encoding(Encoding::BINARY) }
+      end
+
+      def xml_entry?(entry)
+        return false if entry.nil?
+        return false if entry.respond_to?(:directory?) && entry.directory?
+
+        name = entry.name
+        return false if name.nil? || name.empty?
+
+        name.downcase.end_with?('.lef', '.xml')
+      end
+
+      def build_io(payload)
+        if payload.nil? || payload.empty?
+          raise Lenex::Parser::Error, 'Lenex archive is missing XML payload'
+        end
+
+        binary_payload = payload.dup
+        binary_payload.force_encoding(Encoding::BINARY)
+
+        StringIO.new(binary_payload).tap do |xml_io|
+          xml_io.binmode if xml_io.respond_to?(:binmode)
+          xml_io.rewind if xml_io.respond_to?(:rewind)
+        end
+      end
+
+      def reset_io(io)
+        return unless io.respond_to?(:rewind)
+
+        io.rewind
+      rescue IOError
+        nil
+      end
+    end
+  end
+end

data/lib/lenex/parser.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'stringio'
+
+require_relative 'parser/version'
+require_relative 'parser/objects'
+require_relative 'parser/zip_source'
+require_relative 'parser/sax/document_handler'
+
+# Namespace for Lenex parsing functionality and data structures.
+module Lenex
+  # Lenex namespace for parser functionality.
+  module Parser
+    # Base error class for all parser-specific failures.
+    class Error < StandardError; end
+
+    # Error raised when the parser encounters invalid Lenex XML input.
+    class ParseError < Error; end
+
+    module_function
+
+    # Parses a Lenex XML document and returns an object model representing
+    # the LENEX root node. Accepts an IO-like object or a string containing
+    # the XML payload.
+    #
+    # @param source [#read, String] XML source to parse
+    # @return [Lenex::Parser::Objects::Lenex]
+    # @raise [Lenex::Parser::ParseError] when the payload is invalid
+    def parse(source)
+      io = ensure_io(source)
+      document = ::Lenex::Document.new
+      handler = Sax::DocumentHandler.new(document)
+      parser = Nokogiri::XML::SAX::Parser.new(handler)
+
+      parser.parse(io)
+      document.build_lenex
+    rescue ParseError
+      raise
+    rescue Nokogiri::XML::SyntaxError => e
+      raise ParseError, e.message
+    end
+
+    # Normalizes the provided source so Nokogiri can consume it as an IO.
+    #
+    # @param source [#read, String]
+    # @return [#read] an IO-like object ready for Nokogiri
+    def ensure_io(source)
+      io = normalize_source(source)
+
+      return ZipSource.extract(io) if zip_archive?(io)
+
+      io
+    end
+    private_class_method :ensure_io
+
+    def normalize_source(source)
+      io = if source.respond_to?(:read)
+             ensure_binmode(source)
+           elsif path_argument?(source)
+             open_path(source)
+           else
+             string_io_for(source)
+           end
+
+      ensure_rewindable_io(io)
+    end
+    private_class_method :normalize_source
+
+    def path_argument?(source)
+      return false unless path_like?(source)
+      return false if SourceClassifier.xml_payload?(source)
+      return false if SourceClassifier.zip_payload?(source)
+
+      true
+    end
+    private_class_method :path_argument?
+
+    def ensure_binmode(stream)
+      stream.tap { |io| io.binmode if io.respond_to?(:binmode) }
+    end
+    private_class_method :ensure_binmode
+
+    def path_like?(source)
+      path = extract_path(source)
+      return false unless path
+
+      ::File.file?(path) && ::File.readable?(path)
+    rescue TypeError
+      false
+    end
+    private_class_method :path_like?
+
+    def open_path(source)
+      path = extract_path(source)
+      ::File.open(path, 'rb')
+    end
+    private_class_method :open_path
+
+    def string_io_for(source)
+      StringIO.new(String(source)).tap do |string_io|
+        string_io.binmode if string_io.respond_to?(:binmode)
+      end
+    end
+    private_class_method :string_io_for
+
+    def extract_path(source)
+      path = if source.respond_to?(:to_path)
+               source.to_path
+             elsif source.is_a?(String)
+               source
+             end
+
+      return unless path
+      return if path.include?("\0")
+
+      path
+    end
+    private_class_method :extract_path
+
+    def zip_archive?(io)
+      read_signature(io) == ZipSource::SIGNATURE
+    end
+    private_class_method :zip_archive?
+
+    def read_signature(io)
+      signature = (io.read(ZipSource::SIGNATURE.length) || '').b
+      io.rewind
+      signature
+    end
+    private_class_method :read_signature
+
+    def ensure_rewindable_io(io)
+      return io if io.respond_to?(:rewind)
+
+      buffered = +''
+      while (chunk = io.read(4_096))
+        buffered << chunk
+      end
+
+      StringIO.new(buffered).tap do |buffered_io|
+        buffered_io.binmode if buffered_io.respond_to?(:binmode)
+      end
+    end
+    private_class_method :ensure_rewindable_io
+  end
+end
+
+module Lenex
+  module Parser
+    # Internal heuristics for deciding whether a value is a filesystem path or
+    # inline XML/ZIP payload.
+    module SourceClassifier
+      module_function
+
+      def xml_payload?(source)
+        payload = String(source)
+        bytes = payload.b
+        bytes = strip_utf8_bom(bytes)
+        stripped = bytes.lstrip
+
+        stripped.start_with?('<')
+      rescue Encoding::CompatibilityError, TypeError
+        false
+      end
+
+      def zip_payload?(source)
+        bytes = String(source).b
+
+        bytes.start_with?(ZipSource::SIGNATURE)
+      rescue Encoding::CompatibilityError, TypeError
+        false
+      end
+
+      def strip_utf8_bom(bytes)
+        return bytes unless bytes.start_with?("\xEF\xBB\xBF".b)
+
+        bytes.byteslice(3, bytes.bytesize - 3) || ''.b
+      end
+      module_function :strip_utf8_bom
+      private_class_method :strip_utf8_bom
+    end
+  end
+end