life_game_viewer 0.9.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+.idea/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in life_game_viewer.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Keith Bennett
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,233 @@
+Game of Life Viewer
+===================
+
+This is a JRuby application that calculates and displays generations
+of Conway's Game of Life.
+It uses Java's Swing UI library and is an entirely client side application,
+so there is no need for a web server, browser, or even network connection.
+
+The game itself (as opposed to the viewer) is often used as a programming
+exercise.  More information on the game is at
+http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life.
+
+My intention in writing this was to provide a GUI player
+with which developers could:
+
+<ol>
+<li> view and test their implementations of the Game of Life exercise</li>
+<li> easily inspect the results of different data inputs into the game</li>
+</ol>
+
+(Note: The instructions below assume use of a Unix command line
+(e.g. Linux, Mac OS) and rvm. If you're using Windows,
+make the appropriate substitutions, such as '\' for '/', 'ren' for 'mv'.
+Also, please see the troubleshooting section below if you have
+problems running the program.)
+
+
+JRuby and Java
+==============
+
+This program will only run in [JRuby] [3] (which needs the Java Runtime Environment),
+so you'll need to make sure you have both installed.
+The easiest way to install and use JRuby is with [rvm] [4], which you
+can only do with a Unix-like shell.  Linux or Mac OS will easily work; for Windows,
+you might be able to get it to work with [Cygwin] [5].
+
+
+1.9 Required
+============
+
+This program requires that JRuby be run in 1.9 mode.  In JRuby versions 1.7
+and above, this is the default setting, but for earlier versions
+you'll have to specify this mode by passing the "--1.9" option to JRuby.
+It's probably easiest to do this by putting the following into your startup
+shell's initialization file (e.g. .bashrc or .zshrc):
+
+```
+export JRUBY_OPTS=--1.9
+```
+
+You could do this on your command line instead by preceding your JRuby commands with
+the setting, as in:
+
+```
+JRUBY_OPTS=--1.9 jruby ...
+```
+
+
+Running With the Provided Sample Model
+--------------------------------------
+
+It's fine to use a downloaded copy of the source tree directly,
+but using it as a gem will probably be simpler.
+
+Here is how to run it with the provided model and provided sample data.
+First, install the life_game_viewer gem. This installs a script that
+you can then run on your command line:
+
+```
+life_view_sample
+```
+
+You can experiment with different data sets by:
+
+1) using the clipboard copy and paste feature
+(see _Reading and Writing Game Data Via the Clipboard_ below)
+
+3) (of course) modifying the source code
+
+
+
+Viewing Your Own Game of Life Model Implementation
+--------------------------------------------------
+
+In order to do the exercise, you will need to replace the
+[SampleLifeModel] [6] implementation with your own.  Your model will need to
+respond appropriately to the SampleLifeModel's public method names, because
+they are called by the viewer, but you can implement them any way you
+want, even using the MyLifeModel as a minimal adapter to a completely
+different design. (To take this to the extreme, the model could even
+be implemented in Java, with a thin JRuby adapter around it; or, as
+a RESTful web service in any arbitrary language with the adapter
+making calls to it.)
+
+A [MyLifeModel] [7] skeleton file is provided in the
+lib/model directory as a convenient starting point for you.
+You can copy this file into your own working area.
+
+In your program, all you would need to do is to require life_game_viewer
+and pass an instance of your model to the LifeGameViewer.view method.
+For example:
+
+```ruby
+require 'life_game_viewer'
+model = SampleLifeModel.create(5,5) { |r,c| r.even? } # as an example
+LifeGameViewer.view(model)
+```
+
+
+Where to Find This Software
+---------------------------
+
+This software is located on GitHub at
+https://github.com/keithrbennett/life_game_viewer.
+There is also an [article] [1] about this application on my [blog] [2].
+
+
+Reading and Writing Game Data Via the Clipboard
+-----------------------------------------------
+
+The application starts with a sample data set that can be easily modified in the code.
+You can also use the provided buttons to use the system clipboard to load and save
+game data.  You use the same keys you would normally use for copying pasting,
+that is, _Command_ c and v on a Mac, and _Ctrl_ c and v on other systems. (Note: there
+are currently problems using these keystrokes on Linux and Windows; for now,
+please click the buttons.)
+
+Data is represented as follows:
+
+* The data is a single string of lines, each line representing a row in the matrix
+* Alive (true) values are represented as asterisks ('*'), and false values are hyphens.
+
+For example, the two lines below:
+
+```
+*-
+-*
+```
+
+...represent a 2 x 2 matrix in which only the upper left and
+lower right cells are alive.  The final row's new line is optional.
+
+When you copy a new game's data into the application, it clears all other data and
+uses that as generation #0.
+
+The clipboard functionality enables you to edit game data by doing the following:
+
+* copy the game's current data into the clipboard 
+* paste it into an editor window
+* edit it
+* 'select all' it
+* copy it to your clipboard
+* paste it back into the game
+
+In many cases, it will be easier to generate the string programmatically,
+either in the program itself, or in irb.
+
+
+Navigating the Generations
+--------------------------
+
+There are buttons to help you navigate the generations:
+_First_, _Previous_, _Next_, and _Last_.
+There are keystroke equivalents for your convenience, all numbers
+so that you can put your fingers on the number row of the
+keyboard to do all your navigation. The numbers _1_, _4_, _7_, and _0_
+correspond to _First_, _Previous_, _Next_, and _Last_, respectively.
+
+The Game of Life next generation calculation algorithm
+only considers the most recent generation as input, so
+if there are two consecutive generations that are identical,
+all subsequent ones will be identical as well.  The viewer will
+consider the first of consecutive identical generations to be
+the end of the lineage.
+
+You can have the viewer find this last generation for you
+by pressing the _Last_ button.  Be careful, though --
+this operation runs on the main UI thread and I haven't
+gotten around to enabling its interruption --
+so be prepared to kill the application if it no longer responds.
+You can normally do this by pressing _Ctrl-C_ on the command line
+from which you started the program.
+
+
+Troubleshooting
+---------------
+
+The most common problems will probably be related to the installation and use of JRuby,
+and the unintentional use of MRI Ruby instead of JRuby.
+
+To see which version of Ruby you're using, use the '-v' option for ruby or jruby:
+
+```
+>ruby -v
+jruby 1.6.7 (ruby-1.9.2-p312) (2012-02-22 3e82bc8) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_33) [darwin-x86_64-java]
+```
+
+Another test is to try to require 'java'.  When you see the error in the last command below,
+you know that you're not using JRuby:
+
+```
+>ruby -v
+jruby 1.6.7 (ruby-1.9.2-p312) (2012-02-22 3e82bc8) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_33) [darwin-x86_64-java]
+
+>ruby -e "require 'java'"
+
+>rvm 1.9
+
+>ruby -e "require 'java'"
+/Users/keithb/.rvm/rubies/ruby-1.9.3-p125/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:
+in `require': cannot load such file -- java (LoadError)
+```
+
+
+Feedback
+--------
+
+Constructive feedback is always welcome, even for little things.
+
+
+License
+-------
+
+This software is released under the MIT/X11 license.
+
+
+[1]: http://www.bbs-software.com/blog/2012/09/05/conways-game-of-life-viewer/   "http://www.bbs-software.com/blog/2012/09/05/conways-game-of-life-viewer/"
+[2]: http://www.bbs-software.com/blog/     "http://www.bbs-software.com/blog/"
+[3]: http://jruby.org/        "http://jruby.org/"
+[4]: https://rvm.io/rvm/install/      "https://rvm.io/rvm/install/"
+[5]: http://www.cygwin.com/       "http://www.cygwin.com/"
+[6]: https://github.com/keithrbennett/life_game_viewer/blob/master/lib/life_game_viewer/model/sample_life_model.rb     "https://github.com/keithrbennett/life_game_viewer/blob/master/lib/life_game_viewer/model/sample_life_model.rb"
+[7]: https://github.com/keithrbennett/life_game_viewer/blob/master/lib/life_game_viewer/model/my_life_model.rb     "https://github.com/keithrbennett/life_game_viewer/blob/master/lib/life_game_viewer/model/my_life_model.rb"

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/bin/life_view_sample

@@ -0,0 +1,6 @@
+#!/usr/bin/env jruby
+
+
+require 'life_game_viewer'
+
+LifeGameViewer::Main.view_sample

data/lib/life_game_viewer/model/life_calculator.rb

@@ -0,0 +1,103 @@
+# Performs calculations relating to determination of a cell's neighbors
+# and the next generation.  Generally, 'next_generation' will be the
+# only method that will need to be called, but the others are provided
+# publicly, since the Game of Life is all about experimentation.
+#
+# See Wikipedia for more information about Conway's Game of Life.
+#
+# Rules distilled:
+#
+# 1) Any live cell with fewer than two live neighbours dies, as if caused by under-population.
+# 2) Any live cell with two or three live neighbours lives on to the next generation.
+# 3) Any live cell with more than three live neighbours dies, as if by overcrowding.
+# 4) Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction.
+
+class LifeCalculator
+
+  # Returns a new model with the next generation's data.
+  def next_generation(old_model)
+    old_model.class.send(:create, old_model.row_count, old_model.column_count) do |row, col|
+      should_live(old_model, row, col)
+    end
+  end
+
+  # Returns an array of [row, col] tuples corresponding to the cells
+  # neighboring the specified cell location.  "Neighbor" is defined
+  # as a cell with up/down/left/right/diagonal adjacency to the specified cell.
+  def neighbors(model, row, col)
+
+    neighbors = []
+
+    at_left_edge   = col == 0
+    at_right_edge  = col == model.column_count - 1
+    at_top_edge    = row == 0
+    at_bottom_edge = row == model.row_count - 1
+
+    col_to_left  = col - 1
+    col_to_right = col + 1
+    row_above    = row - 1
+    row_below    = row + 1
+
+    # In its own row, return the cell to the left and right as possible.
+    unless at_left_edge
+      neighbors << [row, col_to_left]
+    end
+    unless at_right_edge
+      neighbors << [row, col_to_right]
+    end
+
+    # Process the row above
+    unless at_top_edge
+      unless at_left_edge
+        neighbors << [row_above, col_to_left]
+      end
+      neighbors << [row_above, col]
+      unless at_right_edge
+        neighbors << [row_above, col_to_right]
+      end
+    end
+
+    # Process the row below
+    unless at_bottom_edge
+      unless at_left_edge
+        neighbors << [row_below, col_to_left]
+      end
+      neighbors << [row_below, col]
+      unless at_right_edge
+        neighbors << [row_below, col_to_right]
+      end
+    end
+
+    neighbors
+
+  end
+
+
+  # Returns an array of [row, col] tuples corresponding to those
+  # neighbor cells that are alive.
+  def num_living_neighbors(model, row, col)
+    neighbors(model, row, col).inject(0) do |num_living, neighbor|
+      neighbor_row, neighbor_column = neighbor
+      num_living += 1 if model.alive?(neighbor_row, neighbor_column)
+      num_living
+    end
+  end
+
+
+  # Returns whether or not (as true or false) the specified cell
+  # should continue to live in the next generation.
+  def should_live(model, row, col)
+    model.alive?(row, col) \
+        ? live_cell_should_continue_to_live(model, row, col) \
+        : dead_cell_should_become_alive(model, row, col)
+  end
+
+  def live_cell_should_continue_to_live(model, row, col)
+    (2..3).include?(num_living_neighbors(model, row, col))
+  end
+
+  def dead_cell_should_become_alive(model, row, col)
+    num_living_neighbors(model, row, col) == 3
+  end
+
+end

data/lib/life_game_viewer/model/life_visualizer.rb

@@ -0,0 +1,19 @@
+# Manages the string display of a life model.
+
+class LifeVisualizer
+
+  # Returns a string representation of a LifeModel.
+  def to_display_string(model)
+    output = ''
+    
+    (0...model.row_count).each do |x|
+      (0...model.column_count).each do |y|
+        alive_as_string = model.alive?(x, y) ? '*' : '-'
+        output << alive_as_string
+      end
+      output << "\n"
+    end
+    
+    output
+  end
+end

data/lib/life_game_viewer/model/model_validation.rb

@@ -0,0 +1,41 @@
+class ModelValidation
+
+  def required_class_methods
+    [
+        :create_from_string
+    ]
+  end
+
+  def required_instance_methods
+    [
+        :row_count,
+        :column_count,
+        :alive?,
+        :set_living_state,
+        :set_living_states,
+        :next_generation_model,
+        :number_living
+    ]
+  end
+
+  def class_methods_missing(instance)
+    required_class_methods - instance.class.methods
+  end
+
+  def instance_methods_missing(instance)
+    required_instance_methods - instance.methods
+  end
+
+  def methods_missing(instance)
+    missing_class_method_display_names = class_methods_missing(instance).map { |m| "self.#{m}" }
+    missing_class_method_display_names + instance_methods_missing(instance)
+  end
+
+  def methods_missing_message(instance)
+    missing_methods = methods_missing(instance)
+    missing_methods.empty? \
+        ? nil \
+        : "Model is missing the following required methods: #{missing_methods.join(", ")}."
+  end
+  private
+end

data/lib/life_game_viewer/model/my_life_model.rb

@@ -0,0 +1,56 @@
+# Object that contains and serves (stores and retrieves)
+# living/dead states in the matrix.
+
+
+class MyLifeModel
+
+  # You may want to copy certain methods from SampleLifeModel that you don't
+  # feel the need to implement yourself.  For example, the to_s and ==
+  # methods may be helpful to you in your development and testing.
+  # Also, set_living_states is a convenience method that merely calls
+  # your set_living_state method.
+
+  # Because this viewer is just a tool and should not drive your implementation,
+  # there are no assumptions about your constructor -- you are free to do whatever
+  # you want with it.  Instead, we require a couple of static factory methods
+  # needed by the application.
+
+  # Creates and returns an instance whose size and values are specified
+  # in the passed string.  Rows must be delimited by "\n".  The '*'
+  # character represents true, and any other value will evaluate to false.
+  def self.create_from_string(string)
+  end
+
+  # This method will create a model with the specified number of rows and
+  # columns. If a block is passed it will be used to initialize the
+  # alive/dead values; the block should take params row and column number.
+  def self.create(row_count, column_count)
+  end
+
+  def row_count
+  end
+
+  def column_count
+  end
+
+  def alive?(row, col)
+  end
+
+  def set_living_state(row, col, alive)
+  end
+
+  def set_living_states(array_of_row_col_tuples, alive)
+  end
+
+  def next_generation_model
+  end
+
+  def number_living
+  end
+
+  def to_s
+  end
+
+  def ==(other)
+  end
+end

data/lib/life_game_viewer/model/sample_life_model.rb

@@ -0,0 +1,132 @@
+require_relative "life_calculator"
+
+# Object that contains and serves (stores and retrieves)
+# living/dead states in the matrix.
+#
+# All public methods here should be responded to in alternate
+# model implementations.
+#
+# See Wikipedia for more information about Conway's Game of Life.
+#
+# Rules distilled:
+#
+# 1) Any live cell with fewer than two live neighbours dies, as if caused by under-population.
+# 2) Any live cell with two or three live neighbours lives on to the next generation.
+# 3) Any live cell with more than three live neighbours dies, as if by overcrowding.
+# 4) Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction.
+
+class SampleLifeModel
+  
+  attr_accessor :data
+
+
+  # Creates an instance with the specified number of rows and columns.
+  # All values are initialized to false.
+  def initialize(row_count, column_count)
+    @data = create_data(row_count, column_count)
+  end
+
+
+  # Creates a LifeModel instance whose size and values are specified
+  # in the passed string.  Rows must be delimited by "\n".  The '*'
+  # character represents alive, and the hyphen signifies dead.
+  def self.create_from_string(string)
+    row_count = string.chomp.count("\n") + 1
+    lines = string.split("\n")
+    col_count = lines.first.size
+    model = new(row_count, col_count)
+
+    (0...row_count).each do |row|
+      line = lines[row]
+      (0...(line.size)).each do |col|
+        ch = line[col]
+        alive = (ch == '*')
+        model.set_living_state(row, col, alive)
+      end
+    end
+    model
+  end
+
+
+  # This method will create a model with the specified number of rows and
+  # columns. If a block is passed it will be used to initialize the
+  # alive/dead values; the block should take params row and column number.
+  def self.create(row_count, column_count)
+    model = new(row_count, column_count)
+    if block_given?
+      (0...row_count).each do |row|
+        (0...column_count).each do |col|
+          model.set_living_state(row, col, yield(row, col))
+        end
+      end
+    end
+    model
+  end
+  
+
+  def row_count
+    @data.size
+  end
+
+
+  def column_count
+    @data[0].size
+  end
+  
+
+  def alive?(row, col)
+    @data[row][col]
+  end
+  
+
+  def set_living_state(row, col, alive)
+    @data[row][col] = alive
+  end
+
+
+  def set_living_states(array_of_row_col_tuples, alive)
+    array_of_row_col_tuples.each do |row_col_tuple|
+      row, col = row_col_tuple
+      set_living_state(row, col, alive)
+    end
+  end
+
+
+  def next_generation_model
+    LifeCalculator.new.next_generation(self)
+  end
+
+
+  def to_s
+    super.to_s + ": #{row_count} rows, #{column_count} column_count, #{number_living} alive."
+  end
+
+
+  def ==(other)
+    other.is_a?(self.class)            &&
+    other.row_count == row_count       &&
+    other.column_count == column_count &&
+    other.data == data
+  end
+
+
+  def number_living
+    num = 0
+    (0...row_count).each do |row|
+      (0...column_count).each do |col|
+        num += 1 if alive?(row, col)
+      end
+    end
+    num
+  end
+
+
+  private
+
+  def create_data(row_count, column_count)
+    data = []
+    row_count.times { |n| data << Array.new(column_count, false) }
+    data
+  end
+
+end

data/lib/life_game_viewer/version.rb

@@ -0,0 +1,3 @@
+module LifeGameViewer
+  VERSION = "0.9.1"
+end