sashite-pcn 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f625658b6b690f035a94cd44ce2a9f6a53a85b53b62d77c17662729d4abb05bd
-  data.tar.gz: 5009624a8b0e42fe16d4c0d6f5be74e1d28a689666e0fadc28bd30647f9b9456
+  metadata.gz: 1e856d0d80b2560d24cfd77f6359b655d4b5d67f52ad320e04504f79cab49536
+  data.tar.gz: e539e626bd827a49071f2c80cc9095aa13abf4965433e8f14245b4461308009a
 SHA512:
-  metadata.gz: c446a92bc406f944d7999628b0347a64ed9cfdae252ce6e49be4205c837a14f53cc63d1736c98a9b4b404bcb1c0387f0ea2160177e7398032a38883001320a74
-  data.tar.gz: 0b815bee7f8aa325619ad19e165e4d92c68bfd697bd4b1be8b9a9c73eefac74c69fb90f231a18d97d76a310dbf2c6484259bfad335a681c297390a391bb82336
+  metadata.gz: abdfa7ddc44437089a0a8a3d7e2a959692f33f00760a273b1df37a86d8c125fb16ef684da67a7bf382f0a67b598e5083cbb569a6de967b40b9527dd9b6d47c4d
+  data.tar.gz: ce3dc76261263878b55a13995784074c5c1c3b4ef04a213c47b406e8faad7406a745bb232bab09a72a86cb22c8a5fdbebc10f09e8f697d3622e60451fffa1f6c

data/README.md

