boardsy 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b750bc02093aeb9aea661c3b0d7bf93caa6cc2be38fabeffd433ca8522db2e6f
-  data.tar.gz: ec74970ab7983c3147f65836eda15465d261ee14bdb8e9b40b2919b13da844f7
+  metadata.gz: 7647121cd08dd81183448c76927556e7a3108b8ba7389aa1c07b2e725f9f6bad
+  data.tar.gz: d40ab647023bceecd9cfd1ee36000e74af399a52e501f72cb9acb726ffd5c870
 SHA512:
-  metadata.gz: c032c995235e197e62821bf4a9e8d386a5d8085e060756f139c5645886b516862fd4683984bb289eee350c848b0a1973dc61ce58222ffad26e339e35b7b68a3c
-  data.tar.gz: dcedcc62f3221897f2a64eb69a7cb40e34916324a7cfe789e00279329ac62409da286bac48d24c9c966c5a80e73d29344f9061c13d1fca717b62cc0851b6546b
+  metadata.gz: 05d95b4953afaeb3a5580f5c9f827e3e3182f5f0c934fe30891030fc113371bdf0a42e60d2ba708e9d86e01fcc6897a1efc1117cf9b0e2d2a54f1a4777c42a40
+  data.tar.gz: 4556cb6740b1dff68354ef98385acb151d670e6edf5ceb54ea9ee92ab90233d5bd46aa4dcbd9165ba9aec22ef80dcffaa8ab97d6f5d5e91ff839bad6e390c272

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boardsy (0.2.0)
+    boardsy (0.2.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,7 @@
 # Boardsy
 
-TODO: describe the gem
+This gem provides a `Board` class to build Command Line Interface board games in Ruby. See the "Usage" section below for available methods.
+This project is actively being worked on. Additional functionality will be added on a consistent basis.
 
 ## Installation
 
@@ -20,7 +21,177 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The board is stored by the class as a 2D array of `Square` objects.
+Each `Square` object contains a value and its x and y coordinates within the board.
+By default, each `Square` object is initialized with its value set to `nil`.
+
+### Initialization
+
+The board is initialized as an 8x8 board by default.
+
+```ruby
+Board.new # returns a Board object of 8x8 Square objects
+```
+
+The length and width can be specified by passing a single argument.
+
+```ruby
+Board.new(4) # returns a Board object of 4x4 Square objects
+```
+
+The length and width can be individually specified by passing an 'x' value and a 'y' value as arguments.
+
+```ruby
+Board.new(6,8) # returns a Board object of 6x8 Square objects
+```
+
+A `value` argument can be passed to initialize each `Square` object with the value passed.
+
+```ruby
+Board.new(6, 8, value: 'empty')
+```
+
+In addition, a block can be passed to `Board#new` to assign a value to each `Square` object.
+
+```ruby
+Board.new(4) { |x,y| (x.odd? && y.odd?) ? 'X' : 'O' } # returns a Board object laid out as the following:
+#|O|O|O|O|
+#|X|O|X|O|
+#|O|O|O|O|
+#|X|O|X|O|
+```
+
+### Enumerable methods
+
+The `Board` class includes the `Enumerable` module, and has access to each method provided `Enumerable`.
+The squares of the board are passed row by row starting from the bottom left-square and ending with the upper-right square.
+Calling `Board#each` without passing a block will return an `Enumerable` object.
+
+### Methods for retrieving information about the board
+
+`Board#length` returns the length of the board as an integer.
+`Board#width` returns the width of the board as an integer.
+
+```ruby
+board = Board.new(5,8)
+board.length # 5
+board.width # 8
+```
+
+`Board#squares` will return an array of each `Square` object, in the order that they are iterated by `Board#each`
+
+```ruby
+board = Board.new(2)
+board.squares.map { |sq| sq.coords } # [[1,1], [2,1], [1,2], [2,2]]
+```
+
+### Methods for selection portions of the board.
+
+`Board#square` returns the `Square` object as specified by the coordinates passed as an argument.
+The 'x' and 'y' coordinates can be passed as individual arguments, an `[x,y]` array, or an `'xy'` string.
+The coordinates can additionally be passed an algebraic format, as done in chess: `d4`, `['d',5]`.
+This also applies to any following method that takes coordinates as an argument.
+
+```ruby
+board = Board.new
+board.square(4,4)
+board.square([7,2])
+board.square('a5')
+```
+
+`Board#row` returns the row,from left to right as an array, in which the given square is located.
+`Board#col` or `Board#column` returns the column, from bottom to top as an array, in which the given square is located.
+Both methods will accept a `Square` object as an argument as well as coordinates formatted in the same way as `Board#square`.
+
+```ruby
+board = Board.new
+board.row(5,8) # returns an array of the squares in the top row
+board.col('a7') # returns an array of the squares in the left-most column
+
+square = board.square(['h',4])
+board.col(square) # returns an array of the squares in the right-most column
+```
+
+`Board#diagonals` returns a 2D array where each nested array is an array of squares along a diagonal which intersects the passed coordinates.
+This method accepts the same argument formats as `Board#row` and `Board#col`.
+
+```ruby
+board = Board.new(4)
+diagonals = board.diagonals(2,2)
+diagonals.each { |diagonal| p diagonal.map { |sq| sq.coords } }
+=> [[1,1], [2,2], [3,3], [4,4]]
+=> [[1,3], [2,2], [3,1]]
+```
+
+The standard `[]` notation can be used to select an array of squares by standard indexing.
+
+```ruby
+board = Board.new(8)
+square = board[0][3]
+square.coords # [4,8]
+```
+
+The `Board#index` method can be used to retrieve the indexes of a square within the 2D array that the board is represented in.
+
+```ruby
+board = Board.new(4)
+board.index([3,3]) # [1,2]
+board[1][2] # [3,3]
+```
+
+### Testing the relationship between squares
+
+Each of the following methods accepts an array of coordinates or an array of `Square` objects as an argument and returns a boolean value.
+`Board#same_row?`, `Board#same_col?` (alias: `Board#same_column?`), `Board#same_diagonal?`.
+
+```ruby
+board = Board.new
+board.same_row?('a4', 'd4', 'g4') # true
+board.same_col?([3,2], [3,7], [2,5]) # false
+
+sq1 = board.square('a1')
+sq2 = board.square('d4')
+board.same_diagonal?(sq1,sq2) # true
+```
+
+### Altering the orientation of the board
+
+The `Board` class provides methods for flipping the board.
+At the moment, these methods will only flip the values of the squares along the given axis. The coordinates of the squares will stay the same. Methods allowing 'hard' flips will be added soon.
+Methods succeeded by a '!' will mutate the `Board` object itself. Methods without the exclamation mark will leave the original `Board` object and return a new `Board` object.
+The current available methods are `flip`, `flip!`, `flip_x`, `flip_y`, `flip_x!`, and `flip_y!`.
+`flip` and `flip!` take as an argument the axis as either a string or a symbol. By default they flip along the x axis.
+
+```ruby
+board = Board.new(3, value: 'O')
+board.square([1,2]).value = 'X'
+board.square([3,3]).value = 'X'
+board_x = board.flip(:x)
+board_y = board.flip('y')
+
+board # returns the following Board object:
+# |O|O|X|
+# |X|O|O|
+# |O|O|O|
+
+board_x # returns the following Board object:
+# |O|O|O|
+# |X|O|O|
+# |O|O|X|
+
+board_y # returns the following Board object:
+# |X|O|O|
+# |O|O|X|
+# |O|O|O|
+
+board.flip!('x')
+board.flip!(:y)
+
+board # now returns the folling Board object:
+# |O|O|O|
+# |O|O|X|
+# |X|O|O|
+```
 
 ## Development
 

data/lib/boardsy/lib/board.rb

@@ -13,32 +13,25 @@ class Board
     end
   end
   
-  #TODO: write exception tests
-  def square(*coords)
-    coords = format_coords(coords)
-    each { |square| return square if square.coords == coords }
-    raise ArgumentError, 'Coordinates passed are out of bounds.'
+  def length
+    grid.first.size
   end
   
-  def index(coords)
-    x,y = format_coords(coords)
-    [grid.size - y, x - 1]
-  end
-  
-  def rows
+  def width
     grid.size
   end
   
-  def cols
-    grid.transpose.size
-  end
-  
   def squares
     each.to_a
   end
   
-  alias :columns :cols
-
+  #TODO: write exception tests
+  def square(*coords)
+    coords = format_coords(coords)
+    each { |square| return square if square.coords == coords }
+    raise ArgumentError, 'Coordinates passed are out of bounds.'
+  end
+  
   def col(*coords)
     grid.transpose[format_coords(coords).first - 1].reverse
   end
@@ -121,9 +114,7 @@ class Board
   def flip(axis = :x)
     raise ArgumentError unless [:x, :y].include?(axis.to_sym)
     flip!(axis)
-    board = Board.new(grid.first.size, grid.size) do |x,y|
-      square(x,y).value
-    end
+    board = Board.new(grid.first.size, grid.size) { |x,y| square(x,y).value }
     flip!(axis)
     board
   end
@@ -158,6 +149,11 @@ class Board
     grid[idx]
   end
   
+  def index(coords)
+    x,y = format_coords(coords)
+    [grid.size - y, x - 1]
+  end
+  
   private
   
   #write tests for this method

data/lib/boardsy/version.rb

@@ -1,3 +1,3 @@
 module Boardsy
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boardsy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Bennett Struttman