sashite-pcn 0.3.0 → 0.4.0

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

@@ -10,20 +10,21 @@ module Sashite
       #
       # @example With standard fields
       #   meta = Meta.new(
+      #     name: "Italian Game",
       #     event: "World Championship",
       #     location: "London",
       #     round: 5,
-      #     started_on: "2024-11-20",
-      #     finished_at: "2024-11-20T18:45:00Z",
+      #     started_at: "2025-01-27T14:00:00Z",
       #     href: "https://example.com/game/123"
       #   )
       #
       # @example With custom fields
       #   meta = Meta.new(
-      #     event: "Tournament",
+      #     event: "Online Tournament",
       #     platform: "lichess.org",
-      #     time_control: "3+2",
-      #     rated: true
+      #     time_control: "5+3",
+      #     rated: true,
+      #     opening_eco: "C50"
       #   )
       #
       # @example Empty metadata
@@ -34,21 +35,25 @@ module Sashite
         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_STARTED_AT = "started_at must be in ISO 8601 datetime format (e.g., 2025-01-27T14:00:00Z)"
         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
+        STANDARD_FIELDS = %i[name event location round started_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/
+        # ISO 8601 datetime - accepts various formats:
+        # - Basic: 2025-01-27T14:00:00Z
+        # - With milliseconds: 2025-01-27T14:00:00.123Z
+        # - With timezone offset: 2025-01-27T14:00:00+02:00
+        # - Local time without timezone: 2025-01-27T14:00:00
+        DATETIME_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?\z/
         URL_PATTERN = /\Ahttps?:\/\/.+/
 
         # Create a new Meta instance
         #
         # @param fields [Hash] metadata with optional standard and custom fields
+        # @raise [ArgumentError] if standard field values don't meet validation requirements
         def initialize(**fields)
           @data = {}
 
@@ -68,6 +73,7 @@ module Sashite
         #
         # @example
         #   meta[:event]  # => "World Championship"
+        #   meta["started_at"]  # => "2025-01-27T14:00:00Z"
         def [](key)
           @data[key.to_sym]
         end
@@ -82,17 +88,83 @@ module Sashite
           @data.empty?
         end
 
+        # Get all metadata keys
+        #
+        # @return [Array<Symbol>] array of defined field keys
+        #
+        # @example
+        #   meta.keys  # => [:event, :round, :platform]
+        def keys
+          @data.keys
+        end
+
+        # Check if a metadata field is present
+        #
+        # @param key [Symbol, String] the metadata key
+        # @return [Boolean] true if the field is defined
+        #
+        # @example
+        #   meta.key?(:event)  # => true
+        #   meta.key?("round")  # => true
+        def key?(key)
+          @data.key?(key.to_sym)
+        end
+
+        # Iterate over each metadata field
+        #
+        # @yield [key, value] yields each key-value pair
+        # @return [Enumerator] if no block given
+        #
+        # @example
+        #   meta.each { |k, v| puts "#{k}: #{v}" }
+        def each(&)
+          return @data.each unless block_given?
+
+          @data.each(&)
+        end
+
         # Convert to hash representation
         #
         # @return [Hash] hash with all defined metadata fields
         #
         # @example
         #   meta.to_h
-        #   # => { event: "Tournament", round: 5, platform: "lichess.org" }
+        #   # => {
+        #   #   event: "Tournament",
+        #   #   round: 5,
+        #   #   started_at: "2025-01-27T14:00:00Z",
+        #   #   platform: "lichess.org"
+        #   # }
         def to_h
           @data.dup.freeze
         end
 
+        # String representation for debugging
+        #
+        # @return [String] string representation
+        def inspect
+          "#<#{self.class.name} #{@data.inspect}>"
+        end
+
+        # Check equality with another Meta object
+        #
+        # @param other [Object] object to compare
+        # @return [Boolean] true if equal
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          @data == other.to_h
+        end
+
+        alias eql? ==
+
+        # Hash code for use in collections
+        #
+        # @return [Integer] hash code
+        def hash
+          @data.hash
+        end
+
         private
 
         # Validate and store a field
@@ -110,10 +182,8 @@ module Sashite
             validate_location(value)
           when :round
             validate_round(value)
-          when :started_on
-            validate_started_on(value)
-          when :finished_at
-            validate_finished_at(value)
+          when :started_at
+            validate_started_at(value)
           when :href
             validate_href(value)
           else
@@ -147,16 +217,15 @@ module Sashite
           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)
+        # Validate started_at field (ISO 8601 datetime format)
+        # Accepts various ISO 8601 formats:
+        # - 2025-01-27T14:00:00Z (UTC)
+        # - 2025-01-27T14:00:00+02:00 (with timezone offset)
+        # - 2025-01-27T14:00:00.123Z (with milliseconds)
+        # - 2025-01-27T14:00:00 (local time, no timezone)
+        def validate_started_at(value)
+          raise ::ArgumentError, ERROR_INVALID_STARTED_AT unless value.is_a?(::String)
+          raise ::ArgumentError, ERROR_INVALID_STARTED_AT unless value.match?(DATETIME_PATTERN)
         end
 
         # Validate href field (absolute URL with http:// or https://)

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

@@ -4,15 +4,46 @@ module Sashite
   module Pcn
     class Game
       class Sides
-        # Represents a single player with optional metadata
+        # Represents a single player with optional metadata and time control
         #
         # All fields are optional. An empty Player object (no information) is valid.
+        # The periods field defines time control settings for this player.
         #
-        # @example Complete player
-        #   player = Player.new(name: "Carlsen", elo: 2830, style: "CHESS")
+        # @example Complete player with time control
+        #   player = Player.new(
+        #     name: "Carlsen",
+        #     elo: 2830,
+        #     style: "CHESS",
+        #     periods: [
+        #       { time: 5400, moves: 40, inc: 0 },    # 90 min for first 40 moves
+        #       { time: 1800, moves: nil, inc: 30 }   # 30 min + 30s/move for rest
+        #     ]
+        #   )
         #
-        # @example Minimal player
-        #   player = Player.new(name: "Player 1")
+        # @example Fischer/Increment time control (5+3 blitz)
+        #   player = Player.new(
+        #     name: "Player 1",
+        #     periods: [
+        #       { time: 300, moves: nil, inc: 3 }     # 5 min + 3s increment
+        #     ]
+        #   )
+        #
+        # @example Byōyomi time control
+        #   player = Player.new(
+        #     name: "Yamada",
+        #     style: "SHOGI",
+        #     periods: [
+        #       { time: 3600, moves: nil, inc: 0 },   # Main time: 1 hour
+        #       { time: 60, moves: 1, inc: 0 },       # 60s per move (5 periods)
+        #       { time: 60, moves: 1, inc: 0 },
+        #       { time: 60, moves: 1, inc: 0 },
+        #       { time: 60, moves: 1, inc: 0 },
+        #       { time: 60, moves: 1, inc: 0 }
+        #     ]
+        #   )
+        #
+        # @example No time control (casual game)
+        #   player = Player.new(name: "Casual Player", periods: [])
         #
         # @example Empty player
         #   player = Player.new  # Valid, no player information
@@ -21,14 +52,21 @@ module Sashite
           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)"
+          ERROR_INVALID_PERIODS = "periods must be an array"
+          ERROR_INVALID_PERIOD = "each period must be a hash"
+          ERROR_MISSING_TIME = "period must have 'time' field"
+          ERROR_INVALID_TIME = "time must be a non-negative integer (>= 0)"
+          ERROR_INVALID_MOVES = "moves must be nil or a positive integer (>= 1)"
+          ERROR_INVALID_INC = "inc 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)
+          # @param periods [Array<Hash>, nil] time control periods (optional)
           # @raise [ArgumentError] if field values don't meet constraints
-          def initialize(style: nil, name: nil, elo: nil)
+          def initialize(style: nil, name: nil, elo: nil, periods: nil)
             # Validate and assign style (optional)
             if style
               raise ::ArgumentError, ERROR_INVALID_STYLE unless style.is_a?(::String)
@@ -54,6 +92,12 @@ module Sashite
               @elo = nil
             end
 
+            # Validate and assign periods
+            periods = [] if periods.nil?
+
+            raise ::ArgumentError, ERROR_INVALID_PERIODS unless periods.is_a?(::Array)
+            @periods = validate_and_normalize_periods(periods).freeze
+
             freeze
           end
 
@@ -87,6 +131,51 @@ module Sashite
             @elo
           end
 
+          # Get time control periods
+          #
+          # @return [Array<Hash>] periods if not defined
+          #
+          # @example
+          #   player.periods
+          #   # => [
+          #   #   { time: 300, moves: nil, inc: 3 }
+          #   # ]
+          def periods
+            @periods
+          end
+
+          # Check if player has time control
+          #
+          # @return [Boolean] true if periods are defined
+          #
+          # @example
+          #   player.has_time_control?  # => true
+          def has_time_control?
+            !unlimited_time?
+          end
+
+          # Check if player has unlimited time (no time control)
+          #
+          # @return [Boolean] true if periods is empty array or nil
+          #
+          # @example
+          #   player.unlimited_time?  # => false
+          def unlimited_time?
+            @periods.empty?
+          end
+
+          # Get initial time budget (sum of all period times)
+          #
+          # @return [Integer, nil] total seconds or nil if no periods
+          #
+          # @example
+          #   player.initial_time_budget  # => 7200 (2 hours)
+          def initial_time_budget
+            return if unlimited_time?
+
+            @periods.sum { |period| period[:time] }
+          end
+
           # Check if no player information is present
           #
           # @return [Boolean] true if all fields are nil
@@ -94,7 +183,7 @@ module Sashite
           # @example
           #   player.empty?  # => true
           def empty?
-            @style.nil? && @name.nil? && @elo.nil?
+            @style.nil? && @name.nil? && @elo.nil? && @periods.empty?
           end
 
           # Convert to hash representation
@@ -102,15 +191,23 @@ module Sashite
           # 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
+          # @return [Hash] hash with :style, :name, :elo, and/or :periods keys
           #
           # @example Complete player
           #   player.to_h
-          #   # => { style: "CHESS", name: "Carlsen", elo: 2830 }
+          #   # => {
+          #   #   style: "CHESS",
+          #   #   name: "Carlsen",
+          #   #   elo: 2830,
+          #   #   periods: [
+          #   #     { time: 5400, moves: 40, inc: 0 },
+          #   #     { time: 1800, moves: nil, inc: 30 }
+          #   #   ]
+          #   # }
           #
           # @example Partial player
           #   player.to_h
-          #   # => { name: "Alice" }
+          #   # => { name: "Alice", periods: [] }
           #
           # @example Empty player
           #   player.to_h
@@ -120,8 +217,93 @@ module Sashite
             result[:style] = @style.to_s unless @style.nil?
             result[:name] = @name unless @name.nil?
             result[:elo] = @elo unless @elo.nil?
+            result[:periods] = @periods unless @periods.empty?
             result
           end
+
+          # String representation for debugging
+          #
+          # @return [String] string representation
+          def inspect
+            attrs = []
+            attrs << "style=#{@style.inspect}" if @style
+            attrs << "name=#{@name.inspect}" if @name
+            attrs << "elo=#{@elo.inspect}" if @elo
+            attrs << "periods=#{@periods.inspect}" if @periods.any?
+
+            "#<#{self.class.name} #{attrs.join(' ')}>"
+          end
+
+          # Check equality with another Player object
+          #
+          # @param other [Object] object to compare
+          # @return [Boolean] true if equal
+          def ==(other)
+            return false unless other.is_a?(self.class)
+
+            @style == other.style &&
+              @name == other.name &&
+              @elo == other.elo &&
+              @periods == other.periods
+          end
+
+          alias eql? ==
+
+          # Hash code for use in collections
+          #
+          # @return [Integer] hash code
+          def hash
+            [@style, @name, @elo, @periods].hash
+          end
+
+          private
+
+          # Validate and normalize periods array
+          #
+          # @param periods [Array<Hash>] array of period hashes
+          # @return [Array<Hash>] normalized periods with all required fields
+          # @raise [ArgumentError] if any period is invalid
+          def validate_and_normalize_periods(periods)
+            periods.map.with_index do |period, index|
+              validate_and_normalize_period(period, index)
+            end
+          end
+
+          # Validate and normalize a single period
+          #
+          # @param period [Hash] period hash
+          # @param index [Integer] index for error messages
+          # @return [Hash] normalized period with time, moves, and inc fields
+          # @raise [ArgumentError] if period is invalid
+          def validate_and_normalize_period(period, index)
+            raise ::ArgumentError, "#{ERROR_INVALID_PERIOD} at index #{index}" unless period.is_a?(::Hash)
+
+            # Convert keys to symbols for consistent access
+            period = period.transform_keys(&:to_sym)
+
+            # Validate required 'time' field
+            raise ::ArgumentError, "#{ERROR_MISSING_TIME} at index #{index}" unless period.key?(:time)
+
+            time = period[:time]
+            raise ::ArgumentError, "#{ERROR_INVALID_TIME} at index #{index}" unless time.is_a?(::Integer) && time >= 0
+
+            # Validate optional 'moves' field (nil or integer >= 1)
+            moves = period[:moves]
+            unless moves.nil? || (moves.is_a?(::Integer) && moves >= 1)
+              raise ::ArgumentError, "#{ERROR_INVALID_MOVES} at index #{index}"
+            end
+
+            # Validate optional 'inc' field (defaults to 0)
+            inc = period.fetch(:inc, 0)
+            raise ::ArgumentError, "#{ERROR_INVALID_INC} at index #{index}" unless inc.is_a?(::Integer) && inc >= 0
+
+            # Return normalized period with all three fields
+            {
+              time:  time,
+              moves: moves,
+              inc:   inc
+            }.freeze
+          end
         end
       end
     end