terminal_game_of_life 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e653045a66a53af6c2b4c5b58f0330ec18d8125e7ce70b2b9c8803e8d7f67b2a
+  data.tar.gz: 75ffbbd48c0b9cb883a2cd1aab1f0b7e7606856223a18e88c4dd0a9916a5afc6
+SHA512:
+  metadata.gz: a4ae52be24a7bbadf45997c129b1e4b407f3b6f47ecc1cb6c6c63c002d57add5f6ac231581ef024458f366189555f73fad4995a279d4b9b92c0fc5e2d5721141
+  data.tar.gz: b3f717f56369f87ed173a57ff9f79364e3400af441c543c58a64a244fa8b9a328304fd00a9de8d82593fbb6aeb0795f81d15ceb67b29a698d1b0ebe0133ff1ea

data/README.md

@@ -0,0 +1,52 @@
+# GameOfLife
+
+The implementation of the [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) ruby CLI gem
+
+## Installation
+```bash
+$ gem install terminal_game_of_life
+```
+
+## Usage
+
+Check `game-of-life --help` for usage info.
+
+```
+  game-of-life --version, -v    # Prints the Game of Life version information
+  game-of-life help [COMMAND]   # Describe available commands or one specific command
+  game-of-life start [OPTIONS]  # Start the Game of Life simulations (default command)
+
+Options:
+  -s, [--seed=SEED]            # Specify the seed number to use as an initial state (default to random).
+  -i, [--input=VALUE]          # Specify the path/URL for the file to use as an initial state. (used instead of seed)
+  -w, [--width=WIDTH]          # Specify the width of generated universe. (default to terminal width)
+  -h, [--height=HEIGHT]        # Specify the hight of generated universe. (default to terminal height)
+      [--dead-cell=CHAR]       # Specify the dead-cell representation
+                               # Default:
+      [--live-cell=CHAR]       # Specify the dead-cell representation
+                               # Default: █
+  -d, [--delay=Milli-Seconds]  # Specify the introduced delay between each generation
+                               # Default: 50
+```
+
+## Development
+
+- Clone the repo.
+- Navigate to the ruby CLI implementation `cd game-of-life/CLI/ruby`.
+- run `bundle install` to install dependencies.
+- run `bundle rake build` to build the gem/CLI into the `pkg` directory.
+- run `bundle rake install` to build and install gem/CLI into system gems.
+
+## Linting
+Run `bundle exec rubocop`
+
+## Testing
+Run `bundle exec rspec` or `bundle exec rake spec`
+
+## Documentation
+Run `bundle exec yard`
+
+## Extra information
+### [Contributing](../../CONTRIBUTING.md)
+### [License](../../LICENSE.md)
+### [Code of Conduct](../../CODE_OF_CONDUCT.md)

data/bin/game-of-life

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "game_of_life"
+require "thor"
+require "io/console"
+
+class CLI < Thor
+  map %w[-v --version] => :version
+  desc "--version, -v", "Prints the Game of Life version information"
+  def version
+    puts "Game of Life version #{GameOfLife::VERSION}"
+  end
+
+  default_task :start
+  desc "start [OPTIONS]", "Start the Game of Life simulations"
+  class_option "seed",  aliases: "-s", type: :numeric, banner: :SEED,
+                        desc: "Specify the seed number to use as an initial state (default to random)."
+
+  class_option "input", aliases: "-i", type: :string, banner: :VALUE,
+                        desc: "Specify the path/URL for the file to use as an initial state. (used instead of seed)"
+
+  class_option "width", aliases: "-w", type: :numeric, banner: :WIDTH,
+                        desc: "Specify the width of generated universe. (default to terminal width)"
+
+  class_option "height", aliases: "-h", type: :numeric, banner: :HEIGHT,
+                         desc: "Specify the hight of generated universe. (default to terminal height)"
+
+  class_option "dead-cell", type: :string, banner: :CHAR, default: "\s",
+                            desc: "Specify the dead-cell representation"
+
+  class_option "live-cell", type: :string, banner: :CHAR, default: "\u2588",
+                            desc: "Specify the dead-cell representation"
+
+  class_option "delay", aliases: "-d", type: :numeric, banner: "Milli-Seconds", default: 50,
+                        desc: "Specify the introduced delay between each generation"
+  def start
+    options_with_console_defaults = {
+      # Defaults the hight to less then the height of the terminal to allow banner info
+      # and an extra emtpy line to avoid triggering terminal scroll while flushing
+      "height" => IO.console.winsize[0] - 3,
+      "width" => IO.console.winsize[1],
+      "seed" => rand(100_000),
+    }.merge(options)
+
+    universe = GameOfLife.generate(options_with_console_defaults)
+    GameOfLife.run(universe)
+  end
+
+  class << self
+    # Allow exit with status 1 on failure
+    # Ref: https://github.com/erikhuda/thor/issues/244#issue-6116190
+    def exit_on_failure?
+      true
+    end
+  end
+end
+
+begin
+  CLI.start(ARGV)
+rescue SystemExit, Interrupt
+  "Do nothing when user exits with Interrupt (CMD/Ctrl + C)"
+rescue NotImplementedError
+  puts "Seed option isn't implemented yet, please use --input option"
+end

data/game_of_life.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/game_of_life/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "terminal_game_of_life"
+  spec.version       = GameOfLife::VERSION
+  spec.authors       = ["a14m"]
+  spec.email         = ["a14m@pm.me"]
+
+  spec.summary       = "Game of Life CLI"
+  spec.description   = "Conway's game of life implementation as a CLI ruby gem."
+  spec.homepage      = "https://gitlab.com/a14m/game-of-life"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.4.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = "https://gitlab.com/a14m/game-of-life/-/tree/master/CLI/ruby/"
+
+  spec.executables   = ["game-of-life"]
+  spec.require_paths = ["lib"]
+  spec.files         = Dir["README.md", "game_of_life.gemspec", "bin/game-of-life", "lib/**/*.rb"]
+
+  spec.add_dependency "thor", "~> 1.0"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "pry-byebug"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rubocop"
+  # Documentation dependencies
+  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "yard"
+end

data/lib/game_of_life.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "game_of_life/version"
+require "game_of_life/plane"
+require "game_of_life/universe"
+require "game_of_life/cell"
+
+# Game of Life module entry point
+module GameOfLife
+  class << self
+    # Generate a universe based on the options (from an input file/URI) or using a random/passed seed
+    # This method also sets the Classes/Modules constants for the run defining the options for
+    # Cell (Dead/Live) state representations, and the delay introduced after rendering each universe/generation
+    # and the banner for the info/options
+    #
+    # @param options [Hash] CLI options to generate initial conditions
+    # @option options [String | nil] "input" path to a local file or URL to open
+    # @option options [Numeric] "seed" number to use if no "input" is provided (defaults to random)
+    # @option options [Numeric] "width" of the universe
+    # @option options [Numeric] "height" of the universe
+    # @option options [Numeric] "delay" introduced after each cycle
+    # @option options [String] "live-cell" representation
+    # @option options [String] "dead-cell" representation
+    # @return [GameOfLife::Universe] populated with the parsed input/seed
+    def generate(options)
+      # Define the constants for Cell representation
+      GameOfLife::Cell.const_set(:LIVE_CELL, options["live-cell"])
+      GameOfLife::Cell.const_set(:DEAD_CELL, options["dead-cell"])
+      # Define the constant used for delay
+      GameOfLife.const_set(:DELAY, options["delay"].to_f)
+
+      banner = options["input"] ? "Input: #{options['input']}" : "Seed: #{options['seed']}"
+      # Define the constant used for banner info
+      GameOfLife.const_set(:BANNER, banner)
+
+      return GameOfLife::Generators::Input.new(options) if options["input"]
+      GameOfLife::Generators::Seed.new(options)
+    end
+
+    # The infinite running loop for rendering the current state of a universe
+    # and then evolving it and repeating.
+    def run(universe)
+      Kernel.loop do
+        GameOfLife.render(universe)
+        universe.evolve!
+      end
+    end
+
+    # Private method to do the terminal screen/scrollback buffer cleaning
+    # and rendering of the current universe/banner info
+    # based on the delay configured by the user
+    def render(universe)
+      puts "\33c\e[3J" # Clears the screen and scrollback buffer.
+      puts universe.to_s
+      puts BANNER
+      sleep(DELAY / 1000.0)
+    end
+  end
+
+  # Generators module for generating the universe initial state
+  module Generators
+    autoload :Input, "game_of_life/generators/input.rb"
+    autoload :Seed,  "game_of_life/generators/seed.rb"
+  end
+end

data/lib/game_of_life/cell.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module GameOfLife
+  # Class representing a cell in the GemeOfLife universe
+  # @!attribute [r] alive
+  #   @return [True | False] the living state of the cell
+  # @!attribute [r] x
+  #   @return [Integer] the X-axis position of the cell in the universe
+  # @!attribute [r] y
+  #   @return [Integer] the Y-axis position of the cell in the universe
+  class Cell
+    attr_reader :alive, :x, :y
+
+    # Initialize a cell in the game of life universe
+    # @param alive [True|False] boolean indicating if the cell is considered alive
+    # @param x [Integer] the x position on the cyclic universe plane
+    # @param y [Integer] the y position on the cyclic universe plane
+    def initialize(alive:, x:, y:)
+      @alive = alive
+      @x = x
+      @y = y
+    end
+
+    # Representation of a cell
+    # Both LIVE_CELL, and DEAD_CELL constant are defined on the application start from the options
+    # @return [String] if a cell is alive or an empty space
+    def to_s
+      alive? ? LIVE_CELL : DEAD_CELL
+    end
+
+    # Evolve a cell in the game of life to the new state in the next generation
+    # @param neighbors [Array<GameOfLife::Cell>] that are neighboring the current cell (size of 8)
+    # @return [GameOfLife::Cell] representing the new state in the next generation
+    #
+    # @note There are some optimizations of returning a new object only when the state changes, otherwise returning self
+    #   This optimization is done to limit the spacial complexity to `O(2n^2) = O(2*witdht*height)`
+    #   in the worst case scenario, and to `O(n^2) = O(width * hight)` in the best case scenario
+    #   (when the universe is stale and don't evolve anymore).
+    # @see #living_neighbors
+    def evolve!(neighbors)
+      return repopulate! if dead? && living_neighbors(neighbors) == 3
+      return survive! if alive? && [2, 3].include?(living_neighbors(neighbors))
+      die!
+    end
+
+    # Helper method to define the language used in GameOfLife
+    # @return [True | False] cell living state
+    def alive?
+      @alive
+    end
+
+    # Helper method to define the language used in GameOfLife
+    # @return [True | False] cell dead state
+    # @see #alive?
+    def dead?
+      !alive?
+    end
+
+    # Count the living neighbor cells relatively to the current cell in the {GameOfLife::Universe}
+    # @param neighbors [Array<GameOfLife::Cell>] that are neighboring the current cell (size of 8)
+    # @return [Integer] the number of living neighbors
+    # @see GameOfLive::Universe#neighbors
+    private def living_neighbors(neighbors)
+      neighbors.select(&:alive?).size
+    end
+
+    # Helper method to define the language used in GameOfLife
+    # @return [GameOfLife::Cell] new living cell
+    # @see #survive!
+    # @see #die!
+    private def repopulate!
+      self.class.new(x: x, y: y, alive: true)
+    end
+
+    # Helper method to define the language used in GameOfLife
+    # @return [GameOfLife::Cell] self (since no change in state needed)
+    # @see #repopulate!
+    # @see #die!
+    private def survive!
+      self
+    end
+
+    # Helper method to define the language used in GameOfLife
+    # When a cell is dead returns self otherwise return a new dead cell
+    # @return [GameOfLife::Cell] self (if already dead) or new dead cell
+    # @see #repopulate!
+    # @see #survive!
+    private def die!
+      dead? ? self : self.class.new(x: x, y: y, alive: false)
+    end
+  end
+end

