pgn2 0.4.0 → 1.0.0

data/spec/move_spec.rb

@@ -0,0 +1,136 @@
+require 'spec_helper'
+
+describe PGN::Move do
+  describe 'pawn pushes' do
+    it 'parses a white pawn push' do
+      m = PGN::Move.new('e4', :white)
+      expect(m.piece).to eq('P')
+      expect(m.destination).to eq('e4')
+      expect(m.capture).to eq(false)
+      expect(m.pawn?).to eq(true)
+      expect(m.white?).to eq(true)
+    end
+
+    it 'parses a black pawn push' do
+      m = PGN::Move.new('d5', :black)
+      expect(m.piece).to eq('p')
+      expect(m.destination).to eq('d5')
+      expect(m.pawn?).to eq(true)
+      expect(m.black?).to eq(true)
+    end
+  end
+
+  describe 'pawn captures' do
+    it 'parses a pawn capture, using the file as disambiguation' do
+      m = PGN::Move.new('exd5', :white)
+      expect(m.piece).to eq('P')
+      expect(m.capture).to eq(true)
+      expect(m.disambiguation).to eq('e')
+      expect(m.destination).to eq('d5')
+    end
+  end
+
+  describe 'piece moves' do
+    it 'parses knight, bishop, queen, king moves' do
+      expect(PGN::Move.new('Nf3', :white).piece).to eq('N')
+      expect(PGN::Move.new('Bc4', :white).piece).to eq('B')
+      expect(PGN::Move.new('Qd1', :white).piece).to eq('Q')
+      expect(PGN::Move.new('Ke2', :white).piece).to eq('K')
+    end
+
+    it 'parses black piece moves as lowercase' do
+      expect(PGN::Move.new('Nf6', :black).piece).to eq('n')
+      expect(PGN::Move.new('Qd8', :black).piece).to eq('q')
+    end
+
+    it 'is not a pawn for piece moves' do
+      expect(PGN::Move.new('Nf3', :white).pawn?).to eq(false)
+    end
+  end
+
+  describe 'disambiguation' do
+    it 'parses file disambiguation' do
+      m = PGN::Move.new('Nbd2', :white)
+      expect(m.piece).to eq('N')
+      expect(m.disambiguation).to eq('b')
+      expect(m.destination).to eq('d2')
+    end
+
+    it 'parses rank disambiguation' do
+      m = PGN::Move.new('N4c3', :white)
+      expect(m.disambiguation).to eq('4')
+      expect(m.destination).to eq('c3')
+    end
+
+    it 'parses a capturing disambiguated rook move' do
+      m = PGN::Move.new('Raxc1', :white)
+      expect(m.piece).to eq('R')
+      expect(m.disambiguation).to eq('a')
+      expect(m.capture).to eq(true)
+      expect(m.destination).to eq('c1')
+    end
+  end
+
+  describe 'promotion' do
+    it 'parses a white promotion' do
+      m = PGN::Move.new('e8=Q', :white)
+      expect(m.piece).to eq('P')
+      expect(m.destination).to eq('e8')
+      expect(m.promotion).to eq('Q')
+    end
+
+    it 'lowercases the promotion piece for black' do
+      m = PGN::Move.new('b8=Q', :black)
+      expect(m.promotion).to eq('q')
+    end
+
+    it 'parses a capturing promotion' do
+      m = PGN::Move.new('exd8=Q', :white)
+      expect(m.capture).to eq(true)
+      expect(m.disambiguation).to eq('e')
+      expect(m.destination).to eq('d8')
+      expect(m.promotion).to eq('Q')
+    end
+  end
+
+  describe 'check and mate' do
+    it 'parses a checking move' do
+      m = PGN::Move.new('g5+', :white)
+      expect(m.check).to eq('+')
+      expect(m.check?).to eq(true)
+      expect(m.checkmate?).to eq(false)
+    end
+
+    it 'parses a checkmate move' do
+      m = PGN::Move.new('Qe7#', :white)
+      expect(m.check).to eq('#')
+      expect(m.checkmate?).to eq(true)
+      expect(m.check?).to eq(false)
+    end
+  end
+
+  describe 'castling' do
+    it 'parses white kingside and queenside' do
+      expect(PGN::Move.new('O-O', :white).castle).to eq('K')
+      expect(PGN::Move.new('O-O-O', :white).castle).to eq('Q')
+    end
+
+    it 'parses black kingside and queenside (lowercase)' do
+      expect(PGN::Move.new('O-O', :black).castle).to eq('k')
+      expect(PGN::Move.new('O-O-O', :black).castle).to eq('q')
+    end
+
+    it 'has nil piece for castling moves' do
+      expect(PGN::Move.new('O-O', :white).piece).to be_nil
+    end
+  end
+
+  describe "the don't-care move" do
+    it 'parses -- as a no-op with no piece or destination' do
+      m = PGN::Move.new('--', :white)
+      expect(m.piece).to be_nil
+      expect(m.destination).to be_nil
+      expect(m.pawn?).to eq(false)
+    end
+  end
+end

data/spec/parser_explicit_spec.rb

@@ -0,0 +1,210 @@
+require 'spec_helper'
+require 'pgn'
+
+# Explicit, hardcoded expectations for the Racc + StringScanner parser.
+# These do not reference the legacy whittle parser and survive its removal;
+# they pin the public PGN.parse behavior on the features exercised by the
+# fixtures plus representative edge cases.
+RSpec.describe PGN, '.parse (racc parser)' do
+  def notations(moves)
+    moves.map(&:notation)
+  end
+
+  def variations_as(move)
+    (move.variations || []).map { |v| notations(v) }
+  end
+
+  describe 'results' do
+    it 'parses a 1-0 result' do
+      game = PGN.parse('[White "A"] 1. e4 e5 1-0').first
+      expect(game.result).to eq('1-0')
+    end
+
+    it 'parses a 0-1 result' do
+      game = PGN.parse('[White "A"] 1. e4 e5 0-1').first
+      expect(game.result).to eq('0-1')
+    end
+
+    it 'parses a 1/2-1/2 draw result' do
+      game = PGN.parse('[White "A"] 1. e4 e5 1/2-1/2').first
+      expect(game.result).to eq('1/2-1/2')
+    end
+
+    it 'parses a * (unknown) result' do
+      game = PGN.parse('[White "A"] 1. e4 e5 *').first
+      expect(game.result).to eq('*')
+    end
+
+    it 'parses a result-only (empty movetext) game' do
+      game = PGN.parse('[Event "?"] *').first
+      expect(game.result).to eq('*')
+      expect(game.moves).to be_empty
+    end
+  end
+
+  describe 'tags' do
+    it 'extracts tag values (stripping surrounding quotes)' do
+      game = PGN.parse(%([White "Kasparov"]\n[Black "Deep Blue"] 1. e4 1-0)).first
+      expect(game.tags['White']).to eq('Kasparov')
+      expect(game.tags['Black']).to eq('Deep Blue')
+    end
+
+    it 'keeps the first value on duplicate tag keys' do
+      game = PGN.parse(%([White "First"]\n[White "Second"] 1. e4 1-0)).first
+      expect(game.tags['White']).to eq('First')
+    end
+
+    it 'preserves unescaped double-quotes inside a tag value' do
+      game = PGN.parse(File.read('./spec/pgn_files/doublequotes.pgn')).first
+      expect(game.tags['Event']).to eq('IRT BLITZ "Sub Zonal"')
+    end
+
+    it 'honors the Encoding argument for multibyte tag values' do
+      text = File.read('./spec/pgn_files/specialcharacters.pgn')
+      games = PGN.parse(text, Encoding::UTF_8)
+      expect(games.first.tags['WhiteTeam']).to eq('NARIÑO')
+      expect(games.last.tags['Site']).to eq(
+        'HOTEL CAFEIRA Calle 18 Nro. 5 – 38 Centro de Pereira – Risaralda'
+      )
+    end
+  end
+
+  describe 'san moves' do
+    it 'parses pawn moves and captures' do
+      game = PGN.parse('[White "A"] 1. e4 d5 2. exd5 1-0').first
+      expect(notations(game.moves)).to eq(%w[e4 d5 exd5])
+    end
+
+    it 'parses promotion with check' do
+      game = PGN.parse('[White "A"] 1. e7 d8=Q+ 1-0').first
+      expect(game.moves[-1].notation).to eq('d8=Q+')
+    end
+
+    it 'parses check and checkmate' do
+      game = PGN.parse('[White "A"] 1. Qe7+ Qxe7 2. Qxf7# 1-0').first
+      expect(notations(game.moves)).to eq(%w[Qe7+ Qxe7 Qxf7#])
+    end
+
+    it 'parses castling (O-O and O-O-O)' do
+      game = PGN.parse('[White "A"] 1. O-O O-O-O 1-0').first
+      expect(notations(game.moves)).to eq(%w[O-O O-O-O])
+    end
+
+    it 'normalizes 0-form castling to O-form in move notation' do
+      game = PGN.parse(File.read('./spec/pgn_files/alternate_castling.pgn')).first
+      expect(game.moves.last.notation).to eq('O-O-O')
+    end
+
+    it 'parses major-piece moves with disambiguation' do
+      game = PGN.parse('[White "A"] 1. Nf3 Nc6 2. Nef6 Nef6 1-0').first
+      expect(notations(game.moves)).to eq(%w[Nf3 Nc6 Nef6 Nef6])
+    end
+
+    it 'parses the dont-care move (--) inside a variation' do
+      game = PGN.parse('[White "A"] 1. e4 (1. -- d5) e5 1-0').first
+      expect(variations_as(game.moves.first)).to eq([%w[-- d5]])
+    end
+  end
+
+  describe 'annotations' do
+    it 'parses numeric annotation glyphs' do
+      game = PGN.parse('[White "A"] 1. e4 e5 2. Nf3 $1 Nc6 1-0').first
+      expect(game.moves[2].annotation).to eq(['$1'])
+    end
+
+    it 'parses punctuation annotations (!?, ?!, !!, ??)' do
+      game = PGN.parse('[White "A"] 1. e4!? e5?! 2. Nf3 Nc6 1-0').first
+      expect(game.moves[0].annotation).to eq(['!?'])
+      expect(game.moves[1].annotation).to eq(['?!'])
+    end
+
+    it 'parses multiple annotations on one move' do
+      game = PGN.parse(File.read('./spec/pgn_files/two_annotations.pgn')).first
+      expect(game.moves[1].annotation).to eq(['$2', '$11'])
+    end
+  end
+
+  describe 'comments' do
+    it 'attaches a comment after a move and cleans whitespace' do
+      game = PGN.parse('[White "A"] 1. e4 { a  comment } e5 1-0').first
+      expect(game.moves[0].comment).to eq('a comment')
+    end
+
+    it 'parses a multiline comment and collapses whitespace' do
+      game = PGN.parse(File.read('./spec/pgn_files/multiline_comments.pgn')).first
+      expect(game.moves[5].comment).to eq('I pity the fool!')
+    end
+
+    it 'parses nested brace comments (lexer recurses inner braces)' do
+      game = PGN.parse(File.read('./spec/pgn_files/nested_comments.pgn')).first
+      # The lexer recurses and captures the full nested comment; the exact
+      # cleaned text is sensitive to the (pre-existing, shared with whittle)
+      # double-clean in Game#moves=, so assert stable substrings.
+      comment = game.moves[2].comment
+      expect(comment).to include('nested')
+      expect(comment).to include('comment')
+    end
+
+    it 'captures a standalone comment as the game comment (with braces)' do
+      game = PGN.parse(File.read('./spec/pgn_files/no_moves.pgn')).last
+      expect(game.comment).to eq('{game comment}')
+    end
+  end
+
+  describe 'variations' do
+    it 'parses a single variation attached to a move' do
+      game = PGN.parse('[White "A"] 1. e4 (1. d4 d5) e5 1-0').first
+      expect(variations_as(game.moves.first)).to eq([%w[d4 d5]])
+    end
+
+    it 'parses a nested variation' do
+      game = PGN.parse('[White "A"] 1. e4 (1. d4 (1... d5) dxc4) e5 1-0').first
+      outer = game.moves.first.variations.first
+      expect(notations(outer)).to eq(%w[d4 dxc4])
+      expect(variations_as(outer[0])).to eq([%w[d5]])
+    end
+
+    it 'compares multiple variations as an order-independent set' do
+      game = PGN.parse('[White "A"] 1. e4 (1. d4) (1. Nf3) e5 1-0').first
+      expect(variations_as(game.moves.first).sort).to eq([%w[d4], %w[Nf3]].sort)
+    end
+
+    it 'parses a variation that itself contains an empty move' do
+      game = PGN.parse(File.read('./spec/pgn_files/empty_variation_move.pgn')).first
+      expect(game.result).to eq('*')
+      expect(game.moves.last.notation).to eq('Ng5')
+    end
+  end
+
+  describe 'pgn (verbatim raw text)' do
+    it 'returns the verbatim text for a single game' do
+      input = "[White \"A\"] 1. e4 1-0\n"
+      expect(PGN.parse(input).first.pgn).to eq(input)
+    end
+
+    it 'partitions consecutive games contiguously' do
+      input = "[White \"A\"] 1. e4 1-0\n\n[White \"B\"] 1. d4 0-1\n"
+      games = PGN.parse(input)
+      expect(games.map(&:pgn)).to eq(["[White \"A\"] 1. e4 1-0\n\n", "[White \"B\"] 1. d4 0-1\n"])
+    end
+
+    it 'includes a leading percent comment in the first game pgn' do
+      input = "% header\n[White \"A\"] 1. e4 *\n"
+      expect(PGN.parse(input).first.pgn).to eq(input)
+    end
+  end
+
+  describe 'multiple games' do
+    it 'returns games in source order' do
+      games = PGN.parse("[White \"One\"] 1. e4 1-0\n\n[White \"Two\"] 1. d4 0-1")
+      expect(games.map { |g| g.tags['White'] }).to eq(%w[One Two])
+    end
+  end
+
+  describe 'starting position (FEN tag)' do
+    it 'uses the FEN tag for positions' do
+      game = PGN.parse(File.read('./spec/pgn_files/fen.pgn')).first
+      expect(game.positions.first.to_fen.to_s).to eq(game.tags['FEN'])
+    end
+  end
+end

data/spec/parser_spec.rb

@@ -139,5 +139,20 @@ describe PGN do
       game = games.last
       expect(game.comment).to eq('{game comment}')
     end
+
+    it 'tag_values with double quotes' do
+      games = PGN.parse(File.read('./spec/pgn_files/doublequotes.pgn'))
+      game = games.last
+      expect(game.tags['Event']).to eq('IRT BLITZ "Sub Zonal"')
+    end
+
+    it 'set encoding' do
+      file = File.read('./spec/pgn_files/specialcharacters.pgn')
+      games = PGN.parse(file, Encoding::UTF_8)
+      game1 = games.first
+      game2 = games.last
+      expect(game1.tags['WhiteTeam']).to eq('NARIÑO')
+      expect(game2.tags['Site']).to eq('HOTEL CAFEIRA Calle 18 Nro. 5 – 38 Centro de Pereira – Risaralda')
+    end
   end
 end

data/spec/pgn_files/doublequotes.pgn

@@ -0,0 +1,21 @@
+[Event "IRT BLITZ "Sub Zonal""]
+[Site "HOTEL CAFEIRA Calle 18 Nro. 5 - 38 Centro de Pereira Risaralda"]
+[Date "2021.11.27"]
+[Round "5"]
+[Board "2"]
+[White "Estrada Velandia, Henry Andres"]
+[Black "Vargas Arteaga, Alexis"]
+[Result "0-1"]
+[ECO "D00"]
+[WhiteElo "2055"]
+[BlackElo "2343"]
+[PlyCount "64"]
+[EventDate "2021.11.27"]
+[EventRounds "18"]
+[EventCountry "COL"]
+
+1. d4 Nf6 2. c3 d5 3. e3 c5 4. Bd3 Nc6 5. f4 e6 6. Nf3 Bd6 7. O-O O-O 8. Bd2 b6
+9. Be1 Ne7 10. Ne5 Nf5 11. Bxf5 exf5 12. Bh4 Be6 13. Nd2 Rc8 14. Qf3 Be7 15.
+Bxf6 Bxf6 16. Kh1 g6 17. Rg1 b5 18. g4 b4 19. gxf5 Bxf5 20. Raf1 Bg7 21. Rg5
+bxc3 22. bxc3 cxd4 23. Rxf5 dxc3 24. Nxf7 Qd7 25. Rxd5 Qxf7 26. Nb3 c2 27. Rc1
+Bb2 28. Rg1 c1=Q 29. Nxc1 Rxc1 30. Rxc1 Bxc1 31. h4 Bxe3 32. f5 Bh6  0-1

data/spec/pgn_files/specialcharacters.pgn

@@ -0,0 +1,79 @@
+[Event "XXI Juegos Deportivos Nacionales AJEDREZ RAPIDO Absoluto por Equipos 2019"]
+[Site "Cartagena (Bolivar-Colombia) Centro Amurallado, Palacio de la Proclamación"]
+[Date "2019.11.29"]
+[Round "1"]
+[Board "1"]
+[White "Pai, Juan David"]
+[Black "Vargas Arteaga, Alexis"]
+[Result "0-1"]
+[ECO ""]
+[WhiteElo "2008"]
+[BlackElo "2339"]
+[PlyCount "0"]
+[EventDate "2019.11.29"]
+[EventType "team"]
+[EventRounds "7"]
+[EventCountry "COL"]
+[WhiteTeam "NARIÑO"]
+[BlackTeam "SANTANDER"]
+
+1. d4 {[%clk 00:15:18]} {[%emt 00:00:02]} Nf6 {[%clk 00:15:17]} {[%emt
+00:00:03]} 2. Nf3 {[%clk 00:15:12]} {[%emt 00:00:16]} e6 {[%clk 00:15:25]}
+{[%emt 00:00:01]} 3. c4 {[%clk 00:15:19]} {[%emt 00:00:03]} b6 {[%clk
+00:15:30]} {[%emt 00:00:05]} 4. g3 {[%clk 00:15:28]} {[%emt 00:00:02]} Ba6
+{[%clk 00:15:37]} {[%emt 00:00:02]} 5. b3 {[%clk 00:15:37]} {[%emt 00:00:02]}
+b5 {[%clk 00:15:46]} {[%emt 00:00:01]} 6. Bg2 {[%clk 00:15:36]} {[%emt
+00:00:12]} bxc4 {[%clk 00:15:54]} {[%emt 00:00:01]} 7. Ne5 {[%clk 00:15:45]}
+Bb4+ {[%clk 00:16:03]} {[%emt 00:00:01]} 8. Bd2 {[%clk 00:15:54]} cxb3 {[%clk
+00:16:12]} {[%emt 00:00:01]} 9. axb3 {[%clk 00:15:53]} {[%emt 00:00:11]} Bxd2+
+{[%clk 00:16:18]} {[%emt 00:00:04]} 10. Qxd2 {[%clk 00:14:36]} {[%emt
+00:01:27]} d5 {[%clk 00:16:27]} 11. O-O {[%clk 00:13:50]} {[%emt 00:00:57]} O-O
+{[%clk 00:16:34]} {[%emt 00:00:03]} 12. Rc1 {[%clk 00:13:49]} {[%emt 00:00:11]}
+Nfd7 {[%clk 00:16:15]} {[%emt 00:00:28]} 13. Nc6 {[%clk 00:11:27]} {[%emt
+00:02:32]} Nxc6 {[%clk 00:16:23]} {[%emt 00:00:02]} 14. Rxa6 {[%clk 00:11:26]}
+{[%emt 00:00:11]} Ncb8 {[%clk 00:16:06]} {[%emt 00:00:27]} 15. Ra5 {[%clk
+00:11:12]} {[%emt 00:00:24]} a6 {[%clk 00:16:13]} {[%emt 00:00:02]} 16. Qb4
+{[%clk 00:10:47]} {[%emt 00:00:36]} Ra7 {[%clk 00:16:17]} {[%emt 00:00:05]} 17.
+Nc3 {[%clk 00:10:51]} {[%emt 00:00:07]} Nc6 {[%clk 00:16:15]} {[%emt 00:00:12]}
+18. Qa4 {[%clk 00:10:45]} {[%emt 00:00:17]} Nxa5 {[%clk 00:16:23]} {[%emt
+00:00:01]} 19. Qxa5 {[%clk 00:10:54]} {[%emt 00:00:01]} c5 {[%clk 00:16:22]}
+{[%emt 00:00:11]} 20. Qxd8 {[%clk 00:10:27]} {[%emt 00:00:37]} Rxd8 {[%clk
+00:16:30]} {[%emt 00:00:01]} 21. dxc5 {[%clk 00:10:36]} {[%emt 00:00:02]} Nxc5
+{[%clk 00:16:23]} {[%emt 00:00:16]} 22. Nxd5 {[%clk 00:10:36]} {[%emt
+00:00:12]} Nxb3 {[%clk 00:15:29]} {[%emt 00:01:03]} 23. Rc3 {[%clk 00:10:33]}
+{[%emt 00:00:13]} Nd4 {[%clk 00:15:23]} {[%emt 00:00:16]} 24. Nf4 {[%clk
+00:10:30]} {[%emt 00:00:13]} g5 {[%clk 00:15:21]} {[%emt 00:00:12]} 25. e3
+{[%clk 00:10:25]} {[%emt 00:00:16]} gxf4 {[%clk 00:15:28]} {[%emt 00:00:02]} 26.
+exd4 {[%clk 00:10:34]} {[%emt 00:00:02]} Rxd4 {[%clk 00:15:36]} {[%emt
+00:00:01]} 27. gxf4 {[%clk 00:10:36]} {[%emt 00:00:08]} Rxf4 {[%clk 00:15:42]}
+{[%emt 00:00:04]} 28. Rg3+ {[%clk 00:09:57]} {[%emt 00:00:48]} Kf8 {[%clk
+00:15:49]} {[%emt 00:00:03]} 29. Rh3 {[%clk 00:10:06]} {[%emt 00:00:02]} f6
+{[%clk 00:15:51]} {[%emt 00:00:07]} 30. Ra3 {[%clk 00:10:07]} {[%emt 00:00:10]}
+a5 {[%clk 00:15:45]} {[%emt 00:00:16]} 31. Bc6 {[%clk 00:10:15]} {[%emt
+00:00:01]} Ke7 {[%clk 00:15:43]} {[%emt 00:00:13]} 32. Rd3 {[%clk 00:10:23]}
+{[%emt 00:00:02]} Rc7 {[%clk 00:15:42]} {[%emt 00:00:10]} 33. Ba4 {[%clk
+00:10:12]} {[%emt 00:00:22]} Rxa4 {[%clk 00:15:49]} {[%emt 00:00:03]}  0-1
+
+[Event "Subzonal 2.3.4 Absoluto COLOMBIA"]
+[Site "HOTEL CAFEIRA Calle 18 Nro. 5 – 38 Centro de Pereira – Risaralda"]
+[Date "2021.11.23"]
+[Round "1"]
+[Board "7"]
+[White "Vargas Arteaga, Alexis"]
+[Black "Murillo Loreo, Oscar Miguel"]
+[Result "1-0"]
+[ECO "B37"]
+[WhiteElo "2277"]
+[BlackElo "1775"]
+[PlyCount "83"]
+[EventDate "2021.11.23"]
+[EventRounds "9"]
+[EventCountry "COL"]
+
+1. e4 c5 2. Nf3 Nc6 3. d4 cxd4 4. Nxd4 g6 5. c4 Bg7 6. Nc2 Nf6 7. Nc3 d6 8. Be2
+O-O 9. O-O Nd7 10. Re1 Nc5 11. Bf1 Be6 12. Nd5 h6 13. Rb1 a5 14. b3 Kh7 15. Bb2
+Bxb2 16. Rxb2 f5 17. exf5 Bxf5 18. Nd4 e5 19. Nb5 e4 20. Ne3 Ne5 21. Rd2 Ncd3
+22. Bxd3 Nxd3 23. Nxf5 gxf5 24. Rxd3 exd3 25. Qxd3 Qf6 26. Qd5 Rae8 27. Rd1 Qe5
+28. g3 Qxd5 29. Rxd5 f4 30. Kf1 f3 31. Rd2 Rf4 32. Nd4 a4 33. Rd3 axb3 34. axb3
+Ref8 35. Re3 R8f7 36. h3 h5 37. h4 Kg6 38. Ne6 Kf5 39. Ng5 Rf8 40. Nh7 Kg4 41.
+Re4 Kh3 42. Kg1  1-0

data/spec/position_spec.rb

@@ -52,3 +52,76 @@ describe PGN::Position do
     end
   end
 end
+
+# New exhaustive coverage below. Existing `should` examples above are
+# intentionally left untouched.
+
+describe PGN::Position do
+  describe '.start attributes' do
+    it 'has the expected starting state' do
+      pos = PGN::Position.start
+      expect(pos.player).to eq(:white)
+      expect(pos.castling).to eq(%w[K Q k q])
+      expect(pos.en_passant).to be_nil
+      expect(pos.halfmove).to eq(0)
+      expect(pos.fullmove).to eq(1)
+    end
+  end
+
+  describe '#next_player' do
+    it 'toggles white to black and back' do
+      expect(PGN::Position.start.next_player).to eq(:black)
+      expect(PGN::Position.start.move('e4').next_player).to eq(:white)
+    end
+  end
+
+  describe '#move' do
+    it 'returns a new PGN::Position and does not mutate the source' do
+      pos = PGN::Position.start
+      nxt = pos.move('e4')
+      expect(nxt).to be_a(PGN::Position)
+      expect(nxt).not_to be(pos)
+      expect(pos.board.at('e4')).to be_nil
+      expect(pos.player).to eq(:white)
+    end
+
+    it 'toggles the player to move' do
+      expect(PGN::Position.start.move('e4').player).to eq(:black)
+      expect(PGN::Position.start.move('e4').move('e5').player).to eq(:white)
+    end
+
+    it 'updates state after 1.e4' do
+      nxt = PGN::Position.start.move('e4')
+      expect(nxt.en_passant).to eq('e3')
+      expect(nxt.halfmove).to eq(0)
+      expect(nxt.fullmove).to eq(1)
+      expect(nxt.board.at('e4')).to eq('P')
+      expect(nxt.board.at('e2')).to be_nil
+    end
+
+    it 'updates state after 1.e4 e5' do
+      nxt = PGN::Position.start.move('e4').move('e5')
+      expect(nxt.player).to eq(:white)
+      expect(nxt.en_passant).to eq('e6')
+      expect(nxt.fullmove).to eq(2)
+    end
+
+    it 'propagates castling restrictions' do
+      fen = 'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1'
+      nxt = PGN::FEN.new(fen).to_position.move('O-O')
+      expect(nxt.castling.sort).to eq(%w[k q])
+    end
+  end
+
+  describe '#to_fen' do
+    it 'round-trips the start position to FEN::INITIAL' do
+      expect(PGN::Position.start.to_fen.to_s).to eq(PGN::FEN::INITIAL)
+    end
+
+    it 'round-trips an arbitrary position through FEN' do
+      fen = 'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6'
+      parsed = PGN::FEN.new(fen).to_position
+      expect(parsed.to_fen.to_s).to eq(fen)
+    end
+  end
+end

data/spec/serializer_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe PGN::Serializer do
+  describe '#to_s' do
+    it 'serializes a simple game with tags and result' do
+      game = PGN::Game.new(%w[e4 e5], { 'White' => 'A', 'Black' => 'B' }, '1-0')
+      expected = "[White \"A\"]\n[Black \"B\"]\n\n1. e4 e5 1-0\n"
+      expect(PGN::Serializer.new(game).to_s).to eq(expected)
+    end
+
+    it 'synthesizes a Result tag when there are no tags' do
+      game = PGN::Game.new(%w[e4 e5])
+      expected = "[Result \"*\"]\n\n1. e4 e5 *\n"
+      expect(PGN::Serializer.new(game).to_s).to eq(expected)
+    end
+
+    it 'serializes an empty game as just the result' do
+      game = PGN::Game.new([], nil, '*')
+      expected = "[Result \"*\"]\n\n*\n"
+      expect(PGN::Serializer.new(game).to_s).to eq(expected)
+    end
+
+    it 'emits * when there is no result' do
+      game = PGN::Game.new(%w[e4 e5], { 'White' => 'A' })
+      expect(PGN::Serializer.new(game).to_s).to end_with("1. e4 e5 *\n")
+    end
+
+    it 'escapes backslashes and quotes in tag values' do
+      game = PGN::Game.new(%w[e4], { 'White' => 'A "B" \\C' }, '1-0')
+      expect(PGN::Serializer.new(game).to_s).to start_with("[White \"A \\\"B\\\" \\\\C\"]\n")
+    end
+
+    it 'serializes castling as O-O / O-O-O' do
+      game = PGN::Game.new(%w[O-O O-O-O])
+      expect(PGN::Serializer.new(game).to_s).to eq("[Result \"*\"]\n\n1. O-O O-O-O *\n")
+    end
+
+    it 'emits a single annotation after the notation' do
+      moves = [PGN::MoveText.new('e4', ['$4'])]
+      game = PGN::Game.new(moves, { 'White' => 'A' }, '1-0')
+      expect(PGN::Serializer.new(game).to_s).to eq("[White \"A\"]\n\n1. e4 $4 1-0\n")
+    end
+
+    it 'emits symbolic annotations verbatim' do
+      moves = [PGN::MoveText.new('e4', ['??'])]
+      game = PGN::Game.new(moves, { 'White' => 'A' }, '1-0')
+      expect(PGN::Serializer.new(game).to_s).to eq("[White \"A\"]\n\n1. e4 ?? 1-0\n")
+    end
+
+    it 'emits multiple annotations in order' do
+      moves = [PGN::MoveText.new('d4'), PGN::MoveText.new('d5', ['$2', '$11'])]
+      game = PGN::Game.new(moves, { 'White' => 'A' }, '1/2-1/2')
+      expect(PGN::Serializer.new(game).to_s).to eq("[White \"A\"]\n\n1. d4 d5 $2 $11 1/2-1/2\n")
+    end
+
+    it 'wraps move comments in braces with spaces' do
+      moves = [PGN::MoveText.new('e4', nil, 'good move')]
+      game = PGN::Game.new(moves, { 'White' => 'A' }, '1-0')
+      expect(PGN::Serializer.new(game).to_s).to eq("[White \"A\"]\n\n1. e4 { good move } 1-0\n")
+    end
+
+    it 'reproduces the variations.pgn movetext shape, including 2... after variations' do
+      game = PGN.parse(File.read('./spec/pgn_files/variations.pgn')).first
+      expected = "[Black \"Petrov\"]\n[White \"Somebody\"]\n\n" \
+                "1. e4 e5 2. Nf3 { comment } " \
+                "(2. f4 exf4 { final variation }) " \
+                "(2. Nc3 { other } 2... d5 (2... f5) 3. exd5) " \
+                "2... Nf6 *\n"
+      expect(PGN::Serializer.new(game).to_s).to eq(expected)
+    end
+
+    it 'emits a game comment as the first movetext token' do
+      game = PGN::Game.new([], nil, '*', nil, 'game comment')
+      expect(PGN::Serializer.new(game).to_s).to eq("[Result \"*\"]\n\n{ game comment } *\n")
+    end
+
+    it 'numbers the first move 1... when starting from a FEN with black to move' do
+      fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR b KQkq - 0 1'
+      game = PGN::Game.new(%w[e5], { 'FEN' => fen }, '*')
+      expected = "[FEN \"#{fen}\"]\n\n1... e5 *\n"
+      expect(PGN::Serializer.new(game).to_s).to eq(expected)
+    end
+
+    it 'serializes -- moves verbatim and alternates color/fullmove' do
+      game = PGN::Game.new(%w[-- e4])
+      expect(PGN::Serializer.new(game).to_s).to eq("[Result \"*\"]\n\n1. -- e4 *\n")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -7,7 +7,6 @@ require 'pgn'
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
-  config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true
   config.filter_run :focus