pgn2 1.5.0 → 2.0.0

data/lib/pgn/serializer.rb

@@ -17,7 +17,7 @@ module PGN
 
     # @return [String] a canonical PGN string ending with a trailing newline
     def to_s
-      tag_section + "\n\n" + movetext_section + "\n"
+      "#{tag_section}\n\n#{movetext_section}\n"
     end
 
     private
@@ -39,18 +39,16 @@ module PGN
     # result, all joined by spaces.
     def movetext_section
       tokens = []
-      if @game.comment && !@game.comment.empty?
-        tokens << "{ #{escape_comment(@game.comment)} }"
-      end
+      tokens << "{ #{escape_comment(@game.comment)} }" if @game.comment && !@game.comment.empty?
       line = emit_line(@game.moves, starting_fullmove, starting_player)
       tokens << line unless line.empty?
       tokens << result_token
-      tokens.join(" ")
+      tokens.join(' ')
     end
 
     # The result token: the game's result if present and non-empty, else "*".
     def result_token
-      (@game.result.nil? || @game.result.empty?) ? "*" : @game.result
+      @game.result.nil? || @game.result.empty? ? '*' : @game.result
     end
 
     # Emit a single line (mainline or variation) of movetext, tracking the
@@ -63,12 +61,11 @@ module PGN
       moves.each do |move|
         if player == :white
           tokens << "#{fullmove}."
-          tokens << move_token(move, fullmove, player)
         else # black
           need_number = prev_player.nil? || prev_had_extras || prev_player != :white
           tokens << "#{fullmove}..." if need_number
-          tokens << move_token(move, fullmove, player)
         end
+        tokens << move_token(move, fullmove, player)
 
         prev_player = player
         prev_had_extras = has_extras?(move)
@@ -76,7 +73,7 @@ module PGN
         player = opposite(player)
       end
 
-      tokens.join(" ")
+      tokens.join(' ')
     end
 
     # A move token: notation plus trailing extras (annotation, comment,
@@ -85,13 +82,11 @@ module PGN
     def move_token(move, fullmove, player)
       parts = [move.notation]
       (move.annotation || []).each { |a| parts << a }
-      if move.comment && !move.comment.empty?
-        parts << "{ #{escape_comment(move.comment)} }"
-      end
+      parts << "{ #{escape_comment(move.comment)} }" if move.comment && !move.comment.empty?
       (move.variations || []).each do |variation|
         parts << "(#{emit_line(variation, fullmove, player)})"
       end
-      parts.join(" ")
+      parts.join(' ')
     end
 
     # Whether a move carries any annotation, comment, or variation.
@@ -118,8 +113,8 @@ module PGN
     # string replacement would otherwise re-interpret backslashes).
     def escape_tag(value)
       value.to_s
-           .gsub("\\") { "\\\\" }
-           .gsub('"') { "\\\"" }
+           .gsub('\\') { '\\\\' }
+           .gsub('"') { '\"' }
     end
 
     # Escape backslashes and braces for a comment body (block form, so the
@@ -133,9 +128,9 @@ module PGN
     # acknowledged v1 limitation.
     def escape_comment(text)
       text.to_s
-          .gsub("\\") { "\\\\" }
-          .gsub("{") { "\\{" }
-          .gsub("}") { "\\}" }
+          .gsub('\\') { '\\\\' }
+          .gsub('{') { '\\{' }
+          .gsub('}') { '\\}' }
     end
   end
 end

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '1.5.0'.freeze
+  VERSION = '2.0.0'.freeze
 end

data/lib/pgn/zobrist.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PGN
+  # Zobrist hashing keys for incremental position hashing. All keys are
+  # fixed 64-bit pseudo-random Integers generated once at load time from a
+  # frozen seed so hashes are stable for the life of the process.
+  #
+  # Indexing is by 0x88 square index (0..127); off-board indices are
+  # allocated but never read.
+  module Zobrist
+    SEED = 0x1234_5678_9abc_def1
+
+    # Deterministic pseudo-random generator so hashes are stable per
+    # process and across machines (no Kernel#rand).
+    def self.gen
+      @gen ||= Random.new(SEED)
+    end
+    private_class_method :gen
+
+    def self.rand64
+      gen.rand(1 << 64)
+    end
+    private_class_method :rand64
+
+    PIECES = %w[P N B R Q K p n b r q k].freeze
+
+    TABLE = PIECES.to_h { |piece| [piece, Array.new(128) { rand64 }] }.freeze
+
+    SIDE = rand64
+    CASTLING = { 'K' => rand64, 'Q' => rand64, 'k' => rand64, 'q' => rand64 }.freeze
+    EP_FILE = Array.new(8) { rand64 }.freeze
+
+    # @param board [PGN::Board]
+    # @param player [Symbol] :white or :black
+    # @param castling [Array<String>] e.g. %w[K Q k q]
+    # @param en_passant [String, nil] e.g. "e3" or nil
+    # @return [Integer] the Zobrist hash of the position
+    def self.seed(board, player, castling, en_passant)
+      h = 0
+      0.upto(7) do |rank|
+        0.upto(7) do |file|
+          idx = board.index_for(file, rank)
+          piece = board.at_index(idx)
+          h ^= TABLE[piece][idx] if piece
+        end
+      end
+      h ^= SIDE if player == :black
+      castling.to_a.each { |right| h ^= CASTLING[right] if CASTLING.key?(right) }
+      h ^= EP_FILE[Board::FILE_TO_INDEX[en_passant[0]]] if en_passant && !en_passant.empty?
+      h
+    end
+  end
+end

data/lib/pgn.rb

@@ -5,11 +5,13 @@ require 'pgn/move'
 require 'pgn/move_calculator'
 require 'pgn/lexer'
 require 'pgn/notation'
+require 'pgn/zobrist'
 require 'pgn/pgn_parser'
 require 'pgn/parser'
 require 'pgn/position'
 require 'pgn/serializer'
 require 'pgn/version'
+require 'pgn/bitboard'
 
 module PGN
   # @param pgn [String] a pgn representation of one or more chess games

data/pgn2.gemspec

@@ -1,3 +1,4 @@
+require 'English'
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'pgn/version'
@@ -10,27 +11,33 @@ Gem::Specification.new do |spec|
   spec.description   = 'A PGN parser and FEN generator for Ruby'
   spec.summary       = 'A PGN parser for Ruby'
   spec.homepage      = 'https://github.com/muriloime/pgn'
-  spec.license       = 'MIT'
+  spec.licenses      = ['MIT', 'MPL-2.0']
   spec.required_ruby_version = '>= 3.0'
 
   spec.metadata = {
-    'homepage_uri'      => 'https://github.com/muriloime/pgn',
-    'source_code_uri'   => 'https://github.com/muriloime/pgn',
-    'bug_tracker_uri'   => 'https://github.com/muriloime/pgn/issues',
-    'changelog_uri'     => 'https://github.com/muriloime/pgn/blob/main/CHANGELOG.md'
+    'homepage_uri' => 'https://github.com/muriloime/pgn',
+    'source_code_uri' => 'https://github.com/muriloime/pgn',
+    'bug_tracker_uri' => 'https://github.com/muriloime/pgn/issues',
+    'changelog_uri' => 'https://github.com/muriloime/pgn/blob/main/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true'
   }
 
-  spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
+  spec.extensions = ['ext/pgn2_native/extconf.rb']
+  spec.add_dependency 'rb_sys', '~> 0.9.39'
+  spec.add_development_dependency 'rake-compiler', '~> 1.2'
+  spec.add_development_dependency 'rake-compiler-dock', '~> 1.6'
+
+  spec.add_development_dependency 'benchmark-ips'
   spec.add_development_dependency 'bundler', '~> 2.3'
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'memory_profiler'
   spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'racc'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'racc'