data/lib/game_of_life/generators/input.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "open-uri"
+
+module GameOfLife
+  module Generators
+    # Generate a new Universe/Board with a parsed local file or remote URL/file
+    module Input
+      class << self
+        # Generate a new Universe/Board with a parsed local file or remote URL/file
+        # @param options [Hash] CLI options to generate initial conditions
+        # @option options [String] "input" path to a local file or URL to open
+        # @option options [Numeric] "width" (floored) and used as the width of the universe
+        # @option options [Numeric] "height" (floored) and used as the height of the universe
+        # @return [GameOfLife::Universe] populated with the parsed input
+        # @see ::GameOfLife::Generators::Input.populate
+        def new(options)
+          # By design, it's intentional that we use URI.open to to allow seamless file and url access
+          raw = URI.open(options["input"]).read.split("\n") # rubocop:disable Security/Open
+
+          # Parse the file and convert it to a boolean 2D array
+          # where any alpha numeric character is considered a living cell (true)
+          raw.map! { |row| row.chars.map { |char| char.match?(/[[:alnum:]]/) } }
+          populate(parsed_input: raw, width: options["width"].to_i, height: options["height"].to_i)
+        end
+
+        # Populate the {GameOfLife::Universe} with reference to the parsed input 2D array (True/False)
+        # @param parsed_input [Array<Array<True|False>>]
+        # @param width [Integer] width of the generated cyclic universe
+        # @param height [Integer] height of the generated cyclic universe
+        # @return [GameOfLife::Universe] populated with the parsed input
+        private def populate(parsed_input:, width:, height:)
+          # Generate a universe based on the parsed raw file and fill it with the cells
+          universe = GameOfLife::Universe.new(height: height, width: width)
+          (0...height).each do |i|
+            (0...width).each do |j|
+              cell = { x: j, y: i, alive: parsed_input.fetch(i, nil)&.fetch(j, nil) }
+              universe[i][j] = ::GameOfLife::Cell.new(cell)
+            end
+          end
+          universe
+        end
+      end
+    end
+  end
+end

data/lib/game_of_life/generators/seed.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GameOfLife
+  module Generators
+    # Generate a new Universe/Board from a seed number
+    module Seed
+      class << self
+        # Generate a new Universe/Board from a seed number
+        # @param options [Hash] CLI options to generate initial conditions
+        # @option options [Numeric] "seed" number to use for generation
+        # @option options [Numeric] "width" (floored) and used as the width of the universe
+        # @option options [Numeric] "height" (floored) and used as the height of the universe
+        # @return [GameOfLife::Universe] populated with the parsed input
+        def new(options)
+          fail NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/game_of_life/plane.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GameOfLife
+  # Custom Plane class that represent a cyclic/circular plane/array
+  # This class would always return an element unless the array is empty
+  class Plane < Array
+    # Extending the default array behaviour by treating the array as cyclic/circular object
+    #
+    # @example working with normal array
+    #   a = [0, 1, 2, 3]
+    #   a[-6] == a[-2] == a[2]
+    #   a[-5] == a[-1] == a[3]
+    #   a[-4] == a[0]  == a[4]
+    #   a[-3] == a[1]  == a[5]
+    #   a[-2] == a[2]  == a[6]
+    #   a[-1] == a[3]  == a[7]
+    #   a[0]  == a[4]  == a[8]
+    #
+    # @example working with empty array
+    #   b = []
+    #   b[0] == b[1] == b[-1] == nil
+    def [](index)
+      return nil if empty?
+      super(index % size)
+    end
+  end
+end

