sashite-pcn 0.2.0 → 0.4.0

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

@@ -0,0 +1,239 @@
+# 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(
+      #     name: "Italian Game",
+      #     event: "World Championship",
+      #     location: "London",
+      #     round: 5,
+      #     started_at: "2025-01-27T14:00:00Z",
+      #     href: "https://example.com/game/123"
+      #   )
+      #
+      # @example With custom fields
+      #   meta = Meta.new(
+      #     event: "Online Tournament",
+      #     platform: "lichess.org",
+      #     time_control: "5+3",
+      #     rated: true,
+      #     opening_eco: "C50"
+      #   )
+      #
+      # @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_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_at href].freeze
+
+        # Regular expressions for validation
+        # 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 = {}
+
+          # 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"
+        #   meta["started_at"]  # => "2025-01-27T14:00:00Z"
+        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
+
+        # 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,
+        #   #   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
+        #
+        # @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_at
+            validate_started_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_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://)
+        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,311 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    class Game
+      class Sides
+        # 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 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 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
+        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)"
+          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, periods: 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
+
+            # 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
+
+          # 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
+
+          # 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
+          #
+          # @example
+          #   player.empty?  # => true
+          def empty?
+            @style.nil? && @name.nil? && @elo.nil? && @periods.empty?
+          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, :elo, and/or :periods keys
+          #
+          # @example Complete player
+          #   player.to_h
+          #   # => {
+          #   #   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", periods: [] }
+          #
+          # @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[: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
+  end
+end