dsv7-parser 7.0.0 → 7.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46a266cb139c92c4211efbec9a9675f72615b37a0a93bda512193e307f2965c4
-  data.tar.gz: c53949825909b9261ba0a2f49a462bc55a2223feb8829e220d33c5c2251de243
+  metadata.gz: bb8097275fb6859296653a95615ebd304fcb53a36436118946b60e035b3ccdaf
+  data.tar.gz: cc2693be6d15b7cc2654bf378f3288cd87782ec40bc4b04c5f66c52dcdaf26c3
 SHA512:
-  metadata.gz: d2e86049d2d517aa43733f222bd81c76938f8175022d8377c79cb1df74dc71a6eaad192a5b1bc8a979f9b3eb4f9bdfa4d80d7a92632681f704860f6b0f755fd3
-  data.tar.gz: a3d348801f8ba8c4a95be3e707ff5199399f3b626b2b8084fa8c33efa419f3597ff83a172bc9f2f3ee8dcfff4591f91b2244e929e7e4df7306fe7b92796f0d32
+  metadata.gz: f705afebef80f7863205632454a92f5bd2b5c910c8df0ec94ae684bcb3c9b6bc36f4afe8c887a57e537eea3b223525c8fff66e43acb007c773b179cccacb9025
+  data.tar.gz: 13628c729df524abc3a5eb2cbb9378fd76845a6cf8f258e9ef24612dcf64d9c1b22f98b96c0bf18757851513367949b91ba3b439476f0c88a328c16ea1879faf

data/README.md

