sashite-pcn 0.1.0

data/lib/sashite/pcn/player.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    # Immutable representation of player information.
+    #
+    # All fields are optional. Player provides identification and
+    # rating information for game participants.
+    #
+    # @see https://sashite.dev/specs/pcn/1.0.0/
+    class Player
+      # @return [String, nil] Style name in SNN format
+      attr_reader :style
+
+      # @return [String, nil] Player name or identifier
+      attr_reader :name
+
+      # @return [Integer, nil] Elo rating
+      attr_reader :elo
+
+      # Parse a player hash into a Player object.
+      #
+      # @param hash [Hash] Player hash
+      # @return [Player] Immutable player object
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   player = Player.parse({
+      #     "name" => "Magnus Carlsen",
+      #     "elo" => 2830,
+      #     "style" => "CHESS"
+      #   })
+      def self.parse(hash)
+        raise Error::Validation, "Player must be a Hash, got #{hash.class}" unless hash.is_a?(::Hash)
+
+        new(
+          style: hash["style"],
+          name:  hash["name"],
+          elo:   hash["elo"]
+        )
+      end
+
+      # Validate a player hash without raising exceptions.
+      #
+      # @param hash [Hash] Player hash
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Player.valid?({ "name" => "Alice" })  # => true
+      def self.valid?(hash)
+        parse(hash)
+        true
+      rescue Error
+        false
+      end
+
+      # Create a new Player.
+      #
+      # @param style [String, nil] Style name (SNN format)
+      # @param name [String, nil] Player name
+      # @param elo [Integer, nil] Elo rating
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   player = Player.new(
+      #     name: "Magnus Carlsen",
+      #     elo: 2830,
+      #     style: "CHESS"
+      #   )
+      def initialize(style: nil, name: nil, elo: nil)
+        @style = style
+        @name = name
+        @elo = elo
+
+        validate!
+
+        freeze
+      end
+
+      # Check if the player is valid.
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate!
+        true
+      rescue Error
+        false
+      end
+
+      # Check if player is empty (all fields nil).
+      #
+      # @return [Boolean] true if all fields are nil
+      def empty?
+        style.nil? && name.nil? && elo.nil?
+      end
+
+      # Convert to hash representation.
+      #
+      # @return [Hash] Player hash (excludes nil values)
+      #
+      # @example
+      #   player.to_h  # => { "name" => "Alice", "elo" => 2800 }
+      def to_h
+        hash = {}
+
+        hash["style"] = style unless style.nil?
+        hash["name"] = name unless name.nil?
+        hash["elo"] = elo unless elo.nil?
+
+        hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Inspectable representation
+      def to_s
+        fields = []
+        fields << "name=#{name.inspect}" unless name.nil?
+        fields << "elo=#{elo}" unless elo.nil?
+        fields << "style=#{style.inspect}" unless style.nil?
+
+        "#<#{self.class} #{fields.join(' ')}>"
+      end
+      alias inspect to_s
+
+      # Equality comparison.
+      #
+      # @param other [Player] Other player
+      # @return [Boolean] true if equal
+      def ==(other)
+        other.is_a?(self.class) &&
+          other.style == style &&
+          other.name == name &&
+          other.elo == elo
+      end
+      alias eql? ==
+
+      # Hash code for equality.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [self.class, style, name, elo].hash
+      end
+
+      private
+
+      # Validate all fields.
+      def validate!
+        validate_style!
+        validate_name!
+        validate_elo!
+      end
+
+      # Validate style field.
+      def validate_style!
+        return if style.nil?
+
+        raise Error::Validation, "Player 'style' must be a String, got #{style.class}" unless style.is_a?(::String)
+
+        return if ::Sashite::Snn.valid?(style)
+
+        raise Error::Validation, "Player 'style' must be valid SNN format, got #{style.inspect}"
+      end
+
+      # Validate name field.
+      def validate_name!
+        return if name.nil?
+
+        return if name.is_a?(::String)
+
+        raise Error::Validation, "Player 'name' must be a String, got #{name.class}"
+      end
+
+      # Validate elo field.
+      def validate_elo!
+        return if elo.nil?
+
+        raise Error::Validation, "Player 'elo' must be an Integer, got #{elo.class}" unless elo.is_a?(::Integer)
+
+        return unless elo < 0
+
+        raise Error::Validation, "Player 'elo' must be >= 0, got #{elo}"
+      end
+    end
+  end
+end

data/lib/sashite/pcn/sides.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    # Immutable representation of player information for both sides.
+    #
+    # Contains player information for first and second player.
+    # At least one player must be defined when sides are present.
+    #
+    # @see https://sashite.dev/specs/pcn/1.0.0/
+    class Sides
+      # @return [Player, nil] First player information
+      attr_reader :first
+
+      # @return [Player, nil] Second player information
+      attr_reader :second
+
+      # Parse a sides hash into a Sides object.
+      #
+      # @param hash [Hash] Sides hash
+      # @return [Sides] Immutable sides object
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   sides = Sides.parse({
+      #     "first" => { "name" => "Alice", "elo" => 2800 },
+      #     "second" => { "name" => "Bob", "elo" => 2750 }
+      #   })
+      def self.parse(hash)
+        raise Error::Validation, "Sides must be a Hash, got #{hash.class}" unless hash.is_a?(::Hash)
+
+        first = parse_player(hash["first"], "first")
+        second = parse_player(hash["second"], "second")
+
+        new(first:, second:)
+      end
+
+      # Validate a sides hash without raising exceptions.
+      #
+      # @param hash [Hash] Sides hash
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Sides.valid?({ "first" => { "name" => "Alice" } })  # => true
+      def self.valid?(hash)
+        parse(hash)
+        true
+      rescue Error
+        false
+      end
+
+      # Create a new Sides.
+      #
+      # @param first [Player, Hash, nil] First player information
+      # @param second [Player, Hash, nil] Second player information
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   sides = Sides.new(
+      #     first: Player.new(name: "Alice", elo: 2800),
+      #     second: Player.new(name: "Bob", elo: 2750)
+      #   )
+      def initialize(first: nil, second: nil)
+        @first = normalize_player(first, "first")
+        @second = normalize_player(second, "second")
+
+        validate!
+
+        freeze
+      end
+
+      # Check if the sides are valid.
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate!
+        true
+      rescue Error
+        false
+      end
+
+      # Check if both sides are empty.
+      #
+      # @return [Boolean] true if both players are nil
+      def empty?
+        first.nil? && second.nil?
+      end
+
+      # Convert to hash representation.
+      #
+      # @return [Hash] Sides hash (excludes nil values)
+      #
+      # @example
+      #   sides.to_h  # => { "first" => {...}, "second" => {...} }
+      def to_h
+        hash = {}
+
+        hash["first"] = first.to_h unless first.nil?
+        hash["second"] = second.to_h unless second.nil?
+
+        hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Inspectable representation
+      def to_s
+        fields = []
+        fields << "first=#{first.name.inspect}" if first && first.name
+        fields << "second=#{second.name.inspect}" if second && second.name
+
+        "#<#{self.class} #{fields.join(' ')}>"
+      end
+      alias inspect to_s
+
+      # Equality comparison.
+      #
+      # @param other [Sides] Other sides
+      # @return [Boolean] true if equal
+      def ==(other)
+        other.is_a?(self.class) &&
+          other.first == first &&
+          other.second == second
+      end
+      alias eql? ==
+
+      # Hash code for equality.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [self.class, first, second].hash
+      end
+
+      private
+
+      # Parse player field.
+      def self.parse_player(value, field_name)
+        return nil if value.nil?
+
+        Player.parse(value)
+      rescue Error => e
+        raise Error::Validation, "Invalid '#{field_name}' player: #{e.message}"
+      end
+
+      # Normalize player to Player object.
+      def normalize_player(value, field_name)
+        return nil if value.nil?
+        return value if value.is_a?(Player)
+
+        Player.parse(value)
+      rescue Error => e
+        raise Error::Validation, "Invalid '#{field_name}' player: #{e.message}"
+      end
+
+      # Validate all fields.
+      def validate!
+        validate_structure!
+        validate_first!
+        validate_second!
+      end
+
+      # Validate that at least one player is defined.
+      def validate_structure!
+        return unless first.nil? && second.nil?
+
+        raise Error::Validation, "Sides must have at least one player defined"
+      end
+
+      # Validate first player.
+      def validate_first!
+        return if first.nil?
+
+        raise Error::Validation, "Sides 'first' must be a Player object, got #{first.class}" unless first.is_a?(Player)
+
+        return if first.valid?
+
+        raise Error::Validation, "Sides 'first' player validation failed"
+      end
+
+      # Validate second player.
+      def validate_second!
+        return if second.nil?
+
+        unless second.is_a?(Player)
+          raise Error::Validation, "Sides 'second' must be a Player object, got #{second.class}"
+        end
+
+        return if second.valid?
+
+        raise Error::Validation, "Sides 'second' player validation failed"
+      end
+    end
+  end
+end

data/lib/sashite/pcn.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "sashite/pmn"
+require "sashite/feen"
+require "sashite/snn"
+
+require_relative "pcn/error"
+require_relative "pcn/meta"
+require_relative "pcn/player"
+require_relative "pcn/sides"
+require_relative "pcn/game"
+
+module Sashite
+  # PCN (Portable Chess Notation) implementation.
+  #
+  # Provides a comprehensive, rule-agnostic format for representing complete
+  # chess game records across variants, integrating PMN, FEEN, and SNN
+  # specifications.
+  #
+  # @see https://sashite.dev/specs/pcn/1.0.0/
+  module Pcn
+    # Parse a PCN hash into a Game object.
+    #
+    # @param hash [Hash] PCN document hash
+    # @return [Game] Immutable game object
+    # @raise [Error] If parsing or validation fails
+    #
+    # @example
+    #   game = Sashite::Pcn.parse({
+    #     "setup" => "8/8/8/8/8/8/8/8 / C/c",
+    #     "moves" => []
+    #   })
+    def self.parse(hash)
+      Game.parse(hash)
+    end
+
+    # Validate a PCN hash without raising exceptions.
+    #
+    # @param hash [Hash] PCN document hash
+    # @return [Boolean] true if valid, false otherwise
+    #
+    # @example
+    #   Sashite::Pcn.valid?({ "setup" => "...", "moves" => [] })  # => true
+    #   Sashite::Pcn.valid?({ "setup" => "" })                    # => false
+    def self.valid?(hash)
+      Game.valid?(hash)
+    end
+
+    # Create a new game from components.
+    #
+    # @param attributes [Hash] Game attributes as keyword arguments
+    # @option attributes [Feen::Position, String] :setup Initial position (required)
+    # @option attributes [Array<Pmn::Move, Array>] :moves Move sequence (required)
+    # @option attributes [String, nil] :status Game status (optional)
+    # @option attributes [Meta, Hash, nil] :meta Metadata (optional)
+    # @option attributes [Sides, Hash, nil] :sides Player information (optional)
+    # @return [Game] Immutable game object
+    #
+    # @example
+    #   game = Sashite::Pcn.new(
+    #     setup: Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c"),
+    #     moves: []
+    #   )
+    def self.new(**attributes)
+      Game.new(**attributes)
+    end
+  end
+end

data/lib/sashite-pcn.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/pcn"
+
+# Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Sashité Protocol specifications.
+#
+# @see https://sashite.dev/protocol/ Sashité Protocol
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
+module Sashite
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: sashite-pcn
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sashite-feen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: sashite-pmn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: sashite-snn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: |
+  PCN (Portable Chess Notation) provides a comprehensive, JSON-based format for representing
+  complete chess game records across variants. This gem implements the PCN Specification v1.0.0
+  with a modern Ruby interface featuring immutable game objects and functional programming
+  principles. PCN integrates the Sashité ecosystem specifications (PMN for moves, FEEN for
+  positions, and SNN for style identification) to create a unified, rule-agnostic game recording
+  system. Supports traditional single-variant games and cross-variant scenarios where players
+  use different game systems, with complete metadata tracking including player information,
+  tournament context, and game status. Perfect for game engines, database storage, game analysis
+  tools, and archival systems requiring comprehensive game record management across diverse
+  abstract strategy board games.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-pcn.rb
+- lib/sashite/pcn.rb
+- lib/sashite/pcn/error.rb
+- lib/sashite/pcn/game.rb
+- lib/sashite/pcn/meta.rb
+- lib/sashite/pcn/player.rb
+- lib/sashite/pcn/sides.rb
+homepage: https://github.com/sashite/pcn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/pcn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/pcn.rb/main
+  homepage_uri: https://github.com/sashite/pcn.rb
+  source_code_uri: https://github.com/sashite/pcn.rb
+  specification_uri: https://sashite.dev/specs/pcn/1.0.0/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: PCN (Portable Chess Notation) implementation for Ruby with comprehensive
+  game record representation
+test_files: []