dsv7-parser 7.0.0 → 7.0.2

data/lib/dsv7/parser.rb

@@ -7,14 +7,64 @@ require_relative 'stream'
 require_relative 'lex'
 
 module Dsv7
+  ##
+  # Dsv7::Parser
+  #
+  # Streaming parser for DSV7 lists. It yields a simple event stream so callers
+  # can build their own structures without loading the whole file into memory.
+  # The parser is intentionally tolerant (e.g., it scrubs invalid UTF‑8 and
+  # accepts BOM) — pair it with {Dsv7::Validator} for strict conformance.
+  #
+  # Events
+  # - `[:format, { list_type: String, version: String }, line_number]` — first
+  #   effective line must be a FORMAT line.
+  # - `[:element, { name: String, attrs: Array<String> }, line_number]` — for
+  #   each element line between FORMAT and DATEIENDE.
+  # - `[:end, nil, line_number]` — emitted after `DATEIENDE` (or EOF if missing).
+  #
+  # @api public
+  # @since 7.0.0
+  # @example Enumerate events for any list type
+  #   Dsv7::Parser.parse(io_or_path_or_string) do |type, payload, ln|
+  #     case type
+  #     when :format  then # inspect payload[:list_type], payload[:version]
+  #     when :element then # payload[:name], payload[:attrs]
+  #     when :end     then # done
+  #     end
+  #   end
+  #
+  # Documenting new helpers
+  # - Describe when a helper raises (e.g., wrong list type for a type‑specific
+  #   parser) and what it yields.
+  # - Note streaming/encoding behavior and that comments are stripped inline.
   module Parser
+    # Error type raised by the parser when the input
+    # does not satisfy basic envelope expectations.
     class Error < StandardError; end
 
+    # @!group Parsers
+    #
     # Generic streaming parser that auto-detects the list type from the
     # first effective FORMAT line and yields events for any DSV7 list.
-    # Yields [:format|:element|:end, payload, line_number].
-    # The first event is always :format with payload
-    #   { list_type: <String>, version: <String> }.
+    #
+    # The first event is always `:format` with payload
+    # `{ list_type: <String>, version: <String> }`.
+    #
+    # @api public
+    # @since 7.0.0
+    # @overload parse(input, &block)
+    #   @param input [IO, String] An IO, a file path String, or a String with file content
+    #   @yield [type, payload, line_number] Emitted for each event
+    #   @yieldparam type [Symbol] Event type (:format, :element, :end)
+    #   @yieldparam payload [Hash, nil] Event payload
+    #   @yieldparam line_number [Integer] 1-based line number of the event
+    #   @return [void]
+    # @overload parse(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator] Enumerator over `[type, payload, line_number]`
+    # @see Dsv7::Validator
+    # @raise [Dsv7::Parser::Error] when the first effective line is not FORMAT
+    # @raise [ArgumentError] if the input type is unsupported
     def self.parse(input, &block)
       enum = Enumerator.new { |y| Engine.stream_any(input, y) }
       return enum.each(&block) if block_given?
@@ -23,8 +73,23 @@ module Dsv7
     end
 
     # Streaming parser for Wettkampfdefinitionsliste (WKDL).
-    # Yields [:format|:element|:end, payload, line_number].
     # Performs inline comment stripping, tolerates BOM, and scrubs UTF-8.
+    #
+    # @api public
+    # @since 7.0.0
+    # @overload parse_wettkampfdefinitionsliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @yieldparam type [Symbol] Event type (:format, :element, :end)
+    #   @yieldparam payload [Hash, nil]
+    #   @yieldparam line_number [Integer]
+    #   @return [void]
+    # @overload parse_wettkampfdefinitionsliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not WKDL
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_wettkampfdefinitionsliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Wettkampfdefinitionsliste') }
       return enum.each(&block) if block_given?
@@ -33,8 +98,20 @@ module Dsv7
     end
 
     # Streaming parser for Vereinsmeldeliste (VML).
-    # Same contract as parse_wettkampfdefinitionsliste, but expects
-    # FORMAT:Vereinsmeldeliste;7; as the first effective line.
+    # Same contract as {parse_wettkampfdefinitionsliste}, but expects
+    # `FORMAT:Vereinsmeldeliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_vereinsmeldeliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_vereinsmeldeliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not VML
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_vereinsmeldeliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Vereinsmeldeliste') }
       return enum.each(&block) if block_given?
@@ -44,7 +121,19 @@ module Dsv7
 
     # Streaming parser for Wettkampfergebnisliste (ERG).
     # Same contract as the other parse_* methods, but expects
