bangkok 0.1.0

data/ChangeLog

@@ -0,0 +1,5 @@
+2005-03-24  Jim Menard  <jimm@io.com>
+
+	* Initial project creation.
+
+

data/Credits

@@ -0,0 +1,6 @@
+Bangkok is developed by Jim Menard <jimm@io.com> and originated from ideas and
+conversations with Tom Peak <himself@tompeak.com>.
+
+Additional bug fixes and suggestions have come from:
+
+[nobody yet, since this is the first release.]

data/README

@@ -0,0 +1,227 @@
+= Bangkok
+
+Bangkok reads chess game descriptions and re-play the games. Notice of events
+(moves, captures, checks, etc.) are sent to a listener. Bangkok comes with a
+listener that generates a MIDI file. In other words, the chess game is turned
+into music.
+
+Bangkok originated as the code for an art project by Tom Peak
+<himself@tompeak.com>.
+
+The Web site of Bangkok is (http://bangkok.rubyforge.org). The RubyForge
+project page is http://rubyforge.org/projects/bangkok, where the latest
+version of bangkok may be downloaded. bangkok is also available as a RubyGem.
+
+
+=== Recent Changes
+
+Since this is the first release, there's nothing to say.
+
+
+== Dependencies
+
+The MIDI generation portion of Bangkok requires midilib 0.8.4 or later. If you
+install Bangkok as a RubyGem, it will fetch and install midilib for you.
+
+The test suite in the tests directory requires the testing framework TestUnit,
+which comes with Ruby 1.8 and later and can also be found in the Ruby
+Application Archive (http://raa.ruby-lang.org).
+
+To rebuild the gem or RDocs or run the tests easily, you can use the Rakefile
+which requires Rake (http://rake.rubyforge.org).
+
+
+== Installation
+
+=== RubyGems Installation
+
+To install Bangkok as a gem, type
+
+    % gem install bangkok
+
+You may need root privileges to install the gem.
+
+=== Manual Installation
+
+After downloading and expanding the archive, you can install Bangkok with the
+command
+
+    % ruby install.rb
+(or)
+    % ruby install.rb --install-dir=my_directory
+
+You may need root privileges to install Bangkok.
+
+
+== Testing
+
+  % rake test
+
+runs all of the tests in the test directory.
+
+
+== Overview
+
+Bangkok replays a chess game. It reads chess game .pgn files. Interesting
+events during each game (moves, captures, checks, etc.) are sent to a
+listener.
+
+Bangkok comes with a GameListener that creates a MIDI sequence. The listener
+is given to a ChessGame object, which then reads a .pgn file, creates a board,
+gives the moves to the board so it can move the pieces, and tells the listener
+when the game is over. At that time, the GameListener writes the MIDI sequence
+out to a MIDI file.
+
+
+== How to Use
+
+=== From the command line
+
+Here is how to generate a MIDI file from a chess match file, using the
+built-in GameListener. (This command line is awkward, and needs to get
+simpler.)
+
+    % bangkok [-c my_program_changes.rb] chess_game_file.pgn
+
+Running that command creates the MIDI file chess_game_file.mid. The optional
+configuration file my_program_changes.rb lets you change the default program
+numbers used for each of the pieces. See examples/program_changes.rb for an
+example file.
+
+For example, to run bangkok on the chess game in the examples directory, type
+
+    % bangkok examples/game.pgn
+
+=== Example Scripts and Files
+
+Here are short descriptions of each of the files found in the examples
+directory.
+
+* examples/announcer.rb creates a new listener that "announces" the game by
+  printing some descriptive text for everything that happens during the game.
+
+* examples/game.pgn is an example chess match.
+
+* examples/program_changes.rb is an example configuration file that shows you
+  how to change the default program change values. The values in this file are
+  the same as the default values used by GameListener.
+
+
+== The Code
+
+Only one class has anything to do with MIDI at all: GameListener. The rest of
+the classes in Bangkok know only about chess moves. This separation allows you
+to use Bangkok for your own nefarious chess-related purposes, whether musical
+or un-.
+
+GameListener creates a MIDI sequence from the chess game's moves. When a piece
+moves, MIDI notes are generated and a few controller values are set. Any
+listener you write must implement the methods
+* start_game(io)
+* end_game
+* move(piece, from_square, to_square)
+* capture(attacker_piece, loser_piece)
+* check
+* checkmate
+* pawn_to_queen(pawn)
+
+For each move, the GameListener generates three sets of MIDI events: one for
+the move start, one for a point halfway between the start and the destination,
+and one for the destination. GameListener#midi_for_position creates a pan
+value (left = queenside, right = kingside), a volume value (max = center of
+board, min = top and bottom of board), and a quarter note. The note is from a
+C scale, where the low C = the color's home rank and the high C = the opposite
+color's home rank.
+
+  SPEAKER    midi 1 - 8    SPEAKER (black)
+
+     low
+      ^
+      |
+     high
+    volume
+      |
+      v
+     low
+
+      <---- panning ---->
+
+  SPEAKER    midi 9 - 16    SPEAKER (white)
+
+ChessGame takes a listener in its constructor and creates a Board. The method
+ChessGame#read_moves reads game data. Calling ChessGame#play moves the pieces,
+which in turn sends messages to the listener so it can react. See bin/bangkok
+and examples/announcer.rb for examples of how to use a ChessGame object.
+
+Board creates pieces and hands moves to pieces. It tells the listener about
+things like captures and castles.
+
+A Square represents a location on a Board.
+
+A Piece has a color and a Square. It tells the listener about its moves.
+Subclasses of Piece such as Queen and Knight override
+Piece#could_perform_move, which checks to see if that piece could move from
+its current position to the move's destination square. could_perform_move is
+called by the Board to determine which piece on the board needs to be moved.
+
+A Move has a color, a destination square, an optional starting rank or file,
+and optional modifiers such as check or capture. A castle Move has no
+destination square (the Board moves the pieces).
+
+
+== Resources
+
+The Ruby Web site (http://www.ruby-lang.org/en/index.html) contains an
+introduction to Ruby, the Ruby Application Archive (RAA) at
+http://raa.ruby-lang.org, and pointers to more information.
+
+
+_Programming Ruby, The Pragmatic Programmer's Guide_, by David Thomas
+and Andrew Hunt, is a well-written and practical introduction to Ruby. Its Web
+page at http://www.rubycentral.com/book also contains a wealth of Ruby
+information. Though the book is available online, I encourage you to purchase
+a copy of the second edition, available at
+http://pragmaticprogrammer.com/titles/ruby/.
+
+midilib's home is http://midilib.rubyforge.org.
+
+
+= To Do
+
+:include: TODO
+
+
+= Support
+
+* Visit the forums, bug list, and mailing list pages at
+  http://rubyforge.org/projects/bangkok
+
+* Send email to Jim Menard at mailto:jimm@io.com
+
+* Ask on the ruby-talk mailing list
+
+
+= Administrivia
+
+Author:: Jim Menard (mailto:jimm@io.com)
+Copyright:: Copyright (c) 2005 Jim Menard
+License:: Distributed under the same license as Ruby.
+
+
+== Copying
+
+Bangkok is copyrighted free software by Jim Menard and is released under the
+same license as Ruby. See the Ruby license at
+http://www.ruby-lang.org/en/LICENSE.txt.
+
+Bangkok may be freely copied in its entirety providing this notice, all
+source code, all documentation, and all other files are included.
+
+Bangkok is Copyright (c) 2005 by Jim Menard.
+
+
+== Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantability and fitness for a particular purpose.

data/Rakefile

@@ -0,0 +1,83 @@
+require 'rubygems'
+require_gem 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/runtest'
+
+PROJECT_NAME = 'bangkok'
+RUBYFORGE_USER = 'jimm'
+RDOC_DIR = 'html'
+
+PKG_FILES = FileList[ 'ChangeLog', 'Credits', 'README', 'Rakefile', 'TODO',
+                     'examples/**/*',
+                     'html/**/*',
+                     'install.rb',
+                     'lib/**/*.rb',
+                     'test/**/*.rb']
+
+task :default => [:package]
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = PROJECT_NAME
+  s.version = `ruby -Ilib -e 'require "bangkok/info"; puts Version'`.strip
+  s.requirements << 'midilib'
+  s.add_dependency('midilib', '>= 0.8.4')
+
+  s.require_path = 'lib'
+  s.autorequire = PROJECT_NAME
+
+  s.files = PKG_FILES.to_a
+  s.executables = ['bangkok']
+  s.bindir = 'bin'
+
+  s.has_rdoc = true
+  s.rdoc_options << '--main' << 'README'
+  s.extra_rdoc_files = ['README', 'TODO']
+
+  s.author = 'Jim Menard'
+  s.email = 'jimm@io.com'
+  s.homepage = 'http://bangkok.rubyforge.org'
+  s.rubyforge_project = PROJECT_NAME
+
+  s.summary = "Chess game file reader and player; can turn games into MIDI files"
+  s.description = <<EOF
+Bangkok can read chess game descriptions and re-play the games. Notice of
+events (moves, captures, checks, etc.) are sent to a listener. Bangkok comes
+with a listener that generates a MIDI file. In other words, the chess game is
+turned into music.
+EOF
+end
+
+# Creates a :package task (also named :gem). Also useful are :clobber_package
+# and :repackage.
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+# require 'rbconfig'
+# if Config::CONFIG['target_os'] =~ /mswin/i
+#   RDOC_FILES = FileList['README', 'TODO', 'lib/**/*.rb']
+#   RDOC_FILES.each { | f | file f }
+#   task :rdoc => RDOC_FILES do
+#     ruby "#{File.join(Config::CONFIG['bindir'], 'rdoc')} -o html " +
+#       " --main 'README' --title '#{PROJECT_NAME}' -T 'html' #{RDOC_FILES}"
+#   end
+# else
+  # creates an "rdoc" task
+  Rake::RDocTask.new do | rd |
+    rd.main = 'README'
+    rd.title = PROJECT_NAME
+    rd.rdoc_files.include('README', 'TODO', 'lib/**/*.rb')
+  end
+# end
+
+task :rubyforge => [:rdoc] do
+  Rake::RubyForgePublisher.new(PROJECT_NAME, RUBYFORGE_USER).upload
+end
+
+task :test do
+  Rake::run_tests
+end

data/TODO

@@ -0,0 +1,26 @@
+== Bugs
+
+- Pawn#could_perform_move does not check for en passant.
+
+- Move#initialize does not handle "e.p." or "ep" in move text.
+
+== To Do
+
+- better way to specify configs/program numbers; file must not live in same
+  directory as source code
+
+- write "-c" code in bin/bangkok and examples
+
+- test bankgok -c examples/program_changes.rb examples/game.pgn
+
+- implement check for en passant in Pawn#could_perform_move. Might need a new
+  ivar @moved_two_spaces_on_first_move.
+
+- glide between squares
+
+- time to move relative to distance travelled (quarter note per unit;
+  length_to_delta(dist))
+
+- configuration file: volume offset, min, max; other params
+
+- more tests

data/bin/bangkok

@@ -0,0 +1,40 @@
+require 'getoptlong'
+begin
+  require 'bangkok/chessgame'
+rescue LoadError
+  require 'rubygems'
+  require_gem 'bangkok/chessgame'
+end
+
+def usage
+  $stderr.puts <<EOS
+usage: bangkok [-v] chessgame.pgn ...
+  -v   Verbose (prints each move)
+  -h   This message
+
+Using the default GameListener, creates chessgame.mid for every chessgame.pgn.
+To use your own GameListener, see the Bangkok README file.
+EOS
+  
+  exit 1
+end
+
+$verbose = false
+g = GetoptLong.new(['-v', '--verbose', GetoptLong::NO_ARGUMENT],
+		   ['-h', '--help', GetoptLong::NO_ARGUMENT])
+g.each { | opt, arg |
+  case opt
+  when '-v'
+    $verbose = true
+  else
+    usage
+  end
+}
+usage if ARGV.length == 0
+
+ARGV.each { | fname |
+  game = ChessGame.new
+  File.open(fname, 'r') { | f | game.read_moves(f) }
+  midi_file_name = File.basename(fname).sub(/(\..+)?$/
+  File.open(midi_file_name, '.mid'), 'wb') { | f | game.play(f) }
+}

data/examples/announcer.rb

@@ -0,0 +1,71 @@
+#! /usr/bin/env ruby
+
+require 'getoptlong'
+begin
+  require 'bangkok/chessgame'
+rescue LoadError
+  require 'rubygems'
+  require_gem 'bangkok/chessgame'
+end
+
+class Announcer
+  def start_game(io)
+    @out = io
+    @out.puts 'Start of game'
+  end
+
+  def end_game
+    @out.puts 'End of game'
+  end
+
+  def move(piece, from, to)
+    @out.puts "Piece #{piece} moving to #{to}"
+  end
+
+  def capture(attacker, loser)
+    @out.puts "#{attacker} captures #{loser}"
+  end
+
+  def check
+    @out.puts "Check"
+  end
+
+  def checkmate
+    @out.puts "Checkmate"
+  end
+
+  def pawn_to_queen(pawn)
+    @out.puts "#{pawn} has been turned into a queen"
+  end
+end
+
+def usage
+  $stderr.puts <<EOS
+usage: announcer [-v] chessgame.pgn ...
+  -v   Verbose (prints each move)
+  -h   This message
+
+For each chess game, prints each event to stdout.
+EOS
+  
+  exit 1
+end
+
+$verbose = false
+g = GetoptLong.new(['-v', '--verbose', GetoptLong::NO_ARGUMENT],
+		   ['-h', '--help', GetoptLong::NO_ARGUMENT])
+g.each { | opt, arg |
+  case opt
+  when '-v'
+    $verbose = true
+  else
+    usage
+  end
+}
+usage if ARGV.length == 0
+
+ARGV.each { | fname |
+  game = ChessGame.new(Announcer.new)
+  File.open(fname, 'r') { | f | game.read_moves(f) }
+  game.play($stdout)
+}