@@ -15,6 +15,7 @@
 - [API Documentation](#api-documentation)
 - [Format Specifications](#format-specifications)
 - [Time Control Examples](#time-control-examples)
+- [Draw Offers](#draw-offers)
 - [Error Handling](#error-handling)
 - [Complete Examples](#complete-examples)
 - [JSON Interoperability](#json-interoperability)
@@ -24,6 +25,7 @@
 PCN (Portable Chess Notation) is a comprehensive, JSON-based format for representing complete chess game records across variants. This Ruby implementation provides:
 
 - **Complete game records** with positions, moves, time tracking, and metadata
+- **Draw offer tracking** for recording draw proposals between players
 - **Time control support** for Fischer, Classical, Byōyomi, Canadian, and more
 - **Rule-agnostic design** supporting all abstract strategy board games
 - **Immutable objects** with functional transformations
@@ -80,11 +82,16 @@ game.status         # => CGSN status object
 # Transform immutably
 new_game = game.add_move(["g1-f3", 1.8])
 final_game = new_game.with_status("checkmate")
+
+# Handle draw offers
+game_with_offer = game.with_draw_offered_by("first")
+game.draw_offered?  # => true
+game.draw_offered_by # => "first"
 ```
 
 ## API Documentation
 
-For complete API documentation, see [API.md](API.md).
+For complete API documentation, see [API Reference](https://rubydoc.info/github/sashite/pcn.rb/main/file/API.md).
 
 The API documentation includes:
 - All classes and methods
@@ -93,6 +100,7 @@ The API documentation includes:
 - Code examples for every method
 - Common usage patterns
 - Time control formats
+- Draw offer handling
 - Error handling
 
 ## Format Specifications
@@ -102,7 +110,7 @@ The API documentation includes:
 ```ruby
 # Standard chess starting position
 "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
-# └─ board ─────────────────────────────────────────────────────┘ └┘ └─┘
+# └─ board ──────────────────────────────────────────────┘ └┘ └─┘
 #                                                               turn styles
 
 # Empty board
@@ -150,8 +158,10 @@ The API documentation includes:
 # Explicit only (must be declared)
 "resignation"    # Player resigned
 "time_limit"     # Time expired
-"agreement"      # Mutual agreement
+"agreement"      # Mutual agreement (draw)
 "illegal_move"   # Invalid move played
+"repetition"     # Draw by repetition
+"move_limit"     # Move limit reached
 ```
 
 ### SNN (Styles)
@@ -232,6 +242,74 @@ periods: []      # Empty array
 periods: nil     # Or omit entirely
 ```
 
+## Draw Offers
+
+PCN supports tracking draw offers between players using the `draw_offered_by` field.
+
+### Basic Usage
+
+```ruby
+# Offer a draw
+game = game.with_draw_offered_by("first")  # First player offers
+
+# Check if draw offered
+game.draw_offered?       # => true
+game.draw_offered_by     # => "first"
+
+# Accept the draw
+game = game.with_status("agreement")
+
+# Decline/withdraw draw offer
+game = game.with_draw_offered_by(nil)
+```
+
+### Draw Offer Values
+
+```ruby
+nil        # No draw offer pending (default)
+"first"    # First player has offered a draw
+"second"   # Second player has offered a draw
+```
+
+### Example: Draw Offer During Game
+
+```ruby
+# Game in progress with draw offer
+game = Sashite::Pcn.parse({
+  "setup" => "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
+  "moves" => [
+    ["e2-e4", 8.0],
+    ["e7-e5", 12.0],
+    ["g1-f3", 15.0]
+  ],
+  "draw_offered_by" => "first",
+  "status" => "in_progress"
+})
+
+# First player has offered a draw after move 3
+puts "Draw offered by: #{game.draw_offered_by}"  # => "first"
+```
+
+### Example: Accepted Draw
+
+```ruby
+# Draw accepted
+game = Sashite::Pcn.parse({
+  "setup" => "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
+  "moves" => [
+    ["e2-e4", 15.0],
+    ["e7-e5", 18.0],
+    ["g1-f3", 22.0],
+    ["b8-c6", 12.0]
+  ],
+  "draw_offered_by" => "first",
+  "status" => "agreement"
+})
+
+# First player offered, second player accepted
+puts "Game result: Draw by agreement"
+```
+
 ## Error Handling
 
 ```ruby
@@ -256,6 +334,16 @@ rescue ArgumentError => e
   puts e.message  # => "Each move must be [PAN string, seconds float] tuple"
 end
 
+# Draw offer validation
+begin
+  Sashite::Pcn::Game.new(
+    setup: "8/8/8/8/8/8/8/8 / U/u",
+    draw_offered_by: "third"  # Invalid: must be nil, "first", or "second"
+  )
+rescue ArgumentError => e
+  puts e.message  # => "draw_offered_by must be nil, 'first', or 'second'"
+end
+
 # Metadata validation
 begin
   Sashite::Pcn::Game.new(
@@ -275,6 +363,7 @@ begin
       ]
     }
   }
+  Sashite::Pcn::Game.new(setup: "8/8/8/8/8/8/8/8 / U/u", sides: sides)
 rescue ArgumentError => e
   puts e.message  # => "time must be a non-negative integer (>= 0)"
 end
@@ -353,14 +442,58 @@ puts "Moves played: #{game.move_count}"
 puts "White time: #{game.first_player_time}s"
 puts "Black time: #{game.second_player_time}s"
 
+# Offer a draw
+game = game.with_draw_offered_by("first")
+
 # Finish game
 if some_condition
   game = game.with_status("checkmate")
-elsif another_condition
+elsif draw_accepted?
+  game = game.with_status("agreement")
+else
   game = game.with_status("resignation")
 end
 ```
 
+### Game with Draw Offer
+
+```ruby
+# Complete game with draw offer and acceptance
+game = Sashite::Pcn::Game.new(
+  meta: {
+    event: "Club Match",
+    round: 5,
+    started_at: "2025-01-27T14:00:00Z"
+  },
+  sides: {
+    first: {
+      name: "Player A",
+      elo: 2200,
+      style: "CHESS"
+    },
+    second: {
+      name: "Player B",
+      elo: 2190,
+      style: "chess"
+    }
+  },
+  setup: "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
+  moves: [
+    ["e2-e4", 15.0],
+    ["e7-e5", 18.0],
+    ["g1-f3", 22.0],
+    ["b8-c6", 12.0],
+    ["d2-d4", 31.0],
+    ["e5+d4", 25.0]
+  ],
+  draw_offered_by: "first",
+  status: "agreement"
+)
+
+puts "Result: Draw by agreement"
+puts "Initiated by: #{game.draw_offered_by}"
+```
+
 ### Complex Tournament Game
 
 ```ruby
@@ -437,7 +570,41 @@ puts "Winner: #{game.status == 'resignation' ? 'First player (White)' : 'Unknown
 puts "Total moves: #{game.move_count}"
 
 # Export to JSON file
-File.write("game.json", JSON.generate(game.to_h))
+File.write("game.json", JSON.pretty_generate(game.to_h))
+```
+
+### Draw Offer Scenario
+
+```ruby
+# Game progressing with draw offer
+game = Sashite::Pcn::Game.new(
+  setup: "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
+)
+
+# Play several moves
+game = game.add_move(["e2-e4", 8.0])
+game = game.add_move(["e7-e5", 12.0])
+game = game.add_move(["g1-f3", 15.0])
+game = game.add_move(["b8-c6", 5.0])
+
+# First player offers a draw
+game = game.with_draw_offered_by("first")
+
+# Check the offer
+if game.draw_offered?
+  puts "Draw offered by: #{game.draw_offered_by}"
+
+  # Second player can accept
+  if player_accepts_draw?
+    game = game.with_status("agreement")
+    puts "Draw accepted!"
+  else
+    # Or decline and continue
+    game = game.with_draw_offered_by(nil)
+    game = game.add_move(["f1-c4", 9.0])
+    puts "Draw declined, game continues"
+  end
+end
 ```
 
 ## JSON Interoperability
@@ -511,6 +678,7 @@ record.save!
 record = GameRecord.find(id)
 game = record.game
 puts game.move_count
+puts "Draw offered: #{game.draw_offered?}"
 ```
 
 ## Properties
@@ -520,13 +688,14 @@ puts game.move_count
 - **Type-safe**: Strong type checking throughout
 - **Rule-agnostic**: Independent of specific game rules
 - **JSON-native**: Direct serialization to/from JSON
-- **Comprehensive**: Complete game information including time tracking
+- **Comprehensive**: Complete game information including time tracking and draw offers
 - **Extensible**: Custom metadata and player fields supported
 
 ## Documentation
 
 - [Official PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/)
 - [PCN Examples](https://sashite.dev/specs/pcn/1.0.0/examples/)
+- [Draw Offer Examples](https://sashite.dev/specs/pcn/1.0.0/examples/draw-offers/)
 - [API Documentation](https://rubydoc.info/github/sashite/pcn.rb/main)
 - [PAN Specification](https://sashite.dev/specs/pan/) (moves)
 - [FEEN Specification](https://sashite.dev/specs/feen/) (positions)

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

@@ -404,7 +404,7 @@ module Sashite
 
         # Describe time control periods in human-readable format
         #
-        # @param periods [Array<Hash>, nil] period array
+        # @param periods [Array<Hash>] period array
         # @return [String] description
         def describe_periods(periods)
           return "unlimited" if periods.empty?

data/lib/sashite/pcn/game.rb

@@ -13,8 +13,8 @@ module Sashite
     # Represents a complete game record in PCN (Portable Chess Notation) format.
     #
     # A game consists of an initial position (setup), optional move sequence with time tracking,
-    # optional game status, optional metadata, and optional player information with time control.
-    # All instances are immutable - transformations return new instances.
+    # optional game status, optional draw offer tracking, optional metadata, and optional player
+    # information with time control. All instances are immutable - transformations return new instances.
     #
     # All parameters are validated at initialization time. An instance of Game
     # cannot be created with invalid data.
@@ -55,6 +55,14 @@ module Sashite
     #     ],
     #     status: "in_progress"
     #   )
+    #
+    # @example Game with draw offer
+    #   game = Game.new(
+    #     setup: "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
+    #     moves: [["e2-e4", 8.0], ["e7-e5", 12.0]],
+    #     draw_offered_by: "first",
+    #     status: "in_progress"
+    #   )
     class Game
       # Error messages
       ERROR_MISSING_SETUP = "setup is required"
@@ -64,19 +72,24 @@ module Sashite
       ERROR_INVALID_SECONDS = "seconds must be a non-negative number"
       ERROR_INVALID_META = "meta must be a hash"
       ERROR_INVALID_SIDES = "sides must be a hash"
+      ERROR_INVALID_DRAW_OFFERED_BY = "draw_offered_by must be nil, 'first', or 'second'"
 
       # Status constants
       STATUS_IN_PROGRESS = "in_progress"
 
+      # Valid draw_offered_by values
+      VALID_DRAW_OFFERED_BY = [nil, "first", "second"].freeze
+
       # Create a new game instance
       #
       # @param setup [String] initial position in FEEN format (required)
       # @param moves [Array<Array>] sequence of [PAN, seconds] tuples (optional, defaults to [])
       # @param status [String, nil] game status in CGSN format (optional)
+      # @param draw_offered_by [String, nil] draw offer indicator: nil, "first", or "second" (optional)
       # @param meta [Hash] game metadata (optional)
       # @param sides [Hash] player information with time control (optional)
       # @raise [ArgumentError] if required fields are missing or invalid
-      def initialize(setup:, moves: [], status: nil, meta: {}, sides: {})
+      def initialize(setup:, moves: [], status: nil, draw_offered_by: nil, meta: {}, sides: {})
         # Validate and parse setup (required)
         raise ::ArgumentError, ERROR_MISSING_SETUP if setup.nil?
         @setup = ::Sashite::Feen.parse(setup)
@@ -88,6 +101,10 @@ module Sashite
         # Validate and parse status (optional)
         @status = status.nil? ? nil : ::Sashite::Cgsn.parse(status)
 
+        # Validate draw_offered_by (optional)
+        validate_draw_offered_by(draw_offered_by)
+        @draw_offered_by = draw_offered_by
+
         # Validate meta (optional)
         raise ::ArgumentError, ERROR_INVALID_META unless meta.is_a?(::Hash)
         @meta = Meta.new(**meta.transform_keys(&:to_sym))
@@ -153,6 +170,17 @@ module Sashite
         @status
       end
 
+      # Get draw offer indicator
+      #
+      # @return [String, nil] "first", "second", or nil
+      #
+      # @example
+      #   game.draw_offered_by  # => "first"
+      #   game.draw_offered_by  # => nil
+      def draw_offered_by
+        @draw_offered_by
+      end
+
       # ========================================================================
       # Player Access
       # ========================================================================
@@ -221,6 +249,7 @@ module Sashite
           setup: @setup.to_s,
           moves: new_moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
@@ -334,6 +363,30 @@ module Sashite
           setup: @setup.to_s,
           moves: @moves,
           status: new_status,
+          draw_offered_by: @draw_offered_by,
+          meta: @meta.to_h,
+          sides: @sides.to_h
+        )
+      end
+
+      # Create new game with updated draw offer
+      #
+      # @param player [String, nil] "first", "second", or nil
+      # @return [Game] new game instance with updated draw offer
+      # @raise [ArgumentError] if player is invalid
+      #
+      # @example
+      #   # First player offers a draw
+      #   game_with_offer = game.with_draw_offered_by("first")
+      #
+      #   # Withdraw draw offer
+      #   game_no_offer = game.with_draw_offered_by(nil)
+      def with_draw_offered_by(player)
+        self.class.new(
+          setup: @setup.to_s,
+          moves: @moves,
+          status: @status&.to_s,
+          draw_offered_by: player,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
@@ -352,6 +405,7 @@ module Sashite
           setup: @setup.to_s,
           moves: @moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
           meta: merged_meta,
           sides: @sides.to_h
         )
@@ -370,6 +424,7 @@ module Sashite
           setup: @setup.to_s,
           moves: new_moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
@@ -403,6 +458,17 @@ module Sashite
         !in_progress?
       end
 
+      # Check if a draw offer is pending
+      #
+      # @return [Boolean] true if a draw offer is pending
+      #
+      # @example
+      #   game.draw_offered?  # => true (if draw_offered_by is "first" or "second")
+      #   game.draw_offered?  # => false (if draw_offered_by is nil)
+      def draw_offered?
+        !@draw_offered_by.nil?
+      end
+
       # ========================================================================
       # Serialization
       # ========================================================================
@@ -417,6 +483,7 @@ module Sashite
       #   #   "setup" => "...",
       #   #   "moves" => [["e2-e4", 2.5], ["e7-e5", 3.1]],
       #   #   "status" => "in_progress",
+      #   #   "draw_offered_by" => "first",
       #   #   "meta" => {...},
       #   #   "sides" => {...}
       #   # }
@@ -428,12 +495,59 @@ module Sashite
 
         # Include optional fields if present
         result["status"] = @status.to_s if @status
+        result["draw_offered_by"] = @draw_offered_by if @draw_offered_by
         result["meta"] = @meta.to_h unless @meta.empty?
         result["sides"] = @sides.to_h unless @sides.empty?
 
         result
       end
 
+      # Compare with another game
+      #
+      # @param other [Object] object to compare
+      # @return [Boolean] true if equal
+      #
+      # @example
+      #   game1 == game2  # => true if all attributes match
+      def ==(other)
+        return false unless other.is_a?(Game)
+
+        @setup.to_s == other.setup.to_s &&
+          @moves == other.moves &&
+          @status&.to_s == other.status&.to_s &&
+          @draw_offered_by == other.draw_offered_by &&
+          @meta == other.meta &&
+          @sides == other.sides
+      end
+
+      # Generate hash code
+      #
+      # @return [Integer] hash code for this game
+      #
+      # @example
+      #   game.hash  # => 123456789
+      def hash
+        [@setup.to_s, @moves, @status&.to_s, @draw_offered_by, @meta, @sides].hash
+      end
+
+      # Generate debug representation
+      #
+      # @return [String] debug string
+      #
+      # @example
+      #   game.inspect
+      #   # => "#<Game setup=\"...\" moves=[...] status=\"in_progress\" draw_offered_by=\"first\">"
+      def inspect
+        parts = ["setup=#{@setup.to_s.inspect}"]
+        parts << "moves=#{@moves.inspect}"
+        parts << "status=#{@status&.to_s.inspect}" if @status
+        parts << "draw_offered_by=#{@draw_offered_by.inspect}" if @draw_offered_by
+        parts << "meta=#{@meta.inspect}" unless @meta.empty?
+        parts << "sides=#{@sides.inspect}" unless @sides.empty?
+
+        "#<#{self.class.name} #{parts.join(' ')}>"
+      end
+
       private
 
       # Validate and parse moves array
@@ -478,6 +592,16 @@ module Sashite
         # Return the move tuple with seconds as float
         [pan_notation, seconds.to_f].freeze
       end
+
+      # Validate draw_offered_by field
+      #
+      # @param value [String, nil] draw offer value to validate
+      # @raise [ArgumentError] if value is invalid
+      def validate_draw_offered_by(value)
+        return if VALID_DRAW_OFFERED_BY.include?(value)
+
+        raise ::ArgumentError, ERROR_INVALID_DRAW_OFFERED_BY
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pcn
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -113,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.6.9
 specification_version: 4
 summary: PCN (Portable Chess Notation) implementation for Ruby with comprehensive
   game record representation