-    # FORMAT:Wettkampfergebnisliste;7; as the first effective line.
+    # `FORMAT:Wettkampfergebnisliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_wettkampfergebnisliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_wettkampfergebnisliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not ERG
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_wettkampfergebnisliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Wettkampfergebnisliste') }
       return enum.each(&block) if block_given?
@@ -54,13 +143,26 @@ module Dsv7
 
     # Streaming parser for Vereinsergebnisliste (VRL).
     # Same contract as the other parse_* methods, but expects
-    # FORMAT:Vereinsergebnisliste;7; as the first effective line.
+    # `FORMAT:Vereinsergebnisliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_vereinsergebnisliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_vereinsergebnisliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not VRL
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_vereinsergebnisliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Vereinsergebnisliste') }
       return enum.each(&block) if block_given?
 
       enum
     end
+    # @!endgroup
     # no additional private class methods
   end
 end

data/lib/dsv7/stream.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
 module Dsv7
+  ##
+  # Low‑level IO helpers for streaming DSV7 content.
+  #
+  # Responsibilities
+  # - Binary mode, BOM detection, and UTF‑8 normalization.
+  # - Per‑line sanitization and CR/LF handling.
+  # - Inline single‑line comment removal using the `(* ... *)` syntax.
+  #
+  # These helpers are shared by both the validator and the parser.
+  #
+  # @api private
   module Stream
     module_function
 
     # Puts IO into binary mode when possible (no-op for StringIO)
+    # @param io [IO]
+    # @return [void]
     def binmode_if_possible(io)
       io.binmode
     rescue StandardError
@@ -14,6 +27,8 @@ module Dsv7
     # Reads potential UTF-8 BOM from the start of IO.
     # Returns true if a BOM was found (and consumed), false otherwise.
     # If no BOM was found, unread the peeked bytes back into the IO.
+    # @param io [IO]
+    # @return [Boolean]
     def read_bom?(io)
       head = io.read(3)
       return false if head.nil? || head.empty?
@@ -29,6 +44,9 @@ module Dsv7
     # Normalizes a raw line by trimming trailing LF/CR and forcing UTF-8.
     # If invalid encoding is detected, it scrubs replacement chars and
     # calls the optional on_invalid callback.
+    # @param raw [String]
+    # @param on_invalid [Proc,nil]
+    # @return [String]
     def sanitize_line(raw, on_invalid: nil)
       s = raw.delete_suffix("\n").delete_suffix("\r")
       s.force_encoding(Encoding::UTF_8)
@@ -39,6 +57,8 @@ module Dsv7
     end
 
     # Removes inline single-line comments in the form: (* ... *)
+    # @param line [String]
+    # @return [String]
     def strip_inline_comment(line)
       return line unless line.include?('(*') && line.include?('*)')
 
@@ -47,6 +67,12 @@ module Dsv7
 
     # Iterates sanitized lines, yielding [line, line_number].
     # Returns true if any CRLF lines were observed.
+    # @param io [IO]
+    # @param on_invalid [Proc,nil]
+    # @yield [line, line_number]
+    # @yieldparam line [String]
+    # @yieldparam line_number [Integer]
+    # @return [Boolean] whether any CRLF lines were observed
     def each_sanitized_line(io, on_invalid: nil)
       had_crlf = false
       line_number = 0

data/lib/dsv7/validator/cardinality.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Element cardinality validation for each list type.
+#
+# Each validator receives the shared Result and a Hash of observed element
+# counts, then asserts required presence and max occurrences according to the
+# current understanding of the spec.
+
 module Dsv7
   class Validator
     # Validates Wettkampfdefinitionsliste element cardinalities

data/lib/dsv7/validator/core.rb

@@ -7,12 +7,30 @@ require_relative 'line_analyzer'
 module Dsv7
   class Validator
     # Core pipeline for validator: encoding + line parsing
+    ##
+    # Core validation pipeline.
+    #
+    # Implements the IO/line streaming for the validator:
+    # - puts IO in binary mode and detects BOM
+    # - normalizes lines to UTF‑8 and tracks CRLF presence
+    # - strips inline comments and delegates per‑line logic to LineAnalyzer
+    # - adds a filename warning if the provided path does not match the guidance
+    #
+    # Notes for maintainers
+    # - Keep this class side‑effect free beyond writing to `Result`.
+    # - Avoid accumulating state; process line‑by‑line to preserve streaming.
+    #
+    # @api private
     class Core
+      # @param result [Dsv7::Validator::Result]
+      # @param filename [String, nil]
       def initialize(result, filename)
         @result = result
         @filename = filename
       end
 