@@ -103,21 +103,85 @@ vml_result = Dsv7::Validator.validate(vml)
 puts vml_result.valid?    # => true
 ```
 
-Validated VML elements: ERZEUGER, VERANSTALTUNG, ABSCHNITT, WETTKAMPF, VEREIN,
-ANSPRECHPARTNER, KARIMELDUNG, KARIABSCHNITT, TRAINER, PNMELDUNG, HANDICAP,
-STARTPN, STMELDUNG, STARTST, STAFFELPERSON.
-
-Validated WKDL elements: ERZEUGER, VERANSTALTUNG, VERANSTALTUNGSORT, AUSSCHREIBUNGIMNETZ,
-VERANSTALTER, AUSRICHTER, MELDEADRESSE, MELDESCHLUSS, BANKVERBINDUNG, BESONDERES,
-NACHWEIS, ABSCHNITT, WETTKAMPF, WERTUNG, MELDEGELD.
-
-Validated ERG elements: ERZEUGER, VERANSTALTUNG, VERANSTALTER, AUSRICHTER, ABSCHNITT,
-KAMPFGERICHT, WETTKAMPF, WERTUNG, VEREIN, PNERGEBNIS, PNZWISCHENZEIT, PNREAKTION,
-STAFFELERGEBNIS/STERGEBNIS, STAFFELPERSON, STZWISCHENZEIT, STABLOESE.
-
-Validated VRL elements: ERZEUGER, VERANSTALTUNG, VERANSTALTER, AUSRICHTER, ABSCHNITT,
-KAMPFGERICHT, WETTKAMPF, WERTUNG, VEREIN, PERSON, PERSONENERGEBNIS, PNZWISCHENZEIT,
-PNREAKTION, STAFFEL, STAFFELPERSON, STAFFELERGEBNIS/STERGEBNIS, STZWISCHENZEIT, STABLOESE.
+## Validated elements
+
+WKDL (Wettkampfdefinitionsliste)
+
+- `ERZEUGER`
+- `VERANSTALTUNG`
+- `VERANSTALTUNGSORT`
+- `AUSSCHREIBUNGIMNETZ`
+- `VERANSTALTER`
+- `AUSRICHTER`
+- `MELDEADRESSE`
+- `MELDESCHLUSS`
+- `BANKVERBINDUNG`
+- `BESONDERES`
+- `NACHWEIS`
+- `ABSCHNITT`
+- `WETTKAMPF`
+- `WERTUNG`
+- `MELDEGELD`
+
+VML (Vereinsmeldeliste)
+
+- `ERZEUGER`
+- `VERANSTALTUNG`
+- `ABSCHNITT`
+- `WETTKAMPF`
+- `VEREIN`
+- `ANSPRECHPARTNER`
+- `KARIMELDUNG`
+- `KARIABSCHNITT`
+- `TRAINER`
+- `PNMELDUNG`
+- `HANDICAP`
+- `STARTPN`
+- `STMELDUNG`
+- `STARTST`
+- `STAFFELPERSON`
+
+ERG (Wettkampfergebnisliste)
+
+- `ERZEUGER`
+- `VERANSTALTUNG`
+- `VERANSTALTER`
+- `AUSRICHTER`
+- `ABSCHNITT`
+- `KAMPFGERICHT`
+- `WETTKAMPF`
+- `WERTUNG`
+- `VEREIN`
+- `PNERGEBNIS`
+- `PNZWISCHENZEIT`
+- `PNREAKTION`
+- `STAFFELERGEBNIS`
+- `STERGEBNIS`
+- `STAFFELPERSON`
+- `STZWISCHENZEIT`
+- `STABLOESE`
+
+VRL (Vereinsergebnisliste)
+
+- `ERZEUGER`
+- `VERANSTALTUNG`
+- `VERANSTALTER`
+- `AUSRICHTER`
+- `ABSCHNITT`
+- `KAMPFGERICHT`
+- `WETTKAMPF`
+- `WERTUNG`
+- `VEREIN`
+- `PERSON`
+- `PERSONENERGEBNIS`
+- `PNZWISCHENZEIT`
+- `PNREAKTION`
+- `STAFFEL`
+- `STAFFELPERSON`
+- `STAFFELERGEBNIS`
+- `STERGEBNIS`
+- `STZWISCHENZEIT`
+- `STABLOESE`
 
 Common error and warning examples:
 

data/Rakefile

@@ -3,6 +3,7 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
+require 'rdoc/task'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
@@ -22,3 +23,11 @@ task lint: :rubocop
 
 desc 'CI: run tests and lint'
 task ci: %i[test lint]
+
+desc 'Generate RDoc documentation into doc/'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.main = 'README.md'
+  rdoc.title = 'dsv7-parser'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+end

data/dsv7-parser.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['maintheme@gmail.com']
 
   spec.summary       = 'SAX parser for the DSV7 swim file format'
-  spec.description   = 'Ruby gem for a DSV7 SAX parser.'
+  spec.description   = 'Ruby gem for a SAX parser targeting the DSV7 swim file format'
   spec.homepage      = 'https://github.com/bigcurl/dsv7-parser'
   spec.license       = 'MIT'
 
@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
   spec.metadata['changelog_uri'] = spec.homepage
+  spec.metadata['documentation_uri'] = 'https://www.rubydoc.info/gems/dsv7-parser'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
@@ -26,6 +27,9 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ['lib']
 
+  # Include top-level docs in packaged RDoc
+  spec.extra_rdoc_files = ['README.md', 'LICENSE']
+
   # Runtime dependencies (none yet)
   # spec.add_dependency "nokogiri", ">= 1.14"
 

data/lib/dsv7/lex.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# Lexical helpers for simple DSV7 tokens.
+#
+# - `parse_format(line)` extracts the list type and version from an exact
+#   `FORMAT:<Listentyp>;<Version>;` line.
+# - `element(content)` splits an element line into its name and attributes.
+#
+# These functions are intentionally minimal and do not perform semantic checks.
+
 module Dsv7
   module Lex
     module_function

data/lib/dsv7/parser/engine.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Internal streaming engine used by `Dsv7::Parser`.
+#
+# Converts an input (path/IO/String) into a stream of parser events. It
+# performs the same line normalization as the validator (via Stream/IoUtil),
+# strips inline comments, and stops emitting at `DATEIENDE`.
+
 require 'stringio'
 require_relative '../stream'
 require_relative '../lex'

data/lib/dsv7/parser/io_util.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Parser IO utilities.
+#
+# `to_io` converts supported inputs to an IO; `with_io` manages lifetime
+# and applies Stream normalization; `each_content_line` yields non‑empty,
+# comment‑stripped content lines with 1‑based line numbers.
+
 require 'stringio'
 require_relative '../stream'
 

data/lib/dsv7/parser/version.rb

@@ -2,6 +2,6 @@
 
 module Dsv7
   module Parser
-    VERSION = '7.0.0'
+    VERSION = '7.0.1'
   end
 end

data/lib/dsv7/parser.rb

@@ -1,5 +1,33 @@
 # frozen_string_literal: true
 
+# 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).
+#
+# Usage
+#   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.
+
 require_relative 'parser/version'
 require_relative 'parser/engine'
 require_relative 'validator'

data/lib/dsv7/stream.rb

@@ -1,5 +1,14 @@
 # frozen_string_literal: true
 
+# 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.
+
 module Dsv7
   module Stream
     module_function

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

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
+# 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.
+
 require_relative '../stream'
 require_relative '../lex'
 require_relative 'line_analyzer'

data/lib/dsv7/validator/line_analyzer.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+# 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 `Result` instance.
+
 require_relative '../stream'
 require_relative 'line_analyzer_common'
 require_relative 'schemas/wk_schema'

data/lib/dsv7/validator/line_analyzer_common.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# List‑specific analyzer mixins
+#
+# These modules encapsulate per‑list tracking and validation methods used by
+# 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
+
 require_relative '../lex'
 require_relative 'cardinality'
 

data/lib/dsv7/validator/result.rb

@@ -1,5 +1,15 @@
 # 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

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

@@ -1,5 +1,22 @@
 # frozen_string_literal: true
 
+# 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.
+
 module Dsv7
   class Validator
     class SchemaBase

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

@@ -5,7 +5,9 @@ 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).
     class ErgSchema < SchemaBase
       include WkTypeChecks
 

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

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

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

@@ -5,7 +5,9 @@ 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).
     class VrlSchema < SchemaBase
       include WkTypeChecks
 

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

@@ -5,7 +5,10 @@ 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.
     class WkSchema < SchemaBase
       include WkTypeChecks
 

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

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# 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
+
 module Dsv7
   class Validator
     module WkTypeChecksCommon

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

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+# 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)
+
 require 'date'
 
 module Dsv7

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# 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.
+
 module Dsv7
   class Validator
     module WkTypeChecksEnums1

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# 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.
+
 module Dsv7
   class Validator
     module WkTypeChecksEnums2

data/lib/dsv7/validator/types.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# 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.
+
 require_relative 'types/common'
 require_relative 'types/datetime'
 require_relative 'types/enums1'

data/lib/dsv7/validator.rb

@@ -1,5 +1,41 @@
 # frozen_string_literal: true
 
+# Dsv7::Validator
+#
+# Validates DSV7 files (German Swimming Federation “Format 7”) against a
+# pragmatic subset of the official specification. The validator focuses on
+# high‑level envelope rules (FORMAT/DATEIENDE, encoding, comments, delimiters),
+# filename hints, element cardinalities, and per‑element attribute types for all
+# four supported list types (WKDL, VML, ERG, VRL).
+#
+# Intent
+# - Provide fast, streaming validation without external dependencies.
+# - Produce precise, stable error and warning messages suitable for tooling and
+#   tests (see `test/dsv7/*`).
+# - Keep responsibilities narrow: structural checks here; parsing in
+#   `Dsv7::Parser`.
+#
+# Public API
+# - `.validate(input) -> Dsv7::Validator::Result`
+#   Accepts a file path String, an IO, or a content String (streamed via
+#   StringIO). Always returns a `Result` object with `errors`, `warnings`,
+#   `list_type`, `version`, and `valid?`.
+#
+# Examples
+#   result = Dsv7::Validator.validate('2024-01-01-Example-Wk.DSV7')
+#   result.valid?        # => true/false
+#   result.errors        # => ["..."]
+#   result.warnings      # => ["..."]
+#   result.list_type     # => 'Wettkampfdefinitionsliste' (after FORMAT)
+#   result.version       # => '7'
+#
+# Writing good docs for new checks
+# - State the rule’s purpose and scope (what it enforces, and why).
+# - Describe inputs/outputs and when an error vs. warning is emitted.
+# - Keep messages actionable and stable; include line numbers where helpful.
+# - Reference spec sections or examples in commit messages or tests.
+# - Add both accept and reject tests under `test/dsv7/`.
+
 require 'stringio'
 require_relative 'validator/result'
 require_relative 'validator/core'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsv7-parser
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.0.1
 platform: ruby
 authors:
 - bigcurl
@@ -9,12 +9,14 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Ruby gem for a DSV7 SAX parser.
+description: Ruby gem for a SAX parser targeting the DSV7 swim file format
 email:
 - maintheme@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- LICENSE
+- README.md
 files:
 - ".gitignore"
 - ".rubocop.yml"
@@ -57,6 +59,7 @@ metadata:
   homepage_uri: https://github.com/bigcurl/dsv7-parser
   source_code_uri: https://github.com/bigcurl/dsv7-parser
   changelog_uri: https://github.com/bigcurl/dsv7-parser
+  documentation_uri: https://www.rubydoc.info/gems/dsv7-parser
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: