sashite-lcn 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94ba5ec45b43c16436dbe3b980dada0475f14592b12163871ce40a9bd22db38e
+  data.tar.gz: b5a32943c9d2c14127b0ff24bd14d3a4cd1aba729e9e6bedc9d1db937c10e458
+SHA512:
+  metadata.gz: 5c065503d9b548066bf2915e3b28cf0ba816e37ba407463900c2cc4665aef086243721872fe40dcab3d67cb07190c5884b73b5e5daa7e0ede133e7b560957984
+  data.tar.gz: d8d4b68044bf2e118c09acc5d89fa967ffecd8efd74f307fcc6b8f528a5dce9e30102c16c1563409f34ce06f7d5f5a67bc396f6708e3cc152a15517e1e1c5f27

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Sashite
+
+MIT License
+
+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,435 @@
+# Lcn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/lcn.rb?label=Version&logo=github)](https://github.com/sashite/lcn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/lcn.rb/main)
+![Ruby](https://github.com/sashite/lcn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/lcn.rb?label=License&logo=github)](https://github.com/sashite/lcn.rb/raw/main/LICENSE.md)
+
+> **LCN** (Location Condition Notation) implementation for the Ruby language.
+
+## What is LCN?
+
+LCN (Location Condition Notation) is a rule-agnostic format for describing **location conditions** in abstract strategy board games. LCN provides a standardized way to express constraints on board locations, defining what states specific locations should have.
+
+This gem implements the [LCN Specification v1.0.0](https://sashite.dev/specs/lcn/1.0.0/) exactly, providing environmental constraint validation with CELL coordinates and state values including reserved keywords and QPI piece identifiers.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-lcn"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-lcn
+```
+
+## Dependencies
+
+LCN builds upon two foundational primitive specifications:
+
+```ruby
+gem "sashite-cell"  # Coordinate Encoding for Layered Locations
+gem "sashite-qpi"   # Qualified Piece Identifier
+```
+
+## Usage
+
+### Basic Operations
+
+```ruby
+require "sashite/lcn"
+
+# Parse location condition data (string keys only)
+conditions = Sashite::Lcn.parse({
+                                  "e4" => "empty",
+                                  "f5" => "enemy"
+                                })
+
+# Create directly using symbol keys (constructor)
+conditions = Sashite::Lcn::Conditions.new(
+  e4: "empty",
+  f5: "enemy"
+)
+
+# Validate condition data
+Sashite::Lcn.valid?({ "e4" => "empty" })          # => true
+Sashite::Lcn.valid?({ "invalid" => "empty" })     # => false
+Sashite::Lcn.valid?({ "e4" => "unknown" })        # => false
+
+# Access conditions using symbols
+conditions[:e4]                                   # => "empty"
+conditions[:f5]                                   # => "enemy"
+conditions.locations                              # => [:e4, :f5]
+conditions.size                                   # => 2
+conditions.empty?                                 # => false
+
+# Convert to hash with symbol keys
+conditions.to_h # => { e4: "empty", f5: "enemy" }
+```
+
+### State Value Types
+
+LCN supports two categories of state values:
+
+#### Reserved Keywords
+
+```ruby
+# Empty location requirement
+empty_condition = Sashite::Lcn.parse({ "e4" => "empty" })
+empty_condition[:e4] # => "empty"
+
+# Enemy piece requirement (context-dependent)
+enemy_condition = Sashite::Lcn.parse({ "f5" => "enemy" })
+enemy_condition[:f5] # => "enemy"
+```
+
+#### QPI Piece Identifiers
+
+```ruby
+# Specific piece requirements
+piece_conditions = Sashite::Lcn.parse({
+                                        "h1" => "C:+R", # Chess rook with castling rights
+                                        "e1" => "C:+K",    # Chess king with castling rights
+                                        "f5" => "c:-p"     # Enemy pawn vulnerable to en passant
+                                      })
+
+# Access using symbol keys
+piece_conditions[:h1]                             # => "C:+R"
+piece_conditions[:e1]                             # => "C:+K"
+piece_conditions[:f5]                             # => "c:-p"
+```
+
+### Complex Conditions
+
+```ruby
+# Path clearance for movement
+path_clear = Sashite::Lcn::Conditions.new(
+  b2: "empty",
+  c3: "empty",
+  d4: "empty"
+)
+
+# Castling requirements
+castling_conditions = Sashite::Lcn::Conditions.new(
+  f1: "empty",
+  g1: "empty",
+  h1: "C:+R"
+)
+
+# File restriction (Shogi pawn drop)
+file_restriction = Sashite::Lcn::Conditions.new(
+  e1: "S:P",
+  e2: "S:P",
+  e3: "S:P",
+  e4: "S:P",
+  e5: "S:P",
+  e6: "S:P",
+  e7: "S:P",
+  e8: "S:P",
+  e9: "S:P"
+)
+```
+
+### Empty Conditions
+
+```ruby
+# No constraints
+no_conditions = Sashite::Lcn::Conditions.new
+no_conditions.empty?                              # => true
+no_conditions.locations                           # => []
+no_conditions.to_h                                # => {}
+```
+
+### Validation and Analysis
+
+```ruby
+conditions = Sashite::Lcn::Conditions.new(
+  e4: "empty",
+  f5: "enemy",
+  h1: "C:+R"
+)
+
+# Basic queries
+conditions.size # => 3
+conditions.location?(:e4)                     # => true
+conditions.location?(:g1)                     # => false
+
+# State value analysis
+conditions.keywords                               # => ["empty", "enemy"]
+conditions.qpi_identifiers                        # => ["C:+R"]
+conditions.keywords? # => true
+conditions.qpi_identifiers? # => true
+
+# Specific state checks
+conditions.empty_locations                        # => [:e4]
+conditions.enemy_locations                        # => [:f5]
+conditions.piece_locations                        # => [:h1]
+```
+
+## API Reference
+
+### Main Module Methods
+
+- `Sashite::Lcn.parse(data)` - Parse condition data into LCN object (raises on invalid, string keys only)
+- `Sashite::Lcn.valid?(data)` - Check if data represents valid LCN conditions
+
+### LCN::Conditions Class
+
+#### Creation and Parsing
+- `Sashite::Lcn::Conditions.new(**conditions_hash)` - Create from validated hash using keyword arguments (symbol keys)
+- `Sashite::Lcn::Conditions.parse(data)` - Parse and validate condition data (string keys only, converts to symbols internally)
+
+#### Data Access
+- `#to_h` - Convert to hash with symbol keys
+- `#[](location)` - Get state value for location (symbol key)
+- `#locations` - Get array of all location symbols
+- `#size` - Get number of conditions
+- `#empty?` - Check if no conditions specified
+
+#### Validation and Queries
+- `#location?(location)` - Check if location has condition (symbol key)
+- `#valid_location?(location)` - Check if location uses valid CELL coordinate
+- `#valid_state_value?(value)` - Check if state value is valid
+
+#### State Value Analysis
+- `#keywords` - Get array of keyword state values used
+- `#qpi_identifiers` - Get array of QPI identifiers used
+- `#keywords?` - Check if any keywords are used
+- `#qpi_identifiers?` - Check if any QPI identifiers are used
+
+#### Categorized Access
+- `#empty_locations` - Get locations requiring empty state (array of symbols)
+- `#enemy_locations` - Get locations requiring enemy pieces (array of symbols)
+- `#piece_locations` - Get locations requiring specific pieces (array of symbols)
+
+#### Iteration
+- `#each` - Iterate over location-state pairs (location as symbol)
+- `#each_location` - Iterate over locations only (symbols)
+- `#each_state_value` - Iterate over state values only
+
+## Format Specification
+
+### Internal Ruby Representation
+```ruby
+# Symbol keys for Ruby idiomatic usage
+{
+  e4: "empty",
+  f5: "enemy",
+  h1: "C:+R"
+}
+```
+
+### Specification Format (JSON/external)
+```ruby
+# String keys as per LCN specification (required for parse method)
+{
+  "e4" => "empty",
+  "f5" => "enemy",
+  "h1" => "C:+R"
+}
+```
+
+### State Value Types
+```ruby
+# Reserved keywords
+"empty"      # Location should be unoccupied
+"enemy"      # Location should contain opposing piece (context-dependent)
+
+# QPI identifiers (examples)
+"C:K"        # Chess king, first player
+"c:p"        # Chess pawn, second player
+"S:+P"       # Shogi promoted pawn, first player
+"x:-c"       # Xiangqi diminished cannon, second player
+```
+
+### Validation Rules
+
+- **Keys**: Must be valid CELL coordinates (required as strings for parse, stored as symbols internally)
+- **Values**: Must be reserved keywords or valid QPI identifiers
+- **Structure**: Must be a Hash (after JSON parsing if applicable)
+- **Encoding**: String values, symbol keys internally
+
+## Context Dependency
+
+### Reference Piece Requirement
+
+The `"enemy"` keyword is **context-dependent** and requires a reference piece for evaluation:
+
+```ruby
+conditions = Sashite::Lcn::Conditions.new(f5: "enemy")
+
+# The consuming specification must provide:
+# 1. Reference piece identification (e.g., the moving piece)
+# 2. Side determination logic
+# 3. Enemy evaluation rules
+
+# LCN validates format but doesn't interpret "enemy" semantics
+conditions.enemy_locations                        # => [:f5]
+conditions[:f5]                                   # => "enemy"
+```
+
+### Integration with Consuming Specifications
+
+LCN is designed to be used by higher-level specifications:
+
+- **GGN**: Uses LCN for movement pre-conditions with the moving piece as reference
+- **Pattern matching**: Could use LCN with designated reference pieces
+- **Rule validation**: Could combine multiple LCN objects with logical operators
+
+## Common Usage Patterns
+
+### Movement Validation
+
+```ruby
+# Path must be clear
+path_conditions = Sashite::Lcn::Conditions.new(
+  b2: "empty",
+  c3: "empty",
+  d4: "empty"
+)
+
+# Destination must contain enemy
+capture_condition = Sashite::Lcn::Conditions.new(e5: "enemy")
+```
+
+### Special Move Requirements
+
+```ruby
+# Castling conditions
+castling = Sashite::Lcn::Conditions.new(
+  f1: "empty",      # King's path clear
+  g1: "empty",      # King's destination clear
+  h1: "C:+R"        # Rook in position with rights
+)
+
+# En passant conditions
+en_passant = Sashite::Lcn::Conditions.new(
+  f6: "empty",      # Capture destination empty
+  f5: "c:-p"        # Enemy pawn vulnerable
+)
+```
+
+### Restriction Patterns
+
+```ruby
+# File cannot contain same piece type (Shogi pawn drop)
+file_check = Sashite::Lcn::Conditions.new(
+  e1: "S:P",
+  e2: "S:P",
+  e3: "S:P",
+  e4: "S:P",
+  e5: "S:P",
+  e6: "S:P",
+  e7: "S:P",
+  e8: "S:P",
+  e9: "S:P"
+)
+```
+
+## Error Handling
+
+```ruby
+# Invalid CELL coordinates
+begin
+  Sashite::Lcn.parse({ "invalid" => "empty" })
+rescue ArgumentError => e
+  puts e.message # => "Invalid CELL coordinate: invalid"
+end
+
+# Invalid state values
+begin
+  Sashite::Lcn.parse({ "e4" => "unknown" })
+rescue ArgumentError => e
+  puts e.message # => "Invalid state value: unknown"
+end
+
+# Invalid data structure
+begin
+  Sashite::Lcn.parse("not a hash")
+rescue ArgumentError => e
+  puts e.message # => "LCN data must be a Hash"
+end
+
+# Direct construction with keyword arguments ensures type safety
+conditions_data = { e4: "empty", f5: "enemy" }
+conditions = Sashite::Lcn::Conditions.new(**conditions_data)
+# Functional approach with clear separation of construction methods
+```
+
+## Input Format Specification
+
+### Parse Method - String Keys Only
+
+```ruby
+# ✅ Valid input for parse() - string keys required
+string_input = { "e4" => "empty", "f5" => "enemy" }
+conditions = Sashite::Lcn.parse(string_input)
+
+# ❌ Symbol keys not accepted by parse()
+symbol_input = { e4: "empty", f5: "enemy" }
+# Sashite::Lcn.parse(symbol_input)  # => ArgumentError
+
+# Internal representation always uses symbol keys
+conditions.to_h                                   # => { e4: "empty", f5: "enemy" }
+conditions[:e4]                                   # => "empty"
+```
+
+### Constructor - Symbol Keys Only
+
+```ruby
+# ✅ Constructor accepts symbol keys via keyword arguments
+conditions = Sashite::Lcn::Conditions.new(
+  e4: "empty",
+  f5: "enemy"
+)
+
+# This provides clear separation:
+# - parse() for external data (JSON/string keys)
+# - new() for internal construction (symbol keys)
+```
+
+### Design Rationale
+
+This design provides clear separation between:
+
+1. **External data parsing** (`parse()` with string keys) - matches LCN specification format
+2. **Internal construction** (`new()` with symbol keys) - Ruby-idiomatic with keyword arguments
+3. **Consistent internal representation** (always symbol keys) - optimal performance and developer experience
+
+Benefits:
+- **Reduced API complexity** - no ambiguity about which key types are accepted where
+- **Specification compliance** - parse() strictly follows LCN format with string keys
+- **Performance** - no key conversion logic needed in parse()
+- **Clarity** - clear distinction between external and internal interfaces
+
+## Design Properties
+
+- **Rule-agnostic**: Independent of specific game mechanics
+- **Context-neutral**: Provides format without imposing evaluation logic
+- **Composable**: Can be combined by consuming specifications
+- **Type-safe**: Clear distinction between keywords and piece identifiers
+- **Ruby-idiomatic**: Symbol keys for better performance and developer experience
+- **Specification-compliant**: String keys for external data parsing
+- **Foundational**: Designed as building block for higher-level specifications
+- **Immutable**: All instances frozen, transformations return new objects
+- **Functional**: Pure functions with no side effects
+
+## Related Specifications
+
+- [LCN Specification v1.0.0](https://sashite.dev/specs/lcn/1.0.0/) - Complete technical specification
+- [LCN Examples](https://sashite.dev/specs/lcn/1.0.0/examples/) - Practical implementation examples
+- [CELL Specification v1.0.0](https://sashite.dev/specs/cell/1.0.0/) - Coordinate system component
+- [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) - Piece identification component
+- [GGN Specification v1.0.0](https://sashite.dev/specs/ggn/1.0.0/) - Consumer of LCN for movement notation
+- [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## About
+
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/lcn/conditions.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "sashite/cell"
+require "sashite/qpi"
+
+module Sashite
+  module Lcn
+    # Represents a set of location conditions in LCN format
+    #
+    # This class provides an immutable, functional interface for working with
+    # location conditions. All instances are frozen after creation to ensure
+    # thread safety and prevent accidental mutations.
+    #
+    # Conditions are stored internally with symbol keys for Ruby idiomatic access
+    # while supporting flexible input formats (string or symbol keys).
+    #
+    # @example Creating conditions
+    #   conditions = Sashite::Lcn::Conditions.new(
+    #     e4: "empty",
+    #     f5: "enemy",
+    #     h1: "C:+R"
+    #   )
+    #
+    # @example Accessing conditions
+    #   conditions[:e4]          # => "empty"
+    #   conditions.locations     # => [:e4, :f5, :h1]
+    #   conditions.size          # => 3
+    #
+    # @example Analyzing conditions
+    #   conditions.empty_locations    # => [:e4]
+    #   conditions.enemy_locations    # => [:f5]
+    #   conditions.piece_locations    # => [:h1]
+    #   conditions.keywords?      # => true
+    #   conditions.qpi_identifiers? # => true
+    class Conditions
+      include Enumerable
+
+      # Reserved keywords from LCN specification
+      EMPTY_KEYWORD = "empty"
+      ENEMY_KEYWORD = "enemy"
+      RESERVED_KEYWORDS = [EMPTY_KEYWORD, ENEMY_KEYWORD].freeze
+
+      # Error messages
+      ERROR_INVALID_LOCATION = "Invalid CELL coordinate: %s"
+      ERROR_INVALID_STATE = "Invalid state value: %s"
+      ERROR_NOT_HASH = "Conditions data must be a Hash"
+
+      # Create a new Conditions instance
+      #
+      # @param conditions_hash [Hash] validated conditions with symbol keys
+      # @note The hash is duplicated and frozen to ensure immutability
+      #
+      # @example Direct creation with keyword arguments
+      #   conditions = Sashite::Lcn::Conditions.new(
+      #     e4: "empty",
+      #     f5: "enemy"
+      #   )
+      def initialize(**conditions_hash)
+        # Deep duplicate to ensure complete isolation
+        @conditions = conditions_hash.dup.freeze
+        freeze
+      end
+
+      # Parse and create a Conditions instance from raw data
+      #
+      # Accepts both string and symbol keys, normalizing to symbols internally.
+      # Validates all locations and state values before creating the instance.
+      #
+      # @param data [Hash] conditions data with string or symbol keys
+      # @return [Conditions] new validated instance
+      # @raise [ArgumentError] if data is invalid
+      #
+      # @example Parse with string keys
+      #   conditions = Sashite::Lcn::Conditions.parse({
+      #     "e4" => "empty",
+      #     "f5" => "enemy"
+      #   })
+      #
+      # @example Parse with symbol keys
+      #   conditions = Sashite::Lcn::Conditions.parse({
+      #     e4: "empty",
+      #     f5: "enemy"
+      #   })
+      def self.parse(data)
+        raise ArgumentError, ERROR_NOT_HASH unless data.is_a?(Hash)
+
+        validated = {}
+
+        data.each do |location, state_value|
+          location_str = location.to_s
+
+          raise ArgumentError, format(ERROR_INVALID_LOCATION, location_str) unless Cell.valid?(location_str)
+
+          raise ArgumentError, format(ERROR_INVALID_STATE, state_value) unless valid_state_value?(state_value)
+
+          validated[location_str.to_sym] = state_value
+        end
+
+        new(**validated)
+      end
+
+      # Convert to hash with symbol keys
+      #
+      # @return [Hash] conditions as a hash with symbol keys
+      def to_h
+        @conditions.dup
+      end
+
+      # Get state value for a location
+      #
+      # @param location [Symbol, String] the location coordinate
+      # @return [String, nil] state value or nil if location not present
+      #
+      # @example
+      #   conditions[:e4]     # => "empty"
+      #   conditions["e4"]    # => "empty"
+      #   conditions[:z9]     # => nil
+      def [](location)
+        @conditions[location.to_sym]
+      end
+
+      # Get array of all location symbols
+      #
+      # @return [Array<Symbol>] all location coordinates as symbols
+      def locations
+        @conditions.keys
+      end
+
+      # Get number of conditions
+      #
+      # @return [Integer] number of location conditions
+      def size
+        @conditions.size
+      end
+
+      # Check if no conditions are specified
+      #
+      # @return [Boolean] true if no conditions
+      def empty?
+        @conditions.empty?
+      end
+
+      # Check if location has a condition
+      #
+      # @param location [Symbol, String] the location to check
+      # @return [Boolean] true if location has a condition
+      def location?(location)
+        @conditions.key?(location.to_sym)
+      end
+
+      # Check if location uses valid CELL coordinate
+      #
+      # @param location [Symbol, String] the location to validate
+      # @return [Boolean] true if valid CELL coordinate
+      def valid_location?(location)
+        Cell.valid?(location.to_s)
+      end
+
+      # Check if state value is valid
+      #
+      # @param value [Object] the value to validate
+      # @return [Boolean] true if valid state value
+      def valid_state_value?(value)
+        self.class.valid_state_value?(value)
+      end
+
+      # Get array of keyword state values used
+      #
+      # @return [Array<String>] unique keywords used in conditions
+      #
+      # @example
+      #   conditions.keywords  # => ["empty", "enemy"]
+      def keywords
+        @conditions.values.select { |v| RESERVED_KEYWORDS.include?(v) }.uniq
+      end
+
+      # Get array of QPI identifiers used
+      #
+      # @return [Array<String>] unique QPI identifiers used in conditions
+      #
+      # @example
+      #   conditions.qpi_identifiers  # => ["C:+R", "c:p"]
+      def qpi_identifiers
+        @conditions.values.reject { |v| RESERVED_KEYWORDS.include?(v) }.uniq
+      end
+
+      # Check if any keywords are used
+      #
+      # @return [Boolean] true if any reserved keywords are present
+      def keywords?
+        @conditions.values.any? { |v| RESERVED_KEYWORDS.include?(v) }
+      end
+
+      # Check if any QPI identifiers are used
+      #
+      # @return [Boolean] true if any QPI identifiers are present
+      def qpi_identifiers?
+        @conditions.values.any? { |v| !RESERVED_KEYWORDS.include?(v) }
+      end
+
+      # Get locations requiring empty state
+      #
+      # @return [Array<Symbol>] locations that must be empty
+      #
+      # @example
+      #   conditions.empty_locations  # => [:e4, :f1, :g1]
+      def empty_locations
+        @conditions.select { |_, v| v == EMPTY_KEYWORD }.keys
+      end
+
+      # Get locations requiring enemy pieces
+      #
+      # @return [Array<Symbol>] locations that must contain enemy pieces
+      #
+      # @example
+      #   conditions.enemy_locations  # => [:f5]
+      def enemy_locations
+        @conditions.select { |_, v| v == ENEMY_KEYWORD }.keys
+      end
+
+      # Get locations requiring specific pieces
+      #
+      # @return [Array<Symbol>] locations with QPI piece requirements
+      #
+      # @example
+      #   conditions.piece_locations  # => [:h1, :e1]
+      def piece_locations
+        @conditions.reject { |_, v| RESERVED_KEYWORDS.include?(v) }.keys
+      end
+
+      # Iterate over location-state pairs
+      #
+      # @yield [location, state_value] each location-state pair
+      # @yieldparam location [Symbol] location coordinate as symbol
+      # @yieldparam state_value [String] state value
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   conditions.each do |location, state|
+      #     puts "#{location}: #{state}"
+      #   end
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        @conditions.each(&)
+      end
+
+      # Iterate over locations only
+      #
+      # @yield [location] each location
+      # @yieldparam location [Symbol] location coordinate as symbol
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   conditions.each_location do |location|
+      #     puts location
+      #   end
+      def each_location(&)
+        return enum_for(:each_location) unless block_given?
+
+        @conditions.each_key(&)
+      end
+
+      # Iterate over state values only
+      #
+      # @yield [state_value] each state value
+      # @yieldparam state_value [String] state value
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   conditions.each_state_value do |state|
+      #     puts state
+      #   end
+      def each_state_value(&)
+        return enum_for(:each_state_value) unless block_given?
+
+        @conditions.each_value(&)
+      end
+
+      # Check equality with another Conditions instance
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if conditions are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        @conditions == other.to_h
+      end
+
+      # Alias for == to ensure proper equality in collections
+      alias eql? ==
+
+      # Generate hash code for use in Hash and Set
+      #
+      # @return [Integer] hash code
+      def hash
+        [self.class, @conditions].hash
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] human-readable representation
+      def inspect
+        "#<#{self.class.name} #{@conditions.inspect}>"
+      end
+
+      # String representation
+      #
+      # @return [String] conditions as string
+      def to_s
+        @conditions.to_s
+      end
+
+      # Check if a state value is valid (class method for internal use)
+      #
+      # @param value [Object] the value to validate
+      # @return [Boolean] true if valid state value
+      def self.valid_state_value?(value)
+        return false unless value.is_a?(String)
+
+        # Check if it's a reserved keyword
+        return true if RESERVED_KEYWORDS.include?(value)
+
+        # Otherwise, check if it's a valid QPI identifier
+        Qpi.valid?(value)
+      end
+    end
+  end
+end

data/lib/sashite/lcn.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "lcn/conditions"
+require "sashite/cell"
+require "sashite/qpi"
+
+module Sashite
+  # LCN (Location Condition Notation) implementation for Ruby
+  #
+  # Provides a rule-agnostic format for describing location conditions in abstract strategy
+  # board games. LCN provides a standardized way to express constraints on board locations,
+  # defining what states specific locations should have.
+  #
+  # ## Concept
+  #
+  # LCN is a foundational specification designed to be used by other formats that require
+  # location state definitions. It expresses environmental constraints as key-value pairs
+  # where keys are CELL coordinates and values are state values.
+  #
+  # ## State Value Types
+  #
+  # LCN supports two categories of state values:
+  #
+  # ### Reserved Keywords
+  # - `"empty"`: Location should be unoccupied
+  # - `"enemy"`: Location should contain a piece from the opposing side (context-dependent)
+  #
+  # ### QPI Piece Identifiers
+  # - Exact piece requirements using QPI format (e.g., "C:K", "c:p", "S:+P")
+  #
+  # ## Context Dependency
+  #
+  # The `"enemy"` keyword is context-dependent and requires a reference piece for interpretation.
+  # The consuming specification must provide:
+  # 1. Reference piece identification (which piece determines the perspective)
+  # 2. Side determination logic (how the reference piece's side is established)
+  # 3. Enemy evaluation rules (how opposing pieces are identified)
+  #
+  # ## Format Structure
+  #
+  # LCN uses a simple JSON object structure:
+  # ```json
+  # {
+  #   "<cell-coordinate>": "<state-value>"
+  # }
+  # ```
+  #
+  # Where:
+  # - Keys: CELL coordinates (string, conforming to CELL specification)
+  # - Values: State values (reserved keywords or QPI identifiers)
+  #
+  # ## Examples
+  #
+  # ### Basic Conditions
+  #
+  #   # Empty location requirement
+  #   conditions = Sashite::Lcn.parse({ "e4" => "empty" })
+  #   conditions[:e4]  # => "empty"
+  #
+  #   # Enemy piece requirement (context-dependent)
+  #   conditions = Sashite::Lcn.parse({ "f5" => "enemy" })
+  #   conditions[:f5]  # => "enemy"
+  #
+  # ### Specific Piece Requirements
+  #
+  #   conditions = Sashite::Lcn.parse({
+  #     "h1" => "C:+R",    # Chess rook with castling rights
+  #     "e1" => "C:+K",    # Chess king with castling rights
+  #     "f5" => "c:-p"     # Enemy pawn vulnerable to en passant
+  #   })
+  #
+  # ### Complex Path Conditions
+  #
+  #   # Path clearance for movement
+  #   path_conditions = Sashite::Lcn.parse({
+  #     "b2" => "empty",
+  #     "c3" => "empty",
+  #     "d4" => "empty"
+  #   })
+  #
+  #   # Castling requirements
+  #   castling = Sashite::Lcn.parse({
+  #     "f1" => "empty",
+  #     "g1" => "empty",
+  #     "h1" => "C:+R"
+  #   })
+  #
+  # ### Empty Conditions
+  #
+  #   no_conditions = Sashite::Lcn.parse({})
+  #   no_conditions.empty?  # => true
+  #
+  # ## Design Properties
+  #
+  # - **Rule-agnostic**: Independent of specific game mechanics
+  # - **Context-neutral**: Provides format without imposing evaluation logic
+  # - **Composable**: Can be combined by consuming specifications
+  # - **Type-safe**: Clear distinction between keywords and piece identifiers
+  # - **Minimal syntax**: Clean key-value pairs without nesting
+  # - **Functional**: Pure functions with no side effects
+  # - **Immutable**: All instances are frozen for thread safety
+  #
+  # @see https://sashite.dev/specs/lcn/1.0.0/ LCN Specification v1.0.0
+  # @see https://sashite.dev/specs/lcn/1.0.0/examples/ LCN Examples
+  # @see https://sashite.dev/specs/cell/1.0.0/ CELL Specification (coordinate system)
+  # @see https://sashite.dev/specs/qpi/1.0.0/ QPI Specification (piece identifiers)
+  module Lcn
+    # Reserved keywords for common location states
+    EMPTY_KEYWORD = "empty"
+    ENEMY_KEYWORD = "enemy"
+    RESERVED_KEYWORDS = [EMPTY_KEYWORD, ENEMY_KEYWORD].freeze
+
+    # Check if data represents valid LCN conditions
+    #
+    # Validates that the data is a Hash with:
+    # - Keys: Valid CELL coordinates
+    # - Values: Reserved keywords ("empty", "enemy") or valid QPI identifiers
+    #
+    # @param data [Object] the data to validate
+    # @return [Boolean] true if valid LCN data, false otherwise
+    #
+    # @example Validate various LCN formats
+    #   Sashite::Lcn.valid?({ "e4" => "empty" })          # => true
+    #   Sashite::Lcn.valid?({ "f5" => "enemy" })          # => true
+    #   Sashite::Lcn.valid?({ "h1" => "C:+R" })           # => true
+    #   Sashite::Lcn.valid?({ "invalid" => "empty" })     # => false (invalid CELL)
+    #   Sashite::Lcn.valid?({ "e4" => "unknown" })        # => false (invalid state)
+    #   Sashite::Lcn.valid?("not a hash")                 # => false
+    #   Sashite::Lcn.valid?({})                           # => true (empty conditions)
+    def self.valid?(data)
+      return false unless data.is_a?(Hash)
+
+      data.all? do |location, state_value|
+        valid_location?(location) && valid_state_value?(state_value)
+      end
+    end
+
+    # Parse LCN data into a Conditions object
+    #
+    # Creates a new LCN Conditions instance by parsing and validating the input data.
+    # Accepts both string and symbol keys for compatibility, but internally
+    # normalizes to symbol keys for Ruby idiomatic usage.
+    #
+    # @param data [Hash] LCN conditions data with CELL coordinates as keys
+    # @return [Lcn::Conditions] parsed conditions object with validated data
+    # @raise [ArgumentError] if the data is invalid (not a Hash, invalid keys, or invalid values)
+    #
+    # @example Parse different LCN formats
+    #   # String keys (as per specification)
+    #   conditions = Sashite::Lcn.parse({ "e4" => "empty", "f5" => "enemy" })
+    #   conditions[:e4]  # => "empty"
+    #
+    #   # Symbol keys (Ruby idiomatic)
+    #   conditions = Sashite::Lcn.parse({ e4: "empty", f5: "enemy" })
+    #   conditions[:e4]  # => "empty"
+    #
+    #   # Mixed QPI and keywords
+    #   conditions = Sashite::Lcn.parse({
+    #     "f1" => "empty",
+    #     "g1" => "empty",
+    #     "h1" => "C:+R"
+    #   })
+    #
+    # @example Error handling
+    #   Sashite::Lcn.parse({ "invalid" => "empty" })  # => ArgumentError: Invalid CELL coordinate: invalid
+    #   Sashite::Lcn.parse({ "e4" => "unknown" })     # => ArgumentError: Invalid state value: unknown
+    #   Sashite::Lcn.parse("not a hash")              # => ArgumentError: LCN data must be a Hash
+    def self.parse(data)
+      raise ArgumentError, "LCN data must be a Hash" unless data.is_a?(Hash)
+
+      validated_conditions = {}
+
+      data.each do |location, state_value|
+        # Convert location to string for validation, then to symbol for storage
+        location_str = location.to_s
+
+        raise ArgumentError, "Invalid CELL coordinate: #{location_str}" unless valid_location?(location_str)
+
+        raise ArgumentError, "Invalid state value: #{state_value}" unless valid_state_value?(state_value)
+
+        # Store with symbol key for Ruby idiomatic access
+        validated_conditions[location_str.to_sym] = state_value
+      end
+
+      Conditions.new(**validated_conditions)
+    end
+
+    private
+
+    # Check if a location is a valid CELL coordinate
+    #
+    # @param location [Object] the location to validate
+    # @return [Boolean] true if valid CELL coordinate
+    def self.valid_location?(location)
+      return false unless location.is_a?(String) || location.is_a?(Symbol)
+
+      Sashite::Cell.valid?(location.to_s)
+    end
+
+    # Check if a state value is valid (keyword or QPI identifier)
+    #
+    # @param state_value [Object] the state value to validate
+    # @return [Boolean] true if valid state value
+    def self.valid_state_value?(state_value)
+      return false unless state_value.is_a?(String)
+
+      # Check if it's a reserved keyword
+      return true if RESERVED_KEYWORDS.include?(state_value)
+
+      # Otherwise, check if it's a valid QPI identifier
+      Sashite::Qpi.valid?(state_value)
+    end
+
+    private_class_method :valid_location?, :valid_state_value?
+  end
+end

data/lib/sashite-lcn.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/lcn"
+
+# 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,86 @@
+--- !ruby/object:Gem::Specification
+name: sashite-lcn
+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-cell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sashite-qpi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  LCN (Location Condition Notation) provides a rule-agnostic format for describing location conditions
+  in abstract strategy board games. This gem implements the LCN Specification v1.0.0 with a modern
+  Ruby interface featuring immutable condition objects and functional programming principles. LCN
+  enables standardized representation of environmental constraints on board locations using reserved
+  keywords ("empty", "enemy") and QPI piece identifiers with CELL coordinate system integration.
+  Perfect for movement validation, pre-condition checking, constraint evaluation, and rule-agnostic
+  game logic requiring precise location state requirements across multiple game types and traditions.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-lcn.rb
+- lib/sashite/lcn.rb
+- lib/sashite/lcn/conditions.rb
+homepage: https://github.com/sashite/lcn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/lcn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/lcn.rb/main
+  homepage_uri: https://github.com/sashite/lcn.rb
+  source_code_uri: https://github.com/sashite/lcn.rb
+  specification_uri: https://sashite.dev/specs/lcn/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: LCN (Location Condition Notation) implementation for Ruby with environmental
+  constraint validation
+test_files: []