sashite-feen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5bcbcddcc2de55695f9a203e30fa5d3d236deaf7c0e3975011ae1a47f389cd7c
+  data.tar.gz: 98b184086642d30761cf4646dbeac1ca0a88860c11d18a15866f01e7f0b0e040
+SHA512:
+  metadata.gz: cb41ec980de1a7ae5237da821f0a3be0cabe50768cb0dceec8988465336512a0705aec6f5aa9acfe1b0cf43770996581355029be8623a19d8a44dc737c628d83
+  data.tar.gz: 95507ce051c09837ca92da2b9447b2ef3f3c9a34fdc4e412cce0ed8e32595acf91acdbae37d2ed313315db9c0e29069edae0ec1c71770b3d1f853f20896a3c0c

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License
+
+Copyright (c) 2025 Sashité
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,236 @@
+Here you go — a lean, easy-to-read README that reflects the new “API / parser / dumper” design without drowning the reader in details.
+
+---
+
+# Feen.rb
+
+> **FEEN** — Forsyth–Edwards Enhanced Notation for rule-agnostic board positions (Chess, Shōgi-like, Xiangqi-like, variants).
+
+Purely functional, immutable Ruby implementation built on top of **EPIN** (piece identifiers) and **SIN** (style identifiers).
+
+---
+
+## Why FEEN?
+
+* **Rule-agnostic**: expresses a board **position** without baking in game rules.
+* **Portable & canonical**: a single, deterministic string per position.
+* **Composable**: works nicely alongside other Sashité specs (e.g., STN for transitions).
+
+FEEN strings have **three space-separated fields**:
+
+```
+<piece_placement> <pieces_in_hand> <style_turn>
+```
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "sashite-feen"
+````
+
+Then:
+
+```sh
+bundle install
+```
+
+This gem depends on:
+
+```ruby
+gem "sashite-epin"
+gem "sashite-sin"
+```
+
+Bundler will install them automatically when you use `sashite-feen`.
+
+---
+
+## Quick start
+
+```ruby
+require "sashite/feen"
+
+# Parse
+pos = Sashite::Feen.parse("<placement> <hands> <style1>/<style2>")
+
+# Validate
+Sashite::Feen.valid?("<your FEEN>") # => true/false
+
+# Normalize (parse → canonical dump)
+Sashite::Feen.normalize("<your FEEN>") # => canonical FEEN string
+
+# Build from fields (strings)
+pos = Sashite::Feen.build(
+  piece_placement: "<placement>",
+  pieces_in_hand:  "<bagFirst>/<bagSecond>", # empty bags allowed: "/"
+  style_turn:      "<activeSIN>/<inactiveSIN>"
+)
+
+# Dump a Position (canonical)
+Sashite::Feen.dump(pos) # => "<placement> <hands> <style1>/<style2>"
+```
+
+> **Tip:** FEEN itself does not do JSON; keep it minimal and functional. Serialize externally if needed.
+
+---
+
+## Public API
+
+```ruby
+Sashite::Feen.parse(str)      # => Position (or raises Sashite::Feen::Error)
+Sashite::Feen.valid?(str)     # => Boolean
+Sashite::Feen.dump(position)  # => String (canonical)
+Sashite::Feen.normalize(str)  # => String (dump(parse(str)))
+Sashite::Feen.build(
+  piece_placement:, pieces_in_hand:, style_turn:
+)                             # => Position
+```
+
+Position value-objects are immutable:
+
+```ruby
+pos.placement  # => Sashite::Feen::Placement
+pos.hands      # => Sashite::Feen::Hands
+pos.styles     # => Sashite::Feen::Styles
+pos.to_s       # => canonical FEEN string (same as dump(pos))
+```
+
+---
+
+## Canonicalization (short rules)
+
+* **Piece placement (field 1)**
+
+  * Consecutive empties compress to digits `1..9`; runs `>9` are split into `"9"` + remainder.
+  * Digit `0` in empties is invalid.
+  * EPIN tokens are validated via `sashite-epin` and re-emitted canonically.
+
+* **Pieces in hand (field 2)**
+
+  * Two concatenated bags separated by `/` (either side may be empty).
+  * Counts are aggregated; `1` is omitted in output.
+  * Deterministic sort per EPIN: quantity ↓, letter ↑ (case-insensitive), uppercase before lowercase, prefix `-` < `+` < none, suffix none < `'`.
+
+* **Style-turn (field 3)**
+
+  * Exactly two SIN tokens separated by `/`.
+  * Exactly **one uppercase** style (first player) and **one lowercase** style (second).
+  * The **first token is the active** player’s style.
+
+---
+
+## Design overview
+
+The gem is small, layered, and testable:
+
+* **API**: `Sashite::Feen` (parse / valid? / dump / normalize / build)
+* **Value objects**: `Position`, `Placement`, `Hands`, `Styles` (immutable, canonical)
+* **Parser**: `Feen::Parser` orchestrates field parsers (`Parser::PiecePlacement`, `Parser::PiecesInHand`, `Parser::StyleTurn`)
+* **Dumper**: `Feen::Dumper` orchestrates field dumpers (`Dumper::PiecePlacement`, `Dumper::PiecesInHand`, `Dumper::StyleTurn`)
+* **Ordering**: `Feen::Ordering` — single comparator used by the hands dumper
+* **Errors**: `Feen::Error` (see below)
+
+### Project layout
+
+```
+lib/
+├─ sashite-feen.rb
+└─ sashite/
+   ├─ feen.rb                 # Public API
+   └─ feen/
+      ├─ error.rb
+      ├─ position.rb
+      ├─ placement.rb
+      ├─ hands.rb
+      ├─ styles.rb
+      ├─ ordering.rb
+      ├─ parser.rb
+      ├─ parser/
+      │  ├─ piece_placement.rb
+      │  ├─ pieces_in_hand.rb
+      │  └─ style_turn.rb
+      ├─ dumper.rb
+      └─ dumper/
+         ├─ piece_placement.rb
+         ├─ pieces_in_hand.rb
+         └─ style_turn.rb
+```
+
+> Version is defined outside of `lib/sashite/feen/version.rb` (e.g., `VERSION.semver`).
+
+---
+
+## Errors
+
+Rescue at the granularity you need:
+
+* `Sashite::Feen::Error::Syntax` – tokenization/field arity
+* `Sashite::Feen::Error::Piece`  – EPIN validation failures
+* `Sashite::Feen::Error::Style`  – SIN validation/case issues
+* `Sashite::Feen::Error::Count`  – invalid counts in hands
+* `Sashite::Feen::Error::Bounds` – internal dimension constraints (when relevant)
+* `Sashite::Feen::Error::Validation` – generic structural/semantic errors
+
+Example:
+
+```ruby
+begin
+  pos = Sashite::Feen.parse(str)
+rescue Sashite::Feen::Error::Style => e
+  warn "Bad style-turn: #{e.message}"
+end
+```
+
+---
+
+## Dependencies & compatibility
+
+* Runtime: `sashite-epin`, `sashite-sin`
+* Purely functional; all objects are frozen; methods return new values.
+* No JSON serialization in this gem.
+
+---
+
+## Development
+
+```sh
+# Clone
+git clone https://github.com/sashite/feen.rb.git
+cd feen.rb
+
+# Install
+bundle install
+
+# Run smoke tests
+ruby test.rb
+
+# Generate YARD docs
+yard doc
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-change`
+3. Add tests covering your changes
+4. Ensure everything is green (lint, tests, docs)
+5. Commit with a conventional message
+6. Push and open a Pull Request
+
+---
+
+## License
+
+Open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## About
+
+Maintained by **Sashité** — promoting chess variants and sharing the beauty of board-game cultures.

data/lib/sashite/feen/dumper/piece_placement.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Dumper
+      module PiecePlacement
+        # Separator between ranks
+        RANK_SEPARATOR = "/"
+
+        module_function
+
+        # Dump a Placement grid to FEEN ranks (e.g., "rnbqkbnr/pppppppp/8/...")
+        #
+        # @param placement [Sashite::Feen::Placement]
+        # @return [String]
+        def dump(placement)
+          pl = _coerce_placement(placement)
+
+          grid = pl.grid
+          raise Error::Bounds, "empty grid" if grid.empty?
+          raise Error::Bounds, "grid must be an Array of rows" unless grid.is_a?(Array)
+
+          width = nil
+          dumped_rows = grid.each_with_index.map do |row, r_idx|
+            raise Error::Bounds, "row #{r_idx + 1} must be an Array, got #{row.class}" unless row.is_a?(Array)
+
+            width ||= row.length
+            raise Error::Bounds, "row #{r_idx + 1} has zero width" if width.zero?
+
+            if row.length != width
+              raise Error::Bounds,
+                    "inconsistent row width at row #{r_idx + 1} (expected #{width}, got #{row.length})"
+            end
+
+            _dump_row(row, r_idx)
+          end
+
+          dumped_rows.join(RANK_SEPARATOR)
+        end
+
+        # -- internals ---------------------------------------------------------
+
+        # Accept nil (and legacy "") as empty cells
+        def _empty_cell?(cell)
+          cell.nil? || cell == ""
+        end
+        private_class_method :_empty_cell?
+
+        def _dump_row(row, r_idx)
+          out = +""
+          empty_run = 0
+
+          row.each_with_index do |cell, c_idx|
+            if _empty_cell?(cell)
+              empty_run += 1
+              next
+            end
+
+            if empty_run.positive?
+              out << empty_run.to_s
+              empty_run = 0
+            end
+
+            begin
+              out << ::Sashite::Epin.dump(cell)
+            rescue StandardError => e
+              raise Error::Piece,
+                    "invalid EPIN value at (row #{r_idx + 1}, col #{c_idx + 1}): #{e.message}"
+            end
+          end
+
+          out << empty_run.to_s if empty_run.positive?
+          out
+        end
+        private_class_method :_dump_row
+
+        def _coerce_placement(obj)
+          return obj if obj.is_a?(Placement)
+
+          raise TypeError, "expected Sashite::Feen::Placement, got #{obj.class}"
+        end
+        private_class_method :_coerce_placement
+      end
+    end
+  end
+end

data/lib/sashite/feen/dumper/pieces_in_hand.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Dumper
+      module PiecesInHand
+        # Separator between hand entries
+        ENTRY_SEPARATOR = ","
+
+        module_function
+
+        # Dump a Hands multiset to FEEN (e.g., "-", "P,2xN,R")
+        #
+        # Canonicalization:
+        #   - entries sorted lexicographically by EPIN token
+        #   - counts rendered as "NxTOKEN" when N > 1
+        #
+        # @param hands [Sashite::Feen::Hands]
+        # @return [String]
+        def dump(hands)
+          h = _coerce_hands(hands)
+
+          map = h.map
+          raise Error::Count, "negative counts are not allowed" if map.values.any? { |v| Integer(v).negative? }
+
+          return "-" if map.empty?
+
+          entries = map.map do |epin_value, count|
+            c = Integer(count)
+            raise Error::Count, "hand count must be >= 1, got #{c}" if c <= 0
+
+            token = begin
+              ::Sashite::Epin.dump(epin_value)
+            rescue StandardError => e
+              raise Error::Piece, "invalid EPIN value in hands: #{e.message}"
+            end
+
+            [token, c]
+          end
+
+          # Sort by EPIN token for deterministic output
+          entries.sort_by! { |(token, _)| token }
+
+          entries.map { |token, c| c == 1 ? token : "#{c}x#{token}" }
+                 .join(ENTRY_SEPARATOR)
+        end
+
+        # -- helpers -----------------------------------------------------------
+
+        def _coerce_hands(obj)
+          return obj if obj.is_a?(Hands)
+
+          raise TypeError, "expected Sashite::Feen::Hands, got #{obj.class}"
+        end
+        private_class_method :_coerce_hands
+      end
+    end
+  end
+end

data/lib/sashite/feen/dumper/style_turn.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Dumper
+      module StyleTurn
+        # Separator between turn and styles
+        TURN_STYLES_SEPARATOR = ";"
+        # Separator between multiple style tokens
+        STYLES_SEPARATOR = ","
+
+        module_function
+
+        # Dump the style/turn field (e.g., "w", "b;rule1,variantX")
+        #
+        # Canonicalization:
+        #   - styles sorted lexicographically by SIN token
+        #
+        # @param styles [Sashite::Feen::Styles]
+        # @return [String]
+        def dump(styles)
+          st = _coerce_styles(styles)
+
+          turn_str = _dump_turn(st.turn)
+
+          return turn_str if st.list.nil? || st.list.empty?
+
+          tokens = st.list.map do |sin_value|
+            ::Sashite::Sin.dump(sin_value)
+          rescue StandardError => e
+            raise Error::Style, "invalid SIN value in styles: #{e.message}"
+          end
+
+          tokens.sort!
+          "#{turn_str}#{TURN_STYLES_SEPARATOR}#{tokens.join(STYLES_SEPARATOR)}"
+        end
+
+        # -- internals ---------------------------------------------------------
+
+        def _dump_turn(turn)
+          case turn
+          when :first  then "w"
+          when :second then "b"
+          else
+            raise Error::Style, "invalid turn symbol #{turn.inspect}"
+          end
+        end
+        private_class_method :_dump_turn
+
+        def _coerce_styles(obj)
+          return obj if obj.is_a?(Styles)
+
+          raise TypeError, "expected Sashite::Feen::Styles, got #{obj.class}"
+        end
+        private_class_method :_coerce_styles
+      end
+    end
+  end
+end

data/lib/sashite/feen/dumper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# FEEN Dumper (entry point)
+# -------------------------
+# Serializes a Position object into its canonical FEEN string by delegating
+# each field to its dedicated sub-dumper.
+#
+# Sub-dumpers:
+#   dumper/piece_placement.rb
+#   dumper/pieces_in_hand.rb
+#   dumper/style_turn.rb
+
+require_relative "dumper/piece_placement"
+require_relative "dumper/pieces_in_hand"
+require_relative "dumper/style_turn"
+
+module Sashite
+  module Feen
+    module Dumper
+      # Separator used between the three FEEN fields
+      FIELD_SEPARATOR = " "
+
+      module_function
+
+      # Dump a Position into a FEEN string
+      #
+      # @param position [Sashite::Feen::Position]
+      # @return [String]
+      def dump(position)
+        pos = _coerce_position(position)
+
+        [
+          PiecePlacement.dump(pos.placement),
+          PiecesInHand.dump(pos.hands),
+          StyleTurn.dump(pos.styles)
+        ].join(FIELD_SEPARATOR)
+      end
+
+      # -- helpers -------------------------------------------------------------
+
+      def _coerce_position(obj)
+        return obj if obj.is_a?(Position)
+
+        raise TypeError, "expected Sashite::Feen::Position, got #{obj.class}"
+      end
+      private_class_method :_coerce_position
+    end
+  end
+end

data/lib/sashite/feen/error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Namespaced error types for FEEN
+    module Error
+      # Base FEEN error (immutable, with optional context payload)
+      class Base < StandardError
+        # @return [Hash, nil] optional contextual information (e.g., { rank: 3, col: 5 })
+        attr_reader :context
+
+        # @param message [String, nil]
+        # @param context [Hash, nil] optional structured context (will be frozen)
+        def initialize(message = nil, context: nil)
+          @context = context&.dup&.freeze
+          super(message)
+          freeze
+        end
+      end
+
+      # Raised when the FEEN text does not match the required grammar
+      class Syntax < Base; end
+
+      # Raised for structural/semantic violations after syntactic parsing
+      class Validation < Base; end
+
+      # Raised when an EPIN token/value is invalid in the current context
+      class Piece < Base; end
+
+      # Raised when a SIN token/value or the style/turn field is invalid
+      class Style < Base; end
+
+      # Raised when a numeric count (e.g., run-length or hand quantity) is invalid
+      class Count < Base; end
+
+      # Raised when board/grid dimensions are empty/inconsistent/out of bounds
+      class Bounds < Base; end
+    end
+  end
+end

