pnn 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c243c47d75b03455ad8fa85bebd13cf90b6e3abb2c37f93cf425a1a51f14b16
-  data.tar.gz: 89a3d75180c92c5627e6dfb9c301f0ba3637e59c923448b7e5c9cde175805144
+  metadata.gz: b48e598bec9d6aeb11a7212428d279f153bbfd00ae6f1a7dc3d0485f4985695c
+  data.tar.gz: d7d8c7da11021a1056e048ab17605bd5db9abdc4cbbdafc90bd00820e651fedc
 SHA512:
-  metadata.gz: 688721867ee73331f8b2b49606caefafe3239efccc7756d122b1cb76453c472d9a71dba2de13224388a6ea110651abb5386d87039a3c110e0366a03c00cfd4f0
-  data.tar.gz: 82e0e2c1d4f058a8d09c107ad1f6beef50a0a2c826b9467504fca411281ce766d8cac9468cca105760ba16db1a014d5d0db1c92b6a4fdd268f24c07c273274e6
+  metadata.gz: 3957d2e98391d216817a37cf4c9ebc479172c1aeb3415ecc19c1e8abb2d9b29298277312c5b187cdbf1ede2a6f30414bf11b5b05a35ef324abf6a314fc5e7108
+  data.tar.gz: 10665b2f56ae9869dc68db08066dd2e1520691bc4e649ae48cf22643100427d0d0af9981708e3427aab0b8c0894feef37feda79a8c73bd036c020eb423052730

data/README.md

@@ -40,7 +40,7 @@ A PNN record consists of a single ASCII letter that represents a piece, with opt
 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 `>`)
+- `<suffix>` is an optional modifier following the letter (`'`)
 
 ## Basic Usage
 
@@ -60,12 +60,12 @@ result = Pnn.parse("+k")
 # => { letter: "k", prefix: "+" }
 
 # With suffix
-result = Pnn.parse("k=")
-# => { letter: "k", suffix: "=" }
+result = Pnn.parse("k'")
+# => { letter: "k", suffix: "'" }
 
 # With both prefix and suffix
-result = Pnn.parse("+k=")
-# => { letter: "k", prefix: "+", suffix: "=" }
+result = Pnn.parse("+k'")
+# => { letter: "k", prefix: "+", suffix: "'" }
 ```
 
 ### Safe Parsing
@@ -76,8 +76,8 @@ Parse a PNN string without raising exceptions:
 require "pnn"
 
 # Valid PNN string
-result = Pnn.safe_parse("+k=")
-# => { letter: "k", prefix: "+", suffix: "=" }
+result = Pnn.safe_parse("+k'")
+# => { letter: "k", prefix: "+", suffix: "'" }
 
 # Invalid PNN string
 result = Pnn.safe_parse("invalid pnn string")
@@ -100,12 +100,12 @@ Pnn.dump(letter: "p", prefix: "+")
 # => "+p"
 
 # With suffix
-Pnn.dump(letter: "k", suffix: "=")
-# => "k="
+Pnn.dump(letter: "k", suffix: "'")
+# => "k'"
 
 # With both prefix and suffix
-Pnn.dump(letter: "p", prefix: "+", suffix: ">")
-# => "+p>"
+Pnn.dump(letter: "p", prefix: "+", suffix: "'")
+# => "+p'"
 ```
 
 ### Validation
@@ -117,37 +117,79 @@ require "pnn"
 
 Pnn.valid?("k")      # => true
 Pnn.valid?("+p")     # => true
-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
+Pnn.valid?("k''")    # => false
 ```
 
 ### Piece Modifiers
 
-PNN supports prefixes and suffixes for pieces to denote various states or capabilities:
+PNN supports prefixes and suffixes for pieces to denote various states or capabilities. It's important to note that these modifiers are rule-agnostic - they provide a framework for representing piece states, but their specific meaning is determined by the game implementation:
 
-- **Prefix `+`**: Alternative or enhanced state
-  - Example in shogi: `+p` may represent a promoted pawn
+- **Prefix `+`**: Enhanced state
+  - Example in shogi: `+p` represents a promoted pawn with enhanced movement capabilities
+  - Example in chess variants: `+Q` might represent a queen with special powers
 
-- **Prefix `-`**: Diminished or restricted state
-  - Example: `-k` may represent a king with restricted movement
+- **Prefix `-`**: Diminished state
+  - Example in variants: `-R` might represent a rook with restricted movement abilities
+  - Example in weakened pieces: `-N` could indicate a knight that has been partially immobilized
 
-- **Suffix `=`**: Bidirectional or dual-option state
-  - Example in chess: `k=` may represent a king eligible for both kingside and queenside castling
+- **Suffix `'`**: Intermediate state
+  - Example in chess: `R'` represents a rook that can still be used for castling
+  - Example in chess: `P'` represents a pawn that can be captured en passant
+  - Example in variants: `B'` might indicate a bishop with a special one-time ability
 
