feat(PiecesInHand): reduction of the length of serialized strings

When several occurrences of the same piece is present, it is grouped via a "*" sign and the number of occurrences.

.rubocop.yml

@@ -18,6 +18,8 @@ AllCops:
 
  - doc/
 
+ - pkg/
+
  - test.rb
  - config/**/*
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
  remote: .
  specs:
- feen (4.0.3)
+ feen (5.0.0.beta0)
 
 GEM
  remote: https://rubygems.org/

README.md

@@ -1,4 +1,4 @@
-# FEEN.rb
+# Feen.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/releases)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/feen.rb/main)
@@ -10,7 +10,13 @@
 
 ## Overview
 
-This is an implementation of [FEEN](https://developer.sashite.com/specs/fen-easy-extensible-notation), a generic format that can be used for serializing and deserializing chess positions.
+This is an implementation of [FEEN](https://developer.sashite.com/specs/fen-easy-extensible-notation), a generic format that can be used for serializing and deserializing positions.
+
+A __FEEN__ string consists of a single line of ASCII text containing three data fields, separated by a space. These are:
+
+1. Piece placement
+2. Side to move
+3. Pieces in hand
 
 The main chess variants may be supported, including [Chess](https://en.wikipedia.org/wiki/Chess), [Janggi](https://en.wikipedia.org/wiki/Janggi), [Makruk](https://en.wikipedia.org/wiki/Makruk), [Shogi](https://en.wikipedia.org/wiki/Shogi), [Xiangqi](https://en.wikipedia.org/wiki/Xiangqi).
 
@@ -23,7 +29,7 @@ More exotic variants may be also supported, like: [Dai dai shogi](https://en.wik
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "feen"
+gem "feen", ">= 5.0.0.beta0"
 ```
 
 And then execute:
@@ -35,32 +41,58 @@ bundle install
 Or install it yourself as:
 
 ```sh
-gem install feen
+gem install feen --pre
 ```
 
 ## Usage
 
+### Serialization
+
+A position can be serialized by filling in these fields:
+
+- **Piece placement**: Describes the placement of pieces on the board with a hash that references each piece on the board. The keys could be numbers, or strings of characters representing coordinates.
+- **Side to move**: A char that indicates who moves next. In chess, "`w`" would mean that White must move, and "`b`" that Black must move. In Shogi, "`s`" could mean that Sente must move, and "`g`" that Gote must move. In Xiangqi, "`r`" could mean that Red must move, and "`b`" that Black must move.
+- **Pieces in hand**: An array of all captured pieces that remain _in hand_, like in Shogi.
+- **Board shape**: An array of integers. For instance, it would be `[10, 9]` in Xiangqi. And it would be `[8, 8]` in Chess.
+
+#### Examples
+
+##### A classic Tsume Shogi problem
+
 ```ruby
 require "feen"
 
-# Dump a classic Tsume Shogi problem
-FEEN.dump(
- in_hand: %w[S r r b g g g g s n n n n p p p p p p p p p p p p p p p p p],
- shape: [9, 9],
- side_id: 0,
- square: {
+Feen.dump(
+ side_to_move: "s",
+ pieces_in_hand: %w[S r r b g g g g s n n n n p p p p p p p p p p p p p p p p p],
+ board_shape: [9, 9],
+ piece_placement: {
  3 => "s",
  4 => "k",
  5 => "s",
  22 => "+P",
  43 => "+B"
  }
 )
-# => "3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 0 S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s"
+# => "3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 s S,b,g*4,n*4,p*17,r*2,s"
+```
+
+### Deserialization
+
+Serialized positions can be converted back to fields.
+
+#### Examples
+
+##### A classic Tsume Shogi problem
+
+```ruby
+require "feen"
 
-# Parse a classic Tsume Shogi problem
-FEEN.parse("3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 0 S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s")
-# => {:square=>{3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}, :shape=>[9, 9], :in_hand=>["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"], :side_id=>0}
+Feen.parse("3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 s S,b,g*4,n*4,p*17,r*2,s")
+# {:board_shape=>[9, 9],
+# :pieces_in_hand=>["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"],
+# :piece_placement=>{3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"},
+# :side_to_move=>"s"}
 ```
 
 ## License

VERSION.semver

@@ -1 +1 @@
-4.0.3
+5.0.0.beta0

brutal/feen/dumper_brutal.yaml

@@ -16,18 +16,18 @@ header: |
  end
 
 subject: |
- FEEN.dump(
- in_hand: %{in_hand},
- shape: %{shape},
- side_id: %{side_id},
- square: %{square}
+ Feen.dump(
+ side_to_move: %{side_to_move},
+ pieces_in_hand: %{pieces_in_hand},
+ board_shape: %{board_shape},
+ piece_placement: %{piece_placement}
  )
 
 contexts:
- in_hand:
+ pieces_in_hand:
  - []
  - [S, r, r, b, g, g, s, n, n, p]
- shape:
+ board_shape:
  -
  - 8
  - 8
@@ -38,12 +38,12 @@ contexts:
  -
  - 14
  - 14
- side_id:
+ side_to_move:
  - 0
  - 1
  - 2
  - 3
- square:
+ piece_placement:
  - {}
  -
  3: "yR"

brutal/feen/parser_brutal.yaml

@@ -16,19 +16,19 @@ header: |
  end
 
 subject: |
- FEEN.parse("%{string}")
+ Feen.parse("%{string}")
 
 contexts:
  string:
- - 8/8/8/8/8/8/8/8//8/8/8/8/8/8/8/8//8/8/8/8/8/8/8/8 0 -
- - 3,yR,yN,yB,yK,yQ,yB,yN,yR,3/3,yP,yP,yP,yP,yP,yP,yP,yP,3/14/bR,bP,10,gP,gR/bN,bP,10,gP,gN/bB,bP,10,gP,gB/bK,bP,10,gP,gQ/bQ,bP,10,gP,gK/bB,bP,10,gP,gB/bN,bP,10,gP,gN/bR,bP,10,gP,gR/14/3,rP,rP,rP,rP,rP,rP,rP,rP,3/3,rR,rN,rB,rQ,rK,rB,rN,rR,3 0 -
- - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,♟,♟,♟,♟/8/8/8/8/♙,♙,♙,♙,♙,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 0 -
- - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,♟,♟,♟,♟/8/8/4,♙,3/8/♙,♙,♙,♙,1,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 1 -
- - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,1,♟,♟,♟/8/4,♟,3/4,♙,3/8/♙,♙,♙,♙,1,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 0 -
- - ♜,♞,♝,♛,♚,♝,♞,♜/8/♟,♟,♟,♟,♟,♟,♟,♟/8/8/♙,♙,♙,♙,♙,♙,♙,♙/8/♖,♘,♗,♔,♕,♗,♘,♖ 0 -
- - l,n,s,g,k,g,s,n,l/1,r,5,b,1/p,p,p,p,p,p,p,p,p/9/9/9/P,P,P,P,P,P,P,P,P/1,B,5,R,1/L,N,S,G,K,G,S,N,L 0 -
- - 3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 0 S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s
- - 車,馬,象,士,將,士,象,馬,車/9/1,砲,5,砲,1/卒,1,卒,1,卒,1,卒,1,卒/9/9/兵,1,兵,1,兵,1,兵,1,兵/1,炮,5,炮,1/9/俥,傌,相,仕,帥,仕,相,傌,俥 0 -
+ - 8/8/8/8/8/8/8/8//8/8/8/8/8/8/8/8//8/8/8/8/8/8/8/8 0
+ - 3,yR,yN,yB,yK,yQ,yB,yN,yR,3/3,yP,yP,yP,yP,yP,yP,yP,yP,3/14/bR,bP,10,gP,gR/bN,bP,10,gP,gN/bB,bP,10,gP,gB/bK,bP,10,gP,gQ/bQ,bP,10,gP,gK/bB,bP,10,gP,gB/bN,bP,10,gP,gN/bR,bP,10,gP,gR/14/3,rP,rP,rP,rP,rP,rP,rP,rP,3/3,rR,rN,rB,rQ,rK,rB,rN,rR,3 0
+ - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,♟,♟,♟,♟/8/8/8/8/♙,♙,♙,♙,♙,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 0
+ - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,♟,♟,♟,♟/8/8/4,♙,3/8/♙,♙,♙,♙,1,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 1
+ - ♜,♞,♝,♛,♚,♝,♞,♜/♟,♟,♟,♟,1,♟,♟,♟/8/4,♟,3/4,♙,3/8/♙,♙,♙,♙,1,♙,♙,♙/♖,♘,♗,♕,♔,♗,♘,♖ 0
+ - ♜,♞,♝,♛,♚,♝,♞,♜/8/♟,♟,♟,♟,♟,♟,♟,♟/8/8/♙,♙,♙,♙,♙,♙,♙,♙/8/♖,♘,♗,♔,♕,♗,♘,♖ 0
+ - l,n,s,g,k,g,s,n,l/1,r,5,b,1/p,p,p,p,p,p,p,p,p/9/9/9/P,P,P,P,P,P,P,P,P/1,B,5,R,1/L,N,S,G,K,G,S,N,L 0
+ - 3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 0 S,b,g*4,n*4,p*17,r*2,s
+ - 車,馬,象,士,將,士,象,馬,車/9/1,砲,5,砲,1/卒,1,卒,1,卒,1,卒,1,卒/9/9/兵,1,兵,1,兵,1,兵,1,兵/1,炮,5,炮,1/9/俥,傌,相,仕,帥,仕,相,傌,俥 0
 
 actuals:
  - "%{subject}.to_h"