+      # @param io [IO]
+      # @return [Dsv7::Validator::Result]
       def call_io(io)
         Dsv7::Stream.binmode_if_possible(io)
         check_bom_and_rewind(io)

data/lib/dsv7/validator/line_analyzer.rb

@@ -9,12 +9,22 @@ require_relative 'schemas/vrl_schema'
 
 module Dsv7
   class Validator
+    ##
+    # Streaming line analyzer.
+    #
+    # Orchestrates validation once lines have been sanitized and comments stripped.
+    # Tracks the first effective FORMAT line, enforces the final DATEIENDE, and
+    # dispatches element lines to list‑specific schema/type checks and cardinality
+    # tracking. All findings are written into the shared {Dsv7::Validator::Result} instance.
+    #
+    # @api private
     class LineAnalyzer
       include LineAnalyzerWk
       include LineAnalyzerVml
       include LineAnalyzerErg
       include LineAnalyzerVrl
 
+      # @param result [Dsv7::Validator::Result]
       def initialize(result)
         @result = result
         @effective_index = 0
@@ -24,6 +34,7 @@ module Dsv7
         init_schemas_and_counters
       end
 
+      # Initialize schemas and element counters used during streaming.
       def init_schemas_and_counters
         @wk_elements = Hash.new(0)
         @wk_schema = WkSchema.new(@result)
@@ -35,9 +46,13 @@ module Dsv7
         @vrl_schema = VrlSchema.new(@result)
       end
 
+      # Process a raw input line with its 1-based line number.
+      # @param line [String]
+      # @param line_number [Integer]
+      # @return [void]
       def process_line(line, line_number)
         check_comment_balance(line, line_number)
-        trimmed = strip_inline_comment(line)
+        trimmed = Dsv7::Stream.strip_inline_comment(line).strip
         return if trimmed.empty?
 
         @effective_index += 1
@@ -47,6 +62,8 @@ module Dsv7
         handle_content_line(trimmed, line_number)
       end
 
+      # Finalize the analysis and run post/summary checks.
+      # @return [void]
       def finish
         post_validate_positions
         validate_wk_list_elements if @result.list_type == 'Wettkampfdefinitionsliste'
@@ -57,6 +74,9 @@ module Dsv7
 
       private
 
+      # Internal helper to set up schemas and counters
+      private :init_schemas_and_counters
+
       def check_comment_balance(line, line_number)
         return unless line.include?('(*') || line.include?('*)')
 
@@ -72,10 +92,6 @@ module Dsv7
         check_format_line(trimmed, line_number)
       end
 
-      def strip_inline_comment(line)
-        Dsv7::Stream.strip_inline_comment(line).strip
-      end
-
       def check_format_line(trimmed, line_number)
         m = Dsv7::Lex.parse_format(trimmed)
         return format_error(line_number) unless m

data/lib/dsv7/validator/line_analyzer_common.rb

@@ -7,6 +7,19 @@ module Dsv7
   class Validator
     # Handles line-by-line structural checks for WKDL-specific logic
     module LineAnalyzerWk
+      ##
+      # List‑specific analyzer mixins.
+      #
+      # These modules encapsulate per‑list tracking and validation methods used by
+      # {Dsv7::Validator::LineAnalyzer}. Each provides three responsibilities for its list type:
+      # - track_*_element: counts element occurrences for cardinality checks
+      # - validate_*_list_elements: validates the observed counts at finish
+      # - validate_*_line: validates a single element’s attributes via the schema
+      #
+      # @api private
+
+      private
+
       def track_wk_element(trimmed)
         return unless @result.list_type == 'Wettkampfdefinitionsliste'
 
@@ -39,6 +52,10 @@ module Dsv7
 
     # Handles line-by-line structural checks for VML-specific logic
     module LineAnalyzerVml
+      # @api private
+
+      private
+
       def track_vml_element(trimmed)
         return unless @result.list_type == 'Vereinsmeldeliste'
 
@@ -71,6 +88,10 @@ module Dsv7
 
     # Handles line-by-line checks for Wettkampfergebnisliste
     module LineAnalyzerErg
+      # @api private
+
+      private
+
       def track_erg_element(trimmed)
         return unless @result.list_type == 'Wettkampfergebnisliste'
 
@@ -105,6 +126,10 @@ module Dsv7
 
     # Handles line-by-line checks for Vereinsergebnisliste
     module LineAnalyzerVrl
+      # @api private
+
+      private
+
       def track_vrl_element(trimmed)
         return unless @result.list_type == 'Vereinsergebnisliste'
 

