dsv7-parser 7.0.0 → 7.0.2

data/lib/dsv7/validator.rb

@@ -5,6 +5,39 @@ require_relative 'validator/result'
 require_relative 'validator/core'
 
 module Dsv7
+  ##
+  # 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}.
+  #
+  # Semantics
+  # - Errors on UTF‑8 BOM and on invalid UTF‑8 (input is scrubbed for messages).
+  # - Warns once when CRLF line endings are detected (still valid).
+  # - When validating a file path, may add a filename pattern warning if it
+  #   does not match `JJJJ-MM-TT-Ort-Zusatz.DSV7`.
+  #
+  # @api public
+  # @since 7.0.0
+  # @example Validate a file by path
+  #   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'
+  #
+  # @see Dsv7::Parser For streaming parsing helpers and event API
   # Validates overall conformity of a DSV7 file against high-level rules
   # extracted from the specification markdown under `specification/dsv7`.
   #
@@ -12,6 +45,7 @@ module Dsv7
   # knowledge of the full element schemas.
   class Validator
     # Known list types from the overview section
+    # @return [Array<String>]
     ALLOWED_LIST_TYPES = %w[
       Wettkampfdefinitionsliste
       Vereinsmeldeliste
@@ -19,10 +53,18 @@ module Dsv7
       Vereinsergebnisliste
     ].freeze
 
-    # Single public entrypoint. Accepts:
-    # - IO-like objects (respond_to?(:read)) → streamed
+    # Validate a DSV7 input.
+    #
+    # Accepts:
+    # - IO-like objects (`respond_to?(:read)`) → streamed
     # - String paths to files → streamed
     # - String content → streamed via StringIO
+    #
+    # @param input [IO, String] An IO, a file path String, or a String with file content
+    # @api public
+    # @since 7.0.0
+    # @return [Dsv7::Validator::Result] Validation result with errors/warnings and metadata
+    # @raise [ArgumentError] if an unsupported input type is provided
     def self.validate(input)
       return new.send(:validate_stream, input) if input.respond_to?(:read)
       return validate_path(input) if input.is_a?(String) && File.file?(input)
@@ -34,6 +76,7 @@ module Dsv7
     class << self
       private
 
+      # @api private
       def validate_path(path)
         File.open(path, 'rb') do |io|
           return new.send(:validate_stream, io, filename: File.basename(path))
@@ -43,6 +86,10 @@ module Dsv7
 
     private
 
+    # @api private
+    # @param io [IO]
+    # @param filename [String, nil]
+    # @return [Dsv7::Validator::Result]
     def validate_stream(io, filename: nil)
       result = Result.new
       Core.new(result, filename).call_io(io)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsv7-parser
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.0.2
 platform: ruby
 authors:
 - bigcurl
@@ -9,16 +9,19 @@ 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"
 - ".ruby-version"
+- ".yardopts"
 - AGENTS.md
 - Gemfile
 - Gemfile.lock
@@ -57,6 +60,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: