sashite-pcn 0.2.0 → 0.3.0

data/lib/sashite/pcn.rb

@@ -1,68 +1,58 @@
 # 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.
+  # PCN (Portable Chess Notation) implementation for Ruby
   #
-  # Provides a comprehensive, rule-agnostic format for representing complete
-  # chess game records across variants, integrating PMN, FEEN, and SNN
-  # specifications.
+  # Provides functionality for representing complete chess game records
+  # across variants using a comprehensive JSON-based format.
   #
-  # @see https://sashite.dev/specs/pcn/1.0.0/
+  # This implementation is strictly compliant with PCN Specification v1.0.0
+  # @see https://sashite.dev/specs/pcn/1.0.0/ PCN Specification v1.0.0
   module Pcn
-    # Parse a PCN hash into a Game object.
+    # Parse a PCN document from a hash structure
     #
-    # @param hash [Hash] PCN document hash
-    # @return [Game] Immutable game object
-    # @raise [Error] If parsing or validation fails
+    # @param hash [Hash] the PCN document data
+    # @return [Game] new game instance
+    # @raise [ArgumentError] if the document is invalid
     #
-    # @example
+    # @example Parse minimal PCN
+    #   game = Sashite::Pcn.parse({
+    #     "setup" => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c"
+    #   })
+    #
+    # @example Parse complete game
     #   game = Sashite::Pcn.parse({
-    #     "setup" => "8/8/8/8/8/8/8/8 / C/c",
-    #     "moves" => []
+    #     "meta" => { "event" => "World Championship" },
+    #     "sides" => {
+    #       "first" => { "name" => "Carlsen", "elo" => 2830, "style" => "CHESS" },
+    #       "second" => { "name" => "Nakamura", "elo" => 2794, "style" => "chess" }
+    #     },
+    #     "setup" => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c",
+    #     "moves" => [["e2", "e4"], ["e7", "e5"]],
+    #     "status" => "in_progress"
     #   })
     def self.parse(hash)
-      Game.parse(hash)
+      Game.new(**hash.transform_keys(&:to_sym))
     end
 
-    # Validate a PCN hash without raising exceptions.
+    # Validate a PCN document structure
     #
-    # @param hash [Hash] PCN document hash
-    # @return [Boolean] true if valid, false otherwise
+    # @param hash [Hash] the PCN document data
+    # @return [Boolean] true if the document is structurally valid
     #
     # @example
-    #   Sashite::Pcn.valid?({ "setup" => "...", "moves" => [] })  # => true
-    #   Sashite::Pcn.valid?({ "setup" => "" })                    # => false
+    #   Sashite::Pcn.valid?({ "setup" => "8/8/8/8/8/8/8/8 / C/c" })  # => true
+    #   Sashite::Pcn.valid?({ "moves" => [] })                        # => false
     def self.valid?(hash)
-      Game.valid?(hash)
-    end
+      return false unless hash.is_a?(::Hash)
+      return false unless hash.key?("setup") || hash.key?(:setup)
 
-    # 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)
+      parse(hash)
+      true
+    rescue ::ArgumentError, ::TypeError
+      false
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pcn
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: sashite-cgsn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: sashite-feen
   requirement: !ruby/object:Gem::Requirement
@@ -71,11 +85,10 @@ files:
 - 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
+- lib/sashite/pcn/game/meta.rb
+- lib/sashite/pcn/game/sides.rb
+- lib/sashite/pcn/game/sides/player.rb
 homepage: https://github.com/sashite/pcn.rb
 licenses:
 - MIT

data/lib/sashite/pcn/error.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Pcn
-    # Base error class for all PCN-related errors.
-    #
-    # @see https://sashite.dev/specs/pcn/1.0.0/
-    class Error < ::StandardError
-      # Error raised when PCN structure parsing fails.
-      #
-      # This occurs when the PCN hash structure is malformed or missing
-      # required fields.
-      #
-      # @example
-      #   raise Error::Parse, "Missing required field 'setup'"
-      class Parse < Error; end
-
-      # Error raised when PCN format validation fails.
-      #
-      # This occurs when field values do not conform to their expected
-      # formats (e.g., invalid FEEN string, invalid PMN array, invalid
-      # status value).
-      #
-      # @example
-      #   raise Error::Validation, "Invalid status value: 'unknown'"
-      class Validation < Error; end
-
-      # Error raised when PCN semantic consistency validation fails.
-      #
-      # This occurs when field combinations violate semantic rules
-      # (e.g., SNN/SIN case consistency, invalid player object structure).
-      #
-      # @example
-      #   raise Error::Semantic, "SNN 'CHESS' does not match SIN 'c' in FEEN"
-      class Semantic < Error; end
-    end
-  end
-end

data/lib/sashite/pcn/meta.rb

@@ -1,275 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Pcn
-    # Immutable representation of game metadata.
-    #
-    # All fields are optional. Metadata provides contextual information
-    # about the game session.
-    #
-    # @see https://sashite.dev/specs/pcn/1.0.0/
-    class Meta
-      # ISO 8601 date format: YYYY-MM-DD
-      DATE_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
-
-      # ISO 8601 datetime format with UTC timezone: YYYY-MM-DDTHH:MM:SSZ
-      DATETIME_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\z/
-
-      # Absolute URL pattern (http:// or https://)
-      URL_PATTERN = %r{\Ahttps?://.+\z}
-
-      # @return [String, nil] Game name or opening identification
-      attr_reader :name
-
-      # @return [String, nil] Tournament or event name
-      attr_reader :event
-
-      # @return [String, nil] Physical or virtual venue
-      attr_reader :location
-
-      # @return [Integer, nil] Round number in tournament context
-      attr_reader :round
-
-      # @return [String, nil] Game start date (ISO 8601: YYYY-MM-DD)
-      attr_reader :started_on
-
-      # @return [String, nil] Game completion timestamp (ISO 8601 UTC: YYYY-MM-DDTHH:MM:SSZ)
-      attr_reader :finished_at
-
-      # @return [String, nil] Reference link to external resource
-      attr_reader :href
-
-      # Parse a meta hash into a Meta object.
-      #
-      # @param hash [Hash] Metadata hash
-      # @return [Meta] Immutable meta object
-      # @raise [Error::Validation] If validation fails
-      #
-      # @example
-      #   meta = Meta.parse({
-      #     "event" => "World Championship",
-      #     "round" => 5
-      #   })
-      def self.parse(hash)
-        raise Error::Validation, "Meta must be a Hash, got #{hash.class}" unless hash.is_a?(::Hash)
-
-        new(
-          name:        hash["name"],
-          event:       hash["event"],
-          location:    hash["location"],
-          round:       hash["round"],
-          started_on:  hash["started_on"],
-          finished_at: hash["finished_at"],
-          href:        hash["href"]
-        )
-      end
-
-      # Validate a meta hash without raising exceptions.
-      #
-      # @param hash [Hash] Metadata hash
-      # @return [Boolean] true if valid, false otherwise
-      #
-      # @example
-      #   Meta.valid?({ "event" => "Tournament" })  # => true
-      def self.valid?(hash)
-        parse(hash)
-        true
-      rescue Error
-        false
-      end
-
-      # Create a new Meta.
-      #
-      # @param name [String, nil] Game name
-      # @param event [String, nil] Event name
-      # @param location [String, nil] Location
-      # @param round [Integer, nil] Round number
-      # @param started_on [String, nil] Start date (YYYY-MM-DD)
-      # @param finished_at [String, nil] Finish timestamp (YYYY-MM-DDTHH:MM:SSZ)
-      # @param href [String, nil] Reference URL
-      # @raise [Error::Validation] If validation fails
-      #
-      # @example
-      #   meta = Meta.new(
-      #     event: "World Championship",
-      #     round: 5,
-      #     started_on: "2025-11-15"
-      #   )
-      def initialize(name: nil, event: nil, location: nil, round: nil, started_on: nil, finished_at: nil, href: nil)
-        @name = name
-        @event = event
-        @location = location
-        @round = round
-        @started_on = started_on
-        @finished_at = finished_at
-        @href = href
-
-        validate!
-
-        freeze
-      end
-
-      # Check if the meta is valid.
-      #
-      # @return [Boolean] true if valid
-      def valid?
-        validate!
-        true
-      rescue Error
-        false
-      end
-
-      # Check if metadata is empty (all fields nil).
-      #
-      # @return [Boolean] true if all fields are nil
-      def empty?
-        name.nil? && event.nil? && location.nil? && round.nil? &&
-          started_on.nil? && finished_at.nil? && href.nil?
-      end
-
-      # Convert to hash representation.
-      #
-      # @return [Hash] Metadata hash (excludes nil values)
-      #
-      # @example
-      #   meta.to_h  # => { "event" => "Tournament", "round" => 5 }
-      def to_h
-        hash = {}
-
-        hash["name"] = name unless name.nil?
-        hash["event"] = event unless event.nil?
-        hash["location"] = location unless location.nil?
-        hash["round"] = round unless round.nil?
-        hash["started_on"] = started_on unless started_on.nil?
-        hash["finished_at"] = finished_at unless finished_at.nil?
-        hash["href"] = href unless href.nil?
-
-        hash
-      end
-
-      # String representation.
-      #
-      # @return [String] Inspectable representation
-      def to_s
-        fields = []
-        fields << "event=#{event.inspect}" unless event.nil?
-        fields << "round=#{round}" unless round.nil?
-        fields << "location=#{location.inspect}" unless location.nil?
-
-        "#<#{self.class} #{fields.join(' ')}>"
-      end
-      alias inspect to_s
-
-      # Equality comparison.
-      #
-      # @param other [Meta] Other meta
-      # @return [Boolean] true if equal
-      def ==(other)
-        other.is_a?(self.class) &&
-          other.name == name &&
-          other.event == event &&
-          other.location == location &&
-          other.round == round &&
-          other.started_on == started_on &&
-          other.finished_at == finished_at &&
-          other.href == href
-      end
-      alias eql? ==
-
-      # Hash code for equality.
-      #
-      # @return [Integer] Hash code
-      def hash
-        [self.class, name, event, location, round, started_on, finished_at, href].hash
-      end
-
-      private
-
-      # Validate all fields.
-      def validate!
-        validate_name!
-        validate_event!
-        validate_location!
-        validate_round!
-        validate_started_on!
-        validate_finished_at!
-        validate_href!
-      end
-
-      # Validate name field.
-      def validate_name!
-        return if name.nil?
-
-        return if name.is_a?(::String)
-
-        raise Error::Validation, "Meta 'name' must be a String, got #{name.class}"
-      end
-
-      # Validate event field.
-      def validate_event!
-        return if event.nil?
-
-        return if event.is_a?(::String)
-
-        raise Error::Validation, "Meta 'event' must be a String, got #{event.class}"
-      end
-
-      # Validate location field.
-      def validate_location!
-        return if location.nil?
-
-        return if location.is_a?(::String)
-
-        raise Error::Validation, "Meta 'location' must be a String, got #{location.class}"
-      end
-
-      # Validate round field.
-      def validate_round!
-        return if round.nil?
-
-        raise Error::Validation, "Meta 'round' must be an Integer, got #{round.class}" unless round.is_a?(::Integer)
-
-        return unless round < 1
-
-        raise Error::Validation, "Meta 'round' must be >= 1, got #{round}"
-      end
-
-      # Validate started_on field.
-      def validate_started_on!
-        return if started_on.nil?
-
-        unless started_on.is_a?(::String)
-          raise Error::Validation, "Meta 'started_on' must be a String, got #{started_on.class}"
-        end
-
-        return if DATE_PATTERN.match?(started_on)
-
-        raise Error::Validation, "Meta 'started_on' must match format YYYY-MM-DD, got #{started_on.inspect}"
-      end
-
-      # Validate finished_at field.
-      def validate_finished_at!
-        return if finished_at.nil?
-
-        unless finished_at.is_a?(::String)
-          raise Error::Validation, "Meta 'finished_at' must be a String, got #{finished_at.class}"
-        end
-
-        return if DATETIME_PATTERN.match?(finished_at)
-
-        raise Error::Validation, "Meta 'finished_at' must match format YYYY-MM-DDTHH:MM:SSZ, got #{finished_at.inspect}"
-      end
-
-      # Validate href field.
-      def validate_href!
-        return if href.nil?
-
-        raise Error::Validation, "Meta 'href' must be a String, got #{href.class}" unless href.is_a?(::String)
-
-        return if URL_PATTERN.match?(href)
-
-        raise Error::Validation, "Meta 'href' must be an absolute URL (http:// or https://), got #{href.inspect}"
-      end
-    end
-  end
-end

data/lib/sashite/pcn/player.rb

@@ -1,186 +0,0 @@
-# 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