-- **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
+These modifiers have no intrinsic semantics in the PNN specification itself. They merely provide a flexible framework for representing piece-specific conditions or states while maintaining PNN's rule-agnostic nature. Game implementations are responsible for interpreting these modifiers according to their specific rules.
 
-- **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
+## Examples of PNN in Common Games
 
-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.
+The following examples demonstrate how PNN might be used in familiar games. Remember that PNN itself defines only the notation format, not the game-specific interpretations.
+
+### Chess Examples
+
+In the context of chess:
+
+```
+K       # King (first player)
+k       # King (second player)
+Q       # Queen (first player)
+R '      # Rook that has not moved yet and can be used for castling
+P'      # Pawn that can be captured en passant
+```
+
+### Shogi Examples
+
+In the context of shogi:
+
+```
+K       # King (first player)
+k       # King (second player)
++P      # Promoted pawn (tokin)
++L      # Promoted lance (narikyou)
+```
+
+### Example: A Complete Chess Position with PNN
+
+A chess position might contain a mix of standard and modified pieces. Here's an example after the moves 1. e4 c5 2. e5 d5:
+
+```
+r' n  b  q  k  b  n  r'    # Eighth rank with unmoved rooks (castling rights)
+p  p  .  .  p  p  p  p     # Seventh rank pawns (d and c pawns have moved)
+.  .  .  .  .  .  .  .     # Empty sixth rank
+.  .  p  p' P  .  .  .     # Fifth rank with pawn that can be captured en passant (d5) and other pawns
+.  .  .  .  .  .  .  .     # Empty fourth rank
+.  .  .  .  .  .  .  .     # Empty third rank
+P  P  P  P  .  P  P  P     # Second rank pawns (e pawn has moved)
+R' N  B  Q  K  B  N  R'    # First rank with unmoved rooks (castling rights)
+```
+
+In this position, White could capture Black's queen pawn (d5) en passant with the e5 pawn moving to d6.
+
+Note: The above representation is merely illustrative; PNN itself only defines the notation for individual pieces, not complete board states.
 
 ## Properties of PNN
 