data/lib/dsv7/validator/result.rb

@@ -1,9 +1,31 @@
 # frozen_string_literal: true
 
+##
+# Validation result container.
+#
+# Collects errors and warnings during a validation run and exposes
+# `list_type`/`version` after a valid FORMAT line is seen. `valid?` is true
+# iff there are no errors; warnings never affect validity.
+#
+# Message stability
+# - Keep message texts stable where possible; tests rely on them.
+# - Include line numbers when relevant to aid debugging.
+
 module Dsv7
   class Validator
     # Result container for validation
+    #
+    # @api public
+    # @since 7.0.0
     class Result
+      # @!attribute [r] errors
+      #   @return [Array<String>] Collected human-readable error messages
+      # @!attribute [r] warnings
+      #   @return [Array<String>] Collected warnings; do not affect validity
+      # @!attribute [r] list_type
+      #   @return [String, nil] List type after parsing the FORMAT line
+      # @!attribute [r] version
+      #   @return [String, nil] Format version after parsing the FORMAT line
       attr_reader :errors, :warnings, :list_type, :version
 
       def initialize
@@ -13,19 +35,31 @@ module Dsv7
         @version = nil
       end
 
+      # Add an error message.
+      # @param message [String]
+      # @return [void]
       def add_error(message)
         @errors << message
       end
 
+      # Add a warning message.
+      # @param message [String]
+      # @return [void]
       def add_warning(message)
         @warnings << message
       end
 
+      # Set FORMAT metadata after a valid FORMAT line was observed.
+      # @param list_type [String]
+      # @param version [String]
+      # @return [void]
       def set_format(list_type, version)
         @list_type = list_type
         @version = version
       end
 
+      # Whether the validation run produced no errors.
+      # @return [Boolean]
       def valid?
         @errors.empty?
       end

data/lib/dsv7/validator/schemas/base.rb

@@ -2,11 +2,36 @@
 
 module Dsv7
   class Validator
+    ##
+    # Base class for per‑list schemas.
+    #
+    # A concrete schema class defines a `SCHEMAS` Hash mapping element names to an
+    # Array of attribute specs. Each attribute spec is a tuple:
+    #   `[type, required, opts=nil]`
+    # where `type` corresponds to a `check_<type>` method mixed in from the
+    # type‑check modules, `required` is a boolean, and `opts` can be used by a
+    # specific checker.
+    #
+    # Cross‑field/element rules may be implemented by overriding
+    # `validate_cross_rules(name, attrs, line_number)`.
+    #
+    # Documentation tips when adding/adjusting schemas:
+    # - Copy the attribute count and types from the spec and real‑world examples.
+    # - Clearly mark intentionally deferred or ambiguous elements in commit msgs.
+    # - Add both positive and negative tests for each element and datatype.
+    #
+    # @see specification/dsv7/dsv7_specification.md Specification reference
+    # @api private
     class SchemaBase
       def initialize(result)
         @result = result
       end
 
+      # Validate a single element against the schema map.
+      # @param name [String]
+      # @param attrs [Array<String>]
+      # @param line_number [Integer]
+      # @return [void]
       def validate_element(name, attrs, line_number)
         schema = self.class::SCHEMAS[name]
         return unless schema
@@ -33,6 +58,7 @@ module Dsv7
         end
       end
 
+      # @return [void]
       def add_error(msg)
         @result.add_error(msg)
       end

data/lib/dsv7/validator/schemas/erg_schema.rb

@@ -5,7 +5,11 @@ require_relative 'base'
 
 module Dsv7
   class Validator
-    # Validates Wettkampfergebnisliste attribute counts and datatypes
+    # Validates Wettkampfergebnisliste attribute counts and datatypes.
+    # Accepts synonymous element names found in the wild
+    # (e.g., STAFFELERGEBNIS/STERGEBNIS).
+    #
+    # @api private
     class ErgSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/vml_schema.rb

@@ -5,7 +5,9 @@ require_relative 'base'
 
 module Dsv7
   class Validator
-    # Validates Vereinsmeldeliste attribute counts and datatypes
+    # Validates Vereinsmeldeliste attribute counts and datatypes.
+    #
+    # @api private
     class VmlSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/vrl_schema.rb

@@ -5,7 +5,11 @@ require_relative 'base'
 
 module Dsv7
   class Validator
-    # Validates Vereinsergebnisliste attribute counts and datatypes
+    # Validates Vereinsergebnisliste attribute counts and datatypes.
+    # Accepts synonymous element names found in the wild
+    # (e.g., STAFFELERGEBNIS/STERGEBNIS).
+    #
+    # @api private
     class VrlSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/wk_schema.rb

