sashite-feen 0.1.0 → 0.3.0

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.3.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