sashite-cgsn 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5130413add3619290ba1adcb1240d3e924510277ebd1361e25860a23846a4013
+  data.tar.gz: 2a614fa5d19b477db200774bc617e4d55e061232a74bbcd8566a4063930403c8
+SHA512:
+  metadata.gz: 41dddcc173c4d1315668c8179ba8023122bd38a430dd90d62ec7f202d478a6bec09c154deac1867307af53cb0eeb5aca91d9a16e6126f407cfe08d3d71b5ed69
+  data.tar.gz: 3c45298716d464f82383a91f99ef27a06ae17c999df42443445eff2afb628ce36eb998a9500eb3c1085b58f7059b057818ec97e72d8886e0e63fb9443463c487

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Cyril Kato
+
+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,175 @@
+# Cgsn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/cgsn.rb?label=Version&logo=github)](https://github.com/sashite/cgsn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/cgsn.rb/main)
+![Ruby](https://github.com/sashite/cgsn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/cgsn.rb?label=License&logo=github)](https://github.com/sashite/cgsn.rb/raw/main/LICENSE.md)
+
+> **CGSN** (Chess Game Status Notation) implementation for the Ruby language.
+
+## What is CGSN?
+
+CGSN (Chess Game Status Notation) provides a **rule-agnostic** taxonomy of observable game status values for abstract strategy board games. CGSN defines standardized identifiers for terminal conditions, player actions, and game progression states that can be recorded independently of competitive interpretation.
+
+This gem implements the [CGSN Specification v1.0.0](https://sashite.dev/specs/cgsn/1.0.0/), providing a minimal Ruby interface for status validation and categorization with immutable status objects.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-cgsn"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-cgsn
+```
+
+## Format
+
+CGSN status values are lowercase strings using underscore separators:
+
+```ruby
+"checkmate"
+"bare_king"
+"time_limit"
+"in_progress"
+```
+
+## API Reference
+
+### Status Class
+
+#### Creation and Parsing
+
+* `Sashite::Cgsn::Status.new(value)` - Create status instance from string
+* `Sashite::Cgsn.parse(value)` - Parse status value (module convenience method)
+
+#### Instance Methods
+
+* `#inferable?` - Check if status can be inferred from position analysis
+* `#explicit_only?` - Check if status requires explicit declaration
+* `#to_s` - Convert to string representation
+* `#==(other)` - Equality comparison
+* `#hash` - Hash value for use in collections
+
+### Module Methods
+
+#### Validation
+
+* `Sashite::Cgsn.valid?(status)` - Check if string is a valid CGSN status value
+
+#### Categorization
+
+* `Sashite::Cgsn.inferable?(status)` - Check if status can be inferred from position analysis
+* `Sashite::Cgsn.explicit_only?(status)` - Check if status requires explicit declaration
+
+#### Status Lists
+
+* `Sashite::Cgsn.statuses` - Array of all defined CGSN status values
+* `Sashite::Cgsn.inferable_statuses` - Array of position-derivable statuses
+* `Sashite::Cgsn.explicit_only_statuses` - Array of statuses requiring explicit recording
+
+### Constants
+
+* `Sashite::Cgsn::STATUSES` - Frozen array of all defined status values
+* `Sashite::Cgsn::INFERABLE_STATUSES` - Frozen array of inferable status values
+* `Sashite::Cgsn::EXPLICIT_ONLY_STATUSES` - Frozen array of explicit-only status values
+
+## Usage
+
+### Object-Oriented Approach
+
+```ruby
+require "sashite/cgsn"
+
+# Parse status into object
+status = Sashite::Cgsn.parse("checkmate")
+status.inferable?      # => true
+status.explicit_only?  # => false
+status.to_s            # => "checkmate"
+
+# Create from string
+status = Sashite::Cgsn::Status.new("resignation")
+status.inferable?      # => false
+status.explicit_only?  # => true
+
+# Immutable objects
+status.frozen? # => true
+```
+
+### Functional Approach
+
+```ruby
+require "sashite/cgsn"
+
+# Validate status strings
+Sashite::Cgsn.valid?("checkmate")      # => true
+Sashite::Cgsn.valid?("invalid")        # => false
+
+# Check inference capability
+Sashite::Cgsn.inferable?("stalemate") # => true
+Sashite::Cgsn.explicit_only?("time_limit") # => true
+
+# Get all statuses
+Sashite::Cgsn.statuses
+# => ["in_progress", "checkmate", "stalemate", ...]
+```
+
+## Properties
+
+* **Rule-agnostic**: Independent of specific game mechanics or outcome interpretation
+* **Observable-focused**: Records verifiable facts without competitive judgment
+* **Inference-aware**: Distinguishes position-derivable from explicit-only statuses
+* **String-based**: Simple string representation for broad compatibility
+* **Functional**: Pure functions with no side effects
+* **Immutable**: All status instances and data structures are frozen
+* **Object-oriented**: Status objects with query methods
+
+## Related Specifications
+
+- [CGSN](https://sashite.dev/specs/cgsn/) - Chess Game Status Notation (this specification)
+- [PCN](https://sashite.dev/specs/pcn/) - Portable Chess Notation (uses CGSN for status field)
+- [Game Protocol](https://sashite.dev/protocol/) - Conceptual foundation for abstract strategy games
+
+## Documentation
+
+- [Official CGSN Specification v1.0.0](https://sashite.dev/specs/cgsn/1.0.0/)
+- [CGSN Examples](https://sashite.dev/specs/cgsn/1.0.0/examples/)
+- [API Documentation](https://rubydoc.info/github/sashite/cgsn.rb/main)
+
+## Development
+
+```sh
+# Clone the repository
+git clone https://github.com/sashite/cgsn.rb.git
+cd cgsn.rb
+
+# Install dependencies
+bundle install
+
+# Run tests
+ruby test.rb
+
+# Generate documentation
+yard doc
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`ruby test.rb`)
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Create a Pull Request
+
+## 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/cgsn/status.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Cgsn
+    # Represents a status value in CGSN (Chess Game Status Notation) format.
+    #
+    # A status consists of a lowercase string with optional underscore separators.
+    # Each status represents an observable game state that can be recorded
+    # independently of competitive interpretation.
+    #
+    # All instances are immutable.
+    class Status
+      # Error message for invalid status values
+      ERROR_INVALID_STATUS = "Invalid CGSN status: %s"
+
+      # Create a new status instance
+      #
+      # @param value [String] status value
+      # @raise [ArgumentError] if the value is invalid
+      #
+      # @example
+      #   Status.new("checkmate")     # => #<Cgsn::Status value="checkmate">
+      #   Status.new("resignation")   # => #<Cgsn::Status value="resignation">
+      def initialize(value)
+        @value = String(value)
+
+        raise ::ArgumentError, format(ERROR_INVALID_STATUS, @value) unless Cgsn::STATUSES.include?(@value)
+
+        freeze
+      end
+
+      # Check if the status can be inferred from position analysis
+      #
+      # @return [Boolean] true if inferable
+      #
+      # @example
+      #   Status.new("checkmate").inferable?     # => true
+      #   Status.new("resignation").inferable?   # => false
+      def inferable?
+        Cgsn::INFERABLE_STATUSES.include?(@value)
+      end
+
+      # Check if the status requires explicit declaration
+      #
+      # @return [Boolean] true if explicit-only
+      #
+      # @example
+      #   Status.new("resignation").explicit_only?  # => true
+      #   Status.new("checkmate").explicit_only?    # => false
+      def explicit_only?
+        Cgsn::EXPLICIT_ONLY_STATUSES.include?(@value)
+      end
+
+      # Convert the status to its string representation
+      #
+      # @return [String] status value
+      #
+      # @example
+      #   Status.new("checkmate").to_s  # => "checkmate"
+      def to_s
+        @value
+      end
+
+      # Custom equality comparison
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if statuses are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        to_s == other.to_s
+      end
+
+      # Alias for == to ensure Set functionality works correctly
+      alias eql? ==
+
+      # Custom hash implementation for use in collections
+      #
+      # @return [Integer] hash value
+      def hash
+        [self.class, @value].hash
+      end
+    end
+  end
+end

data/lib/sashite/cgsn.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "cgsn/status"
+
+module Sashite
+  # CGSN (Chess Game Status Notation) implementation for Ruby
+  #
+  # Provides functionality for working with rule-agnostic game status values
+  # for abstract strategy board games.
+  #
+  # This implementation is strictly compliant with CGSN Specification v1.0.0
+  # @see https://sashite.dev/specs/cgsn/1.0.0/ CGSN Specification v1.0.0
+  module Cgsn
+    # Complete list of all defined CGSN status values
+    STATUSES = %w[
+      in_progress
+      checkmate
+      stalemate
+      bare_king
+      mare_king
+      insufficient
+      resignation
+      illegal_move
+      time_limit
+      move_limit
+      repetition
+      agreement
+    ].freeze
+
+    # Statuses that can be inferred from position analysis
+    INFERABLE_STATUSES = %w[
+      in_progress
+      checkmate
+      stalemate
+      bare_king
+      mare_king
+      insufficient
+    ].freeze
+
+    # Statuses that require explicit declaration
+    EXPLICIT_ONLY_STATUSES = %w[
+      resignation
+      illegal_move
+      time_limit
+      move_limit
+      repetition
+      agreement
+    ].freeze
+
+    # Check if a string is a valid CGSN status value
+    #
+    # @param value [String] the status to validate
+    # @return [Boolean] true if the status is valid
+    #
+    # @example
+    #   Sashite::Cgsn.valid?("checkmate")     # => true
+    #   Sashite::Cgsn.valid?("time_limit")    # => true
+    #   Sashite::Cgsn.valid?("invalid")       # => false
+    #   Sashite::Cgsn.valid?("Checkmate")     # => false
+    def self.valid?(value)
+      STATUSES.include?(value)
+    rescue ::TypeError
+      false
+    end
+
+    # Parse a status value into a Status object
+    #
+    # @param value [String] the status value to parse
+    # @return [Status] new status instance
+    # @raise [ArgumentError] if the status value is invalid
+    #
+    # @example
+    #   Sashite::Cgsn.parse("checkmate")    # => #<Cgsn::Status value="checkmate">
+    #   Sashite::Cgsn.parse("resignation")  # => #<Cgsn::Status value="resignation">
+    def self.parse(value)
+      Status.new(value)
+    end
+
+    # Check if a status can be inferred from position analysis
+    #
+    # @param status [String, Status] the status to check
+    # @return [Boolean] true if the status is inferable
+    #
+    # @example
+    #   Sashite::Cgsn.inferable?("checkmate")     # => true
+    #   Sashite::Cgsn.inferable?("resignation")   # => false
+    def self.inferable?(status)
+      INFERABLE_STATUSES.include?(status)
+    rescue ::TypeError
+      false
+    end
+
+    # Check if a status requires explicit declaration
+    #
+    # @param status [String, Status] the status to check
+    # @return [Boolean] true if the status is explicit-only
+    #
+    # @example
+    #   Sashite::Cgsn.explicit_only?("resignation")  # => true
+    #   Sashite::Cgsn.explicit_only?("checkmate")    # => false
+    def self.explicit_only?(status)
+      EXPLICIT_ONLY_STATUSES.include?(status)
+    rescue ::TypeError
+      false
+    end
+
+    # Get the list of all defined CGSN status values
+    #
+    # @return [Array<String>] array of all status values
+    #
+    # @example
+    #   Sashite::Cgsn.statuses
+    #   # => ["in_progress", "checkmate", "stalemate", ...]
+    def self.statuses
+      STATUSES.dup
+    end
+
+    # Get the list of inferable status values
+    #
+    # @return [Array<String>] array of inferable status values
+    #
+    # @example
+    #   Sashite::Cgsn.inferable_statuses
+    #   # => ["in_progress", "checkmate", "stalemate", ...]
+    def self.inferable_statuses
+      INFERABLE_STATUSES.dup
+    end
+
+    # Get the list of explicit-only status values
+    #
+    # @return [Array<String>] array of explicit-only status values
+    #
+    # @example
+    #   Sashite::Cgsn.explicit_only_statuses
+    #   # => ["resignation", "illegal_move", "time_limit", ...]
+    def self.explicit_only_statuses
+      EXPLICIT_ONLY_STATUSES.dup
+    end
+  end
+end

data/lib/sashite-cgsn.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/cgsn"
+
+# 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,60 @@
+--- !ruby/object:Gem::Specification
+name: sashite-cgsn
+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: []
+description: |
+  CGSN (Chess Game Status Notation) provides a rule-agnostic taxonomy of observable game status
+  values for abstract strategy board games. This gem implements the CGSN Specification v1.0.0 with
+  a minimal Ruby interface featuring immutable status objects and functional programming principles.
+  CGSN defines standardized identifiers for terminal conditions (checkmate, stalemate, bare_king,
+  mare_king, insufficient), player actions (resignation, agreement, illegal_move), and temporal
+  constraints (time_limit, move_limit, repetition), enabling precise and portable status identification
+  across multiple games and variants. Perfect for game engines, notation systems, and hybrid gaming
+  platforms requiring consistent, rule-agnostic game state representation.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-cgsn.rb
+- lib/sashite/cgsn.rb
+- lib/sashite/cgsn/status.rb
+homepage: https://github.com/sashite/cgsn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/cgsn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/cgsn.rb/main
+  homepage_uri: https://github.com/sashite/cgsn.rb
+  source_code_uri: https://github.com/sashite/cgsn.rb
+  specification_uri: https://sashite.dev/specs/cgsn/1.0.0/
+  wiki_uri: https://sashite.dev/specs/cgsn/1.0.0/examples/
+  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: CGSN (Chess Game Status Notation) implementation for Ruby with immutable
+  status objects
+test_files: []