sashite-pcn 0.2.0 → 0.3.0

data/lib/sashite/pcn/game/meta.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    class Game
+      # Represents game metadata with standard and custom fields
+      #
+      # All fields are optional. An empty Meta object (no metadata) is valid.
+      # Standard fields are validated, custom fields are accepted without validation.
+      #
+      # @example With standard fields
+      #   meta = Meta.new(
+      #     event: "World Championship",
+      #     location: "London",
+      #     round: 5,
+      #     started_on: "2024-11-20",
+      #     finished_at: "2024-11-20T18:45:00Z",
+      #     href: "https://example.com/game/123"
+      #   )
+      #
+      # @example With custom fields
+      #   meta = Meta.new(
+      #     event: "Tournament",
+      #     platform: "lichess.org",
+      #     time_control: "3+2",
+      #     rated: true
+      #   )
+      #
+      # @example Empty metadata
+      #   meta = Meta.new  # Valid, no metadata
+      class Meta
+        # Error messages
+        ERROR_INVALID_NAME = "name must be a string"
+        ERROR_INVALID_EVENT = "event must be a string"
+        ERROR_INVALID_LOCATION = "location must be a string"
+        ERROR_INVALID_ROUND = "round must be a positive integer (>= 1)"
+        ERROR_INVALID_STARTED_ON = "started_on must be in ISO 8601 date format (YYYY-MM-DD)"
+        ERROR_INVALID_FINISHED_AT = "finished_at must be in ISO 8601 datetime format with UTC (YYYY-MM-DDTHH:MM:SSZ)"
+        ERROR_INVALID_HREF = "href must be an absolute URL (http:// or https://)"
+
+        # Standard field keys
+        STANDARD_FIELDS = %i[name event location round started_on finished_at href].freeze
+
+        # Regular expressions for validation
+        DATE_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
+        DATETIME_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\z/
+        URL_PATTERN = /\Ahttps?:\/\/.+/
+
+        # Create a new Meta instance
+        #
+        # @param fields [Hash] metadata with optional standard and custom fields
+        def initialize(**fields)
+          @data = {}
+
+          # Process and validate each field
+          fields.each do |key, value|
+            validate_and_store(key, value)
+          end
+
+          @data.freeze
+          freeze
+        end
+
+        # Get a metadata value by key
+        #
+        # @param key [Symbol, String] the metadata key
+        # @return [Object, nil] the value or nil if not present
+        #
+        # @example
+        #   meta[:event]  # => "World Championship"
+        def [](key)
+          @data[key.to_sym]
+        end
+
+        # Check if no metadata is present
+        #
+        # @return [Boolean] true if no fields are defined
+        #
+        # @example
+        #   meta.empty?  # => true
+        def empty?
+          @data.empty?
+        end
+
+        # Convert to hash representation
+        #
+        # @return [Hash] hash with all defined metadata fields
+        #
+        # @example
+        #   meta.to_h
+        #   # => { event: "Tournament", round: 5, platform: "lichess.org" }
+        def to_h
+          @data.dup.freeze
+        end
+
+        private
+
+        # Validate and store a field
+        #
+        # @param key [Symbol] the field key
+        # @param value [Object] the field value
+        # @raise [ArgumentError] if validation fails
+        def validate_and_store(key, value)
+          case key
+          when :name
+            validate_name(value)
+          when :event
+            validate_event(value)
+          when :location
+            validate_location(value)
+          when :round
+            validate_round(value)
+          when :started_on
+            validate_started_on(value)
+          when :finished_at
+            validate_finished_at(value)
+          when :href
+            validate_href(value)
+          else
+            # Custom fields are accepted without validation
+            @data[key] = value
+            return
+          end
+
+          # Store frozen value for standard string fields
+          @data[key] = value.is_a?(::String) ? value.freeze : value
+        end
+
+        # Validate name field
+        def validate_name(value)
+          raise ::ArgumentError, ERROR_INVALID_NAME unless value.is_a?(::String)
+        end
+
+        # Validate event field
+        def validate_event(value)
+          raise ::ArgumentError, ERROR_INVALID_EVENT unless value.is_a?(::String)
+        end
+
+        # Validate location field
+        def validate_location(value)
+          raise ::ArgumentError, ERROR_INVALID_LOCATION unless value.is_a?(::String)
+        end
+
+        # Validate round field (must be integer >= 1)
+        def validate_round(value)
+          raise ::ArgumentError, ERROR_INVALID_ROUND unless value.is_a?(::Integer)
+          raise ::ArgumentError, ERROR_INVALID_ROUND unless value >= 1
+        end
+
+        # Validate started_on field (ISO 8601 date format)
+        def validate_started_on(value)
+          raise ::ArgumentError, ERROR_INVALID_STARTED_ON unless value.is_a?(::String)
+          raise ::ArgumentError, ERROR_INVALID_STARTED_ON unless value.match?(DATE_PATTERN)
+        end
+
+        # Validate finished_at field (ISO 8601 datetime format with Z)
+        def validate_finished_at(value)
+          raise ::ArgumentError, ERROR_INVALID_FINISHED_AT unless value.is_a?(::String)
+          raise ::ArgumentError, ERROR_INVALID_FINISHED_AT unless value.match?(DATETIME_PATTERN)
+        end
+
+        # Validate href field (absolute URL with http:// or https://)
+        def validate_href(value)
+          raise ::ArgumentError, ERROR_INVALID_HREF unless value.is_a?(::String)
+          raise ::ArgumentError, ERROR_INVALID_HREF unless value.match?(URL_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/sashite/pcn/game/sides/player.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    class Game
+      class Sides
+        # Represents a single player with optional metadata
+        #
+        # All fields are optional. An empty Player object (no information) is valid.
+        #
+        # @example Complete player
+        #   player = Player.new(name: "Carlsen", elo: 2830, style: "CHESS")
+        #
+        # @example Minimal player
+        #   player = Player.new(name: "Player 1")
+        #
+        # @example Empty player
+        #   player = Player.new  # Valid, no player information
+        class Player
+          # Error messages
+          ERROR_INVALID_STYLE = "style must be a valid SNN string"
+          ERROR_INVALID_NAME = "name must be a string"
+          ERROR_INVALID_ELO = "elo must be a non-negative integer (>= 0)"
+
+          # Create a new Player instance
+          #
+          # @param style [String, nil] player style in SNN format (optional)
+          # @param name [String, nil] player name (optional)
+          # @param elo [Integer, nil] player Elo rating (optional, >= 0)
+          # @raise [ArgumentError] if field values don't meet constraints
+          def initialize(style: nil, name: nil, elo: nil)
+            # Validate and assign style (optional)
+            if style
+              raise ::ArgumentError, ERROR_INVALID_STYLE unless style.is_a?(::String)
+              @style = ::Sashite::Snn.parse(style)
+            else
+              @style = nil
+            end
+
+            # Validate and assign name (optional)
+            if name
+              raise ::ArgumentError, ERROR_INVALID_NAME unless name.is_a?(::String)
+              @name = name.freeze
+            else
+              @name = nil
+            end
+
+            # Validate and assign elo (optional, must be >= 0)
+            if elo
+              raise ::ArgumentError, ERROR_INVALID_ELO unless elo.is_a?(::Integer)
+              raise ::ArgumentError, ERROR_INVALID_ELO unless elo >= 0
+              @elo = elo
+            else
+              @elo = nil
+            end
+
+            freeze
+          end
+
+          # Get player style
+          #
+          # @return [Sashite::Snn::Name, nil] style or nil if not defined
+          #
+          # @example
+          #   player.style  # => #<Sashite::Snn::Name ...>
+          def style
+            @style
+          end
+
+          # Get player name
+          #
+          # @return [String, nil] name or nil if not defined
+          #
+          # @example
+          #   player.name  # => "Carlsen"
+          def name
+            @name
+          end
+
+          # Get player Elo rating
+          #
+          # @return [Integer, nil] elo or nil if not defined
+          #
+          # @example
+          #   player.elo  # => 2830
+          def elo
+            @elo
+          end
+
+          # Check if no player information is present
+          #
+          # @return [Boolean] true if all fields are nil
+          #
+          # @example
+          #   player.empty?  # => true
+          def empty?
+            @style.nil? && @name.nil? && @elo.nil?
+          end
+
+          # Convert to hash representation
+          #
+          # Returns a hash containing only defined (non-nil) fields.
+          # If all fields are nil, returns an empty hash.
+          #
+          # @return [Hash] hash with :style, :name, and/or :elo keys
+          #
+          # @example Complete player
+          #   player.to_h
+          #   # => { style: "CHESS", name: "Carlsen", elo: 2830 }
+          #
+          # @example Partial player
+          #   player.to_h
+          #   # => { name: "Alice" }
+          #
+          # @example Empty player
+          #   player.to_h
+          #   # => {}
+          def to_h
+            result = {}
+            result[:style] = @style.to_s unless @style.nil?
+            result[:name] = @name unless @name.nil?
+            result[:elo] = @elo unless @elo.nil?
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sashite/pcn/game/sides.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "sides/player"
+
+module Sashite
+  module Pcn
+    class Game
+      # Represents player information for both sides of a game
+      #
+      # Both players are optional and default to empty player objects.
+      # An empty Sides object (no player information) is valid.
+      #
+      # @example With both players
+      #   sides = Sides.new(
+      #     first: { name: "Carlsen", elo: 2830, style: "CHESS" },
+      #     second: { name: "Nakamura", elo: 2794, style: "chess" }
+      #   )
+      #
+      # @example With only first player
+      #   sides = Sides.new(
+      #     first: { name: "Player 1", style: "CHESS" }
+      #   )
+      #
+      # @example Empty sides (no player information)
+      #   sides = Sides.new  # Both players default to {}
+      class Sides
+        # Create a new Sides instance
+        #
+        # @param first [Hash] first player information (defaults to {})
+        # @param second [Hash] second player information (defaults to {})
+        def initialize(first: {}, second: {})
+          @first = Player.new(**first.transform_keys(&:to_sym))
+          @second = Player.new(**second.transform_keys(&:to_sym))
+
+          freeze
+        end
+
+        # Get first player information
+        #
+        # @return [Player] first player (may be empty)
+        #
+        # @example
+        #   sides.first  # => #<Sashite::Pcn::Game::Sides::Player ...>
+        def first
+          @first
+        end
+
+        # Get second player information
+        #
+        # @return [Player] second player (may be empty)
+        #
+        # @example
+        #   sides.second  # => #<Sashite::Pcn::Game::Sides::Player ...>
+        def second
+          @second
+        end
+
+        # Check if no player information is present
+        #
+        # @return [Boolean] true if both players are empty
+        #
+        # @example
+        #   sides.empty?  # => true
+        def empty?
+          @first.empty? && @second.empty?
+        end
+
+        # Convert to hash representation
+        #
+        # Returns a hash containing only non-empty player objects.
+        # If both players are empty, returns an empty hash.
+        #
+        # @return [Hash] hash with :first and/or :second keys, or empty hash
+        #
+        # @example With both players
+        #   sides.to_h
+        #   # => { first: { name: "Carlsen", elo: 2830, style: "CHESS" },
+        #   #      second: { name: "Nakamura", elo: 2794, style: "chess" } }
+        #
+        # @example With only first player
+        #   sides.to_h
+        #   # => { first: { name: "Alice" } }
+        #
+        # @example With no players
+        #   sides.to_h
+        #   # => {}
+        def to_h
+          result = {}
+          result[:first] = @first.to_h unless @first.empty?
+          result[:second] = @second.to_h unless @second.empty?
+          result
+        end
+      end
+    end
+  end
+end