data/lib/sashite/feen/hands.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Immutable multiset of pieces-in-hand, keyed by EPIN value (as returned by Sashite::Epin.parse)
+    class Hands
+      attr_reader :map
+
+      # @param map [Hash<any, Integer>] counts per EPIN value
+      def initialize(map)
+        raise TypeError, "hands map must be a Hash, got #{map.class}" unless map.is_a?(Hash)
+
+        # Coerce counts to Integer and validate
+        coerced = {}
+        map.each do |k, v|
+          c = Integer(v)
+          raise Error::Count, "hand count must be >= 0, got #{c}" if c.negative?
+          next if c.zero? # normalize: skip zeros
+
+          coerced[k] = c
+        end
+
+        # Freeze shallowly (keys may already be complex frozen EPIN values)
+        @map = coerced.each_with_object({}) { |(k, v), h| h[k] = v }.freeze
+        freeze
+      end
+
+      # Convenience
+      def empty?
+        @map.empty?
+      end
+
+      def each(&)
+        @map.each(&)
+      end
+    end
+  end
+end

data/lib/sashite/feen/ordering.rb

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

data/lib/sashite/feen/parser/piece_placement.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Parser
+      module PiecePlacement
+        module_function
+
+        # Parse the piece placement field into a Placement value object.
+        #
+        # Grammar (pragmatic):
+        #   placement := rank ( '/' rank | newline rank )*
+        #   rank      := ( int | '.' | epin | sep )*
+        #   int       := [1-9][0-9]*           # run-length of empty cells
+        #   sep       := (',' | whitespace)*
+        #   epin      := bracketed_epin | bare_epin
+        #   bracketed_epin := '[' ... ']'      # balanced brackets
+        #   bare_epin := /[A-Za-z0-9:+\-^~@']+/
+        #
+        # @param field [String]
+        # @return [Sashite::Feen::Placement]
+        def parse(field)
+          src = String(field)
+          raise Error::Syntax, "empty piece placement field" if src.strip.empty?
+
+          ranks = src.split(%r{(?:/|\R)}).map(&:strip)
+          raise Error::Syntax, "no ranks in piece placement" if ranks.empty?
+
+          grid  = []
+          width = nil
+
+          ranks.each_with_index do |rank, r_idx|
+            row = _parse_rank(rank, r_idx)
+            width ||= row.length
+            raise Error::Bounds, "rank #{r_idx + 1} has zero width" if width.zero?
+
+            if row.length != width
+              raise Error::Bounds,
+                    "inconsistent rank width at rank #{r_idx + 1} (expected #{width}, got #{row.length})"
+            end
+            grid << row.freeze
+          end
+
+          raise Error::Bounds, "empty grid" if grid.empty?
+
+          Placement.new(grid.freeze)
+        end
+
+        # -- internals ---------------------------------------------------------
+
+        # Accepts:
+        # - digits => run of empties
+        # - '.'    => single empty
+        # - '['...']' => EPIN token (balanced)
+        # - bare token composed of epin-safe chars
+        # - commas/whitespace ignored
+        def _parse_rank(rank_str, r_idx)
+          i = 0
+          n = rank_str.length
+          cells = []
+
+          while i < n
+            ch = rank_str[i]
+
+            # Skip separators
+            if ch == "," || ch =~ /\s/
+              i += 1
+              next
+            end
+
+            # Dot => single empty
+            if ch == "."
+              cells << nil
+              i += 1
+              next
+            end
+
+            # Number => run of empties
+            if /\d/.match?(ch)
+              j = i + 1
+              j += 1 while j < n && rank_str[j] =~ /\d/
+              count = rank_str[i...j].to_i
+              raise Error::Count, "empty run must be >= 1 at rank #{r_idx + 1}" if count <= 0
+
+              cells.concat([nil] * count)
+              i = j
+              next
+            end
+
+            # Bracketed EPIN token (balanced)
+            if ch == "["
+              token, j = _consume_bracketed(rank_str, i, r_idx)
+              cells << _parse_epin(token, r_idx, cells.length + 1)
+              i = j
+              next
+            end
+
+            # Bare EPIN token
+            token, j = _consume_bare(rank_str, i)
+            if token.empty?
+              raise Error::Piece,
+                    "unexpected character #{rank_str[i].inspect} at rank #{r_idx + 1}, col #{cells.length + 1}"
+            end
+            cells << _parse_epin(token, r_idx, cells.length + 1)
+            i = j
+          end
+
+          cells
+        end
+        module_function :_parse_rank
+        private_class_method :_parse_rank
+
+        # Consume a balanced bracketed token starting at index i (where str[i] == '[')
+        # Returns [token_without_brackets, next_index_after_closing_bracket]
+        def _consume_bracketed(str, i, r_idx)
+          j = i + 1
+          depth = 1
+          while j < str.length && depth.positive?
+            case str[j]
+            when "[" then depth += 1
+            when "]" then depth -= 1
+            end
+            j += 1
+          end
+          raise Error::Piece, "unterminated EPIN bracket at rank #{r_idx + 1}, index #{i}" unless depth.zero?
+
+          [str[(i + 1)...(j - 1)], j]
+        end
+        private_class_method :_consume_bracketed
+
+        # Consume a run of bare EPIN-safe characters.
+        # We choose a wide, permissive class to avoid rejecting valid EPINs that include
+        # promotions/suffixes: letters, digits, + : - ^ ~ @ '
+        def _consume_bare(str, i)
+          j = i
+          # Autorisés : lettres + modificateurs (+ - : ^ ~ @ ')
+          j += 1 while j < str.length && str[j] =~ /[A-Za-z:+\-^~@']/
+          [str[i...j], j]
+        end
+
+        private_class_method :_consume_bare
+
+        def _parse_epin(token, r_idx, c_idx)
+          ::Sashite::Epin.parse(token)
+        rescue StandardError => e
+          raise Error::Piece,
+                "invalid EPIN token at (rank #{r_idx + 1}, col #{c_idx}): #{token.inspect} (#{e.message})"
+        end
+        private_class_method :_parse_epin
+      end
+    end
+  end
+end

data/lib/sashite/feen/parser/pieces_in_hand.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Parser
+      module PiecesInHand
+        module_function
+
+        # Parse the pieces-in-hand field into a Hands value object.
+        #
+        # Strictness:
+        #   - "-"  => empty hands (valid)
+        #   - ""   => invalid (raises Error::Syntax)
+        #
+        # Grammar (tolerant for counts notation):
+        #   hands   := "-" | entry ("," entry)*
+        #   entry   := epin | int ("x"|"*") epin | epin ("x"|"*") int
+        #   int     := [1-9][0-9]*
+        #
+        # @param field [String]
+        # @return [Sashite::Feen::Hands]
+        def parse(field)
+          src = String(field).strip
+          raise Error::Syntax, "empty hands field" if src.empty?
+          return Hands.new({}.freeze) if src == "-"
+
+          entries = src.split(",").map(&:strip).reject(&:empty?)
+          raise Error::Syntax, "malformed hands field" if entries.empty?
+
+          counts = Hash.new(0)
+
+          entries.each_with_index do |entry, idx|
+            epin_token, qty = _parse_hand_entry(entry, idx)
+            epin_id = _parse_epin(epin_token, idx)
+            counts[epin_id] += qty
+          end
+
+          frozen_counts = {}
+          counts.each { |k, v| frozen_counts[k] = Integer(v) }
+
+          Hands.new(frozen_counts.freeze)
+        end
+
+        # Accepts forms: "P", "2xP", "P*2", "10*R", "[Shogi:P]*3"
+        def _parse_hand_entry(str, _idx)
+          s = str.strip
+
+          if (m = /\A(\d+)\s*[x*]\s*(.+)\z/.match(s))
+            n = Integer(m[1])
+            raise Error::Count, "hand count must be >= 1, got #{n}" if n <= 0
+
+            return [m[2].strip, n]
+          end
+
+          if (m = /\A(.+?)\s*[x*]\s*(\d+)\z/.match(s))
+            n = Integer(m[2])
+            raise Error::Count, "hand count must be >= 1, got #{n}" if n <= 0
+
+            return [m[1].strip, n]
+          end
+
+          # Default: single piece
+          [s, 1]
+        end
+        module_function :_parse_hand_entry
+        private_class_method :_parse_hand_entry
+
+        def _parse_epin(token, idx)
+          ::Sashite::Epin.parse(token)
+        rescue StandardError => e
+          raise Error::Piece, "invalid EPIN token in hands (entry #{idx + 1}): #{token.inspect} (#{e.message})"
+        end
+        private_class_method :_parse_epin
+      end
+    end
+  end
+end

data/lib/sashite/feen/parser/style_turn.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    module Parser
+      module StyleTurn
+        module_function
+
+        # Strict FEEN + SIN:
+        #   style_turn := LETTER "/" LETTER              # no whitespace
+        #   semantics :
+        #     - Uppercase marks the side to move.
+        #     - Exactly one uppercase among the two.
+        #     - Each letter is a SIN style code (validated via Sashite::Sin.parse).
+        #
+        # Examples (valid):
+        #   "C/c"  -> first to move,  first_style="C", second_style="C" (Chess vs Chess)
+        #   "c/C"  -> second to move
+        #   "S/o"  -> first to move,  first_style="S" (Shogi), second_style="O" (Ōgi)
+        #
+        # Examples (invalid):
+        #   "w" , "C / c", "Cc", "c/c", "C/C", "x/y "  (wrong pattern or spaces)
+        #
+        # @param field [String]
+        # @return [Sashite::Feen::Styles] with signature Styles.new(first_style, second_style, turn)
+        def parse(field)
+          s = String(field)
+          raise Error::Syntax, "empty style/turn field" if s.empty?
+          raise Error::Syntax, "whitespace not allowed in style/turn" if s.match?(/\s/)
+
+          m = %r{\A([A-Za-z])/([A-Za-z])\z}.match(s)
+          raise Error::Syntax, "invalid style/turn format" unless m
+
+          a_raw = m[1]
+          b_raw = m[2]
+          a_is_up = a_raw.between?("A", "Z")
+          b_is_up = b_raw.between?("A", "Z")
+
+          # Exactly one uppercase marks side to move
+          raise Error::Style, "ambiguous side-to-move: exactly one letter must be uppercase" unless a_is_up ^ b_is_up
+
+          # Canonical SIN tokens are uppercase (style identity is case-insensitive in FEEN)
+          a_tok = a_raw.upcase
+          b_tok = b_raw.upcase
+
+          first_style = begin
+            ::Sashite::Sin.parse(a_tok)
+          rescue StandardError => e
+            raise Error::Style, "invalid SIN token for first side #{a_tok.inspect}: #{e.message}"
+          end
+
+          second_style = begin
+            ::Sashite::Sin.parse(b_tok)
+          rescue StandardError => e
+            raise Error::Style, "invalid SIN token for second side #{b_tok.inspect}: #{e.message}"
+          end
+
+          turn = a_is_up ? :first : :second
+          Styles.new(first_style, second_style, turn)
+        end
+      end
+    end
+  end
+end

data/lib/sashite/feen/parser.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "parser/piece_placement"
+require_relative "parser/pieces_in_hand"
+require_relative "parser/style_turn"
+
+module Sashite
+  module Feen
+    module Parser
+      module_function
+
+      def parse(feen)
+        s = String(feen).strip
+        raise Error::Syntax, "empty FEEN input" if s.empty?
+
+        a, b, c = _split_3_fields(s)
+        placement = PiecePlacement.parse(a)
+        hands     = PiecesInHand.parse(b)
+        styles    = StyleTurn.parse(c)
+
+        Position.new(placement, hands, styles)
+      end
+
+      def _split_3_fields(s)
+        parts = s.split(/\s+/, 3)
+        unless parts.length == 3
+          raise Error::Syntax,
+                "FEEN must have 3 whitespace-separated fields (got #{parts.length})"
+        end
+        parts
+      end
+      private_class_method :_split_3_fields
+    end
+  end
+end

data/lib/sashite/feen/placement.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Immutable board placement: rectangular grid of cells (nil = empty, otherwise EPIN value)
+    class Placement
+      attr_reader :grid, :height, :width
+
+      # @param grid [Array<Array>]
+      #   Each row is an Array; all rows must have identical length.
+      def initialize(grid)
+        raise TypeError, "grid must be an Array of rows, got #{grid.class}" unless grid.is_a?(Array)
+        raise Error::Bounds, "grid cannot be empty" if grid.empty?
+        unless grid.all?(Array)
+          raise Error::Bounds, "grid must be an Array of rows (Array), got #{grid.map(&:class).inspect}"
+        end
+
+        widths = grid.map(&:length)
+        width = widths.first || 0
+        raise Error::Bounds, "rows cannot be empty" if width.zero?
+        raise Error::Bounds, "inconsistent row width (#{widths.uniq.join(', ')})" if widths.any? { |w| w != width }
+
+        # Deep-freeze
+        @grid = grid.map { |row| row.dup.freeze }.freeze
+        @height = @grid.length
+        @width  = width
+        freeze
+      end
+    end
+  end
+end

data/lib/sashite/feen/position.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Immutable aggregate for a FEEN position: placement + hands + styles
+    class Position
+      attr_reader :placement, :hands, :styles
+
+      # @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)
+
+        @placement = placement
+        @hands     = hands
+        @styles    = styles
+        freeze
+      end
+    end
+  end
+end

data/lib/sashite/feen/styles.rb

@@ -0,0 +1,75 @@
+# 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)
+    class Styles
+      attr_reader :first_family, :second_family, :turn
+
+      VALID_TURNS = %i[first second].freeze
+
+      # @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)
+      end
+
+      private
+
+      def _coerce_turn(t)
+        raise ArgumentError, "turn must be :first or :second, got #{t.inspect}" unless VALID_TURNS.include?(t)
+
+        t
+      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
+
+      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
+      end
+    end
+  end
+end

data/lib/sashite/feen.rb

@@ -0,0 +1,106 @@
+# 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"
+
+module Sashite
+  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
+
+      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
+    end
+  end
+end

data/lib/sashite-feen.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/feen"
+
+# 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,101 @@
+--- !ruby/object:Gem::Specification
+name: sashite-feen
+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-epin
+  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-sin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |
+  FEEN (Forsyth—Edwards Enhanced Notation) provides a universal, rule-agnostic format for
+  representing board game positions. This gem implements the FEEN Specification v1.0.0 with
+  a modern Ruby interface featuring immutable position objects and functional programming
+  principles. FEEN extends traditional FEN notation to support multiple game systems (chess,
+  shōgi, xiangqi, makruk), cross-style games, multi-dimensional boards, and captured pieces
+  held in reserve. Built on EPIN (piece notation) and SIN (style notation) foundations,
+  FEEN enables canonical position representation across diverse abstract strategy board games.
+  Perfect for game engines, position analysis tools, and hybrid gaming systems requiring
+  comprehensive board state representation.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-feen.rb
+- lib/sashite/feen.rb
+- lib/sashite/feen/dumper.rb
+- lib/sashite/feen/dumper/piece_placement.rb
+- lib/sashite/feen/dumper/pieces_in_hand.rb
+- 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
+- lib/sashite/feen/parser/style_turn.rb
+- lib/sashite/feen/placement.rb
+- lib/sashite/feen/position.rb
+- lib/sashite/feen/styles.rb
+homepage: https://github.com/sashite/feen.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/feen.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/feen.rb/main
+  homepage_uri: https://github.com/sashite/feen.rb
+  source_code_uri: https://github.com/sashite/feen.rb
+  specification_uri: https://sashite.dev/specs/feen/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.7.1
+specification_version: 4
+summary: FEEN (Forsyth—Edwards Enhanced Notation) implementation for Ruby with universal
+  position representation
+test_files: []