dsv7-parser 7.0.0 → 7.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46a266cb139c92c4211efbec9a9675f72615b37a0a93bda512193e307f2965c4
-  data.tar.gz: c53949825909b9261ba0a2f49a462bc55a2223feb8829e220d33c5c2251de243
+  metadata.gz: c363432be089a4a08ccd0f9c1356b47c8a537436aebd5e75000d767dd8c531b6
+  data.tar.gz: 7683d1b49fe75fa94f0682db2dcc6720b31b250d5657f1171799630807c57248
 SHA512:
-  metadata.gz: d2e86049d2d517aa43733f222bd81c76938f8175022d8377c79cb1df74dc71a6eaad192a5b1bc8a979f9b3eb4f9bdfa4d80d7a92632681f704860f6b0f755fd3
-  data.tar.gz: a3d348801f8ba8c4a95be3e707ff5199399f3b626b2b8084fa8c33efa419f3597ff83a172bc9f2f3ee8dcfff4591f91b2244e929e7e4df7306fe7b92796f0d32
+  metadata.gz: 66254952933799a4d2f823b69731fda0c43a9509f7edfc96a26aac47a4a97b8677ecf4362e957c5b68aec2c4d6156f6276c824354f625449d48aede884ec7241
+  data.tar.gz: 9af9cae918a817ff1c1f927e577b84b01cddb903fc77ba364d97e86271d3a3835dd43bead77d808b8a79075d789c3c28967298e64411cd2b9e9b661f83945a6e

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--markup-provider kramdown
+--readme README.md
+--hide-api private
+lib/**/*.rb

data/Gemfile

@@ -12,4 +12,8 @@ end
 
 group :development do
   gem 'rubocop', require: false
+  # YARD is used for generating API documentation
+  gem 'yard', require: false
+  # Kramdown provides robust Markdown rendering for YARD
+  gem 'kramdown', require: false
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dsv7-parser (7.0.0)
+    dsv7-parser (7.0.1)
 
 GEM
   remote: https://rubygems.org/
@@ -9,6 +9,8 @@ GEM
     ast (2.4.3)
     docile (1.4.1)
     json (2.15.0)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     minitest (5.25.5)
@@ -21,6 +23,7 @@ GEM
     rainbow (3.1.1)
     rake (13.3.0)
     regexp_parser (2.11.3)
+    rexml (3.4.4)
     rubocop (1.81.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -45,6 +48,7 @@ GEM
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
+    yard (0.9.37)
 
 PLATFORMS
   ruby
@@ -52,10 +56,12 @@ PLATFORMS
 
 DEPENDENCIES
   dsv7-parser!
+  kramdown
   minitest (>= 5.18)
   rake (>= 13.0)
   rubocop
   simplecov
+  yard
 
 BUNDLED WITH
    2.7.2

data/README.md

@@ -14,18 +14,18 @@ Requirements
 
 Basic envelope checks plus element validation for all four list types (WKDL, VML, ERG, VRL) are available via one entrypoint:
 
-```
+~~~
 require 'dsv7/parser'
 
 # Pass a path, IO, or a String with file content
 result = Dsv7::Validator.validate('path/to/file.DSV7')
 
-puts "valid?     #{result.valid?}"
-puts "list_type: #{result.list_type}"
-puts "version:   #{result.version}"
-puts "errors:    #{result.errors.inspect}"
-puts "warnings:  #{result.warnings.inspect}"
-```
+puts 'valid?     ' + result.valid?.to_s
+puts 'list_type: ' + result.list_type.to_s
+puts 'version:   ' + result.version.to_s
+puts 'errors:    ' + result.errors.inspect
+puts 'warnings:  ' + result.warnings.inspect
+~~~
 
 Accepted inputs:
 
@@ -49,7 +49,7 @@ Filename guidance (when validating by path):
 
 Minimal example (generic list type):
 
-```
+~~~
 content = <<~DSV
   FORMAT:Vereinsmeldeliste;7;
   DATA;ok
@@ -58,11 +58,11 @@ DSV
 
 result = Dsv7::Validator.validate(content)
 puts result.valid? # => true
-```
+~~~
 
 Wettkampfdefinitionsliste validation (cardinality + attribute types):
 
-```
+~~~
 wkdl = <<~DSV
   FORMAT:Wettkampfdefinitionsliste;7;
   ERZEUGER:Soft;1.0;mail@example.com;
@@ -83,11 +83,11 @@ wk_result = Dsv7::Validator.validate(wkdl)
 puts wk_result.valid?      # => true
 puts wk_result.errors      # => []
 puts wk_result.warnings    # => []
-```
+~~~
 
 Vereinsmeldeliste validation (cardinality + attribute types):
 
-```
+~~~
 vml = <<~DSV
   FORMAT:Vereinsmeldeliste;7;
   ERZEUGER:Soft;1.0;mail@example.com;
@@ -101,27 +101,91 @@ DSV
 
 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:
 
-```
+~~~
 # 1) Unknown list type and missing DATEIENDE
 bad = "FORMAT:Unbekannt;7;\n"
 r = Dsv7::Validator.validate(bad)
@@ -154,7 +218,7 @@ begin
 ensure
   File.delete('tmp/badname.txt')
 end
-```
+~~~
 
 ## Parser (Streaming: WKDL, VML, ERG, VRL)
 
@@ -173,7 +237,7 @@ It is tolerant and focuses on extracting elements efficiently; use the validator
 
 Generic example (auto-detect list type):
 
-```
+~~~
 enum = Dsv7::Parser.parse('path/to/file.DSV7')
 enum.each do |type, payload, line_number|
   case type
@@ -185,7 +249,7 @@ enum.each do |type, payload, line_number|
     # reached DATEIENDE
   end
 end
-```
+~~~
 
 Key points:
 
@@ -196,7 +260,7 @@ Key points:
 
 Basic example (block style):
 
-```
+~~~
 require 'dsv7/parser'
 
 content = <<~DSV
@@ -220,20 +284,20 @@ Dsv7::Parser.parse(content) do |type, payload, line_number|
     p [:end, line_number]
   end
 end
-```
+~~~
 
 Enumerator style:
 
-```
+~~~
 enum = Dsv7::Parser.parse('path/to/2002-03-10-Duisburg-Wk.DSV7')
 enum.each do |type, payload, line_number|
   # same triplets as the block example
 end
-```
+~~~
 
 Building a simple structure (header + elements) from the stream:
 
-```
+~~~
 data = { format: nil, elements: [] }
 
 Dsv7::Parser.parse(content) do |type, payload, line_number|
@@ -249,24 +313,24 @@ end
 wettkaempfe = data[:elements]
   .select { |e| e[:name] == 'WETTKAMPF' }
   .map { |e| e[:attrs] } # arrays of attributes per row
-```
+~~~
 
 Combining validation with parsing:
 
-```
+~~~
 result = Dsv7::Validator.validate('path/to/file.DSV7')
 if result.valid?
   Dsv7::Parser.parse('path/to/file.DSV7') do |type, payload, line_number|
     # consume events
   end
 else
-  warn "Invalid DSV7: #{result.errors.join('; ')}"
+  warn 'Invalid DSV7: ' + result.errors.join('; ')
 end
-```
+~~~
 
 VML usage mirrors WKDL:
 
-```
+~~~
 content = <<~DSV
   FORMAT:Vereinsmeldeliste;7;
   ERZEUGER:Soft;1.0;mail@example.com;
@@ -281,11 +345,11 @@ DSV
 Dsv7::Parser.parse(content) do |type, payload, line_number|
   # same :format, :element, :end semantics
 end
-```
+~~~
 
 ERG usage mirrors WKDL as well:
 
-```
+~~~
 content = <<~DSV
   FORMAT:Wettkampfergebnisliste;7;
   ERZEUGER:Soft;1.0;mail@example.com;
@@ -299,11 +363,11 @@ DSV
 Dsv7::Parser.parse(content) do |type, payload, line_number|
   # same :format, :element, :end semantics
 end
-```
+~~~
 
 VRL usage mirrors WKDL as well:
 
-```
+~~~
 content = <<~DSV
   FORMAT:Vereinsergebnisliste;7;
   ERZEUGER:Soft;1.0;mail@example.com;
@@ -317,7 +381,7 @@ DSV
 Dsv7::Parser.parse(content) do |type, payload, line_number|
   # same :format, :element, :end semantics
 end
-```
+~~~
 
 Errors and edge cases:
 
@@ -332,11 +396,22 @@ Errors and edge cases:
 - Tests use Minitest and live under `test/dsv7/`.
 - Version is defined in `lib/dsv7/parser/version.rb`.
 
+## API Documentation (YARD)
+
+- Hosted docs (Rubydoc): https://www.rubydoc.info/gems/dsv7-parser
+- Generate locally: `bundle install && bundle exec rake yard`
+- Output is written to `doc/`.
+
+Notes:
+
+- Public API is focused on `Dsv7::Validator.validate` and the `Dsv7::Parser.parse*` helpers.
+- Internal helpers are annotated with `@api private` and hidden from the default docs.
+
 ## Compact ERG Example
 
 Minimal Wettkampfergebnisliste validation and parsing in one go:
 
-```
+~~~
 require 'dsv7/parser'
 
 content = <<~DSV
@@ -365,6 +440,6 @@ if result.valid?
     end
   end
 else
-  warn "Invalid ERG: #{result.errors.join('; ')}"
+  warn 'Invalid ERG: ' + result.errors.join('; ')
 end
-```
+~~~

data/Rakefile

@@ -3,6 +3,12 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+rescue LoadError
+  # YARD is a dev dependency; tasks are available when installed
+end
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
@@ -22,3 +28,35 @@ task lint: :rubocop
 
 desc 'CI: run tests and lint'
 task ci: %i[test lint]
+
+  if defined?(YARD)
+    desc 'Generate YARD documentation into doc/'
+    YARD::Rake::YardocTask.new(:yard) do |t|
+    # Parse only Ruby sources; README is provided via --readme for markup rendering
+    t.files = FileList['lib/**/*.rb']
+    t.options = [
+      '--no-cache',
+      '--markup', 'markdown',
+      '--markup-provider', 'kramdown',
+      '--readme', 'README.md',
+      '--hide-api', 'private'
+    ]
+  end
+  # Back-compat target for `rake doc`
+  task doc: :yard
+  # Generate full internal docs (includes @api private and private methods)
+  desc 'Generate full YARD docs (including private API) into doc-internal/'
+  YARD::Rake::YardocTask.new(:yard_full) do |t|
+    t.files = FileList['lib/**/*.rb']
+    t.options = [
+      '--no-cache',
+      '--markup', 'markdown',
+      '--markup-provider', 'kramdown',
+      '--readme', 'README.md',
+      '--private',
+      '-o', 'doc-internal'
+    ]
+  end
+  task 'docs:full' => :yard_full
+  task docs: :yard
+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,10 +1,22 @@
 # frozen_string_literal: true
 
 module Dsv7
+  ##
+  # Lexical helpers for simple DSV7 tokens.
+  #
+  # - {parse_format} extracts the list type and version from an exact
+  #   `FORMAT:<Listentyp>;<Version>;` line.
+  # - {element} splits an element line into its name and attributes.
+  #
+  # These functions are intentionally minimal and do not perform semantic checks.
+  #
+  # @api private
   module Lex
     module_function
 
-    # Parses a FORMAT line. Returns [list_type, version] or nil if not a FORMAT line.
+    # Parses a FORMAT line.
+    # @param line [String]
+    # @return [Array<String>, nil] Pair of [list_type, version] or nil if not a FORMAT line
     def parse_format(line)
       m = line.match(/^FORMAT:([^;]+);([^;]+);$/)
       return nil unless m
@@ -13,7 +25,8 @@ module Dsv7
     end
 
     # Splits an element content line into name and attributes.
-    # Returns [name, attrs] or nil if the line is not an element line.
+    # @param content [String]
+    # @return [Array, nil] Tuple `[name, attrs]` or nil if the line is not an element line
     def element(content)
       return nil unless content.include?(':')
 

data/lib/dsv7/parser/engine.rb

@@ -8,11 +8,21 @@ require_relative 'io_util'
 module Dsv7
   module Parser
     # Internal engine that implements the streaming mechanics.
+    ##
+    # 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`.
+    #
+    # @api private
     class Engine
+      # @api private
       def self.stream_any(input, emitter)
         new(input, emitter).stream_any
       end
 
+      # @api private
       def self.stream_list(input, emitter, expected_list_type)
         new(input, emitter).stream_list(expected_list_type)
       end

data/lib/dsv7/parser/io_util.rb

@@ -6,8 +6,21 @@ require_relative '../stream'
 module Dsv7
   module Parser
     module IoUtil
+      ##
+      # 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.
+      #
+      # @api private
+
       module_function
 
+      # Convert supported inputs into an IO instance.
+      # @param input [IO, String]
+      # @return [IO]
+      # @raise [ArgumentError] for unsupported input types
       def to_io(input)
         return input if input.respond_to?(:read)
         return File.open(input, 'rb') if input.is_a?(String) && File.file?(input)
@@ -16,6 +29,12 @@ module Dsv7
         raise ArgumentError, 'Unsupported input; pass IO, file path String, or content String'
       end
 
+      # Open/normalize an input and yield an IO. Closes the IO when it was
+      # opened from a file path.
+      # @param input [IO, String]
+      # @yield [io]
+      # @yieldparam io [IO]
+      # @return [void]
       def with_io(input)
         close_after = input.is_a?(String) && File.file?(input)
         io = to_io(input)
@@ -26,6 +45,13 @@ module Dsv7
         io&.close if close_after
       end
 
+      # Yield each non-empty, comment-stripped content line with 1-based
+      # line numbers.
+      # @param io [IO]
+      # @yield [content, line_number]
+      # @yieldparam content [String]
+      # @yieldparam line_number [Integer]
+      # @return [void]
       def each_content_line(io)
         ln = 0
         io.each_line("\n") do |raw|

data/lib/dsv7/parser/version.rb

@@ -2,6 +2,9 @@
 
 module Dsv7
   module Parser
-    VERSION = '7.0.0'
+    # Gem version for dsv7-parser
+    # @since 7.0.0
+    # @return [String]
+    VERSION = '7.0.2'
   end
 end