dsv7-parser 7.0.1 → 7.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb8097275fb6859296653a95615ebd304fcb53a36436118946b60e035b3ccdaf
-  data.tar.gz: cc2693be6d15b7cc2654bf378f3288cd87782ec40bc4b04c5f66c52dcdaf26c3
+  metadata.gz: c363432be089a4a08ccd0f9c1356b47c8a537436aebd5e75000d767dd8c531b6
+  data.tar.gz: 7683d1b49fe75fa94f0682db2dcc6720b31b250d5657f1171799630807c57248
 SHA512:
-  metadata.gz: f705afebef80f7863205632454a92f5bd2b5c910c8df0ec94ae684bcb3c9b6bc36f4afe8c887a57e537eea3b223525c8fff66e43acb007c773b179cccacb9025
-  data.tar.gz: 13628c729df524abc3a5eb2cbb9378fd76845a6cf8f258e9ef24612dcf64d9c1b22f98b96c0bf18757851513367949b91ba3b439476f0c88a328c16ea1879faf
+  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,7 +101,7 @@ DSV
 
 vml_result = Dsv7::Validator.validate(vml)
 puts vml_result.valid?    # => true
-```
+~~~
 
 ## Validated elements
 
@@ -185,7 +185,7 @@ VRL (Vereinsergebnisliste)
 
 Common error and warning examples:
 
-```
+~~~
 # 1) Unknown list type and missing DATEIENDE
 bad = "FORMAT:Unbekannt;7;\n"
 r = Dsv7::Validator.validate(bad)
@@ -218,7 +218,7 @@ begin
 ensure
   File.delete('tmp/badname.txt')
 end
-```
+~~~
 
 ## Parser (Streaming: WKDL, VML, ERG, VRL)
 
@@ -237,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
@@ -249,7 +249,7 @@ enum.each do |type, payload, line_number|
     # reached DATEIENDE
   end
 end
-```
+~~~
 
 Key points:
 
@@ -260,7 +260,7 @@ Key points:
 
 Basic example (block style):
 
-```
+~~~
 require 'dsv7/parser'
 
 content = <<~DSV
@@ -284,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|
@@ -313,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;
@@ -345,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;
@@ -363,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;
@@ -381,7 +381,7 @@ DSV
 Dsv7::Parser.parse(content) do |type, payload, line_number|
   # same :format, :element, :end semantics
 end
-```
+~~~
 
 Errors and edge cases:
 
@@ -396,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
@@ -429,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,7 +3,12 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
-require 'rdoc/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'
@@ -24,10 +29,34 @@ 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')
+  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/lib/dsv7/lex.rb

@@ -1,18 +1,22 @@
 # 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
+  ##
+  # 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
@@ -21,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

@@ -1,11 +1,5 @@
 # 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'
@@ -14,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

@@ -1,19 +1,26 @@
 # 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'
 
 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)
@@ -22,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)
@@ -32,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.1'
+    # Gem version for dsv7-parser
+    # @since 7.0.0
+    # @return [String]
+    VERSION = '7.0.2'
   end
 end