@@ -173,4 +215,4 @@ The [gem](https://rubygems.org/gems/pnn) is available as open source under the t
 
 ## 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.
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/pnn/dumper.rb

@@ -7,7 +7,15 @@ module Pnn
     VALID_PREFIXES = ["+", "-", nil].freeze
 
     # Valid suffix modifiers
-    VALID_SUFFIXES = ["=", "<", ">", nil].freeze
+    VALID_SUFFIXES = ["'", nil].freeze
+
+    # Letter validation pattern
+    LETTER_PATTERN = /\A[a-zA-Z]\z/
+
+    # Error messages
+    ERROR_INVALID_LETTER = "Letter must be a single ASCII letter (a-z or A-Z): %s"
+    ERROR_INVALID_PREFIX = "Invalid prefix: %s. Must be '+', '-', or nil."
+    ERROR_INVALID_SUFFIX = "Invalid suffix: %s. Must be ''', or nil."
 
     # Serialize piece components into a PNN string
     #
@@ -17,19 +25,48 @@ module Pnn
     # @return [String] PNN notation string
     # @raise [ArgumentError] If any component is invalid
     def self.dump(letter:, prefix: nil, suffix: nil)
-      letter = String(letter)
+      validate_letter(letter)
+      validate_prefix(prefix)
+      validate_suffix(suffix)
 
-      unless letter.match?(/^[a-zA-Z]$/)
-        raise ArgumentError, "Letter must be a single ASCII letter (a-z or A-Z): #{letter}"
-      end
+      "#{prefix}#{letter}#{suffix}"
+    end
 
-      raise ArgumentError, "Invalid prefix: #{prefix}. Must be '+', '-', or nil." unless VALID_PREFIXES.include?(prefix)
+    # Validates that the letter is a single ASCII letter
+    #
+    # @param letter [Object] The letter to validate
+    # @return [void]
+    # @raise [ArgumentError] If the letter is invalid
+    def self.validate_letter(letter)
+      letter_str = String(letter)
 
-      unless VALID_SUFFIXES.include?(suffix)
-        raise ArgumentError, "Invalid suffix: #{suffix}. Must be '=', '<', '>', or nil."
-      end
+      return if letter_str.match?(LETTER_PATTERN)
 
-      "#{prefix}#{letter}#{suffix}"
+      raise ArgumentError, format(ERROR_INVALID_LETTER, letter_str)
     end
+
+    # Validates that the prefix is valid
+    #
+    # @param prefix [String, nil] The prefix to validate
+    # @return [void]
+    # @raise [ArgumentError] If the prefix is invalid
+    def self.validate_prefix(prefix)
+      return if VALID_PREFIXES.include?(prefix)
+
+      raise ArgumentError, format(ERROR_INVALID_PREFIX, prefix)
+    end
+
+    # Validates that the suffix is valid
+    #
+    # @param suffix [String, nil] The suffix to validate
+    # @return [void]
+    # @raise [ArgumentError] If the suffix is invalid
+    def self.validate_suffix(suffix)
+      return if VALID_SUFFIXES.include?(suffix)
+
+      raise ArgumentError, format(ERROR_INVALID_SUFFIX, suffix)
+    end
+
+    private_class_method :validate_letter, :validate_prefix, :validate_suffix
   end
 end

data/lib/pnn/parser.rb

@@ -4,7 +4,13 @@ module Pnn
   # Parses PNN strings into their component parts
   class Parser
     # PNN regex capture groups for parsing
-    PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>[=<>])?\z/
+    PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>['])?\z/
+
+    # Error message for invalid PNN string
+    ERROR_INVALID_PNN = "Invalid PNN string: %s"
+
+    # Component keys for the result hash
+    COMPONENT_KEYS = %i[letter prefix suffix].freeze
 
     # Parse a PNN string into its components
     #
@@ -12,17 +18,9 @@ module Pnn
     # @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
+      string_value = String(pnn_string)
+      matches = match_pattern(string_value)
+      extract_components(matches)
     end
 
     # Safely parse a PNN string without raising exceptions
@@ -34,5 +32,31 @@ module Pnn
     rescue ArgumentError
       nil
     end
+
+    # Match the PNN pattern against a string
+    #
+    # @param string [String] The string to match
+    # @return [MatchData] The match data
+    # @raise [ArgumentError] If the string doesn't match the pattern
+    def self.match_pattern(string)
+      matches = PATTERN.match(string)
+
+      return matches if matches
+
+      raise ArgumentError, format(ERROR_INVALID_PNN, string)
+    end
+
+    # Extract components from match data
+    #
+    # @param matches [MatchData] The match data
+    # @return [Hash] Hash containing the parsed components
+    def self.extract_components(matches)
+      COMPONENT_KEYS.each_with_object({}) do |key, result|
+        value = matches[key]
+        result[key] = value if value
+      end
+    end
+
+    private_class_method :match_pattern, :extract_components
   end
 end

data/lib/pnn/validator.rb

@@ -4,14 +4,24 @@ 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/
+    PATTERN = /\A[-+]?[a-zA-Z][']?\z/
 
     # Class method to validate PNN strings
     #
-    # @param pnn_string [String] The PNN string to validate
+    # @param pnn_string [Object] 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)
+      validate_string(String(pnn_string))
     end
+
+    # Validates the given string against the PNN pattern
+    #
+    # @param string [String] The string to validate
+    # @return [Boolean] True if the string matches the PNN pattern
+    def self.validate_string(string)
+      string.match?(PATTERN)
+    end
+
+    private_class_method :validate_string
   end
 end

data/lib/pnn.rb

@@ -14,14 +14,14 @@ require_relative File.join("pnn", "validator")
 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 '>')
+  # @param prefix [String, nil] Optional modifier preceding the letter ('+' or '-')
+  # @param suffix [String, nil] Optional modifier following the letter (''')
   # @return [String] PNN notation string
   # @raise [ArgumentError] If any parameter is invalid
   # @example
-  #   Pnn.dump(letter: "k", suffix: "=")
-  #   # => "k="
+  #   Pnn.dump(letter: "k", suffix: "'")
+  #   # => "k'"
   def self.dump(letter:, prefix: nil, suffix: nil)
     Dumper.dump(letter:, prefix:, suffix:)
   end
@@ -35,8 +35,8 @@ module Pnn
   #   - :suffix [String, nil] - The suffix modifier if present
   # @raise [ArgumentError] If the PNN string is invalid
   # @example
-  #   Pnn.parse("+k=")
-  #   # => { letter: "k", prefix: "+", suffix: "=" }
+  #   Pnn.parse("+k'")
+  #   # => { letter: "k", prefix: "+", suffix: "'" }
   def self.parse(pnn_string)
     Parser.parse(pnn_string)
   end
@@ -47,8 +47,8 @@ module Pnn
   # @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: "=" }
+  #   Pnn.safe_parse("+k'")
+  #   # => { letter: "k", prefix: "+", suffix: "'" }
   #
   #   # Invalid PNN string
   #   Pnn.safe_parse("invalid")
@@ -62,7 +62,7 @@ module Pnn
   # @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?("k'") # => true
   #   Pnn.valid?("invalid") # => false
   def self.valid?(pnn_string)
     Validator.valid?(pnn_string)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pnn
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Cyril Kato