-  spec.add_development_dependency 'benchmark-ips'
-  spec.add_development_dependency 'memory_profiler'
   spec.add_development_dependency 'rubocop', '~> 1.60'
 end

data/spec/bitboard_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+RSpec.describe PGN::Bitboard::Engine do
+  let(:startpos) { 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1' }
+
+  # The native extension is optional from the gem's perspective; skip the
+  # whole suite if it isn't compiled in this environment.
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  it 'perfts the start position' do
+    e = described_class.new(startpos)
+    expect(e.perft(1)).to eq(20)
+    expect(e.perft(2)).to eq(400)
+    expect(e.perft(3)).to eq(8902)
+    expect(e.perft(4)).to eq(197_281)
+  end
+
+  it 'perfts Kiwipete' do
+    e = described_class.new('r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1')
+    expect(e.perft(1)).to eq(48)
+    expect(e.perft(3)).to eq(97_862)
+  end
+
+  it 'raises on a bad FEN' do
+    expect { described_class.new('not a fen') }.to raise_error(ArgumentError)
+  end
+
+  it 'lists legal moves in sorted UCI' do
+    e = described_class.new(startpos)
+    moves = e.legal_moves
+    expect(moves.length).to eq(20)
+    expect(moves).to eq(moves.sort)
+    expect(moves).to include('e2e4', 'g1f3', 'd2d4')
+  end
+
+  it 'answers legal? with UCI' do
+    e = described_class.new(startpos)
+    expect(e.legal?('e2e4')).to be(true)
+    expect(e.legal?('e2e5')).to be(false)
+    expect(e.legal?('g1f3')).to be(true)
+  end
+
+  it 'encodes promotions in legal_moves' do
+    e = described_class.new('8/P7/8/8/8/8/8/4k2K w - - 0 1')
+    moves = e.legal_moves
+    expect(moves).to include('a7a8q', 'a7a8r', 'a7a8b', 'a7a8n')
+  end
+
+  it 'recognizes castling as legal' do
+    e = described_class.new('r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1')
+    expect(e.legal?('e1g1')).to be(true)
+    expect(e.legal?('e1c1')).to be(true)
+  end
+end

data/spec/board_spec.rb

@@ -7,6 +7,36 @@ describe PGN::Board do
     end
   end
 
+  describe 'attack masks' do
+    it 'KNIGHT_ATTACKS lists the on-board knight targets for each 0x88 index' do
+      expect(PGN::Board::KNIGHT_ATTACKS[0]).to contain_exactly(18, 33) # a1: c3(0x12), b3(0x21)
+      expect(PGN::Board::KNIGHT_ATTACKS[0x54].length).to eq(8) # e4 = 0x54, centre
+      expect(PGN::Board::KNIGHT_ATTACKS[0x77]).to contain_exactly(86, 101) # h8: f7(0x56), g6(0x65)
+    end
+
+    it 'KING_ATTACKS lists the on-board king targets for each 0x88 index' do
+      expect(PGN::Board::KING_ATTACKS[0]).to contain_exactly(1, 16, 17) # a1: b1, a2, b2
+      expect(PGN::Board::KING_ATTACKS[0x54].length).to eq(8)
+      expect(PGN::Board::KING_ATTACKS[0x77]).to contain_exactly(102, 103, 118) # h8: g7, h7, g8
+    end
+
+    it 'only contains on-board squares and is nil for off-board source indices' do
+      on_board = (0...128).select { |i| i.nobits?(0x88) }
+      expect(PGN::Board::KNIGHT_ATTACKS.length).to eq(128)
+      expect(PGN::Board::KING_ATTACKS.length).to eq(128)
+      on_board.each do |i|
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to be_an(Array)
+        expect(PGN::Board::KING_ATTACKS[i]).to be_an(Array)
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to all(satisfy { |sq| sq.nobits?(0x88) })
+        expect(PGN::Board::KING_ATTACKS[i]).to all(satisfy { |sq| sq.nobits?(0x88) })
+      end
+      (0...128).reject { |i| i.nobits?(0x88) }.each do |i|
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to be_nil
+        expect(PGN::Board::KING_ATTACKS[i]).to be_nil
+      end
+    end
+  end
+
   describe '#at' do
     # Use .dup because PGN::Board.start returns the same shared board
     # backed by the frozen START constant.
@@ -100,6 +130,29 @@ describe PGN::Board do
     end
   end
 
+  describe '#fen_board_string' do
+    it 'serializes the start position to the FEN board string' do
+      expect(PGN::Board.start.fen_board_string)
+        .to eq('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR')
+    end
+
+    it 'collapses runs of empty squares into digits' do
+      board = PGN::FEN.new('8/8/8/8/8/8/8/8 w - - 0 1').board
+      expect(board.fen_board_string).to eq('8/8/8/8/8/8/8/8')
+    end
+
+    it 'serializes a mid-game board byte-for-byte like FEN#board_string' do
+      fen = 'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6'
+      board = PGN::FEN.new(fen).board
+      expect(board.fen_board_string).to eq(fen.split.first)
+    end
+
+    it 'serializes rank 8 first and rank 1 last (FEN order)' do
+      board = PGN::FEN.new('4k3/8/8/8/8/8/8/4K3 w - - 0 1').board
+      expect(board.fen_board_string).to eq('4k3/8/8/8/8/8/8/4K3')
+    end
+  end
+
   describe '#inspect' do
     it 'returns a string with unicode pieces and newlines' do
       inspected = PGN::Board.start.inspect

data/spec/fen_spec.rb

@@ -1,120 +1,120 @@
-require "spec_helper"
+require 'spec_helper'
 
 describe PGN::FEN do
-  describe "castling availability" do
-    it "should remove all castling availabilitiy after castling" do
-      pos = PGN::FEN.new("rnbqk2r/1p3pbp/p2p1np1/2pP4/P3PB2/2N2N2/1P3PPP/R2QKB1R b KQkq e3 0 8").to_position
-      next_pos = pos.move("O-O")
+  describe 'castling availability' do
+    it 'should remove all castling availabilitiy after castling' do
+      pos = PGN::FEN.new('rnbqk2r/1p3pbp/p2p1np1/2pP4/P3PB2/2N2N2/1P3PPP/R2QKB1R b KQkq e3 0 8').to_position
+      next_pos = pos.move('O-O')
       next_pos.to_fen.castling.should_not match(/k|q/)
     end
 
-    it "should remove all castling availability after moving a king" do
-      pos = PGN::FEN.new("r1b1kb1r/pp2pppp/2n5/4P3/1nB5/P4N2/1P3PPP/RNBqK2R w KQkq - 0 9").to_position
-      next_pos = pos.move("Kxd1")
+    it 'should remove all castling availability after moving a king' do
+      pos = PGN::FEN.new('r1b1kb1r/pp2pppp/2n5/4P3/1nB5/P4N2/1P3PPP/RNBqK2R w KQkq - 0 9').to_position
+      next_pos = pos.move('Kxd1')
       next_pos.to_fen.castling.should_not match(/K|Q/)
     end
 
-    it "should remove only the one castling option after moving a rook" do
-      pos = PGN::FEN.new("r3k2r/1pp2pp1/p1pb1qn1/4p3/3PP1p1/8/PPPN1PPN/R1BQR1K1 b kq - 1 11").to_position
-      next_pos = pos.move("Rxh2")
+    it 'should remove only the one castling option after moving a rook' do
+      pos = PGN::FEN.new('r3k2r/1pp2pp1/p1pb1qn1/4p3/3PP1p1/8/PPPN1PPN/R1BQR1K1 b kq - 1 11').to_position
+      next_pos = pos.move('Rxh2')
       next_pos.to_fen.castling.should_not match(/k/)
       next_pos.to_fen.castling.should match(/q/)
     end
 
-    it "should remove one castling option when a rook is taken" do
-      pos = PGN::FEN.new("rn1qkbnr/pbpppppp/1p6/8/6P1/2N4P/PPPPPP2/R1BQKBNR b KQkq - 2 3").to_position
-      next_pos = pos.move("Bxh1")
+    it 'should remove one castling option when a rook is taken' do
+      pos = PGN::FEN.new('rn1qkbnr/pbpppppp/1p6/8/6P1/2N4P/PPPPPP2/R1BQKBNR b KQkq - 2 3').to_position
+      next_pos = pos.move('Bxh1')
       next_pos.to_fen.castling.should_not match(/K/)
     end
 
-    it "should change to a hyphen once no side can castle" do
-      pos = PGN::FEN.new("r1bq1rk1/pp1nbppp/3ppn2/8/2PP1N2/P1N5/1P2BPPP/R1BQK2R w KQ - 2 9").to_position
-      pos.to_fen.castling.should_not == "-"
-      next_pos = pos.move("O-O")
-      next_pos.to_fen.castling.should == "-"
+    it 'should change to a hyphen once no side can castle' do
+      pos = PGN::FEN.new('r1bq1rk1/pp1nbppp/3ppn2/8/2PP1N2/P1N5/1P2BPPP/R1BQK2R w KQ - 2 9').to_position
+      pos.to_fen.castling.should_not
+      next_pos = pos.move('O-O')
+      next_pos.to_fen.castling.should == '-'
     end
   end
 
-  describe "en passant" do
-    it "should display the en passant square whenever a pawn moves two spaces" do
-      pos = PGN::FEN.new("rnbqkb1r/pppppppp/5n2/8/8/5N2/PPPPPPPP/RNBQKB1R w KQkq - 2 1").to_position
-      next_pos = pos.move("c4")
-      next_pos.to_fen.en_passant.should == "c3"
+  describe 'en passant' do
+    it 'should display the en passant square whenever a pawn moves two spaces' do
+      pos = PGN::FEN.new('rnbqkb1r/pppppppp/5n2/8/8/5N2/PPPPPPPP/RNBQKB1R w KQkq - 2 1').to_position
+      next_pos = pos.move('c4')
+      next_pos.to_fen.en_passant.should == 'c3'
     end
 
-    it "should be a hyphen if no pawn moved two spaces the previous move" do
-      pos = PGN::FEN.new("rnbqkb1r/pppppppp/5n2/8/2P5/5N2/PP1PPPPP/RNBQKB1R b KQkq c3 0 1").to_position
-      next_pos = pos.move("d6")
-      next_pos.to_fen.en_passant.should == "-"
+    it 'should be a hyphen if no pawn moved two spaces the previous move' do
+      pos = PGN::FEN.new('rnbqkb1r/pppppppp/5n2/8/2P5/5N2/PP1PPPPP/RNBQKB1R b KQkq c3 0 1').to_position
+      next_pos = pos.move('d6')
+      next_pos.to_fen.en_passant.should == '-'
     end
   end
 
-  describe "halfmove counter" do
-    it "should reset after a pawn advance" do
-      pos = PGN::FEN.new("2b2rk1/2pp1ppp/1p6/r3P2q/3Q4/2P5/PP3PPP/RN3RK1 w - - 3 15").to_position
-      pos.to_fen.halfmove.should == "3"
-      next_pos = pos.move("f4")
-      next_pos.to_fen.halfmove.should == "0"
+  describe 'halfmove counter' do
+    it 'should reset after a pawn advance' do
+      pos = PGN::FEN.new('2b2rk1/2pp1ppp/1p6/r3P2q/3Q4/2P5/PP3PPP/RN3RK1 w - - 3 15').to_position
+      pos.to_fen.halfmove.should
+      next_pos = pos.move('f4')
+      next_pos.to_fen.halfmove.should == '0'
     end
 
-    it "should reset after a capture" do
-      pos = PGN::FEN.new("2r2rk1/1p2ppbp/1q1p1np1/pN4B1/Pnb1PP2/2N5/1PP1B1PP/R2Q1R1K w - - 5 14").to_position
-      pos.to_fen.halfmove.should == "5"
-      next_pos = pos.move("Bxc4")
-      next_pos.to_fen.halfmove.should == "0"
+    it 'should reset after a capture' do
+      pos = PGN::FEN.new('2r2rk1/1p2ppbp/1q1p1np1/pN4B1/Pnb1PP2/2N5/1PP1B1PP/R2Q1R1K w - - 5 14').to_position
+      pos.to_fen.halfmove.should
+      next_pos = pos.move('Bxc4')
+      next_pos.to_fen.halfmove.should == '0'
     end
 
-    it "should not reset otherwise" do
-      pos = PGN::FEN.new("2k2b1r/p4p1p/q1p2p2/8/2br4/5P2/PPQB2PP/R1N1K2R w KQ - 0 17").to_position
-      pos.to_fen.halfmove.should == "0"
-      moves = %w{Qf5+ Rd7 Bc3 Bh6 Qa5 Re8+ Kf2 Be3+ Kg3 Rg8+ Kh4}
+    it 'should not reset otherwise' do
+      pos = PGN::FEN.new('2k2b1r/p4p1p/q1p2p2/8/2br4/5P2/PPQB2PP/R1N1K2R w KQ - 0 17').to_position
+      pos.to_fen.halfmove.should
+      moves = %w[Qf5+ Rd7 Bc3 Bh6 Qa5 Re8+ Kf2 Be3+ Kg3 Rg8+ Kh4]
       moves.each_with_index do |move, i|
         pos = pos.move(move)
-        pos.to_fen.halfmove.should == (i+1).to_s
+        pos.to_fen.halfmove.should == (i + 1).to_s
       end
     end
   end
 
-  describe "fullmove counter" do
-    it "should not increase after white moves" do
-      pos = PGN::FEN.new("4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P2BP1N/R2QR1K1 w - - 3 25").to_position
-      pos.to_fen.fullmove.should == "25"
-      next_pos = pos.move("Qd2")
-      next_pos.to_fen.fullmove.should == "25"
+  describe 'fullmove counter' do
+    it 'should not increase after white moves' do
+      pos = PGN::FEN.new('4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P2BP1N/R2QR1K1 w - - 3 25').to_position
+      pos.to_fen.fullmove.should
+      next_pos = pos.move('Qd2')
+      next_pos.to_fen.fullmove.should == '25'
     end
 
-    it "should increase after black moves" do
-      pos = PGN::FEN.new("4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P1QBP1N/R3R1K1 b - - 4 25").to_position
-      pos.to_fen.fullmove.should == "25"
-      next_pos = pos.move("Kh7")
-      next_pos.to_fen.fullmove.should == "26"
+    it 'should increase after black moves' do
+      pos = PGN::FEN.new('4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P1QBP1N/R3R1K1 b - - 4 25').to_position
+      pos.to_fen.fullmove.should
+      next_pos = pos.move('Kh7')
+      next_pos.to_fen.fullmove.should == '26'
     end
   end
 
-  describe "displaying FEN notation" do
-    it "should return a string on inspect" do
+  describe 'displaying FEN notation' do
+    it 'should return a string on inspect' do
       fen = PGN::FEN.start
       fen.inspect.should be_a(String)
     end
   end
 
-  describe "board_string round-trip" do
+  describe 'board_string round-trip' do
     fens = [
       PGN::FEN::INITIAL,
-      "r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6",
-      "8/8/8/8/8/8/8/8 w - - 0 1",
-      "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1",
-      "4k3/4P3/8/8/8/8/8/4K3 w - - 0 1",
-      "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3",
+      'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6',
+      '8/8/8/8/8/8/8/8 w - - 0 1',
+      'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1',
+      '4k3/4P3/8/8/8/8/8/4K3 w - - 0 1',
+      'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3'
     ]
 
-    it "round-trips every fixture through FEN#to_s" do
+    it 'round-trips every fixture through FEN#to_s' do
       fens.each do |fen|
         expect(PGN::FEN.new(fen).to_s).to eq(fen), fen
       end
     end
 
-    it "round-trips the board portion through FEN#to_position.to_fen" do
+    it 'round-trips the board portion through FEN#to_position.to_fen' do
       fens.each do |fen|
         original  = PGN::FEN.new(fen)
         roundtrip = original.to_position.to_fen

data/spec/game_spec.rb

@@ -4,7 +4,11 @@ describe PGN::Game do
   describe '#positions' do
     it 'does not raise an error' do
       tags   = { 'White' => 'Deep Blue', 'Black' => 'Kasparov' }
-      moves  = %w[e4 c5 c3 d5 exd5 Qxd5 d4 Nf6 Nf3 Bg4 Be2 e6 h3 Bh5 O-O Nc6 Be3 cxd4 cxd4 Bb4 a3 Ba5 Nc3 Qd6 Nb5 Qe7 Ne5 Bxe2 Qxe2 O-O Rac1 Rac8 Bg5 Bb6 Bxf6 gxf6 Nc4 Rfd8 Nxb6 axb6 Rfd1 f5 Qe3 Qf6 d5 Rxd5 Rxd5 exd5 b3 Kh8 Qxb6 Rg8 Qc5 d4 Nd6 f4 Nxb7 Ne5 Qd5 f3 g3 Nd3 Rc7 Re8 Nd6 Re1+ Kh2 Nxf2 Nxf7+ Kg7 Ng5+ Kh6 Rxh7+]
+      moves  = %w[e4 c5 c3 d5 exd5 Qxd5 d4 Nf6 Nf3 Bg4 Be2 e6 h3 Bh5 O-O Nc6 Be3 cxd4
+                  cxd4 Bb4 a3 Ba5 Nc3 Qd6 Nb5 Qe7 Ne5 Bxe2 Qxe2 O-O Rac1 Rac8 Bg5 Bb6
+                  Bxf6 gxf6 Nc4 Rfd8 Nxb6 axb6 Rfd1 f5 Qe3 Qf6 d5 Rxd5 Rxd5 exd5 b3
+                  Kh8 Qxb6 Rg8 Qc5 d4 Nd6 f4 Nxb7 Ne5 Qd5 f3 g3 Nd3 Rc7 Re8 Nd6 Re1+
+                  Kh2 Nxf2 Nxf7+ Kg7 Ng5+ Kh6 Rxh7+]
       result = '1-0'
       game = PGN::Game.new(moves, tags, result)
       expect { game.positions }.not_to raise_error
@@ -19,6 +23,40 @@ describe PGN::Game do
     end
   end
 
+  describe '#each_position' do
+    it 'yields each position in order when given a block' do
+      game = PGN::Game.new(%w[e4 e5])
+      yielded = []
+      game.each_position { |p| yielded << p.to_fen.to_s }
+      expect(yielded).to eq(
+        [
+          PGN::Position.start.to_fen.to_s,
+          game.positions[1].to_fen.to_s,
+          game.positions[2].to_fen.to_s
+        ]
+      )
+    end
+
+    it 'returns an Enumerator when no block is given' do
+      game = PGN::Game.new(%w[e4 e5])
+      expect(game.each_position).to be_an(Enumerator)
+    end
+
+    it 'produces the same positions as #positions' do
+      game = PGN::Game.new(%w[e4 c5 Nf3])
+      expect(game.each_position.map { |p| p.to_fen.to_s })
+        .to eq(game.positions.map { |p| p.to_fen.to_s })
+    end
+
+    it 'does not materialize the full array when only the last is needed' do
+      moves = %w[e4 c5 Nf3 d6]
+      game  = PGN::Game.new(moves)
+      last = nil
+      game.each_position { |p| last = p }
+      expect(last.to_fen.to_s).to eq(game.positions.last.to_fen.to_s)
+    end
+  end
+
   describe '#to_pgn' do
     it 'returns a canonical PGN string ending with a newline' do
       game = PGN::Game.new(%w[e4 e5], { 'White' => 'A' }, '1-0')
@@ -34,20 +72,20 @@ describe PGN::Game do
     # *order* does not round-trip; only the set of variations does. We
     # therefore compare variations order-independently via a canonical
     # signature.
-    def move_signature(m)
-      c = m.comment.to_s
+    def move_signature(move)
+      c = move.comment.to_s
       # The current parser does not unescape \\, {, or }, so comments
       # containing those do not round-trip byte-for-byte (design spec v1
       # limitation). Treat them as a single sentinel so the set comparison
       # ignores the difference.
-      c = "<unescaped-comment>" if c.match?(/[\\{}]/)
-      vars = (m.variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort.join("\x03")
-      "#{m.notation}\x01#{(m.annotation || []).inspect}\x01#{c}\x01#{vars}"
+      c = '<unescaped-comment>' if c.match?(/[\\{}]/)
+      vars = (move.variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort.join("\x03")
+      "#{move.notation}\x01#{(move.annotation || []).inspect}\x01#{c}\x01#{vars}"
     end
 
     def expect_moves_equal(expected, actual, ctx)
       expect(actual.map(&:notation)).to eq(expected.map(&:notation)),
-        "#{ctx}: notation"
+                                        "#{ctx}: notation"
       expected.each_with_index do |e, i|
         expect(actual[i].annotation).to eq(e.annotation), "#{ctx}[#{i}]: annotation"
         # The current parser cannot unescape braces, so comments containing
@@ -55,11 +93,11 @@ describe PGN::Game do
         # limitation). Skip the comparison for those.
         unless e.comment.to_s.match?(/[\\{}]/)
           expect(actual[i].comment).to eq(e.comment),
-            "#{ctx}[#{i}]: comment #{e.comment.inspect} vs #{actual[i].comment.inspect}"
+                                       "#{ctx}[#{i}]: comment #{e.comment.inspect} vs #{actual[i].comment.inspect}"
         end
         # Variations compared as an order-independent set of signatures.
-        exp_sigs = (e.variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort
-        act_sigs = (actual[i].variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort
+        exp_sigs = (e.variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort
+        act_sigs = (actual[i].variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort
         expect(act_sigs).to eq(exp_sigs), "#{ctx}[#{i}]: variations"
       end
     end
@@ -67,17 +105,16 @@ describe PGN::Game do
     # Fixtures that do not round-trip byte-for-byte: doublequotes has
     # unescaped inner quotes (serializer escapes them) and specialcharacters
     # is multibyte and requires the Encoding::UTF_8 argument to parse.
-    NON_ROUND_TRIP = %w[doublequotes.pgn specialcharacters.pgn].freeze
-
     it 'round-trips every tracked fixture' do
+      non_round_trip = %w[doublequotes.pgn specialcharacters.pgn].freeze
       fixtures = `git ls-files spec/pgn_files/`.split.map { |p| File.expand_path(p) }
-      fixtures.reject! { |p| NON_ROUND_TRIP.include?(File.basename(p)) }
+      fixtures.reject! { |p| non_round_trip.include?(File.basename(p)) }
       fixtures.each do |path|
         PGN.parse(File.read(path)).each_with_index do |game, gi|
           reparsed = PGN.parse(game.to_pgn).first
 
           expect(reparsed.result).to eq(game.result),
-            "#{path}##{gi}: result"
+                                     "#{path}##{gi}: result"
           expect_moves_equal(game.moves, reparsed.moves, "#{path}##{gi}")
 
           # Reparsed tags must be a superset of the original (a no-tag game
@@ -86,7 +123,7 @@ describe PGN::Game do
           reparsed_tags = reparsed.tags || {}
           original_tags.each do |k, v|
             expect(reparsed_tags[k]).to eq(v),
-              "#{path}##{gi}: tag #{k} #{v.inspect} vs #{reparsed_tags[k].inspect}"
+                                        "#{path}##{gi}: tag #{k} #{v.inspect} vs #{reparsed_tags[k].inspect}"
           end
         end
       end