data/lib/game_of_life/universe.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module GameOfLife
+  # Representation of the current and future state of the game of life universe
+  class Universe
+    extend Forwardable
+    delegate :[] => :@current
+    delegate :[]= => :@current
+
+    # Initialize the empty initial universe 2D plane (circular arrays)
+    # @param width [Integer] the width of the universe array
+    # @param height [Integer] the height of the universe array
+    def initialize(width:, height:)
+      @current = GameOfLife::Plane.new(height) { GameOfLife::Plane.new(width) }
+      @future  = GameOfLife::Plane.new(height) { GameOfLife::Plane.new(width) }
+    end
+
+    # Representation of the game of life universe
+    # @return [String] representing the current state
+    # @see GameOfLife::Cell#to_s
+    def to_s
+      @current.map(&:join).join("\n")
+    end
+
+    # Update the current state of the universe (according to the game of life laws) and
+    # set the current state to the next future generation
+    #
+    # This have computational order `O(n^2) = O(width * height)`
+    # It loops over all the universe cells and evolves them to the next generation
+    # @see #neighbors
+    def evolve!
+      @current.each do |row|
+        row.each do |cell|
+          @future[cell.y][cell.x] = cell.evolve!(neighbors(cell))
+        end
+      end
+      @current = Marshal.load(Marshal.dump(@future))
+    end
+
+    # Return the array of all the neighboring cells using the circular universe array, <br/>
+    #   given a cell "C" in a universe of cells "." the immediate neighbors would be "x" as in
+    #   the following different examples
+    #
+    #     .....  |  .xxx.  |  .xCx.  |  xCx..  |  Cx..x  |  xx..x  |
+    #     .xxx.  |  .xCx.  |  .xxx.  |  xxx..  |  xx..x  |  Cx..x  |
+    #     .xCx.  |  .xxx.  |  .....  |  .....  |  .....  |  xx..x  |
+    #     .xxx.  |  .....  |  .....  |  .....  |  .....  |  .....  |
+    #     .....  |  .....  |  .xxx.  |  xxx..  |  xx..x  |  .....  |
+    #
+    # @param cell [GameOfLife::Cell] the to return the neighboring cells from the universe current plane
+    # @return [Array<GameOfLife::Cell>] of all the immediate neighboring cells
+    # @smell AbcSize higher than configuration, but needed to return the neighboring cells array
+    #
+    # rubocop:disable Metrics/AbcSize
+    private def neighbors(cell)
+      x, y = cell.x, cell.y # rubocop:disable Style/ParallelAssignment
+      [
+        @current[y - 1][x - 1], @current[y - 1][x], @current[y - 1][x + 1],
+        @current[y][x - 1], @current[y][x + 1],
+        @current[y + 1][x - 1], @current[y + 1][x], @current[y + 1][x + 1]
+      ]
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/lib/game_of_life/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GameOfLife
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,169 @@
+--- !ruby/object:Gem::Specification
+name: terminal_game_of_life
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- a14m
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Conway's game of life implementation as a CLI ruby gem.
+email:
+- a14m@pm.me
+executables:
+- game-of-life
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/game-of-life
+- game_of_life.gemspec
+- lib/game_of_life.rb
+- lib/game_of_life/cell.rb
+- lib/game_of_life/generators/input.rb
+- lib/game_of_life/generators/seed.rb
+- lib/game_of_life/plane.rb
+- lib/game_of_life/universe.rb
+- lib/game_of_life/version.rb
+homepage: https://gitlab.com/a14m/game-of-life
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://gitlab.com/a14m/game-of-life
+  source_code_uri: https://gitlab.com/a14m/game-of-life/-/tree/master/CLI/ruby/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Game of Life CLI
+test_files: []