Feen.rb

FEEN (Forsyth–Edwards Enhanced Notation) implementation for the Ruby language.

FEEN (Forsyth–Edwards Enhanced Notation) 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.

This gem implements the FEEN Specification v1.0.0 as a pure functional library with immutable data structures.

gem "sashite-feen"

The library provides two methods for converting between FEEN strings and position objects:

require "sashite/feen"

# Parse a FEEN string into a position object
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")

# Dump a position object into a canonical FEEN string
feen_string = Sashite::Feen.dump(position)

Parses a FEEN string and returns an immutable Position object.

• Input: FEEN string with three space-separated fields
• Returns: Sashite::Feen::Position instance
• Raises: Sashite::Feen::Error subclasses on invalid input

Converts a position object into its canonical FEEN string representation.

• Input: Sashite::Feen::Position instance
• Returns: Canonical FEEN string
• Guarantees: Deterministic output (same position always produces same string)

The Position object returned by parse is immutable and provides read-only access to the three FEEN components:

position.placement  # => Placement object (board arrangement)
position.hands      # => Hands object (pieces in hand)
position.styles     # => Styles object (style-turn information)
position.to_s       # => Canonical FEEN string (equivalent to dump)

A FEEN string consists of three space-separated fields:

<piece-placement> <pieces-in-hand> <style-turn>

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

For complete format details, see the FEEN Specification.

The library defines specific error classes for different validation failures:

Sashite::Feen::Error  # Base error class
├── Error::Syntax     # Malformed FEEN structure
├── Error::Piece      # Invalid EPIN notation
├── Error::Style      # Invalid SIN notation
├── Error::Count      # Invalid piece counts
└── Error::Validation # Other semantic violations

• Purely functional: Immutable data structures, no side effects
• Canonical output: Deterministic string generation
• Specification compliant: Strict adherence to FEEN v1.0.0
• Minimal API: Two methods for complete functionality
• Composable: Built on EPIN and SIN specifications

• sashite-epin – Extended Piece Identifier Notation
• sashite-sin – Style Identifier Notation

• FEEN Specification v1.0.0
• FEEN Examples
• API Documentation

Available as open source under the MIT License.

Maintained by Sashité – promoting chess variants and sharing the beauty of board game cultures.