pnn 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 464d54188d055a98263efb823fb1e646f5b9c4998c14fac4b1a2ffa1f5d5f63d
+  data.tar.gz: 7a7e8826c51a585879d935a7811316cfc983dfa64e8a9ad2863ca297f7af2f20
+SHA512:
+  metadata.gz: faca96d2dd6e2b2faed85d52c8d45c5ed9725f98010963bf1d6e16c81490bb364795d0dd13acb8099c9dd009f1a209600f31554aaa3348cb3d5dc391f4bf3bfa
+  data.tar.gz: 0c1732d83a4b2bf8be7c64ad4eb8c50137fb7b04ea4cf54d9899eb15e24fcf5258c1e1104f853da12201b8066611bd4a594f43ac6e1c53ead6c9cc1413327132

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,176 @@
+# Pnn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/pnn.rb?label=Version&logo=github)](https://github.com/sashite/pnn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pnn.rb/main)
+![Ruby](https://github.com/sashite/pnn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/pnn.rb?label=License&logo=github)](https://github.com/sashite/pnn.rb/raw/main/LICENSE.md)
+
+> **PNN** (Piece Name Notation) support for the Ruby language.
+
+## What is PNN?
+
+PNN (Piece Name Notation) is a consistent and rule-agnostic format for representing pieces in abstract strategy board games. It defines a standardized way to identify and represent pieces independent of any specific game rules or mechanics.
+
+This gem implements the [PNN Specification v1.0.0](https://sashite.dev/documents/pnn/1.0.0/), providing a Ruby interface for:
+- Serializing piece identifiers to PNN strings
+- Parsing PNN strings into their component parts
+- Validating PNN strings according to the specification
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "pnn"
+```
+
+Or install manually:
+
+```sh
+gem install pnn
+```
+
+## PNN Format
+
+A PNN record consists of a single ASCII letter that represents a piece, with optional prefixes and/or suffixes to indicate modifiers or state information:
+
+```
+[<prefix>]<letter>[<suffix>]
+```
+
+Where:
+- `<letter>` is a single ASCII letter (`a-z` or `A-Z`), with uppercase representing the first player's pieces and lowercase representing the second player's pieces
+- `<prefix>` is an optional modifier preceding the letter (`+` or `-`)
+- `<suffix>` is an optional modifier following the letter (`=`, `<`, or `>`)
+
+## Basic Usage
+
+### Parsing PNN Strings
+
+Convert a PNN string into a structured Ruby hash:
+
+```ruby
+require "pnn"
+
+# Basic letter
+result = Pnn.parse("k")
+# => { letter: "k" }
+
+# With prefix
+result = Pnn.parse("+k")
+# => { letter: "k", prefix: "+" }
+
+# With suffix
+result = Pnn.parse("k=")
+# => { letter: "k", suffix: "=" }
+
+# With both prefix and suffix
+result = Pnn.parse("+k=")
+# => { letter: "k", prefix: "+", suffix: "=" }
+```
+
+### Safe Parsing
+
+Parse a PNN string without raising exceptions:
+
+```ruby
+require "pnn"
+
+# Valid PNN string
+result = Pnn.safe_parse("+k=")
+# => { letter: "k", prefix: "+", suffix: "=" }
+
+# Invalid PNN string
+result = Pnn.safe_parse("invalid pnn string")
+# => nil
+```
+
+### Creating PNN Strings
+
+Convert piece components into a PNN string:
+
+```ruby
+require "pnn"
+
+# Basic letter
+Pnn.dump(letter: "k")
+# => "k"
+
+# With prefix
+Pnn.dump(letter: "p", prefix: "+")
+# => "+p"
+
+# With suffix
+Pnn.dump(letter: "k", suffix: "=")
+# => "k="
+
+# With both prefix and suffix
+Pnn.dump(letter: "p", prefix: "+", suffix: ">")
+# => "+p>"
+```
+
+### Validation
+
+Check if a string is valid PNN notation:
+
+```ruby
+require "pnn"
+
+Pnn.valid?("k")      # => true
+Pnn.valid?("+p")     # => true
+Pnn.valid?("k=")     # => true
+Pnn.valid?("+p>")    # => true
+
+Pnn.valid?("")       # => false
+Pnn.valid?("kp")     # => false
+Pnn.valid?("++k")    # => false
+Pnn.valid?("k==")    # => false
+```
+
+### Piece Modifiers
+
+PNN supports prefixes and suffixes for pieces to denote various states or capabilities:
+
+- **Prefix `+`**: Alternative or enhanced state
+  - Example in shogi: `+p` may represent a promoted pawn
+
+- **Prefix `-`**: Diminished or restricted state
+  - Example: `-k` may represent a king with restricted movement
+
+- **Suffix `=`**: Bidirectional or dual-option state
+  - Example in chess: `k=` may represent a king eligible for both kingside and queenside castling
+
+- **Suffix `<`**: Left-side constraint or condition
+  - Example in chess: `k<` may represent a king eligible for queenside castling only
+  - Example in chess: `p<` may represent a pawn that may be captured _en passant_ from the left
+
+- **Suffix `>`**: Right-side constraint or condition
+  - Example in chess: `k>` may represent a king eligible for kingside castling only
+  - Example in chess: `p>` may represent a pawn that may be captured en passant from the right
+
+These modifiers have no defined semantics in the PNN specification itself but provide a flexible framework for representing piece-specific conditions while maintaining PNN's rule-agnostic nature.
+
+## Properties of PNN
+
+* **Rule-agnostic**: PNN does not encode legality, validity, or game-specific conditions.
+* **Canonical representation**: Ensures that equivalent pieces yield identical strings.
+* **State modifiers**: Express special conditions without compromising rule neutrality.
+
+## Constraints
+
+* PNN supports exactly **two players**.
+* Players are assigned distinct casing: **uppercase letters** (`A-Z`) represent pieces of the player who moves first in the initial position; **lowercase letters** (`a-z`) represent the second player.
+* A maximum of **26 unique piece types per player** is allowed, as identifiers must use single letters (`a-z` or `A-Z`).
+* Modifiers can only be applied to pieces **on the board**, as they express state information. Pieces held off the board (e.g., pieces in hand or captured pieces) must never include modifiers; only the base letter identifier is used.
+
+## Documentation
+
+- [Official PNN Specification](https://sashite.dev/documents/pnn/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/pnn.rb/main)
+
+## License
+
+The [gem](https://rubygems.org/gems/pnn) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## About Sashité
+
+This project is maintained by [Sashité](https://sashite.com/) - a project dedicated to promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/pnn/dumper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Pnn
+  # Serializes piece components into PNN strings
+  class Dumper
+    # Valid prefix modifiers
+    VALID_PREFIXES = ["+", "-", nil].freeze
+
+    # Valid suffix modifiers
+    VALID_SUFFIXES = ["=", "<", ">", nil].freeze
+
+    # Serialize piece components into a PNN string
+    #
+    # @param letter [String] The single ASCII letter identifier
+    # @param prefix [String, nil] Optional prefix modifier
+    # @param suffix [String, nil] Optional suffix modifier
+    # @return [String] PNN notation string
+    # @raise [ArgumentError] If any component is invalid
+    def self.dump(letter:, prefix: nil, suffix: nil)
+      letter = String(letter)
+
+      unless letter.match?(/^[a-zA-Z]$/)
+        raise ArgumentError, "Letter must be a single ASCII letter (a-z or A-Z): #{letter}"
+      end
+
+      raise ArgumentError, "Invalid prefix: #{prefix}. Must be '+', '-', or nil." unless VALID_PREFIXES.include?(prefix)
+
+      unless VALID_SUFFIXES.include?(suffix)
+        raise ArgumentError, "Invalid suffix: #{suffix}. Must be '=', '<', '>', or nil."
+      end
+
+      "#{prefix}#{letter}#{suffix}"
+    end
+  end
+end

data/lib/pnn/parser.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pnn
+  # Parses PNN strings into their component parts
+  class Parser
+    # PNN regex capture groups for parsing
+    PATTERN = /^(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>[=<>])?$/
+
+    # Parse a PNN string into its components
+    #
+    # @param pnn_string [String] The PNN string to parse
+    # @return [Hash] Hash containing the parsed components
+    # @raise [ArgumentError] If the PNN string is invalid
+    def self.parse(pnn_string)
+      pnn_string = String(pnn_string)
+
+      matches = PATTERN.match(pnn_string)
+
+      raise ArgumentError, "Invalid PNN string: #{pnn_string}" if matches.nil?
+
+      {
+        letter: matches[:letter],
+        prefix: matches[:prefix],
+        suffix: matches[:suffix]
+      }.compact
+    end
+
+    # Safely parse a PNN string without raising exceptions
+    #
+    # @param pnn_string [String] The PNN string to parse
+    # @return [Hash, nil] Hash containing the parsed components or nil if invalid
+    def self.safe_parse(pnn_string)
+      parse(pnn_string)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/pnn/validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pnn
+  # Validates PNN strings according to the specification
+  class Validator
+    # PNN validation pattern matching the JSON schema pattern in the spec
+    PATTERN = /\A[-+]?[a-zA-Z][=<>]?\z/
+
+    # Class method to validate PNN strings
+    #
+    # @param pnn_string [String] The PNN string to validate
+    # @return [Boolean] True if the string is valid according to PNN specification
+    def self.valid?(pnn_string)
+      String(pnn_string).match?(PATTERN)
+    end
+  end
+end

data/lib/pnn.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative File.join("pnn", "dumper")
+require_relative File.join("pnn", "parser")
+require_relative File.join("pnn", "validator")
+
+# This module provides a Ruby interface for serialization and
+# deserialization of piece identifiers in PNN format.
+#
+# PNN (Piece Name Notation) defines a consistent and rule-agnostic
+# format for representing pieces in abstract strategy board games.
+#
+# @see https://sashite.dev/documents/pnn/1.0.0/
+module Pnn
+  # Serializes a piece identifier into a PNN string.
+  #
+  # @param prefix [String, nil] Optional modifier preceding the letter ('+' or '-')
+  # @param letter [String] A single ASCII letter ('a-z' or 'A-Z')
+  # @param suffix [String, nil] Optional modifier following the letter ('=', '<', or '>')
+  # @return [String] PNN notation string
+  # @raise [ArgumentError] If any parameter is invalid
+  # @example
+  #   Pnn.dump(letter: "k", suffix: "=")
+  #   # => "k="
+  def self.dump(letter:, prefix: nil, suffix: nil)
+    Dumper.dump(letter:, prefix:, suffix:)
+  end
+
+  # Parses a PNN string into its component parts.
+  #
+  # @param pnn_string [String] PNN notation string
+  # @return [Hash] Hash containing the parsed piece data with the following keys:
+  #   - :letter [String] - The base letter identifier
+  #   - :prefix [String, nil] - The prefix modifier if present
+  #   - :suffix [String, nil] - The suffix modifier if present
+  # @raise [ArgumentError] If the PNN string is invalid
+  # @example
+  #   Pnn.parse("+k=")
+  #   # => { letter: "k", prefix: "+", suffix: "=" }
+  def self.parse(pnn_string)
+    Parser.parse(pnn_string)
+  end
+
+  # Safely parses a PNN string into its component parts without raising exceptions.
+  #
+  # @param pnn_string [String] PNN notation string
+  # @return [Hash, nil] Hash containing the parsed piece data or nil if parsing fails
+  # @example
+  #   # Valid PNN string
+  #   Pnn.safe_parse("+k=")
+  #   # => { letter: "k", prefix: "+", suffix: "=" }
+  #
+  #   # Invalid PNN string
+  #   Pnn.safe_parse("invalid")
+  #   # => nil
+  def self.safe_parse(pnn_string)
+    Parser.safe_parse(pnn_string)
+  end
+
+  # Validates if the given string is a valid PNN string
+  #
+  # @param pnn_string [String] PNN string to validate
+  # @return [Boolean] True if the string is a valid PNN string
+  # @example
+  #   Pnn.valid?("k=") # => true
+  #   Pnn.valid?("invalid") # => false
+  def self.valid?(pnn_string)
+    Validator.valid?(pnn_string)
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: pnn
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby interface for serialization and deserialization of piece identifiers
+  in PNN format. PNN is a consistent and rule-agnostic format for representing pieces
+  in abstract strategy board games, providing a standardized way to identify pieces
+  independent of any specific game rules or mechanics.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/pnn.rb
+- lib/pnn/dumper.rb
+- lib/pnn/parser.rb
+- lib/pnn/validator.rb
+homepage: https://github.com/sashite/pnn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/pnn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/pnn.rb/main
+  homepage_uri: https://github.com/sashite/pnn.rb
+  source_code_uri: https://github.com/sashite/pnn.rb
+  specification_uri: https://sashite.dev/documents/pnn/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.6.7
+specification_version: 4
+summary: PNN (Piece Name Notation) support for the Ruby language.
+test_files: []