sashite-feen 0.1.0 → 0.2.0

data/lib/sashite/feen/position.rb

@@ -2,25 +2,76 @@
 
 module Sashite
   module Feen
-    # Immutable aggregate for a FEEN position: placement + hands + styles
+    # Immutable representation of a complete board game position.
+    #
+    # Combines piece placement, pieces in hand, and style-turn information
+    # into a single unified position object. This represents a complete
+    # snapshot of the game state at a given moment.
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
     class Position
-      attr_reader :placement, :hands, :styles
+      # @return [Placement] Board piece placement configuration
+      attr_reader :placement
 
-      # @param placement [Sashite::Feen::Placement]
-      # @param hands     [Sashite::Feen::Hands]
-      # @param styles    [Sashite::Feen::Styles]
-      def initialize(placement, hands, styles)
-        unless placement.is_a?(Placement)
-          raise TypeError, "placement must be Sashite::Feen::Placement, got #{placement.class}"
-        end
-        raise TypeError, "hands must be Sashite::Feen::Hands, got #{hands.class}" unless hands.is_a?(Hands)
-        raise TypeError, "styles must be Sashite::Feen::Styles, got #{styles.class}" unless styles.is_a?(Styles)
+      # @return [Hands] Pieces held in hand by each player
+      attr_reader :hands
+
+      # @return [Styles] Game styles and active player indicator
+      attr_reader :styles
 
+      # Create a new immutable Position object.
+      #
+      # @param placement [Placement] Board configuration
+      # @param hands [Hands] Captured pieces in hand
+      # @param styles [Styles] Style-turn information
+      #
+      # @example Create a chess starting position
+      #   position = Position.new(placement, hands, styles)
+      #
+      # @example Parse from FEEN string
+      #   position = Sashite::Feen.parse("+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")
+      def initialize(placement, hands, styles)
         @placement = placement
-        @hands     = hands
-        @styles    = styles
+        @hands = hands
+        @styles = styles
+
         freeze
       end
+
+      # Convert position to its canonical FEEN string representation.
+      #
+      # Generates a deterministic FEEN string. The same position will
+      # always produce the same canonical string, enabling position
+      # equality via string comparison.
+      #
+      # @return [String] Canonical FEEN notation string
+      #
+      # @example
+      #   position.to_s
+      #   # => "+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"
+      def to_s
+        Dumper.dump(self)
+      end
+
+      # Compare two positions for equality.
+      #
+      # @param other [Position] Another position object
+      # @return [Boolean] True if all components are equal
+      def ==(other)
+        other.is_a?(Position) &&
+          placement == other.placement &&
+          hands == other.hands &&
+          styles == other.styles
+      end
+
+      alias eql? ==
+
+      # Generate hash code for position.
+      #
+      # @return [Integer] Hash code based on all components
+      def hash
+        [placement, hands, styles].hash
+      end
     end
   end
 end

data/lib/sashite/feen/styles.rb

@@ -1,74 +1,71 @@
 # frozen_string_literal: true
 
-require "sashite/sin"
-
 module Sashite
   module Feen
-    # Immutable styles descriptor for FEEN style/turn field:
-    # - first_family  : one-letter SIN family (Symbol, :A..:Z)
-    # - second_family : one-letter SIN family (Symbol, :A..:Z)
-    # - turn          : :first or :second (uppercase on dumper for the side to move)
+    # Immutable representation of game styles and active player.
+    #
+    # Stores the style identifiers (SIN) for both players, with the active
+    # player's style indicating whose turn it is to move. The case of each
+    # style identifier indicates which player uses it (uppercase = first player,
+    # lowercase = second player).
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
+    # @see https://sashite.dev/specs/sin/1.0.0/
     class Styles
-      attr_reader :first_family, :second_family, :turn
-
-      VALID_TURNS = %i[first second].freeze
+      # @return [Object] Style identifier of the active player (to move)
+      attr_reader :active
+
+      # @return [Object] Style identifier of the inactive player (waiting)
+      attr_reader :inactive
+
+      # Create a new immutable Styles object.
+      #
+      # @param active [Object] SIN identifier for active player's style
+      # @param inactive [Object] SIN identifier for inactive player's style
+      #
+      # @example Chess game, white to move
+      #   styles = Styles.new(sin_C, sin_c)
+      #
+      # @example Chess game, black to move
+      #   styles = Styles.new(sin_c, sin_C)
+      #
+      # @example Cross-style game, first player to move
+      #   styles = Styles.new(sin_C, sin_m)
+      def initialize(active, inactive)
+        @active = active
+        @inactive = inactive
 
-      # @param first_family  [Symbol, String, Sashite::Sin::Identifier]
-      # @param second_family [Symbol, String, Sashite::Sin::Identifier]
-      # @param turn          [:first, :second]
-      def initialize(first_family, second_family, turn)
-        @first_family  = _coerce_family(first_family)
-        @second_family = _coerce_family(second_family)
-        @turn = _coerce_turn(turn)
         freeze
       end
 
-      # Helpers for dumper -----------------------------------------------------
-
-      # Return single-letter uppercase string for first/second family
-      def first_letter_uc
-        _family_letter_uc(@first_family)
-      end
-
-      def second_letter_uc
-        _family_letter_uc(@second_family)
+      # Convert styles to their FEEN string representation.
+      #
+      # @return [String] FEEN style-turn field
+      #
+      # @example
+      #   styles.to_s
+      #   # => "C/c"
+      def to_s
+        Dumper::StyleTurn.dump(self)
       end
 
-      private
-
-      def _coerce_turn(t)
-        raise ArgumentError, "turn must be :first or :second, got #{t.inspect}" unless VALID_TURNS.include?(t)
-
-        t
+      # Compare two styles for equality.
+      #
+      # @param other [Styles] Another styles object
+      # @return [Boolean] True if active and inactive styles are equal
+      def ==(other)
+        other.is_a?(Styles) &&
+          active == other.active &&
+          inactive == other.inactive
       end
 
-      # Accepts SIN Identifier, Symbol, or String
-      # Canonical storage is a Symbol in :A..:Z (uppercase)
-      def _coerce_family(x)
-        family_sym =
-          case x
-          when ::Sashite::Sin::Identifier
-            x.family
-          when Symbol
-            x
-          else
-            s = String(x)
-            raise ArgumentError, "invalid SIN family #{x.inspect}" unless s.match?(/\A[A-Za-z]\z/)
-
-            s.upcase.to_sym
-          end
-
-        raise ArgumentError, "Family must be :A..:Z, got #{family_sym.inspect}" unless (:A..:Z).cover?(family_sym)
-
-        # Validate via SIN once (ensures family is recognized by sashite-sin)
-        raise Error::Style, "Unknown SIN family #{family_sym.inspect}" unless ::Sashite::Sin.valid?(family_sym.to_s)
-
-        family_sym
-      end
+      alias eql? ==
 
-      def _family_letter_uc(family_sym)
-        # Build a canonical SIN identifier to get the letter; side doesn't matter for uc
-        ::Sashite::Sin.identifier(family_sym, :first).to_s # uppercase
+      # Generate hash code for styles.
+      #
+      # @return [Integer] Hash code based on active and inactive styles
+      def hash
+        [active, inactive].hash
       end
     end
   end

data/lib/sashite/feen.rb

@@ -1,106 +1,67 @@
 # frozen_string_literal: true
 
-# Public API for FEEN (Forsyth–Edwards Enhanced Notation)
-# - Pure functions, no global state
-# - Immutable value objects
-# - Delegates parsing/dumping to dedicated components
-
-require "sashite/epin"
-require "sashite/sin"
-
-require_relative "feen/error"
-require_relative "feen/position"
-require_relative "feen/placement"
-require_relative "feen/hands"
-require_relative "feen/styles"
-require_relative "feen/ordering"
-require_relative "feen/parser"
 require_relative "feen/dumper"
+require_relative "feen/parser"
 
 module Sashite
+  # FEEN (Forsyth–Edwards Enhanced Notation) module provides parsing and dumping
+  # functionality for board game positions.
+  #
+  # FEEN is a universal, rule-agnostic notation for representing board game positions.
+  # It extends traditional FEN to support multiple game systems, cross-style games,
+  # multi-dimensional boards, and captured pieces.
+  #
+  # A FEEN string consists of three space-separated fields:
+  # 1. Piece placement: Board configuration using EPIN notation
+  # 2. Pieces in hand: Captured pieces held by each player
+  # 3. Style-turn: Game styles and active player
+  #
+  # @see https://sashite.dev/specs/feen/1.0.0/
   module Feen
-    class << self
-      # Parse a FEEN string into an immutable Position object.
-      #
-      # @param feen [String]
-      # @return [Sashite::Feen::Position]
-      def parse(feen)
-        s = String(feen).strip
-        raise Error::Syntax, "empty FEEN input" if s.empty?
-
-        Parser.parse(s).freeze
-      rescue ArgumentError => e
-        # Normalise en Syntax pour surface d'erreurs plus propre
-        raise Error::Syntax, e.message
-      end
-
-      # Validate a FEEN string.
-      #
-      # @param feen [String]
-      # @return [Boolean]
-      def valid?(feen)
-        parse(feen)
-        true
-      rescue Error::Validation, Error::Syntax, Error::Piece, Error::Style, Error::Count, Error::Bounds
-        false
-      end
-
-      # Dump a Position to its canonical FEEN string.
-      #
-      # @param position [Sashite::Feen::Position, String]  # String => parse puis dump
-      # @return [String] canonical FEEN
-      def dump(position)
-        pos = _coerce_position(position)
-        Dumper.dump(pos).dup.freeze
-      end
-
-      # Canonicalize a FEEN string (parse → dump).
-      #
-      # @param feen [String]
-      # @return [String] canonical FEEN
-      def normalize(feen)
-        dump(parse(feen))
-      end
-
-      # Build a Position from its three FEEN fields.
-      #
-      # Each argument accepts either a String (parsed by its field parser)
-      # or the corresponding value-object (Placement/Hands/Styles).
-      #
-      # @param piece_placement [String, Sashite::Feen::Placement]
-      # @param pieces_in_hand  [String, Sashite::Feen::Hands]
-      # @param style_turn      [String, Sashite::Feen::Styles]
-      # @return [Sashite::Feen::Position]
-      def build(piece_placement:, pieces_in_hand:, style_turn:)
-        placement = _coerce_component(Placement, Parser::PiecePlacement, piece_placement)
-        hands     = _coerce_component(Hands,     Parser::PiecesInHand,   pieces_in_hand)
-        styles    = _coerce_component(Styles,    Parser::StyleTurn,      style_turn)
-
-        Position.new(placement, hands, styles).freeze
-      end
-
-      private
-
-      # -- helpers -------------------------------------------------------------
-
-      def _coerce_position(obj)
-        return obj if obj.is_a?(Position)
-        return parse(obj) if obj.is_a?(String)
-
-        raise TypeError, "expected Sashite::Feen::Position or FEEN String, got #{obj.class}"
-      end
+    # Dump a Position object into its canonical FEEN string representation.
+    #
+    # Generates a deterministic FEEN string from a position object. The same
+    # position will always produce the same canonical string, ensuring
+    # position equality can be tested via string comparison.
+    #
+    # @param position [Position] A position object with placement, hands, and styles
+    # @return [String] Canonical FEEN notation string
+    #
+    # @example Dump a position to FEEN
+    #   feen_string = Sashite::Feen.dump(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"
+    #
+    # @example Round-trip parsing and dumping
+    #   original = "+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"
+    #   position = Sashite::Feen.parse(original)
+    #   Sashite::Feen.dump(position) == original  # => true
+    def self.dump(position)
+      Dumper.dump(position)
+    end
 
-      def _coerce_component(klass, field_parser_mod, value)
-        case value
-        when klass
-          value
-        when String
-          field_parser_mod.parse(value)
-        else
-          raise TypeError,
-                "expected #{klass} or String for #{klass.name.split('::').last.downcase}, got #{value.class}"
-        end
-      end
+    # Parse a FEEN string into an immutable Position object.
+    #
+    # This method parses the three FEEN fields and constructs an immutable position
+    # object with placement, hands, and styles components.
+    #
+    # @param string [String] A FEEN notation string with three space-separated fields
+    # @return [Position] Immutable position object
+    # @raise [Error::Syntax] If the FEEN structure is malformed
+    # @raise [Error::Piece] If EPIN notation is invalid
+    # @raise [Error::Style] If SIN notation is invalid
+    # @raise [Error::Count] If piece counts are invalid
+    # @raise [Error::Validation] For other semantic violations
+    #
+    # @example Parse a chess starting position
+    #   position = Sashite::Feen.parse("+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")
+    #   position.placement  # => Placement object (board configuration)
+    #   position.hands      # => Hands object (pieces in hand)
+    #   position.styles     # => Styles object (style-turn information)
+    #
+    # @example Parse a shogi position with captured pieces
+    #   position = Sashite::Feen.parse("lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL P/p S/s")
+    def self.parse(string)
+      Parser.parse(string)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-feen
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -62,7 +62,6 @@ files:
 - lib/sashite/feen/dumper/style_turn.rb
 - lib/sashite/feen/error.rb
 - lib/sashite/feen/hands.rb
-- lib/sashite/feen/ordering.rb
 - lib/sashite/feen/parser.rb
 - lib/sashite/feen/parser/piece_placement.rb
 - lib/sashite/feen/parser/pieces_in_hand.rb

data/lib/sashite/feen/ordering.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Feen
-    # Deterministic ordering helpers (kept minimal for now).
-    # If you later need domain-specific sort (e.g., EPIN-aware), centralize it here.
-    module Ordering
-      module_function
-
-      # Default lexicographic sort key for serialized EPIN tokens (String)
-      def hand_token_key(token_str)
-        String(token_str)
-      end
-    end
-  end
-end