sashite-gan 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dffb3b5300bf9cfe17f98e0bea0fc2daa5a90d56df88a652e82f4a3b9056d7a1
-  data.tar.gz: a27352efa48e49bff0f89a1371853452edd6ffd09aca5cb8c1e360193f7576cc
+  metadata.gz: 5d75df37e1d20e65cbf461231526922a343dcff9e2c113a6c2dc9a85c4183c51
+  data.tar.gz: 57c80ac8d301e5d06d1d65be1211802587524bda49c95b9b943b035d519f3eac
 SHA512:
-  metadata.gz: 2f635c1fd54f5a81b9c0303471011952197058a8997bcd006ce3f6776ad4ee845e04a444139ebba8c65b9f56b90f9225f305b17cc9b93d7bb1aa75fda8f50e2b
-  data.tar.gz: ac3c7237c234e7bd61c38edf7ac83acced6ef46951ffd19077b855a33f7ce5078edaced35be5b1ee7008fa26beff9102888c9935def92a45b75718210dcd5fac
+  metadata.gz: f63028d5668cd3f8d6f0b74b684f79d9664f7f896b1e606604775a113fd0554bebf2df5e461adbfe46baa4ef3f59df3057407406b19739f2d2ca9e7bb88bfdcb
+  data.tar.gz: ab4807633db42b7d7cdd8d770822d50d9b983fb2210a9b1a2bbd8650304bb991f1399db86a639b79766141cc149f0e6af0cb5dd5fede120efa509b2cd59e7640

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2020 Cyril Kato
+Copyright (c) 2014-2020 Sashite
 
 MIT License
 

data/README.md

@@ -1,52 +1,181 @@
-# Sashite::GAN ♟️
+# GAN.rb
 
-> An implementation of [General Actor Notation](https://developer.sashite.com/specs/general-actor-notation) for storing actors from abstract strategy games.
+[![Build Status](https://travis-ci.org/sashite/gan.rb.svg?branch=master)](https://travis-ci.org/sashite/gan.rb)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'sashite-gan'
+> A Ruby interface for data serialization in [General Actor Notation](https://developer.sashite.com/specs/general-actor-notation) format ♟️
 
-And then execute:
+## Installation
 
-    $ bundle
+1. Add the dependency to your `Gemfile`:
 
-Or install it yourself as:
+   ```ruby
+   gem 'sashite-gan'
+   ```
 
-    $ gem install sashite-gan
+2. Run `bundle install`
 
 ## Usage
 
-    require 'sashite-gan'
-
-    # Chess (Western) Rook, White
-    Sashite::GAN.string(is_checkmateable: false, is_promoted: false, is_topside: false, piece_abbr: 'r', style_abbr: 'c') # => 'C:R'
-
-    # Chess (Western) King, Black
-    Sashite::GAN.string(is_checkmateable: true, is_promoted: false, is_topside: true, piece_abbr: 'k', style_abbr: 'c') # => 'c:-k'
-
-    # Shogi King, Gote
-    Sashite::GAN.string(is_checkmateable: true, is_promoted: false, is_topside: true, piece_abbr: 'k', style_abbr: 's') # => 's:-k'
-
-    # Shogi promoted Pawn, Sente
-    Sashite::GAN.string(is_checkmateable: false, is_promoted: true, is_topside: false, piece_abbr: 'p', style_abbr: 's') # => 'S:+P'
-
-    # Xiangqi General, Red
-    Sashite::GAN.string(is_checkmateable: true, is_promoted: false, is_topside: false, piece_abbr: 'g', style_abbr: 'x') # => 'X:-G'
-
-    # Xiangqi Flying General, Red
-    Sashite::GAN.string(is_checkmateable: true, is_promoted: true, is_topside: false, piece_abbr: 'g', style_abbr: 'x') # => 'X:+-G'
-
-    # Go Stone, Black
-    Sashite::GAN.string(is_checkmateable: false, is_promoted: false, is_topside: false, piece_abbr: 's', style_abbr: 'go') # => 'GO:S'
+```ruby
+require 'sashite-gan'
+
+
+# Chess (Western chess)'s Rook, White
+piece = Sashite::GAN.parse("C:R")
+
+piece.abbr.to_s # => "R"
+piece.style # => "C"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "C:R"
+piece.topside.to_s # => "c:r"
+piece.bottomside.to_s # => "C:R"
+piece.oppositeside.to_s # => "c:r"
+piece.promote.to_s # => "C:+R"
+piece.unpromote.to_s # => "C:R"
+
+
+# Chess (Western chess)'s King, Black
+piece = Sashite::GAN.parse("c:-k")
+
+piece.abbr.to_s # => "-k"
+piece.style # => "c"
+piece.topside? # => true
+piece.bottomside? # => false
+piece.to_s # => "c:-k"
+piece.topside.to_s # => "c:-k"
+piece.bottomside.to_s # => "C:-K"
+piece.oppositeside.to_s # => "C:-K"
+piece.promote.to_s # => "c:+-k"
+piece.unpromote.to_s # => "c:-k"
+
+
+# Makruk (Thai chess)'s Bishop, White
+piece = Sashite::GAN.parse("M:B")
+
+piece.abbr.to_s # => "B"
+piece.style # => "M"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "M:B"
+piece.topside.to_s # => "m:b"
+piece.bottomside.to_s # => "M:B"
+piece.oppositeside.to_s # => "m:b"
+piece.promote.to_s # => "M:+B"
+piece.unpromote.to_s # => "M:B"
+
+
+# Shogi (Japanese chess)'s King, Gote
+piece = Sashite::GAN.parse("s:-k")
+
+piece.abbr.to_s # => "-k"
+piece.style # => "s"
+piece.topside? # => true
+piece.bottomside? # => false
+piece.to_s # => "s:-k"
+piece.topside.to_s # => "s:-k"
+piece.bottomside.to_s # => "S:-K"
+piece.oppositeside.to_s # => "S:-K"
+piece.promote.to_s # => "s:+-k"
+piece.unpromote.to_s # => "s:-k"
+
+
+# Shogi (Japanese chess)'s King, Sente
+piece = Sashite::GAN.parse("S:-K")
+
+piece.abbr.to_s # => "-K"
+piece.style # => "S"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "S:-K"
+piece.topside.to_s # => "s:-k"
+piece.bottomside.to_s # => "S:-K"
+piece.oppositeside.to_s # => "s:-k"
+piece.promote.to_s # => "S:+-K"
+piece.unpromote.to_s # => "S:-K"
+
+
+# Shogi (Japanese chess)'s promoted Pawn, Sente
+piece = Sashite::GAN.parse("S:+P")
+
+piece.abbr.to_s # => "+P"
+piece.style # => "S"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "S:+P"
+piece.topside.to_s # => "s:+p"
+piece.bottomside.to_s # => "S:+P"
+piece.oppositeside.to_s # => "s:+p"
+piece.promote.to_s # => "S:+P"
+piece.unpromote.to_s # => "S:P"
+
+
+# Xiangqi (Chinese chess)'s General, Red
+piece = Sashite::GAN.parse("X:-G")
+
+piece.abbr.to_s # => "-G"
+piece.style # => "X"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "X:-G"
+piece.topside.to_s # => "x:-g"
+piece.bottomside.to_s # => "X:-G"
+piece.oppositeside.to_s # => "x:-g"
+piece.promote.to_s # => "X:+-G"
+piece.unpromote.to_s # => "X:-G"
+
+
+# Xiangqi (Chinese chess)'s Flying General, Red
+piece = Sashite::GAN.parse("X:+-G")
+
+piece.abbr.to_s # => "+-G"
+piece.style # => "X"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "X:+-G"
+piece.topside.to_s # => "x:+-g"
+piece.bottomside.to_s # => "X:+-G"
+piece.oppositeside.to_s # => "x:+-g"
+piece.promote.to_s # => "X:+-G"
+piece.unpromote.to_s # => "X:-G"
+
+
+# Dai Dai Shogi (huge Japanese chess)'s Phoenix, Sente
+piece = Sashite::GAN.parse("DAI_DAI_SHOGI:PH")
+
+piece.abbr.to_s # => "PH"
+piece.style # => "DAI_DAI_SHOGI"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "DAI_DAI_SHOGI:PH"
+piece.topside.to_s # => "dai_dai_shogi:ph"
+piece.bottomside.to_s # => "DAI_DAI_SHOGI:PH"
+piece.oppositeside.to_s # => "dai_dai_shogi:ph"
+piece.promote.to_s # => "DAI_DAI_SHOGI:+PH"
+piece.unpromote.to_s # => "DAI_DAI_SHOGI:PH"
+
+
+# A random FOO chess variant's promoted Z piece, Bottom-side
+piece = Sashite::GAN.parse("FOO:+Z")
+
+piece.abbr.to_s # => "+Z"
+piece.style # => "FOO"
+piece.topside? # => false
+piece.bottomside? # => true
+piece.to_s # => "FOO:+Z"
+piece.topside.to_s # => "foo:+z"
+piece.bottomside.to_s # => "FOO:+Z"
+piece.oppositeside.to_s # => "foo:+z"
+piece.promote.to_s # => "FOO:+Z"
+piece.unpromote.to_s # => "FOO:Z"
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About Sashite
 
-The `sashite-gan` gem is maintained by [Sashite](https://sashite.com/).
+This [gem](https://rubygems.org/gems/sashite-gan) is maintained by [Sashite](https://sashite.com/).
 
 With some [lines of code](https://github.com/sashite/), let's share the beauty of Chinese, Japanese and Western cultures through the game of chess!

data/lib/sashite-gan.rb

@@ -1,3 +1,6 @@
 # frozen_string_literal: true
 
-require 'sashite/gan'
+# Sashite namespace
+module Sashite; end
+
+require_relative 'sashite/gan'

data/lib/sashite/gan.rb

@@ -1,43 +1,49 @@
 # frozen_string_literal: true
 
-module Sashite
-  # General Actor Notation
-  class GAN
-    # @return [String] The representation of an actor.
-    def self.string(is_checkmateable:, is_promoted:, is_topside:, piece_abbr:, style_abbr:)
-      unless [false, true].include?(is_topside)
-        raise TypeError, is_topside.class.inspect
-      end
-
-      piece_code = piece_code_builder(
-        piece_abbr: piece_abbr,
-        is_checkmateable: is_checkmateable,
-        is_promoted: is_promoted
-      )
+require_relative 'gan/parser'
 
-      piece_code_with_prefix = "#{style_abbr}:#{piece_code}"
-
-      if is_topside
-        piece_code_with_prefix.downcase
-      else
-        piece_code_with_prefix.upcase
-      end
-    end
-
-    def self.piece_code_builder(piece_abbr:, is_checkmateable:, is_promoted:)
-      unless [false, true].include?(is_checkmateable)
-        raise TypeError, is_checkmateable.class.inspect
-      end
-
-      unless [false, true].include?(is_promoted)
-        raise TypeError, is_promoted.class.inspect
-      end
+module Sashite
+  # The GAN (General Actor Notation) module.
+  #
+  # @see https://developer.sashite.com/specs/general-actor-notation
+  module GAN
+    SEPARATOR_CHAR = ':'
 
-      str = piece_abbr
-      str = "-#{str}" if is_checkmateable
-      str = "+#{str}" if is_promoted
-      str
+    # Parse the GAN string into a Ruby object structure and return it.
+    #
+    # @example Chess (Western chess)'s Rook, White
+    #   GAN.parse("C:R")
+    #
+    # @example Chess (Western chess)'s King, Black
+    #   GAN.parse("c:-k")
+    #
+    # @example Makruk (Thai chess)'s Bishop, White
+    #   GAN.parse("M:B")
+    #
+    # @example Shogi (Japanese chess)'s King, Gote
+    #   GAN.parse("s:-k")
+    #
+    # @example Shogi (Japanese chess)'s King, Sente
+    #   GAN.parse("S:-K")
+    #
+    # @example Shogi (Japanese chess)'s promoted Pawn, Sente
+    #   GAN.parse("S:+P")
+    #
+    # @example Xiangqi (Chinese chess)'s General, Red
+    #   GAN.parse("X:-G")
+    #
+    # @example Xiangqi (Chinese chess)'s Flying General, Red
+    #   GAN.parse("X:+-G")
+    #
+    # @example Dai Dai Shogi (huge Japanese chess)'s Phoenix, Sente
+    #   GAN.parse("DAI_DAI_SHOGI:PH")
+    #
+    # @example Another FOO chess variant's promoted Z piece, Bottom-side
+    #   GAN.parse("FOO:+Z")
+    #
+    # @return [Piece] An instance of the piece.
+    def self.parse(string)
+      Parser.call(string)
     end
-    private_class_method :piece_code_builder
   end
 end

data/lib/sashite/gan/abbr.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Sashite
+  module GAN
+    # The piece's abbreviation.
+    class Abbr
+      # The piece's type.
+      #
+      # @!attribute [r] type
+      #   @return [String] The type of the piece.
+      attr_reader :type
+
+      def initialize(type, is_promoted:, is_king:)
+        @type = TypeString(type)
+        @is_promoted = Boolean(is_promoted)
+        @is_king = Boolean(is_king)
+
+        freeze
+      end
+
+      # @return [Boolean] Is the piece a king?
+      def king?
+        @is_king
+      end
+
+      # @return [Boolean] Is the piece promoted?
+      def promoted?
+        @is_promoted
+      end
+
+      # @return [String] The abbreviation of the piece.
+      def to_s
+        str = type
+        str = "-#{str}" if king?
+        str = "+#{str}" if promoted?
+        str
+      end
+
+      def inspect
+        to_s
+      end
+
+      private
+
+      # rubocop:disable Naming/MethodName
+
+      # Ensures `arg` is a boolean, and returns it.  Otherwise, raises a
+      #   `TypeError`.
+      def Boolean(arg)
+        raise ::TypeError, arg.class.inspect unless [false, true].include?(arg)
+
+        arg
+      end
+
+      # Ensures `arg` is a type, and returns it.  Otherwise, raises an error.
+      def TypeString(arg)
+        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
+        raise Error::Type, arg.inspect unless arg.match?(/\A[a-z]{1,2}\z/i)
+
+        arg
+      end
+
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end
+
+require_relative 'error'

data/lib/sashite/gan/error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Sashite
+  module GAN
+    # The error namespace.
+    module Error; end
+  end
+end
+
+Dir[File.join(File.dirname(__FILE__), 'error', '*.rb')].each do |fname|
+  require_relative fname
+end

data/lib/sashite/gan/error/string.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Sashite
+  module GAN
+    module Error
+      # `String` is the base class for GAN string errors.
+      class String < ::StandardError; end
+    end
+  end
+end

data/lib/sashite/gan/error/style.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module Sashite
+  module GAN
+    module Error
+      # Raised when encountering an invalid sequence of characters.
+      class Style < String; end
+    end
+  end
+end

data/lib/sashite/gan/error/type.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module Sashite
+  module GAN
+    module Error
+      # Raised when encountering an invalid sequence of characters.
+      class Type < String; end
+    end
+  end
+end

data/lib/sashite/gan/parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'piece'
+
+module Sashite
+  module GAN
+    # The notation parser.
+    module Parser
+      def self.call(arg)
+        raise Error::String, "Invalid: #{arg.inspect}" unless valid?(arg)
+
+        style, abbr = arg.split(SEPARATOR_CHAR)
+
+        Piece.new(
+          abbr.delete('-+'),
+          is_king: abbr.include?('-'),
+          is_promoted: abbr.include?('+'),
+          is_topside: style.downcase.eql?(style),
+          style: style
+        )
+      end
+
+      def self.valid?(arg)
+        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
+
+        arg.match?(/\A([a-z_]+:\+?-?[a-z]{1,2}|[A-Z_]+:\+?-?[A-Z]{1,2})\z/)
+      end
+    end
+  end
+end

data/lib/sashite/gan/piece.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Sashite
+  module GAN
+    # A piece abstraction.
+    class Piece
+      # The abbreviation of the piece.
+      #
+      # @!attribute [r] abbr
+      #   @return [String] The abbreviation of the piece.
+      attr_reader :abbr
+
+      # The piece's style.
+      #
+      # @!attribute [r] style
+      #   @return [String] The piece's style.
+      attr_reader :style
+
+      # Initialize a piece.
+      #
+      # @param type [String] The type of the piece.
+      # @param is_king [Boolean] Is it a King (or a Xiangqi General),
+      #   so it could be checkmated?
+      # @param is_promoted [Boolean] Is it promoted?
+      # @param is_topside [Boolean] Is it owned by top-side player?
+      # @param style [String] The piece's style.
+      def initialize(type, is_king:, is_promoted:, is_topside:, style:)
+        @abbr = Abbr.new(type, is_king: is_king, is_promoted: is_promoted)
+        @is_topside = Boolean(is_topside)
+        @style = StyleString(style)
+
+        freeze
+      end
+
+      # Is it owned by top-side player?
+      #
+      # @return [Boolean] Returns `true` if the top-side player own the piece,
+      #   `false` otherwise.
+      def topside?
+        @is_topside
+      end
+
+      # Is it owned by bottom-side player?
+      #
+      # @return [Boolean] Returns `true` if the bottom-side player own the
+      #   piece, `false` otherwise.
+      def bottomside?
+        !topside?
+      end
+
+      # @see https://developer.sashite.com/specs/general-actor-notation
+      # @return [String] The notation of the piece.
+      def to_s
+        topside? ? raw.downcase : raw.upcase
+      end
+
+      def inspect
+        to_s
+      end
+
+      # @return [Piece] The top-side side version of the piece.
+      def topside
+        topside? ? self : oppositeside
+      end
+
+      # @return [Piece] The bottom-side side version of the piece.
+      def bottomside
+        topside? ? oppositeside : self
+      end
+
+      # @return [Piece] The opposite side version of the piece.
+      def oppositeside
+        self.class.new(abbr.type,
+          is_king: abbr.king?,
+          is_promoted: abbr.promoted?,
+          is_topside: !topside?,
+          style: style
+        )
+      end
+
+      # @return [Piece] The promoted version of the piece.
+      def promote
+        self.class.new(abbr.type,
+          is_king: abbr.king?,
+          is_promoted: true,
+          is_topside: topside?,
+          style: style
+        )
+      end
+
+      # @return [Piece] The unpromoted version of the piece.
+      def unpromote
+        self.class.new(abbr.type,
+          is_king: abbr.king?,
+          is_promoted: false,
+          is_topside: topside?,
+          style: style
+        )
+      end
+
+      private
+
+      # @return [String] The style and the abbreviation of the piece (without
+      #   case).
+      def raw
+        params.join(SEPARATOR_CHAR)
+      end
+
+      # @return [Array] The style and the abbreviation of the piece.
+      def params
+        [style, abbr]
+      end
+
+      # rubocop:disable Naming/MethodName
+
+      # Ensures `arg` is a boolean, and returns it.  Otherwise, raises a
+      #   `TypeError`.
+      def Boolean(arg)
+        raise ::TypeError, arg.class.inspect unless [false, true].include?(arg)
+
+        arg
+      end
+
+      # Ensures `arg` is a style, and returns it.  Otherwise, raises an error.
+      def StyleString(arg)
+        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
+        raise Error::Style, arg.inspect unless arg.match?(/\A[a-z_]+\z/i)
+
+        arg
+      end
+
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end
+
+require_relative 'abbr'
+require_relative 'error'

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: sashite-gan
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-21 00:00:00.000000000 Z
+date: 2020-08-06 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: brutal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -94,8 +108,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Implementation of GAN (General Actor Notation) for storing actors from
-  abstract strategy games.
+description: A Ruby interface for data serialization in GAN format ♟️
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -105,6 +118,13 @@ files:
 - README.md
 - lib/sashite-gan.rb
 - lib/sashite/gan.rb
+- lib/sashite/gan/abbr.rb
+- lib/sashite/gan/error.rb
+- lib/sashite/gan/error/string.rb
+- lib/sashite/gan/error/style.rb
+- lib/sashite/gan/error/type.rb
+- lib/sashite/gan/parser.rb
+- lib/sashite/gan/piece.rb
 homepage: https://developer.sashite.com/specs/general-actor-notation
 licenses:
 - MIT