@@ -5,7 +5,12 @@ require_relative 'base'
 
 module Dsv7
   class Validator
-    # Validates Wettkampfdefinitionsliste attribute counts and datatypes
+    # Validates Wettkampfdefinitionsliste attribute counts and datatypes.
+    #
+    # The `SCHEMAS` constant defines the exact attribute counts and types per
+    # element according to the current spec interpretation.
+    #
+    # @api private
     class WkSchema < SchemaBase
       include WkTypeChecks
 
@@ -49,6 +54,8 @@ module Dsv7
         'MELDEGELD' => [[:meldegeld_typ, true], [:betrag, true], [:zahl, false]]
       }.freeze
 
+      private
+
       def validate_cross_rules(name, attrs, line_number)
         return unless name == 'MELDEGELD'
 

data/lib/dsv7/validator/types/common.rb

@@ -2,7 +2,20 @@
 
 module Dsv7
   class Validator
+    ##
+    # Common datatype checks shared across lists.
+    #
+    # Implementations follow the spec’s informal definitions:
+    # - ZK: arbitrary UTF‑8 string (already scrubbed by the stream layer)
+    # - Zahl: integer (only digits)
+    # - Betrag: monetary amount in the form `x,yy`
+    # - Einzelstrecke: distance (1..25000) or 0 where permitted
+    #
+    # @see specification/dsv7/dsv7_specification.md Datatypes overview
+    # @api private
     module WkTypeChecksCommon
+      private
+
       def check_zk(_name, _index, _val, _line_number, _opts = nil)
         # any string (already UTF-8 scrubbed); nothing to do
       end

data/lib/dsv7/validator/types/datetime.rb

@@ -4,7 +4,19 @@ require 'date'
 
 module Dsv7
   class Validator
+    ##
+    # Date and time datatype checks.
+    #
+    # Enforces textual formats before validating value ranges:
+    # - Datum:    TT.MM.JJJJ (validated via Date.strptime)
+    # - Uhrzeit:  HH:MM      (0..23, 0..59)
+    # - Zeit:     HH:MM:SS,hh (0..23, 0..59, 0..59, 0..99)
+    #
+    # @see specification/dsv7/dsv7_specification.md Date/time formats
+    # @api private
     module WkTypeChecksDateTime
+      private
+
       def check_datum(name, idx, val, line_number, _opts = nil)
         return add_error(datum_format_error(name, idx, val, line_number)) unless
           val.match?(/^\d{2}\.\d{2}\.\d{4}$/)

data/lib/dsv7/validator/types/enums1.rb

@@ -2,7 +2,17 @@
 
 module Dsv7
   class Validator
+    ##
+    # Enum/group checks (part 1): Bahnlänge, Zeitmessung, Land, etc.
+    #
+    # These normalize expectations found in the spec and examples and produce
+    # actionable error messages that include allowed values.
+    #
+    # @see specification/dsv7/dsv7_specification.md Enumerations overview
+    # @api private
     module WkTypeChecksEnums1
+      private
+
       def check_bahnl(name, idx, val, line_number, _opts = nil)
         allowed = %w[16 20 25 33 50 FW X]
         return if allowed.include?(val)

data/lib/dsv7/validator/types/enums2.rb

@@ -2,7 +2,17 @@
 
 module Dsv7
   class Validator
+    ##
+    # Enum/group checks (part 2): Technik, Ausübung, Geschlecht, Wertungstyp,
+    # JG/AK, Meldegeldtypen, Reaktionsart, Nachtragskennzeichen, u. a.
+    #
+    # Keep allowed lists centralized here for clarity and reuse across schemas.
+    #
+    # @see specification/dsv7/dsv7_specification.md Enumerations overview
+    # @api private
     module WkTypeChecksEnums2
+      private
+
       def check_technik(name, idx, val, line_number, _opts = nil)
         return if %w[F R B S L X].include?(val)
 

data/lib/dsv7/validator/types.rb

@@ -7,6 +7,14 @@ require_relative 'types/enums2'
 
 module Dsv7
   class Validator
+    ##
+    # Aggregates type‑check mixins used by schemas.
+    #
+    # Each `check_<type>(name, index, value, line_number, opts)` method is
+    # expected to either accept the value or call `add_error(message)` on the
+    # including schema to record a validation error with context.
+    #
+    # @api private
     module WkTypeChecks
       include WkTypeChecksCommon
       include WkTypeChecksDateTime